blob: b44fdcb73fcad655463c27fbdec99259b01e7d93 [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<!-- Dummy chapter -->
6<chapter id='ref-variables-glos'>
7
8<title>Variables Glossary</title>
9
10<para>
11 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
12 of their function and contents.
13</para>
14
15<glossary id='ref-variables-glossary'>
16
17
18 <para>
19 <link linkend='var-ABIEXTENSION'>A</link>
20 <link linkend='var-B'>B</link>
21 <link linkend='var-CACHE'>C</link>
22 <link linkend='var-D'>D</link>
23 <link linkend='var-EFI_PROVIDER'>E</link>
24 <link linkend='var-FEATURE_PACKAGES'>F</link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040025 <link linkend='var-GCCPIE'>G</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050026 <link linkend='var-HOMEPAGE'>H</link>
27 <link linkend='var-ICECC_DISABLED'>I</link>
28<!-- <link linkend='var-glossary-j'>J</link> -->
29 <link linkend='var-KARCH'>K</link>
30 <link linkend='var-LABELS'>L</link>
31 <link linkend='var-MACHINE'>M</link>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050032 <link linkend='var-NATIVELSBSTRING'>N</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050033 <link linkend='var-OBJCOPY'>O</link>
34 <link linkend='var-P'>P</link>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050035<!-- <link linkend='var-glossary-q'>Q</link> -->
Patrick Williamsc124f4f2015-09-15 14:41:29 -050036 <link linkend='var-RANLIB'>R</link>
37 <link linkend='var-S'>S</link>
38 <link linkend='var-T'>T</link>
39 <link linkend='var-UBOOT_CONFIG'>U</link>
Brad Bishop6e60e8b2018-02-01 10:27:11 -050040 <link linkend='var-VOLATILE_LOG_DIR'>V</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050041 <link linkend='var-WARN_QA'>W</link>
42 <link linkend='var-XSERVER'>X</link>
43<!-- <link linkend='var-glossary-y'>Y</link> -->
44<!-- <link linkend='var-glossary-z'>Z</link>-->
45 </para>
46
47 <glossdiv id='var-glossary-a'><title>A</title>
48
49 <glossentry id='var-ABIEXTENSION'><glossterm>ABIEXTENSION</glossterm>
50 <info>
51 ABIEXTENSION[doc] = "Extension to the Application Binary Interface (ABI) field of the GNU canonical architecture name (e.g. "eabi")."
52 </info>
53 <glossdef>
54 <para role="glossdeffirst">
55<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
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>
Brad Bishop316dfdd2018-06-25 12:45:53 -040075 ALLOW_EMPTY[doc] = "Specifies whether to produce an output package even if it is empty."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050076 </info>
77 <glossdef>
78 <para role="glossdeffirst">
79<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040080 Specifies whether to produce an output package even if it is
81 empty.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050082 By default, BitBake does not produce empty packages.
83 This default behavior can cause issues when there is an
84 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
85 some other hard runtime requirement on the existence of the package.
86 </para>
87
88 <para>
89 Like all package-controlling variables, you must always use them in
90 conjunction with a package name override, as in:
91 <literallayout class='monospaced'>
92 ALLOW_EMPTY_${PN} = "1"
93 ALLOW_EMPTY_${PN}-dev = "1"
94 ALLOW_EMPTY_${PN}-staticdev = "1"
95 </literallayout>
96 </para>
97 </glossdef>
98 </glossentry>
99
100 <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
101 <info>
102 ALTERNATIVE[doc] = "Lists commands in a package that need an alternative binary naming scheme."
103 </info>
104 <glossdef>
105 <para role="glossdeffirst">
106<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
107 Lists commands in a package that need an alternative
108 binary naming scheme.
109 Sometimes the same command is provided in multiple packages.
110 When this occurs, the OpenEmbedded build system needs to
111 use the alternatives system to create a different binary
112 naming scheme so the commands can co-exist.
113 </para>
114
115 <para>
116 To use the variable, list out the package's commands
117 that also exist as part of another package.
118 For example, if the <filename>busybox</filename> package
119 has four commands that also exist as part of another
120 package, you identify them as follows:
121 <literallayout class='monospaced'>
122 ALTERNATIVE_busybox = "sh sed test bracket"
123 </literallayout>
124 For more information on the alternatives system, see the
125 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
126 section.
127 </para>
128 </glossdef>
129 </glossentry>
130
131 <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
132 <info>
133 ALTERNATIVE_LINK_NAME[doc] = "Used by the alternatives system to map duplicated commands to actual locations."
134 </info>
135 <glossdef>
136 <para role="glossdeffirst">
137<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
138 Used by the alternatives system to map duplicated commands
139 to actual locations.
140 For example, if the <filename>bracket</filename> command
141 provided by the <filename>busybox</filename> package is
142 duplicated through another package, you must use the
143 <filename>ALTERNATIVE_LINK_NAME</filename> variable to
144 specify the actual location:
145 <literallayout class='monospaced'>
146 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
147 </literallayout>
148 </para>
149
150 <para>
151 In this example, the binary for the
152 <filename>bracket</filename> command (i.e.
153 <filename>[</filename>) from the
154 <filename>busybox</filename> package resides in
155 <filename>/usr/bin/</filename>.
156 <note>
157 If <filename>ALTERNATIVE_LINK_NAME</filename> is not
158 defined, it defaults to
159 <filename>${bindir}/<replaceable>name</replaceable></filename>.
160 </note>
161 </para>
162
163 <para>
164 For more information on the alternatives system, see the
165 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
166 section.
167 </para>
168 </glossdef>
169 </glossentry>
170
171 <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
172 <info>
173 ALTERNATIVE_PRIORITY[doc] = "Used by the alternatives system to create default priorities for duplicated commands."
174 </info>
175 <glossdef>
176 <para role="glossdeffirst">
177<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
178 Used by the alternatives system to create default
179 priorities for duplicated commands.
180 You can use the variable to create a single default
181 regardless of the command name or package, a default for
182 specific duplicated commands regardless of the package, or
183 a default for specific commands tied to particular packages.
184 Here are the available syntax forms:
185 <literallayout class='monospaced'>
186 ALTERNATIVE_PRIORITY = "<replaceable>priority</replaceable>"
187 ALTERNATIVE_PRIORITY[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>"
188 ALTERNATIVE_PRIORITY_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>"
189 </literallayout>
190 </para>
191
192 <para>
193 For more information on the alternatives system, see the
194 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
195 section.
196 </para>
197 </glossdef>
198 </glossentry>
199
200 <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
201 <info>
202 ALTERNATIVE_TARGET[doc] = "Used by the alternatives system to create default link locations for duplicated commands."
203 </info>
204 <glossdef>
205 <para role="glossdeffirst">
206<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
207 Used by the alternatives system to create default link
208 locations for duplicated commands.
209 You can use the variable to create a single default
210 location for all duplicated commands regardless of the
211 command name or package, a default for
212 specific duplicated commands regardless of the package, or
213 a default for specific commands tied to particular packages.
214 Here are the available syntax forms:
215 <literallayout class='monospaced'>
216 ALTERNATIVE_TARGET = "<replaceable>target</replaceable>"
217 ALTERNATIVE_TARGET[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>"
218 ALTERNATIVE_TARGET_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>"
219 </literallayout>
220 <note>
221 <para>
222 If <filename>ALTERNATIVE_TARGET</filename> is not
223 defined, it inherits the value from the
224 <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
225 variable.
226 </para>
227
228 <para>
229 If <filename>ALTERNATIVE_LINK_NAME</filename> and
230 <filename>ALTERNATIVE_TARGET</filename> are the
231 same, the target for
232 <filename>ALTERNATIVE_TARGET</filename>
233 has "<filename>.{BPN}</filename>" appended to it.
234 </para>
235
236 <para>
237 Finally, if the file referenced has not been
238 renamed, the alternatives system will rename it to
239 avoid the need to rename alternative files in the
240 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
241 task while
242 retaining support for the command if necessary.
243 </para>
244 </note>
245 </para>
246
247 <para>
248 For more information on the alternatives system, see the
249 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
250 section.
251 </para>
252 </glossdef>
253 </glossentry>
254
255 <glossentry id='var-APPEND'><glossterm>APPEND</glossterm>
256 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400257 APPEND[doc] = "An override list of append strings for target specified using LABELS."
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500258 </info>
259 <glossdef>
260 <para role="glossdeffirst">
261<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -0400262 An override list of append strings for each target
263 specified with
264 <link linkend='var-LABELS'><filename>LABELS</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500265 </para>
266
267 <para>
268 See the
269 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
270 class for more information on how this variable is used.
271 </para>
272 </glossdef>
273 </glossentry>
274
275 <glossentry id='var-AR'><glossterm>AR</glossterm>
276 <info>
277 AR[doc] = "Minimal command and arguments to run 'ar'."
278 </info>
279 <glossdef>
280 <para role="glossdeffirst">
281<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
282 The minimal command and arguments used to run
283 <filename>ar</filename>.
284 </para>
285 </glossdef>
286 </glossentry>
287
288 <glossentry id='var-ARCHIVER_MODE'><glossterm>ARCHIVER_MODE</glossterm>
289 <info>
290 ARCHIVER_MODE[doc] = "Controls archive creation used when releasing source files."
291 </info>
292 <glossdef>
293 <para role="glossdeffirst">
294<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
295 When used with the
296 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
297 class, determines the type of information used to create
298 a released archive.
299 You can use this variable to create archives of patched
300 source, original source, configured source, and so forth
301 by employing the following variable flags (varflags):
302 <literallayout class='monospaced'>
303 ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source
304 # files.
305
306 ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is
307 # the default.
308
309 ARCHIVER_MODE[src] = "configured" # Uses configured source files.
310
311 ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and
312 # do_patch.
313
314 ARCHIVER_MODE[diff-exclude] ?= "<replaceable>file</replaceable> <replaceable>file</replaceable> ..." # Lists files and directories to
315 # exclude from diff.
316
317 ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
318
319 ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
320
321 ARCHIVER_MODE[srpm] = "1" # Uses RPM package files.
322 </literallayout>
323 For information on how the variable works, see the
324 <filename>meta/classes/archiver.bbclass</filename> file
325 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500326 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500327 </para>
328 </glossdef>
329 </glossentry>
330
331 <glossentry id='var-AS'><glossterm>AS</glossterm>
332 <info>
333 AS[doc] = "Minimal command and arguments to run the assembler."
334 </info>
335 <glossdef>
336 <para role="glossdeffirst">
337<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop79641f22019-09-10 07:20:22 -0400338 Minimal command and arguments needed to run the
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500339 assembler.
340 </para>
341 </glossdef>
342 </glossentry>
343
344 <glossentry id='var-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm>
345 <info>
346 ASSUME_PROVIDED[doc] = "Lists recipe names (PN values) BitBake does not attempt to build."
347 </info>
348 <glossdef>
349 <para role="glossdeffirst">
350<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
351 Lists recipe names
352 (<link linkend='var-PN'><filename>PN</filename></link>
353 values) BitBake does not attempt to build.
354 Instead, BitBake assumes these recipes have already been
355 built.
356 </para>
357
358 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400359 In OpenEmbedded-Core, <filename>ASSUME_PROVIDED</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500360 mostly specifies native tools that should not be built.
361 An example is <filename>git-native</filename>, which when
362 specified, allows for the Git binary from the host to be
363 used rather than building <filename>git-native</filename>.
364 </para>
365 </glossdef>
366 </glossentry>
367
368 <glossentry id='var-ASSUME_SHLIBS'><glossterm>ASSUME_SHLIBS</glossterm>
369 <info>
Andrew Geissler82c905d2020-04-13 13:39:40 -0500370 ASSUME_SHLIBS[doc] = "Provides additional shlibs provider mapping information, which adds to or overwrites the information provided automatically by the system."
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500371 </info>
372 <glossdef>
373 <para role="glossdeffirst">
374<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
375 Provides additional <filename>shlibs</filename> provider
376 mapping information, which adds to or overwrites the
377 information provided automatically by the system.
378 Separate multiple entries using spaces.
379 </para>
380
381 <para>
382 As an example, use the following form to add an
383 <filename>shlib</filename> provider of
384 <replaceable>shlibname</replaceable> in
385 <replaceable>packagename</replaceable> with the optional
386 <replaceable>version</replaceable>:
387 <literallayout class='monospaced'>
388 <replaceable>shlibname:packagename</replaceable>[_<replaceable>version</replaceable>]
389 </literallayout>
390 </para>
391
392 <para>
393 Here is an example that adds a shared library named
394 <filename>libEGL.so.1</filename> as being provided by
395 the <filename>libegl-implementation</filename> package:
396 <literallayout class='monospaced'>
397 ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"
398 </literallayout>
399 </para>
400 </glossdef>
401 </glossentry>
402
403 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
404 <info>
405 AUTHOR[doc] = "Email address used to contact the original author or authors in order to send patches and forward bugs."
406 </info>
407 <glossdef>
408 <para role="glossdeffirst">
409<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
410 The email address used to contact the original author
411 or authors in order to send patches and forward bugs.
412 </para>
413 </glossdef>
414 </glossentry>
415
416 <glossentry id='var-AUTO_LIBNAME_PKGS'><glossterm>AUTO_LIBNAME_PKGS</glossterm>
417 <info>
418 AUTO_LIBNAME_PKGS[doc] = "Specifies which packages should be checked for libraries and renamed according to Debian library package naming."
419 </info>
420 <glossdef>
421 <para role="glossdeffirst">
422<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
423 When the
424 <link linkend='ref-classes-debian'><filename>debian</filename></link>
425 class is inherited, which is the default behavior,
426 <filename>AUTO_LIBNAME_PKGS</filename> specifies which
427 packages should be checked for libraries and renamed
428 according to Debian library package naming.
429 </para>
430
431 <para>
432 The default value is "${PACKAGES}", which causes the
433 debian class to act on all packages that are
434 explicitly generated by the recipe.
435 </para>
436 </glossdef>
437 </glossentry>
438
439 <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm>AUTO_SYSLINUXMENU</glossterm>
440 <info>
441 AUTO_SYSLINUXMENU[doc] = "Enables creating an automatic menu for the syslinux bootloader."
442 </info>
443 <glossdef>
444 <para role="glossdeffirst">
445<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
446 Enables creating an automatic menu for the syslinux
447 bootloader.
448 You must set this variable in your recipe.
449 The
450 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
451 class checks this variable.
452 </para>
453 </glossdef>
454 </glossentry>
455
456 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
457 <info>
458 AUTOREV[doc] = "When SRCREV is set to the value of this variable, it specifies to use the latest source revision in the repository."
459 </info>
460 <glossdef>
461 <para role="glossdeffirst">
462<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
463 When
464 <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
465 is set to the value of this variable, it specifies to use
466 the latest source revision in the repository.
467 Here is an example:
468 <literallayout class='monospaced'>
469 SRCREV = "${AUTOREV}"
470 </literallayout>
471 </para>
472
473 <para>
474 If you use the previous statement to retrieve the latest
475 version of software, you need to be sure
476 <link linkend='var-PV'><filename>PV</filename></link>
477 contains
478 <filename>${</filename><link linkend='var-SRCPV'><filename>SRCPV</filename></link><filename>}</filename>.
479 For example, suppose you have a kernel recipe that
480 inherits the
481 <link linkend='ref-classes-kernel'>kernel</link> class
482 and you use the previous statement.
483 In this example, <filename>${SRCPV}</filename> does not
484 automatically get into <filename>PV</filename>.
485 Consequently, you need to change <filename>PV</filename>
486 in your recipe so that it does contain
487 <filename>${SRCPV}</filename>.
488 </para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500489
490 <para>
491 For more information see the
492 "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500493 section in the Yocto Project Development Tasks Manual.
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500494 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500495 </glossdef>
496 </glossentry>
497
Andrew Geissler82c905d2020-04-13 13:39:40 -0500498 <glossentry id='var-AVAILABLE_LICENSES'><glossterm>AVAILABLE_LICENSES</glossterm>
499 <info>
500 AVAILABLE_LICENSES[doc] = "List of licenses found in the directories specified by COMMON_LICENSE_DIR and LICENSE_PATH."
501 </info>
502 <glossdef>
503 <para role="glossdeffirst">
504<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
505
506 List of licenses found in the directories specified
507 by <link linkend='var-COMMON_LICENSE_DIR'><filename>COMMON_LICENSE_DIR</filename></link>
508 and <link linkend='var-LICENSE_PATH'><filename>LICENSE_PATH</filename></link>.
509
510 <note>
511 It is assumed that all changes
512 to <filename>COMMON_LICENSE_DIR</filename>
513 and <filename>LICENSE_PATH</filename> have been done
514 before <filename>AVAILABLE_LICENSES</filename> is
515 defined
516 (in <link linkend='ref-classes-license'>license.bbclass</link>).
517 </note>
518 </para>
519 </glossdef>
520 </glossentry>
521
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500522 <glossentry id='var-AVAILTUNES'><glossterm>AVAILTUNES</glossterm>
523 <info>
524 AVAILTUNES[doc] = "The list of defined CPU and Application Binary Interface (ABI) tunings (i.e. "tunes") available for use by the OpenEmbedded build system."
525 </info>
526 <glossdef>
527 <para role="glossdeffirst">
528<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
529 The list of defined CPU and Application Binary Interface
530 (ABI) tunings (i.e. "tunes") available for use by the
531 OpenEmbedded build system.
532 </para>
533
534 <para>
535 The list simply presents the tunes that are available.
536 Not all tunes may be compatible with a particular
537 machine configuration, or with each other in a
538 <ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Multilib</ulink>
539 configuration.
540 </para>
541
542 <para>
543 To add a tune to the list, be sure to append it with
544 spaces using the "+=" BitBake operator.
545 Do not simply replace the list by using the "=" operator.
546 See the
547 "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>"
548 section in the BitBake User Manual for more information.
549 </para>
550 </glossdef>
551 </glossentry>
552
553 </glossdiv>
554
555 <glossdiv id='var-glossary-b'><title>B</title>
556
557 <glossentry id='var-B'><glossterm>B</glossterm>
558 <info>
559 B[doc] = "The Build Directory. The OpenEmbedded build system places generated objects into the Build Directory during a recipe's build process."
560 </info>
561 <glossdef>
562 <para role="glossdeffirst">
563<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
564 The directory within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500565 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500566 in which the OpenEmbedded build system places generated
567 objects during a recipe's build process.
568 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
569 directory, which is defined as:
570 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600571 S = "${WORKDIR}/${BP}"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500572 </literallayout>
573 </para>
574
575 <para>
576 You can separate the (<filename>S</filename>) directory
577 and the directory pointed to by the <filename>B</filename>
578 variable.
579 Most Autotools-based recipes support separating these
580 directories.
581 The build system defaults to using separate directories for
582 <filename>gcc</filename> and some kernel recipes.
583 </para>
584 </glossdef>
585 </glossentry>
586
587 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
588 <info>
589 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."
590 </info>
591 <glossdef>
592 <para role="glossdeffirst">
593<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
594 Lists "recommended-only" packages to not install.
595 Recommended-only packages are packages installed only
596 through the
597 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
598 variable.
599 You can prevent any of these "recommended" packages from
600 being installed by listing them with the
601 <filename>BAD_RECOMMENDATIONS</filename> variable:
602 <literallayout class='monospaced'>
603 BAD_RECOMMENDATIONS = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."
604 </literallayout>
605 </para>
606
607 <para>
608 You can set this variable globally in your
609 <filename>local.conf</filename> file or you can attach it to
610 a specific image recipe by using the recipe name override:
611 <literallayout class='monospaced'>
612 BAD_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"
613 </literallayout>
614 </para>
615
616 <para>
617 It is important to realize that if you choose to not install
618 packages using this variable and some other packages are
619 dependent on them (i.e. listed in a recipe's
620 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
621 variable), the OpenEmbedded build system ignores your
622 request and will install the packages to avoid dependency
623 errors.
624 </para>
625
626 <para>
627 Support for this variable exists only when using the
628 IPK and RPM packaging backend.
629 Support does not exist for DEB.
630 </para>
631
632 <para>
633 See the
634 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
635 and the
636 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
637 variables for related information.
638 </para>
639 </glossdef>
640 </glossentry>
641
642 <glossentry id='var-BASE_LIB'><glossterm>BASE_LIB</glossterm>
643 <info>
644 BASE_LIB[doc] = "The library directory name for the CPU or Application Binary Interface (ABI) tune."
645 </info>
646 <glossdef>
647 <para role="glossdeffirst">
648<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
649 The library directory name for the CPU or Application
650 Binary Interface (ABI) tune.
651 The <filename>BASE_LIB</filename> applies only in the
652 Multilib context.
653 See the
654 "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500655 section in the Yocto Project Development Tasks Manual for
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500656 information on Multilib.
657 </para>
658
659 <para>
660 The <filename>BASE_LIB</filename> variable is defined in
661 the machine include files in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500662 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500663 If Multilib is not being used, the value defaults to "lib".
664 </para>
665 </glossdef>
666 </glossentry>
667
668 <glossentry id='var-BASE_WORKDIR'><glossterm>BASE_WORKDIR</glossterm>
669 <info>
670 BASE_WORKDIR[doc] = "Points to the base of the work directory for all recipes."
671 </info>
672 <glossdef>
673 <para role="glossdeffirst">
674<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
675 Points to the base of the work directory for all recipes.
676 The default value is "${TMPDIR}/work".
677 </para>
678 </glossdef>
679 </glossentry>
680
681 <glossentry id='var-BB_ALLOWED_NETWORKS'><glossterm>BB_ALLOWED_NETWORKS</glossterm>
682 <info>
683 BB_ALLOWED_NETWORKS[doc] = "A list of hosts that the fetcher is allowed to use to obtain the required source code."
684 </info>
685 <glossdef>
686 <para>
687 Specifies a space-delimited list of hosts that the fetcher
688 is allowed to use to obtain the required source code.
689 Following are considerations surrounding this variable:
690 <itemizedlist>
691 <listitem><para>
692 This host list is only used if
693 <filename>BB_NO_NETWORK</filename> is either not
694 set or set to "0".
695 </para></listitem>
696 <listitem><para>
697 Limited support for wildcard matching against the
698 beginning of host names exists.
699 For example, the following setting matches
700 <filename>git.gnu.org</filename>,
701 <filename>ftp.gnu.org</filename>, and
702 <filename>foo.git.gnu.org</filename>.
703 <literallayout class='monospaced'>
704 BB_ALLOWED_NETWORKS = "*.gnu.org"
705 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800706 <note><title>Important</title>
707 <para>The use of the "<filename>*</filename>"
708 character only works at the beginning of
709 a host name and it must be isolated from
710 the remainder of the host name.
711 You cannot use the wildcard character in any
712 other location of the name or combined with
713 the front part of the name.</para>
714
715 <para>For example,
716 <filename>*.foo.bar</filename> is supported,
717 while <filename>*aa.foo.bar</filename> is not.
718 </para>
719 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500720 </para></listitem>
721 <listitem><para>
722 Mirrors not in the host list are skipped and
723 logged in debug.
724 </para></listitem>
725 <listitem><para>
726 Attempts to access networks not in the host list
727 cause a failure.
728 </para></listitem>
729 </itemizedlist>
730 Using <filename>BB_ALLOWED_NETWORKS</filename> in
731 conjunction with
732 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
733 is very useful.
734 Adding the host you want to use to
735 <filename>PREMIRRORS</filename> results in the source code
736 being fetched from an allowed location and avoids raising
737 an error when a host that is not allowed is in a
738 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
739 statement.
740 This is because the fetcher does not attempt to use the
741 host listed in <filename>SRC_URI</filename> after a
742 successful fetch from the
743 <filename>PREMIRRORS</filename> occurs.
744 </para>
745 </glossdef>
746 </glossentry>
747
748 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
749 <info>
750 BB_DANGLINGAPPENDS_WARNONLY[doc] = "Defines how BitBake handles situations where an append file (.bbappend) has no corresponding recipe file (.bb)."
751 </info>
752 <glossdef>
753 <para role="glossdeffirst">
754<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
755 Defines how BitBake handles situations where an append
756 file (<filename>.bbappend</filename>) has no
757 corresponding recipe file (<filename>.bb</filename>).
758 This condition often occurs when layers get out of sync
759 (e.g. <filename>oe-core</filename> bumps a
760 recipe version and the old recipe no longer exists and the
761 other layer has not been updated to the new version
762 of the recipe yet).
763 </para>
764
765 <para>
766 The default fatal behavior is safest because it is
767 the sane reaction given something is out of sync.
768 It is important to realize when your changes are no longer
769 being applied.
770 </para>
771
772 <para>
773 You can change the default behavior by setting this
774 variable to "1", "yes", or "true"
775 in your <filename>local.conf</filename> file, which is
776 located in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500777 <link linkend='build-directory'>Build Directory</link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500778 Here is an example:
779 <literallayout class='monospaced'>
780 BB_DANGLINGAPPENDS_WARNONLY = "1"
781 </literallayout>
782 </para>
783 </glossdef>
784 </glossentry>
785
786 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
787 <info>
788 BB_DISKMON_DIRS[doc] = "Monitors disk space and available inodes during the build and allows you to control the build based on these parameters."
789 </info>
790 <glossdef>
791 <para role="glossdeffirst">
792<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
793 Monitors disk space and available inodes during the build
794 and allows you to control the build based on these
795 parameters.
796 </para>
797
798 <para>
799 Disk space monitoring is disabled by default.
800 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
801 variable to your <filename>conf/local.conf</filename> file found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500802 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500803 Use the following form:
804 <literallayout class='monospaced'>
805 BB_DISKMON_DIRS = "<replaceable>action</replaceable>,<replaceable>dir</replaceable>,<replaceable>threshold</replaceable> [...]"
806
807 where:
808
809 <replaceable>action</replaceable> is:
810 ABORT: Immediately abort the build when
811 a threshold is broken.
812 STOPTASKS: Stop the build after the currently
813 executing tasks have finished when
814 a threshold is broken.
815 WARN: Issue a warning but continue the
816 build when a threshold is broken.
817 Subsequent warnings are issued as
Brad Bishop316dfdd2018-06-25 12:45:53 -0400818 defined by the BB_DISKMON_WARNINTERVAL
819 variable, which must be defined in
820 the conf/local.conf file.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500821
822 <replaceable>dir</replaceable> is:
823 Any directory you choose. You can specify one or
824 more directories to monitor by separating the
825 groupings with a space. If two directories are
826 on the same device, only the first directory
827 is monitored.
828
829 <replaceable>threshold</replaceable> is:
830 Either the minimum available disk space,
831 the minimum number of free inodes, or
832 both. You must specify at least one. To
833 omit one or the other, simply omit the value.
834 Specify the threshold using G, M, K for Gbytes,
835 Mbytes, and Kbytes, respectively. If you do
836 not specify G, M, or K, Kbytes is assumed by
837 default. Do not use GB, MB, or KB.
838 </literallayout>
839 </para>
840
841 <para>
842 Here are some examples:
843 <literallayout class='monospaced'>
844 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
845 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
846 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
847 </literallayout>
848 The first example works only if you also provide
849 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
850 in the <filename>conf/local.conf</filename>.
851 This example causes the build system to immediately
852 abort when either the disk space in <filename>${TMPDIR}</filename> drops
853 below 1 Gbyte or the available free inodes drops below
854 100 Kbytes.
855 Because two directories are provided with the variable, the
856 build system also issue a
857 warning when the disk space in the
858 <filename>${SSTATE_DIR}</filename> directory drops
859 below 1 Gbyte or the number of free inodes drops
860 below 100 Kbytes.
861 Subsequent warnings are issued during intervals as
862 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
863 variable.
864 </para>
865
866 <para>
867 The second example stops the build after all currently
868 executing tasks complete when the minimum disk space
869 in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
870 directory drops below 1 Gbyte.
871 No disk monitoring occurs for the free inodes in this case.
872 </para>
873
874 <para>
875 The final example immediately aborts the build when the
876 number of free inodes in the <filename>${TMPDIR}</filename> directory
877 drops below 100 Kbytes.
878 No disk space monitoring for the directory itself occurs
879 in this case.
880 </para>
881 </glossdef>
882 </glossentry>
883
884 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
885 <info>
886 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."
887 </info>
888 <glossdef>
889 <para role="glossdeffirst">
890<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
891 Defines the disk space and free inode warning intervals.
892 To set these intervals, define the variable in your
893 <filename>conf/local.conf</filename> file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500894 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500895 </para>
896
897 <para>
898 If you are going to use the
899 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
900 also use the
901 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
902 and define its action as "WARN".
903 During the build, subsequent warnings are issued each time
904 disk space or number of free inodes further reduces by
905 the respective interval.
906 </para>
907
908 <para>
909 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
910 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
911 the "WARN" action, the disk monitoring interval defaults to
912 the following:
913 <literallayout class='monospaced'>
914 BB_DISKMON_WARNINTERVAL = "50M,5K"
915 </literallayout>
916 </para>
917
918 <para>
919 When specifying the variable in your configuration file,
920 use the following form:
921 <literallayout class='monospaced'>
922 BB_DISKMON_WARNINTERVAL = "<replaceable>disk_space_interval</replaceable>,<replaceable>disk_inode_interval</replaceable>"
923
924 where:
925
926 <replaceable>disk_space_interval</replaceable> is:
927 An interval of memory expressed in either
928 G, M, or K for Gbytes, Mbytes, or Kbytes,
929 respectively. You cannot use GB, MB, or KB.
930
931 <replaceable>disk_inode_interval</replaceable> is:
932 An interval of free inodes expressed in either
933 G, M, or K for Gbytes, Mbytes, or Kbytes,
934 respectively. You cannot use GB, MB, or KB.
935 </literallayout>
936 </para>
937
938 <para>
939 Here is an example:
940 <literallayout class='monospaced'>
941 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
942 BB_DISKMON_WARNINTERVAL = "50M,5K"
943 </literallayout>
944 These variables cause the OpenEmbedded build system to
945 issue subsequent warnings each time the available
946 disk space further reduces by 50 Mbytes or the number
947 of free inodes further reduces by 5 Kbytes in the
948 <filename>${SSTATE_DIR}</filename> directory.
949 Subsequent warnings based on the interval occur each time
950 a respective interval is reached beyond the initial warning
951 (i.e. 1 Gbytes and 100 Kbytes).
952 </para>
953 </glossdef>
954 </glossentry>
955
956 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
957 <info>
Brad Bishopd89cb5f2019-04-10 09:02:41 -0400958 BB_GENERATE_MIRROR_TARBALLS[doc] = "Causes tarballs of the source control repositories to be placed in the DL_DIR directory."
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500959 </info>
960 <glossdef>
961 <para role="glossdeffirst">
962<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd89cb5f2019-04-10 09:02:41 -0400963 Causes tarballs of the source control repositories
964 (e.g. Git repositories), including metadata, to be placed
965 in the
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500966 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
967 directory.
968 </para>
969
970 <para>
971 For performance reasons, creating and placing tarballs of
Brad Bishopd89cb5f2019-04-10 09:02:41 -0400972 these repositories is not the default action by the
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500973 OpenEmbedded build system.
974 <literallayout class='monospaced'>
975 BB_GENERATE_MIRROR_TARBALLS = "1"
976 </literallayout>
977 Set this variable in your <filename>local.conf</filename>
978 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500979 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500980 </para>
Brad Bishopd89cb5f2019-04-10 09:02:41 -0400981
982 <para>
983 Once you have the tarballs containing your source files,
984 you can clean up your <filename>DL_DIR</filename>
985 directory by deleting any Git or other source control
986 work directories.
987 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500988 </glossdef>
989 </glossentry>
990
991 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
992 <info>
993 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."
994 </info>
995 <glossdef>
996 <para role="glossdeffirst">
997<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
998 The maximum number of tasks BitBake should run in parallel
999 at any one time.
1000 The OpenEmbedded build system automatically configures
1001 this variable to be equal to the number of cores on the
1002 build system.
1003 For example, a system with a dual core processor that
1004 also uses hyper-threading causes the
1005 <filename>BB_NUMBER_THREADS</filename> variable to default
1006 to "4".
1007 </para>
1008
1009 <para>
1010 For single socket systems (i.e. one CPU), you should not
1011 have to override this variable to gain optimal parallelism
1012 during builds.
1013 However, if you have very large systems that employ
1014 multiple physical CPUs, you might want to make sure the
1015 <filename>BB_NUMBER_THREADS</filename> variable is not
1016 set higher than "20".
1017 </para>
1018
1019 <para>
1020 For more information on speeding up builds, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04001021 "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"
1022 section in the Yocto Project Development Tasks Manual.
1023 </para>
1024 </glossdef>
1025 </glossentry>
1026
1027 <glossentry id='var-BB_SERVER_TIMEOUT'><glossterm>BB_SERVER_TIMEOUT</glossterm>
1028 <info>
1029 BB_SERVER_TIMEOUT [doc] = "Specifies the time (in seconds) after which to unload the BitBake server due to inactivity."
1030 </info>
1031 <glossdef>
1032 <para role="glossdeffirst">
1033<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1034 Specifies the time (in seconds) after which to unload the
1035 BitBake server due to inactivity.
1036 Set <filename>BB_SERVER_TIMEOUT</filename> to determine how
1037 long the BitBake server stays resident between invocations.
1038 </para>
1039
1040 <para>
1041 For example, the following statement in your
1042 <filename>local.conf</filename> file instructs the server
1043 to be unloaded after 20 seconds of inactivity:
1044 <literallayout class='monospaced'>
1045 BB_SERVER_TIMEOUT = "20"
1046 </literallayout>
1047 If you want the server to never be unloaded, set
1048 <filename>BB_SERVER_TIMEOUT</filename> to "-1".
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001049 </para>
1050 </glossdef>
1051 </glossentry>
1052
1053 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
1054 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001055 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001056 </info>
1057 <glossdef>
1058 <para role="glossdeffirst">
1059<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1060 Allows you to extend a recipe so that it builds variants of the software.
1061 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
1062 which is a copy of Quilt built to run on the build system;
1063 "crosses" such as <filename>gcc-cross</filename>,
1064 which is a compiler built to run on the build machine but produces binaries
1065 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
1066 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
1067 and "mulitlibs" in the form "<filename>multilib:</filename><replaceable>multilib_name</replaceable>".
1068 </para>
1069
1070 <para>
1071 To build a different variant of the recipe with a minimal amount of code, it usually
1072 is as simple as adding the following to your recipe:
1073 <literallayout class='monospaced'>
1074 BBCLASSEXTEND =+ "native nativesdk"
1075 BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>"
1076 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001077 <note>
1078 <para>
1079 Internally, the <filename>BBCLASSEXTEND</filename>
1080 mechanism generates recipe variants by rewriting
1081 variable values and applying overrides such as
1082 <filename>_class-native</filename>.
1083 For example, to generate a native version of a recipe,
1084 a
1085 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1086 on "foo" is rewritten to a <filename>DEPENDS</filename>
1087 on "foo-native".
1088 </para>
1089
1090 <para>
1091 Even when using <filename>BBCLASSEXTEND</filename>, the
1092 recipe is only parsed once.
1093 Parsing once adds some limitations.
1094 For example, it is not possible to
1095 include a different file depending on the variant,
1096 since <filename>include</filename> statements are
1097 processed when the recipe is parsed.
1098 </para>
1099 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001100 </para>
1101 </glossdef>
1102 </glossentry>
1103
1104 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
1105 <info>
1106 BBFILE_COLLECTIONS[doc] = "Lists the names of configured layers. These names are used to find the other BBFILE_* variables."
1107 </info>
1108 <glossdef>
1109 <para role="glossdeffirst">
1110<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1111 Lists the names of configured layers.
1112 These names are used to find the other <filename>BBFILE_*</filename>
1113 variables.
1114 Typically, each layer will append its name to this variable in its
1115 <filename>conf/layer.conf</filename> file.
1116 </para>
1117 </glossdef>
1118 </glossentry>
1119
1120 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
1121 <info>
1122 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."
1123 </info>
1124 <glossdef>
1125 <para role="glossdeffirst">
1126<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1127 Variable that expands to match files from
1128 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
1129 in a particular layer.
1130 This variable is used in the <filename>conf/layer.conf</filename> file and must
1131 be suffixed with the name of the specific layer (e.g.
1132 <filename>BBFILE_PATTERN_emenlow</filename>).
1133 </para>
1134 </glossdef>
1135 </glossentry>
1136
1137 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
1138 <info>
1139 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."
1140 </info>
1141 <glossdef>
1142 <para role="glossdeffirst">
1143<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1144 Assigns the priority for recipe files in each layer.
1145 </para>
1146
1147 <para>
1148 This variable is useful in situations where the same recipe appears in
1149 more than one layer.
1150 Setting this variable allows you to prioritize a
1151 layer against other layers that contain the same recipe - effectively
1152 letting you control the precedence for the multiple layers.
1153 The precedence established through this variable stands regardless of a
1154 recipe's version
1155 (<link linkend='var-PV'><filename>PV</filename></link> variable).
1156 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
1157 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
1158 lower precedence.
1159 </para>
1160
1161 <para>
1162 A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
1163 precedence.
1164 For example, the value 6 has a higher precedence than the value 5.
1165 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
1166 dependencies (see the
1167 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
1168 more information.
1169 The default priority, if unspecified
1170 for a layer with no dependencies, is the lowest defined priority + 1
1171 (or 1 if no priorities are defined).
1172 </para>
1173 <tip>
1174 You can use the command <filename>bitbake-layers show-layers</filename> to list
1175 all configured layers along with their priorities.
1176 </tip>
1177 </glossdef>
1178 </glossentry>
1179
1180 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
1181 <info>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001182 BBFILES[doc] = "A space-separated list of recipe files BitBake uses to build software."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001183 </info>
1184 <glossdef>
1185 <para role="glossdeffirst">
1186<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001187 A space-separated list of recipe files BitBake uses to
1188 build software.
1189 </para>
1190
1191 <para>
1192 When specifying recipe files, you can pattern match using
1193 Python's
1194 <ulink url='https://docs.python.org/3/library/glob.html'><filename>glob</filename></ulink>
1195 syntax.
1196 For details on the syntax, see the documentation by
1197 following the previous link.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001198 </para>
1199 </glossdef>
1200 </glossentry>
1201
Brad Bishop316dfdd2018-06-25 12:45:53 -04001202 <glossentry id='var-BBFILES_DYNAMIC'><glossterm>BBFILES_DYNAMIC</glossterm>
1203 <info>
1204 BBFILES_DYNAMIC[doc] = "Activates content when identified layers are present."
1205 </info>
1206 <glossdef>
1207 <para role="glossdeffirst">
1208<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1209 Activates content when identified layers are present.
1210 You identify the layers by the collections that the layers
1211 define.
1212 </para>
1213
1214 <para>
1215 Use the <filename>BBFILES_DYNAMIC</filename> variable to
1216 avoid <filename>.bbappend</filename> files whose
1217 corresponding <filename>.bb</filename> file is in a layer
1218 that attempts to modify other layers through
1219 <filename>.bbappend</filename> but does not want to
1220 introduce a hard dependency on those other layers.
1221 </para>
1222
1223 <para>
1224 Use the following form for
1225 <filename>BBFILES_DYNAMIC</filename>:
1226 <literallayout class='monospaced'>
1227 <replaceable>collection_name</replaceable>:<replaceable>filename_pattern</replaceable>
1228 </literallayout>
1229 The following example identifies two collection names and
1230 two filename patterns:
1231 <literallayout class='monospaced'>
1232 BBFILES_DYNAMIC += " \
1233 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
1234 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
1235 "
1236 </literallayout>
1237 This next example shows an error message that occurs
1238 because invalid entries are found, which cause parsing to
1239 abort:
1240 <literallayout class='monospaced'>
1241 ERROR: BBFILES_DYNAMIC entries must be of the form &lt;collection name&gt;:&lt;filename pattern&gt;, not:
1242 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
1243 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
1244 </literallayout>
1245 </para>
1246 </glossdef>
1247 </glossentry>
1248
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001249 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
1250 <info>
1251 BBINCLUDELOGS[doc] = "Variable that controls how BitBake displays logs on build failure."
1252 </info>
1253 <glossdef>
1254 <para role="glossdeffirst">
1255<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1256 Variable that controls how BitBake displays logs on build failure.
1257 </para>
1258 </glossdef>
1259 </glossentry>
1260
1261 <glossentry id='var-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm>
1262 <info>
1263 BBINCLUDELOGS_LINES[doc] = "Amount of log lines printed on failure."
1264 </info>
1265 <glossdef>
1266 <para role="glossdeffirst">
1267<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1268 If
1269 <link linkend='var-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link>
1270 is set, specifies the maximum number of lines from the
1271 task log file to print when reporting a failed task.
1272 If you do not set <filename>BBINCLUDELOGS_LINES</filename>,
1273 the entire log is printed.
1274 </para>
1275 </glossdef>
1276 </glossentry>
1277
1278 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
1279 <info>
1280 BBLAYERS[doc] = "Lists the layers to enable during the build. This variable is defined in the bblayers.conf configuration file."
1281 </info>
1282 <glossdef>
1283 <para role="glossdeffirst">
1284<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1285 Lists the layers to enable during the build.
1286 This variable is defined in the <filename>bblayers.conf</filename> configuration
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001287 file in the
1288 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001289 Here is an example:
1290 <literallayout class='monospaced'>
1291 BBLAYERS = " \
1292 /home/scottrif/poky/meta \
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001293 /home/scottrif/poky/meta-poky \
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001294 /home/scottrif/poky/meta-yocto-bsp \
1295 /home/scottrif/poky/meta-mykernel \
1296 "
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001297 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001298 </para>
1299
1300 <para>
1301 This example enables four layers, one of which is a custom, user-defined layer
1302 named <filename>meta-mykernel</filename>.
1303 </para>
1304 </glossdef>
1305 </glossentry>
1306
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001307 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
1308 <info>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001309 BBMASK[doc] = "Prevents BitBake from processing specific recipes or recipe append files."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001310 </info>
1311 <glossdef>
1312 <para role="glossdeffirst">
1313<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1314 Prevents BitBake from processing recipes and recipe
1315 append files.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001316 </para>
1317
1318 <para>
1319 You can use the <filename>BBMASK</filename> variable
1320 to "hide" these <filename>.bb</filename> and
1321 <filename>.bbappend</filename> files.
1322 BitBake ignores any recipe or recipe append files that
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001323 match any of the expressions.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001324 It is as if BitBake does not see them at all.
1325 Consequently, matching files are not parsed or otherwise
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001326 used by BitBake.
1327 </para>
1328
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001329 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001330 The values you provide are passed to Python's regular
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001331 expression compiler.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001332 Consequently, the syntax follows Python's Regular
1333 Expression (re) syntax.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001334 The expressions are compared against the full paths to
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001335 the files.
1336 For complete syntax information, see Python's
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001337 documentation at
1338 <ulink url='http://docs.python.org/3/library/re.html#re'></ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001339 </para>
1340
1341 <para>
1342 The following example uses a complete regular expression
1343 to tell BitBake to ignore all recipe and recipe append
1344 files in the <filename>meta-ti/recipes-misc/</filename>
1345 directory:
1346 <literallayout class='monospaced'>
1347 BBMASK = "meta-ti/recipes-misc/"
1348 </literallayout>
1349 If you want to mask out multiple directories or recipes,
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001350 you can specify multiple regular expression fragments.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001351 This next example masks out multiple directories and
1352 individual recipes:
1353 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001354 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
1355 BBMASK += "/meta-oe/recipes-support/"
1356 BBMASK += "/meta-foo/.*/openldap"
1357 BBMASK += "opencv.*\.bbappend"
1358 BBMASK += "lzma"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001359 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001360 <note>
1361 When specifying a directory name, use the trailing
1362 slash character to ensure you match just that directory
1363 name.
1364 </note>
1365 </para>
1366 </glossdef>
1367 </glossentry>
1368
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001369 <glossentry id='var-BBMULTICONFIG'><glossterm>BBMULTICONFIG</glossterm>
1370 <info>
Brad Bishopf3f93bb2019-10-16 14:33:32 -04001371 BBMULTICONFIG[doc] = "Specifies each additional separate configuration when you are building targets with multiple configurations."
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001372 </info>
1373 <glossdef>
1374 <para role="glossdeffirst">
1375<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop64c979e2019-11-04 13:55:29 -05001376 Specifies each additional separate configuration when you
1377 are building targets with multiple configurations.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001378 Use this variable in your
1379 <filename>conf/local.conf</filename> configuration file.
1380 Specify a <replaceable>multiconfigname</replaceable> for
1381 each configuration file you are using.
1382 For example, the following line specifies three
1383 configuration files:
1384 <literallayout class='monospaced'>
Brad Bishop96ff1982019-08-19 13:50:42 -04001385 BBMULTICONFIG = "configA configB configC"
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001386 </literallayout>
1387 Each configuration file you use must reside in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001388 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001389 <filename>conf/multiconfig</filename> directory
1390 (e.g.
1391 <replaceable>build_directory</replaceable><filename>/conf/multiconfig/configA.conf</filename>).
1392 </para>
1393
1394 <para>
1395 For information on how to use
1396 <filename>BBMULTICONFIG</filename> in an environment that
1397 supports building targets with multiple configurations,
1398 see the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001399 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-images-for-multiple-targets-using-multiple-configurations'>Building Images for Multiple Targets Using Multiple Configurations</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001400 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001401 </para>
1402 </glossdef>
1403 </glossentry>
1404
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001405 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
1406 <info>
1407 BBPATH[doc] = "Used by BitBake to locate .bbclass and configuration files. This variable is analogous to the PATH variable."
1408 </info>
1409 <glossdef>
1410 <para role="glossdeffirst">
1411<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1412 Used by BitBake to locate
1413 <filename>.bbclass</filename> and configuration files.
1414 This variable is analogous to the
1415 <filename>PATH</filename> variable.
1416 <note>
1417 If you run BitBake from a directory outside of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001418 <link linkend='build-directory'>Build Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001419 you must be sure to set
1420 <filename>BBPATH</filename> to point to the
1421 Build Directory.
1422 Set the variable as you would any environment variable
1423 and then run BitBake:
1424 <literallayout class='monospaced'>
1425 $ BBPATH = "<replaceable>build_directory</replaceable>"
1426 $ export BBPATH
1427 $ bitbake <replaceable>target</replaceable>
1428 </literallayout>
1429 </note>
1430 </para>
1431 </glossdef>
1432 </glossentry>
1433
1434 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
1435 <info>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001436 BBSERVER[doc] = "Points to the BitBake remote server."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001437 </info>
1438 <glossdef>
1439 <para role="glossdeffirst">
1440<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001441 If defined in the BitBake environment,
1442 <filename>BBSERVER</filename> points to the BitBake
1443 remote server.
1444 </para>
1445
1446 <para>
1447 Use the following format to export the variable to the
1448 BitBake environment:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001449 <literallayout class='monospaced'>
Andrew Geissler82c905d2020-04-13 13:39:40 -05001450 export BBSERVER=localhost:$port
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001451 </literallayout>
1452 </para>
1453
1454 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001455 By default, <filename>BBSERVER</filename> also appears in
1456 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink>.
1457 Consequently, <filename>BBSERVER</filename> is excluded
1458 from checksum and dependency data.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001459 </para>
1460 </glossdef>
1461 </glossentry>
1462
1463 <glossentry id='var-BINCONFIG'><glossterm>BINCONFIG</glossterm>
1464 <info>
1465 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."
1466 </info>
1467 <glossdef>
1468 <para role="glossdeffirst">
1469<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1470 When inheriting the
1471 <link linkend='ref-classes-binconfig-disabled'><filename>binconfig-disabled</filename></link>
1472 class, this variable specifies binary configuration
1473 scripts to disable in favor of using
1474 <filename>pkg-config</filename> to query the information.
1475 The <filename>binconfig-disabled</filename> class will
1476 modify the specified scripts to return an error so that
1477 calls to them can be easily found and replaced.
1478 </para>
1479
1480 <para>
1481 To add multiple scripts, separate them by spaces.
1482 Here is an example from the <filename>libpng</filename>
1483 recipe:
1484 <literallayout class='monospaced'>
1485 BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"
1486 </literallayout>
1487 </para>
1488 </glossdef>
1489 </glossentry>
1490
1491 <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
1492 <info>
1493 BINCONFIG_GLOB[doc] = "When inheriting binconfig.bbclass from a recipe, this variable specifies a wildcard for configuration scripts that need editing."
1494 </info>
1495 <glossdef>
1496 <para role="glossdeffirst">
1497<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1498 When inheriting the
1499 <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
1500 class, this variable specifies a wildcard for
1501 configuration scripts that need editing.
1502 The scripts are edited to correct any paths that have been
1503 set up during compilation so that they are correct for
1504 use when installed into the sysroot and called by the
1505 build processes of other recipes.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001506 <note>
1507 The <filename>BINCONFIG_GLOB</filename> variable
1508 uses
1509 <ulink url='http://tldp.org/LDP/abs/html/globbingref.html'>shell globbing</ulink>,
1510 which is recognition and expansion of wildcards during
1511 pattern matching.
1512 Shell globbing is very similar to
1513 <ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>
1514 and
1515 <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>.
1516 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001517 </para>
1518
1519 <para>
1520 For more information on how this variable works, see
1521 <filename>meta/classes/binconfig.bbclass</filename> in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001522 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001523 You can also find general information on the class in the
1524 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
1525 section.
1526 </para>
1527 </glossdef>
1528 </glossentry>
1529
1530 <glossentry id='var-BP'><glossterm>BP</glossterm>
1531 <info>
1532 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}"
1533 </info>
1534 <glossdef>
1535 <para role="glossdeffirst">
1536<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1537 The base recipe name and version but without any special
1538 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
1539 and so forth).
1540 <filename>BP</filename> is comprised of the following:
1541 <literallayout class="monospaced">
1542 ${BPN}-${PV}
1543 </literallayout>
1544 </para>
1545 </glossdef>
1546 </glossentry>
1547
1548 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
1549 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001550 BPN[doc] = "This variable is a version of the PN variable but removes common suffixes and prefixes."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001551 </info>
1552 <glossdef>
1553 <para role="glossdeffirst">
1554<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001555 This variable is a version of the
1556 <link linkend='var-PN'><filename>PN</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001557 variable with common prefixes and suffixes
1558 removed, such as <filename>nativesdk-</filename>,
1559 <filename>-cross</filename>,
1560 <filename>-native</filename>, and multilib's
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001561 <filename>lib64-</filename> and
1562 <filename>lib32-</filename>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001563 The exact lists of prefixes and suffixes removed are
1564 specified by the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001565 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001566 and
1567 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link>
1568 variables, respectively.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001569 </para>
1570 </glossdef>
1571 </glossentry>
1572
1573 <glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm>
1574 <info>
1575 BUGTRACKER[doc] = "Specifies a URL for an upstream bug tracking website for a recipe."
1576 </info>
1577 <glossdef>
1578 <para role="glossdeffirst">
1579<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1580 Specifies a URL for an upstream bug tracking website for
1581 a recipe.
1582 The OpenEmbedded build system does not use this variable.
1583 Rather, the variable is a useful pointer in case a bug
1584 in the software being built needs to be manually reported.
1585 </para>
1586 </glossdef>
1587 </glossentry>
1588
1589 <glossentry id='var-BUILD_ARCH'><glossterm>BUILD_ARCH</glossterm>
1590 <info>
1591 BUILD_ARCH[doc] = "The name of the building architecture (e.g. i686)."
1592 </info>
1593 <glossdef>
1594 <para role="glossdeffirst">
1595<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1596 Specifies the architecture of the build host
1597 (e.g. <filename>i686</filename>).
1598 The OpenEmbedded build system sets the value of
1599 <filename>BUILD_ARCH</filename> from the machine name
1600 reported by the <filename>uname</filename> command.
1601 </para>
1602 </glossdef>
1603 </glossentry>
1604
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001605 <glossentry id='var-BUILD_AS_ARCH'><glossterm>BUILD_AS_ARCH</glossterm>
1606 <info>
1607 BUILD_AS_ARCH[doc] = "Specifies the architecture-specific assembler flags for the build host."
1608 </info>
1609 <glossdef>
1610 <para role="glossdeffirst">
1611<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1612 Specifies the architecture-specific assembler flags for
1613 the build host. By default, the value of
1614 <filename>BUILD_AS_ARCH</filename> is empty.
1615 </para>
1616 </glossdef>
1617 </glossentry>
1618
1619 <glossentry id='var-BUILD_CC_ARCH'><glossterm>BUILD_CC_ARCH</glossterm>
1620 <info>
1621 BUILD_CC_ARCH[doc] = "Specifies the architecture-specific C compiler flags for the build host."
1622 </info>
1623 <glossdef>
1624 <para role="glossdeffirst">
1625<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1626 Specifies the architecture-specific C compiler flags for
1627 the build host. By default, the value of
1628 <filename>BUILD_CC_ARCH</filename> is empty.
1629 </para>
1630 </glossdef>
1631 </glossentry>
1632
1633 <glossentry id='var-BUILD_CCLD'><glossterm>BUILD_CCLD</glossterm>
1634 <info>
1635 BUILD_CCLD[doc] = "Specifies the linker command to be used for the build host when the C compiler is being used as the linker."
1636 </info>
1637 <glossdef>
1638 <para role="glossdeffirst">
1639<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1640 Specifies the linker command to be used for the build host
1641 when the C compiler is being used as the linker. By default,
1642 <filename>BUILD_CCLD</filename> points to GCC and passes as
1643 arguments the value of
1644 <link linkend='var-BUILD_CC_ARCH'><filename>BUILD_CC_ARCH</filename></link>,
1645 assuming <filename>BUILD_CC_ARCH</filename> is set.
1646 </para>
1647 </glossdef>
1648 </glossentry>
1649
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001650 <glossentry id='var-BUILD_CFLAGS'><glossterm>BUILD_CFLAGS</glossterm>
1651 <info>
1652 BUILD_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the build host."
1653 </info>
1654 <glossdef>
1655 <para role="glossdeffirst">
1656<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1657 Specifies the flags to pass to the C compiler when building
1658 for the build host.
1659 When building in the <filename>-native</filename> context,
1660 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
1661 is set to the value of this variable by default.
1662 </para>
1663 </glossdef>
1664 </glossentry>
1665
1666 <glossentry id='var-BUILD_CPPFLAGS'><glossterm>BUILD_CPPFLAGS</glossterm>
1667 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001668 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001669 </info>
1670 <glossdef>
1671 <para role="glossdeffirst">
1672<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -04001673 Specifies the flags to pass to the C preprocessor
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001674 (i.e. to both the C and the C++ compilers) when building
1675 for the build host.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001676 When building in the <filename>-native</filename> context,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001677 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
1678 is set to the value of this variable by default.
1679 </para>
1680 </glossdef>
1681 </glossentry>
1682
1683 <glossentry id='var-BUILD_CXXFLAGS'><glossterm>BUILD_CXXFLAGS</glossterm>
1684 <info>
1685 BUILD_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the build host."
1686 </info>
1687 <glossdef>
1688 <para role="glossdeffirst">
1689<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1690 Specifies the flags to pass to the C++ compiler when
1691 building for the build host.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001692 When building in the <filename>-native</filename> context,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001693 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
1694 is set to the value of this variable by default.
1695 </para>
1696 </glossdef>
1697 </glossentry>
1698
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001699 <glossentry id='var-BUILD_FC'><glossterm>BUILD_FC</glossterm>
1700 <info>
1701 BUILD_FC[doc] = "Specifies the Fortran compiler command for the build host."
1702 </info>
1703 <glossdef>
1704 <para role="glossdeffirst">
1705<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1706 Specifies the Fortran compiler command for the build host.
1707 By default, <filename>BUILD_FC</filename> points to
1708 Gfortran and passes as arguments the value of
1709 <link linkend='var-BUILD_CC_ARCH'><filename>BUILD_CC_ARCH</filename></link>,
1710 assuming <filename>BUILD_CC_ARCH</filename> is set.
1711 </para>
1712 </glossdef>
1713 </glossentry>
1714
1715 <glossentry id='var-BUILD_LD'><glossterm>BUILD_LD</glossterm>
1716 <info>
1717 BUILD_LD[doc] = "Specifies the linker command for the build host."
1718 </info>
1719 <glossdef>
1720 <para role="glossdeffirst">
1721<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1722 Specifies the linker command for the build host. By default,
1723 <filename>BUILD_LD</filename> points to the GNU linker (ld)
1724 and passes as arguments the value of
1725 <link linkend='var-BUILD_LD_ARCH'><filename>BUILD_LD_ARCH</filename></link>,
1726 assuming <filename>BUILD_LD_ARCH</filename> is set.
1727 </para>
1728 </glossdef>
1729 </glossentry>
1730
1731 <glossentry id='var-BUILD_LD_ARCH'><glossterm>BUILD_LD_ARCH</glossterm>
1732 <info>
1733 BUILD_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the build."
1734 </info>
1735 <glossdef>
1736 <para role="glossdeffirst">
1737<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1738 Specifies architecture-specific linker flags for the build
1739 host. By default, the value of
1740 <filename>BUILD_LD_ARCH</filename> is empty.
1741 </para>
1742 </glossdef>
1743 </glossentry>
1744
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001745 <glossentry id='var-BUILD_LDFLAGS'><glossterm>BUILD_LDFLAGS</glossterm>
1746 <info>
1747 BUILD_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the build host."
1748 </info>
1749 <glossdef>
1750 <para role="glossdeffirst">
1751<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1752 Specifies the flags to pass to the linker when building
1753 for the build host.
1754 When building in the <filename>-native</filename> context,
1755 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
1756 is set to the value of this variable by default.
1757 </para>
1758 </glossdef>
1759 </glossentry>
1760
1761 <glossentry id='var-BUILD_OPTIMIZATION'><glossterm>BUILD_OPTIMIZATION</glossterm>
1762 <info>
1763 BUILD_OPTIMIZATION[doc] = "Specifies the optimization flags passed to the C compiler when building for the build host or the SDK."
1764 </info>
1765 <glossdef>
1766 <para role="glossdeffirst">
1767<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1768 Specifies the optimization flags passed to the C compiler
1769 when building for the build host or the SDK.
1770 The flags are passed through the
1771 <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
1772 and
1773 <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
1774 default values.
1775 </para>
1776
1777 <para>
1778 The default value of the
1779 <filename>BUILD_OPTIMIZATION</filename> variable is
1780 "-O2 -pipe".
1781 </para>
1782 </glossdef>
1783 </glossentry>
1784
1785 <glossentry id='var-BUILD_OS'><glossterm>BUILD_OS</glossterm>
1786 <info>
1787 BUILD_OS[doc] = "The operating system (in lower case) of the building architecture (e.g. Linux)."
1788 </info>
1789 <glossdef>
1790 <para role="glossdeffirst">
1791<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1792 Specifies the operating system in use on the build
1793 host (e.g. "linux").
1794 The OpenEmbedded build system sets the value of
1795 <filename>BUILD_OS</filename> from the OS reported by
1796 the <filename>uname</filename> command - the first word,
1797 converted to lower-case characters.
1798 </para>
1799 </glossdef>
1800 </glossentry>
1801
1802 <glossentry id='var-BUILD_PREFIX'><glossterm>BUILD_PREFIX</glossterm>
1803 <info>
1804 BUILD_PREFIX[doc] = "The toolchain binary prefix used for native recipes."
1805 </info>
1806 <glossdef>
1807 <para role="glossdeffirst">
1808<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1809 The toolchain binary prefix used for native recipes.
1810 The OpenEmbedded build system uses the
1811 <filename>BUILD_PREFIX</filename> value to set the
1812 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001813 when building for <filename>native</filename> recipes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001814 </para>
1815 </glossdef>
1816 </glossentry>
1817
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001818 <glossentry id='var-BUILD_STRIP'><glossterm>BUILD_STRIP</glossterm>
1819 <info>
1820 BUILD_STRIP[doc] = "Specifies the command to be used to strip debugging symbols from binaries produced for the build host."
1821 </info>
1822 <glossdef>
1823 <para role="glossdeffirst">
1824<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1825 Specifies the command to be used to strip debugging symbols
1826 from binaries produced for the build host. By default,
1827 <filename>BUILD_STRIP</filename> points to
1828 <filename>${</filename><link linkend='var-BUILD_PREFIX'><filename>BUILD_PREFIX</filename></link><filename>}strip</filename>.
1829 </para>
1830 </glossdef>
1831 </glossentry>
1832
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001833 <glossentry id='var-BUILD_SYS'><glossterm>BUILD_SYS</glossterm>
1834 <info>
1835 BUILD_SYS[doc] = "The toolchain binary prefix used for native recipes."
1836 </info>
1837 <glossdef>
1838 <para role="glossdeffirst">
1839<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1840 Specifies the system, including the architecture and
1841 the operating system, to use when building for the build
1842 host (i.e. when building <filename>native</filename>
1843 recipes).
1844 </para>
1845
1846 <para>
1847 The OpenEmbedded build system automatically sets this
1848 variable based on
1849 <link linkend='var-BUILD_ARCH'><filename>BUILD_ARCH</filename></link>,
1850 <link linkend='var-BUILD_VENDOR'><filename>BUILD_VENDOR</filename></link>,
1851 and
1852 <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>.
1853 You do not need to set the <filename>BUILD_SYS</filename>
1854 variable yourself.
1855 </para>
1856 </glossdef>
1857 </glossentry>
1858
1859 <glossentry id='var-BUILD_VENDOR'><glossterm>BUILD_VENDOR</glossterm>
1860 <info>
1861 BUILD_VENDOR[doc] = "The vendor name to use when building for the build host."
1862 </info>
1863 <glossdef>
1864 <para role="glossdeffirst">
1865<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1866 Specifies the vendor name to use when building for the
1867 build host.
1868 The default value is an empty string ("").
1869 </para>
1870 </glossdef>
1871 </glossentry>
1872
1873 <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
1874 <info>
1875 BUILDDIR[doc] = "Points to the location of the Build Directory."
1876 </info>
1877 <glossdef>
1878 <para role="glossdeffirst">
1879<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1880 Points to the location of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001881 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001882 You can define this directory indirectly through the
1883 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001884 script by passing in a Build Directory path when you run
1885 the script.
1886 If you run the script and do not provide a Build Directory
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001887 path, the <filename>BUILDDIR</filename> defaults to
1888 <filename>build</filename> in the current directory.
1889 </para>
1890 </glossdef>
1891 </glossentry>
1892
1893 <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>BUILDHISTORY_COMMIT</glossterm>
1894 <info>
1895 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."
1896 </info>
1897 <glossdef>
1898 <para role="glossdeffirst">
1899<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1900 When inheriting the
1901 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1902 class, this variable specifies whether or not to commit the
1903 build history output in a local Git repository.
1904 If set to "1", this local repository will be maintained
1905 automatically by the
1906 <filename>buildhistory</filename>
1907 class and a commit will be created on every
1908 build for changes to each top-level subdirectory of the
1909 build history output (images, packages, and sdk).
1910 If you want to track changes to build history over
1911 time, you should set this value to "1".
1912 </para>
1913
1914 <para>
1915 By default, the <filename>buildhistory</filename> class
1916 does not commit the build history output in a local
1917 Git repository:
1918 <literallayout class='monospaced'>
1919 BUILDHISTORY_COMMIT ?= "0"
1920 </literallayout>
1921 </para>
1922 </glossdef>
1923 </glossentry>
1924
1925 <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>BUILDHISTORY_COMMIT_AUTHOR</glossterm>
1926 <info>
1927 BUILDHISTORY_COMMIT_AUTHOR[doc] = "When inheriting the buildhistory class, this variable specifies the author to use for each Git commit."
1928 </info>
1929 <glossdef>
1930 <para role="glossdeffirst">
1931<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1932 When inheriting the
1933 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1934 class, this variable specifies the author to use for each
1935 Git commit.
1936 In order for the <filename>BUILDHISTORY_COMMIT_AUTHOR</filename>
1937 variable to work, the
1938 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
1939 variable must be set to "1".
1940 </para>
1941
1942 <para>
1943 Git requires that the value you provide for the
1944 <filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable
Brad Bishop316dfdd2018-06-25 12:45:53 -04001945 takes the form of "name <replaceable>email@host</replaceable>".
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001946 Providing an email address or host that is not valid does
1947 not produce an error.
1948 </para>
1949
1950 <para>
1951 By default, the <filename>buildhistory</filename> class
1952 sets the variable as follows:
1953 <literallayout class='monospaced'>
1954 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory &lt;buildhistory@${DISTRO}&gt;"
1955 </literallayout>
1956 </para>
1957 </glossdef>
1958 </glossentry>
1959
1960 <glossentry id='var-BUILDHISTORY_DIR'><glossterm>BUILDHISTORY_DIR</glossterm>
1961 <info>
1962 BUILDHISTORY_DIR[doc] = "When inheriting the buildhistory class, this variable specifies the directory in which build history information is kept."
1963 </info>
1964 <glossdef>
1965 <para role="glossdeffirst">
1966<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1967 When inheriting the
1968 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1969 class, this variable specifies the directory in which
1970 build history information is kept.
1971 For more information on how the variable works, see the
1972 <filename>buildhistory.class</filename>.
1973 </para>
1974
1975 <para>
1976 By default, the <filename>buildhistory</filename> class
1977 sets the directory as follows:
1978 <literallayout class='monospaced'>
1979 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
1980 </literallayout>
1981 </para>
1982 </glossdef>
1983 </glossentry>
1984
1985 <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>BUILDHISTORY_FEATURES</glossterm>
1986 <info>
1987 BUILDHISTORY_FEATURES[doc] = "When inheriting the buildhistory class, this variable specifies the build history features to be enabled."
1988 </info>
1989 <glossdef>
1990 <para role="glossdeffirst">
1991<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1992 When inheriting the
1993 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1994 class, this variable specifies the build history features
1995 to be enabled.
1996 For more information on how build history works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04001997 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
1998 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001999 </para>
2000
2001 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002002 You can specify these features in the form of a
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002003 space-separated list:
2004 <itemizedlist>
2005 <listitem><para><emphasis>image:</emphasis>
2006 Analysis of the contents of images, which
2007 includes the list of installed packages among other
2008 things.
2009 </para></listitem>
2010 <listitem><para><emphasis>package:</emphasis>
2011 Analysis of the contents of individual packages.
2012 </para></listitem>
2013 <listitem><para><emphasis>sdk:</emphasis>
2014 Analysis of the contents of the software
2015 development kit (SDK).
2016 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002017 <listitem><para><emphasis>task:</emphasis>
2018 Save output file signatures for
2019 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state</ulink>
2020 (sstate) tasks.
2021 This saves one file per task and lists the SHA-256
2022 checksums for each file staged (i.e. the output of
2023 the task).
2024 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002025 </itemizedlist>
2026 </para>
2027
2028 <para>
2029 By default, the <filename>buildhistory</filename> class
Brad Bishop316dfdd2018-06-25 12:45:53 -04002030 enables the following features:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002031 <literallayout class='monospaced'>
2032 BUILDHISTORY_FEATURES ?= "image package sdk"
2033 </literallayout>
2034 </para>
2035 </glossdef>
2036 </glossentry>
2037
2038 <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>BUILDHISTORY_IMAGE_FILES</glossterm>
2039 <info>
2040 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."
2041 </info>
2042 <glossdef>
2043 <para role="glossdeffirst">
2044<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2045 When inheriting the
2046 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
2047 class, this variable specifies a list of paths to files
2048 copied from the
2049 image contents into the build history directory under
2050 an "image-files" directory in the directory for
2051 the image, so that you can track the contents of each file.
2052 The default is to copy <filename>/etc/passwd</filename>
2053 and <filename>/etc/group</filename>, which allows you to
2054 monitor for changes in user and group entries.
2055 You can modify the list to include any file.
2056 Specifying an invalid path does not produce an error.
2057 Consequently, you can include files that might
2058 not always be present.
2059 </para>
2060
2061 <para>
2062 By default, the <filename>buildhistory</filename> class
2063 provides paths to the following files:
2064 <literallayout class='monospaced'>
2065 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
2066 </literallayout>
2067 </para>
2068 </glossdef>
2069 </glossentry>
2070
2071 <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>BUILDHISTORY_PUSH_REPO</glossterm>
2072 <info>
2073 BUILDHISTORY_PUSH_REPO[doc] = "When inheriting the buildhistory class, this variable optionally specifies a remote repository to which build history pushes Git changes."
2074 </info>
2075 <glossdef>
2076 <para role="glossdeffirst">
2077<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2078 When inheriting the
2079 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
2080 class, this variable optionally specifies a remote
2081 repository to which build history pushes Git changes.
2082 In order for <filename>BUILDHISTORY_PUSH_REPO</filename>
2083 to work,
2084 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
2085 must be set to "1".
2086 </para>
2087
2088 <para>
2089 The repository should correspond to a remote
2090 address that specifies a repository as understood by
2091 Git, or alternatively to a remote name that you have
2092 set up manually using <filename>git remote</filename>
2093 within the local repository.
2094 </para>
2095
2096 <para>
2097 By default, the <filename>buildhistory</filename> class
2098 sets the variable as follows:
2099 <literallayout class='monospaced'>
2100 BUILDHISTORY_PUSH_REPO ?= ""
2101 </literallayout>
2102 </para>
2103 </glossdef>
2104 </glossentry>
2105
2106 <glossentry id='var-BUILDSDK_CFLAGS'><glossterm>BUILDSDK_CFLAGS</glossterm>
2107 <info>
2108 BUILDSDK_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the SDK."
2109 </info>
2110 <glossdef>
2111 <para role="glossdeffirst">
2112<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2113 Specifies the flags to pass to the C compiler when building
2114 for the SDK.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002115 When building in the <filename>nativesdk-</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002116 context,
2117 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
2118 is set to the value of this variable by default.
2119 </para>
2120 </glossdef>
2121 </glossentry>
2122
2123 <glossentry id='var-BUILDSDK_CPPFLAGS'><glossterm>BUILDSDK_CPPFLAGS</glossterm>
2124 <info>
2125 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."
2126 </info>
2127 <glossdef>
2128 <para role="glossdeffirst">
2129<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2130 Specifies the flags to pass to the C pre-processor
2131 (i.e. to both the C and the C++ compilers) when building
2132 for the SDK.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002133 When building in the <filename>nativesdk-</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002134 context,
2135 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
2136 is set to the value of this variable by default.
2137 </para>
2138 </glossdef>
2139 </glossentry>
2140
2141 <glossentry id='var-BUILDSDK_CXXFLAGS'><glossterm>BUILDSDK_CXXFLAGS</glossterm>
2142 <info>
2143 BUILDSDK_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the SDK."
2144 </info>
2145 <glossdef>
2146 <para role="glossdeffirst">
2147<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2148 Specifies the flags to pass to the C++ compiler when
2149 building for the SDK.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002150 When building in the <filename>nativesdk-</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002151 context,
2152 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
2153 is set to the value of this variable by default.
2154 </para>
2155 </glossdef>
2156 </glossentry>
2157
2158 <glossentry id='var-BUILDSDK_LDFLAGS'><glossterm>BUILDSDK_LDFLAGS</glossterm>
2159 <info>
2160 BUILDSDK_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the SDK."
2161 </info>
2162 <glossdef>
2163 <para role="glossdeffirst">
2164<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2165 Specifies the flags to pass to the linker when building
2166 for the SDK.
2167 When building in the <filename>nativesdk-</filename>
2168 context,
2169 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
2170 is set to the value of this variable by default.
2171 </para>
2172 </glossdef>
2173 </glossentry>
2174
2175 <glossentry id='var-BUILDSTATS_BASE'><glossterm>BUILDSTATS_BASE</glossterm>
2176 <info>
2177 BUILDSTATS_BASE[doc] = "Points to the location of the directory that holds build statistics when you use and enable the buildstats class."
2178 </info>
2179 <glossdef>
2180 <para role="glossdeffirst">
2181<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2182 Points to the location of the directory that holds build
2183 statistics when you use and enable the
2184 <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link>
2185 class.
2186 The <filename>BUILDSTATS_BASE</filename> directory defaults
2187 to
2188 <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/buildstats/</filename>.
2189 </para>
2190 </glossdef>
2191 </glossentry>
2192
2193 <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
2194 <info>
2195 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."
2196 </info>
2197 <glossdef>
2198 <para role="glossdeffirst">
2199<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2200 For the BusyBox recipe, specifies whether to split the
2201 output executable file into two parts: one for features
2202 that require <filename>setuid root</filename>, and one for
2203 the remaining features (i.e. those that do not require
2204 <filename>setuid root</filename>).
2205 </para>
2206
2207 <para>
2208 The <filename>BUSYBOX_SPLIT_SUID</filename> variable
Brad Bishop64c979e2019-11-04 13:55:29 -05002209 defaults to "1", which results in splitting the output
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002210 executable file.
Brad Bishop64c979e2019-11-04 13:55:29 -05002211 Set the variable to "0" to get a single output executable
2212 file.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002213 </para>
2214 </glossdef>
2215 </glossentry>
2216
2217 </glossdiv>
2218
2219 <glossdiv id='var-glossary-c'><title>C</title>
2220
2221 <glossentry id='var-CACHE'><glossterm>CACHE</glossterm>
2222 <info>
2223 CACHE[doc] = "The directory BitBake uses to store a cache of the metadata."
2224 </info>
2225 <glossdef>
2226 <para role="glossdeffirst">
2227<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2228 Specifies the directory BitBake uses to store a cache
2229 of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002230 <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002231 so it does not need to be parsed every time BitBake is
2232 started.
2233 </para>
2234 </glossdef>
2235 </glossentry>
2236
2237 <glossentry id='var-CC'><glossterm>CC</glossterm>
2238 <info>
2239 CC[doc] = "Minimum command and arguments to run the C compiler."
2240 </info>
2241 <glossdef>
2242 <para role="glossdeffirst">
2243<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2244 The minimal command and arguments used to run the C
2245 compiler.
2246 </para>
2247 </glossdef>
2248 </glossentry>
2249
2250 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
2251 <info>
2252 CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as TARGET_CFLAGS."
2253 </info>
2254 <glossdef>
2255 <para role="glossdeffirst">
2256<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2257 Specifies the flags to pass to the C compiler.
2258 This variable is exported to an environment
2259 variable and thus made visible to the software being
2260 built during the compilation step.
2261 </para>
2262
2263 <para>
2264 Default initialization for <filename>CFLAGS</filename>
2265 varies depending on what is being built:
2266 <itemizedlist>
2267 <listitem><para>
2268 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
2269 when building for the target
2270 </para></listitem>
2271 <listitem><para>
2272 <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
2273 when building for the build host (i.e.
2274 <filename>-native</filename>)
2275 </para></listitem>
2276 <listitem><para>
2277 <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
2278 when building for an SDK (i.e.
2279 <filename>nativesdk-</filename>)
2280 </para></listitem>
2281 </itemizedlist>
2282 </para>
2283 </glossdef>
2284 </glossentry>
2285
2286 <glossentry id='var-CLASSOVERRIDE'><glossterm>CLASSOVERRIDE</glossterm>
2287 <info>
2288 CLASSOVERRIDE[doc] = "An internal variable specifying the special class override that should currently apply (e.g. "class-target", "class-native", and so forth)."
2289 </info>
2290 <glossdef>
2291 <para role="glossdeffirst">
2292<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2293 An internal variable specifying the special class override
2294 that should currently apply (e.g. "class-target",
2295 "class-native", and so forth).
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002296 The classes that use this variable (e.g.
2297 <link linkend='ref-classes-native'><filename>native</filename></link>,
2298 <link linkend='ref-classes-nativesdk'><filename>nativesdk</filename></link>,
2299 and so forth) set the variable to appropriate values.
2300 <note>
2301 <filename>CLASSOVERRIDE</filename> gets its default
2302 "class-target" value from the
2303 <filename>bitbake.conf</filename> file.
2304 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002305 </para>
2306
2307 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002308 As an example, the following override allows you to install
2309 extra files, but only when building for the target:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002310 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002311 do_install_append_class-target() {
2312 install my-extra-file ${D}${sysconfdir}
2313 }
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002314 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002315 Here is an example where <filename>FOO</filename>
2316 is set to "native" when building for the build host, and
2317 to "other" when not building for the build host:
2318 <literallayout class='monospaced'>
2319 FOO_class-native = "native"
2320 FOO = "other"
2321 </literallayout>
2322 The underlying mechanism behind
2323 <filename>CLASSOVERRIDE</filename> is simply that it is
2324 included in the default value of
2325 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002326 </para>
2327 </glossdef>
2328 </glossentry>
2329
2330 <glossentry id='var-CLEANBROKEN'><glossterm>CLEANBROKEN</glossterm>
2331 <info>
2332 CLEANBROKEN[doc] = "Prevents the build system from running 'make clean' during the do_configure task."
2333 </info>
2334 <glossdef>
2335 <para role="glossdeffirst">
2336<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2337 If set to "1" within a recipe,
2338 <filename>CLEANBROKEN</filename> specifies that
2339 the <filename>make clean</filename> command does
2340 not work for the software being built.
2341 Consequently, the OpenEmbedded build system will not try
2342 to run <filename>make clean</filename> during the
2343 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2344 task, which is the default behavior.
2345 </para>
2346 </glossdef>
2347 </glossentry>
2348
2349 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
2350 <info>
2351 COMBINED_FEATURES[doc] = "A set of features common between MACHINE_FEATURES and DISTRO_FEATURES."
2352 </info>
2353 <glossdef>
2354 <para role="glossdeffirst">
2355<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2356 Provides a list of hardware features that are enabled in
2357 both
2358 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
2359 and
2360 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
2361 This select list of features contains features that make
2362 sense to be controlled both at the machine and distribution
2363 configuration level.
2364 For example, the "bluetooth" feature requires hardware
2365 support but should also be optional at the distribution
2366 level, in case the hardware supports Bluetooth but you
2367 do not ever intend to use it.
2368 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002369 </glossdef>
2370 </glossentry>
2371
2372 <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
2373 <info>
2374 COMMON_LICENSE_DIR[doc] = "Points to meta/files/common-licenses in the Source Directory, which is where generic license files reside."
2375 </info>
2376 <glossdef>
2377 <para role="glossdeffirst">
2378<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2379 Points to <filename>meta/files/common-licenses</filename>
2380 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002381 <link linkend='source-directory'>Source Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002382 which is where generic license files reside.
2383 </para>
2384 </glossdef>
2385 </glossentry>
2386
2387 <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
2388 <info>
2389 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."
2390 </info>
2391 <glossdef>
2392 <para role="glossdeffirst">
2393<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2394 A regular expression that resolves to one or more hosts
2395 (when the recipe is native) or one or more targets (when
2396 the recipe is non-native) with which a recipe is compatible.
2397 The regular expression is matched against
2398 <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
2399 You can use the variable to stop recipes from being built
2400 for classes of systems with which the recipes are not
2401 compatible.
2402 Stopping these builds is particularly useful with kernels.
2403 The variable also helps to increase parsing speed
2404 since the build system skips parsing recipes not
2405 compatible with the current system.
2406 </para>
2407 </glossdef>
2408 </glossentry>
2409
2410 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
2411 <info>
2412 COMPATIBLE_MACHINE[doc] = "A regular expression that resolves to one or more target machines with which a recipe is compatible."
2413 </info>
2414 <glossdef>
2415 <para role="glossdeffirst">
2416<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2417 A regular expression that resolves to one or more
2418 target machines with which a recipe is compatible.
2419 The regular expression is matched against
2420 <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
2421 You can use the variable to stop recipes from being built
2422 for machines with which the recipes are not compatible.
2423 Stopping these builds is particularly useful with kernels.
2424 The variable also helps to increase parsing speed
2425 since the build system skips parsing recipes not
2426 compatible with the current machine.
2427 </para>
2428 </glossdef>
2429 </glossentry>
2430
2431 <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
2432 <info>
2433 COMPLEMENTARY_GLOB[doc] = "Defines wildcards to match when installing a list of complementary packages for all the packages installed in an image."
2434 </info>
2435 <glossdef>
2436 <para role="glossdeffirst">
2437<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2438 Defines wildcards to match when installing a list of
2439 complementary packages for all the packages explicitly
2440 (or implicitly) installed in an image.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08002441 <note>
2442 The <filename>COMPLEMENTARY_GLOB</filename> variable
2443 uses Unix filename pattern matching
2444 (<ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>),
2445 which is similar to the Unix style pathname pattern
2446 expansion
2447 (<ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>).
2448 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002449 The resulting list of complementary packages is associated
2450 with an item that can be added to
2451 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
2452 An example usage of this is the "dev-pkgs" item that when
2453 added to <filename>IMAGE_FEATURES</filename> will
2454 install -dev packages (containing headers and other
2455 development files) for every package in the image.
2456 </para>
2457
2458 <para>
2459 To add a new feature item pointing to a wildcard, use a
2460 variable flag to specify the feature item name and
2461 use the value to specify the wildcard.
2462 Here is an example:
2463 <literallayout class='monospaced'>
2464 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
2465 </literallayout>
2466 </para>
2467 </glossdef>
2468 </glossentry>
2469
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002470 <glossentry id='var-COMPONENTS_DIR'><glossterm>COMPONENTS_DIR</glossterm>
2471 <info>
2472 COMPONENTS_DIR[doc] = "Stores sysroot components for each recipe."
2473 </info>
2474 <glossdef>
2475 <para role="glossdeffirst">
2476<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2477 Stores sysroot components for each recipe.
2478 The OpenEmbedded build system uses
2479 <filename>COMPONENTS_DIR</filename> when constructing
2480 recipe-specific sysroots for other recipes.
2481 </para>
2482
2483 <para>
2484 The default is
2485 "<filename>${</filename><link linkend='var-STAGING_DIR'><filename>STAGING_DIR</filename></link><filename>}-components</filename>."
2486 (i.e. "<filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots-components</filename>").
2487 </para>
2488 </glossdef>
2489 </glossentry>
2490
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002491 <glossentry id='var-CONF_VERSION'><glossterm>CONF_VERSION</glossterm>
2492 <info>
2493 CONF_VERSION[doc] = "Tracks the version of local.conf. Increased each time build/conf/ changes incompatibly."
2494 </info>
2495 <glossdef>
2496 <para role="glossdeffirst">
2497<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2498 Tracks the version of the local configuration file
2499 (i.e. <filename>local.conf</filename>).
2500 The value for <filename>CONF_VERSION</filename>
2501 increments each time <filename>build/conf/</filename>
2502 compatibility changes.
2503 </para>
2504 </glossdef>
2505 </glossentry>
2506
2507 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
2508 <info>
2509 CONFFILES[doc] = "Identifies editable or configurable files that are part of a package."
2510 </info>
2511 <glossdef>
2512 <para role="glossdeffirst">
2513<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2514 Identifies editable or configurable files that are part of a package.
2515 If the Package Management System (PMS) is being used to update
2516 packages on the target system, it is possible that
2517 configuration files you have changed after the original installation
2518 and that you now want to remain unchanged are overwritten.
2519 In other words, editable files might exist in the package that you do not
2520 want reset as part of the package update process.
2521 You can use the <filename>CONFFILES</filename> variable to list the files in the
2522 package that you wish to prevent the PMS from overwriting during this update process.
2523 </para>
2524
2525 <para>
2526 To use the <filename>CONFFILES</filename> variable, provide a package name
2527 override that identifies the resulting package.
2528 Then, provide a space-separated list of files.
2529 Here is an example:
2530 <literallayout class='monospaced'>
2531 CONFFILES_${PN} += "${sysconfdir}/file1 \
2532 ${sysconfdir}/file2 ${sysconfdir}/file3"
2533 </literallayout>
2534 </para>
2535
2536 <para>
2537 A relationship exists between the <filename>CONFFILES</filename> and
2538 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
2539 The files listed within <filename>CONFFILES</filename> must be a subset of
2540 the files listed within <filename>FILES</filename>.
2541 Because the configuration files you provide with <filename>CONFFILES</filename>
2542 are simply being identified so that the PMS will not overwrite them,
2543 it makes sense that
2544 the files must already be included as part of the package through the
2545 <filename>FILES</filename> variable.
2546 </para>
2547
2548 <note>
2549 When specifying paths as part of the <filename>CONFFILES</filename> variable,
2550 it is good practice to use appropriate path variables.
2551 For example, <filename>${sysconfdir}</filename> rather than
2552 <filename>/etc</filename> or <filename>${bindir}</filename> rather
2553 than <filename>/usr/bin</filename>.
2554 You can find a list of these variables at the top of the
2555 <filename>meta/conf/bitbake.conf</filename> file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002556 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002557 </note>
2558 </glossdef>
2559 </glossentry>
2560
2561 <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>
2562 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05002563 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002564 </info>
2565 <glossdef>
2566 <para role="glossdeffirst">
2567<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop37a0e4d2017-12-04 01:01:44 -05002568 Identifies the initial RAM filesystem (initramfs) source
2569 files.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002570 The OpenEmbedded build system receives and uses
2571 this kernel Kconfig variable as an environment variable.
2572 By default, the variable is set to null ("").
2573 </para>
2574
2575 <para>
2576 The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be
2577 either a single cpio archive with a
2578 <filename>.cpio</filename> suffix or a
2579 space-separated list of directories and files for building
2580 the initramfs image.
2581 A cpio archive should contain a filesystem archive
2582 to be used as an initramfs image.
2583 Directories should contain a filesystem layout to be
2584 included in the initramfs image.
2585 Files should contain entries according to the format
2586 described by the
2587 <filename>usr/gen_init_cpio</filename> program in the
2588 kernel tree.
2589 </para>
2590
2591 <para>
2592 If you specify multiple directories and files, the
2593 initramfs image will be the aggregate of all of them.
2594 </para>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05002595
2596 <para>
2597 For information on creating an initramfs, see the
2598 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002599 section in the Yocto Project Development Tasks Manual.
Brad Bishop37a0e4d2017-12-04 01:01:44 -05002600 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002601 </glossdef>
2602 </glossentry>
2603
2604 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
2605 <info>
2606 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."
2607 </info>
2608 <glossdef>
2609 <para role="glossdeffirst">
2610<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2611 A list of files that contains <filename>autoconf</filename> test results relevant
2612 to the current build.
2613 This variable is used by the Autotools utilities when running
2614 <filename>configure</filename>.
2615 </para>
2616 </glossdef>
2617 </glossentry>
2618
2619 <glossentry id='var-CONFIGURE_FLAGS'><glossterm>CONFIGURE_FLAGS</glossterm>
2620 <info>
2621 CONFIGURE_FLAGS[doc] = "The minimal arguments for GNU configure."
2622 </info>
2623 <glossdef>
2624 <para role="glossdeffirst">
2625<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2626 The minimal arguments for GNU configure.
2627 </para>
2628 </glossdef>
2629 </glossentry>
2630
2631 <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>CONFLICT_DISTRO_FEATURES</glossterm>
2632 <info>
2633 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."
2634 </info>
2635 <glossdef>
2636 <para role="glossdeffirst">
2637<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2638 When inheriting the
2639 <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link>
2640 class, this
2641 variable identifies distribution features that would
2642 be in conflict should the recipe
2643 be built.
2644 In other words, if the
2645 <filename>CONFLICT_DISTRO_FEATURES</filename> variable
2646 lists a feature that also appears in
2647 <filename>DISTRO_FEATURES</filename> within the
2648 current configuration, an error occurs and the
2649 build stops.
2650 </para>
2651 </glossdef>
2652 </glossentry>
2653
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002654 <glossentry id='var-COPYLEFT_LICENSE_EXCLUDE'><glossterm>COPYLEFT_LICENSE_EXCLUDE</glossterm>
2655 <info>
2656 COPYLEFT_LICENSE_EXCLUDE[doc] = "Licenses to exclude in the source archived by the archiver class."
2657 </info>
2658 <glossdef>
2659 <para role="glossdeffirst">
2660<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2661 A space-separated list of licenses to exclude from the
2662 source archived by the
2663 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2664 class.
2665 In other words, if a license in a recipe's
2666 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2667 value is in the value of
2668 <filename>COPYLEFT_LICENSE_EXCLUDE</filename>, then its
2669 source is not archived by the class.
2670 <note>
2671 The <filename>COPYLEFT_LICENSE_EXCLUDE</filename>
2672 variable takes precedence over the
2673 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2674 variable.
2675 </note>
2676 The default value, which is "CLOSED Proprietary", for
2677 <filename>COPYLEFT_LICENSE_EXCLUDE</filename> is set
2678 by the
2679 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2680 class, which is inherited by the
2681 <filename>archiver</filename> class.
2682 </para>
2683 </glossdef>
2684 </glossentry>
2685
2686 <glossentry id='var-COPYLEFT_LICENSE_INCLUDE'><glossterm>COPYLEFT_LICENSE_INCLUDE</glossterm>
2687 <info>
2688 COPYLEFT_LICENSE_INCLUDE[doc] = "Licenses to include in the source archived by the archiver class."
2689 </info>
2690 <glossdef>
2691 <para role="glossdeffirst">
2692<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2693 A space-separated list of licenses to include in the
2694 source archived by the
2695 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2696 class.
2697 In other words, if a license in a recipe's
2698 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2699 value is in the value of
2700 <filename>COPYLEFT_LICENSE_INCLUDE</filename>, then its
2701 source is archived by the class.
2702 </para>
2703
2704 <para>
2705 The default value is set by the
2706 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2707 class, which is inherited by the
2708 <filename>archiver</filename> class.
2709 The default value includes "GPL*", "LGPL*", and "AGPL*".
2710 </para>
2711 </glossdef>
2712 </glossentry>
2713
2714 <glossentry id='var-COPYLEFT_PN_EXCLUDE'><glossterm>COPYLEFT_PN_EXCLUDE</glossterm>
2715 <info>
2716 COPYLEFT_PN_EXCLUDE[doc] = "Recipes to exclude in the source archived by the archiver class."
2717 </info>
2718 <glossdef>
2719 <para role="glossdeffirst">
2720<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2721 A list of recipes to exclude in the source archived
2722 by the
2723 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2724 class.
2725 The <filename>COPYLEFT_PN_EXCLUDE</filename> variable
2726 overrides the license inclusion and exclusion caused
2727 through the
2728 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2729 and
2730 <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link>
2731 variables, respectively.
2732 </para>
2733
2734 <para>
2735 The default value, which is "" indicating to not explicitly
2736 exclude any recipes by name, for
2737 <filename>COPYLEFT_PN_EXCLUDE</filename> is set
2738 by the
2739 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2740 class, which is inherited by the
2741 <filename>archiver</filename> class.
2742 </para>
2743 </glossdef>
2744 </glossentry>
2745
2746 <glossentry id='var-COPYLEFT_PN_INCLUDE'><glossterm>COPYLEFT_PN_INCLUDE</glossterm>
2747 <info>
2748 COPYLEFT_PN_INCLUDE[doc] = "Recipes to include in the source archived by the archiver class."
2749 </info>
2750 <glossdef>
2751 <para role="glossdeffirst">
2752<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2753 A list of recipes to include in the source archived
2754 by the
2755 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2756 class.
2757 The <filename>COPYLEFT_PN_INCLUDE</filename> variable
2758 overrides the license inclusion and exclusion caused
2759 through the
2760 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2761 and
2762 <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link>
2763 variables, respectively.
2764 </para>
2765
2766 <para>
2767 The default value, which is "" indicating to not explicitly
2768 include any recipes by name, for
2769 <filename>COPYLEFT_PN_INCLUDE</filename> is set
2770 by the
2771 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2772 class, which is inherited by the
2773 <filename>archiver</filename> class.
2774 </para>
2775 </glossdef>
2776 </glossentry>
2777
2778 <glossentry id='var-COPYLEFT_RECIPE_TYPES'><glossterm>COPYLEFT_RECIPE_TYPES</glossterm>
2779 <info>
2780 COPYLEFT_RECIPE_TYPES[doc] = "Recipe types to include in the source archived by the archiver class."
2781 </info>
2782 <glossdef>
2783 <para role="glossdeffirst">
2784<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2785 A space-separated list of recipe types to include
2786 in the source archived by the
2787 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2788 class.
2789 Recipe types are <filename>target</filename>,
2790 <filename>native</filename>,
2791 <filename>nativesdk</filename>,
2792 <filename>cross</filename>,
2793 <filename>crosssdk</filename>, and
2794 <filename>cross-canadian</filename>.
2795 </para>
2796
2797 <para>
2798 The default value, which is "target*", for
2799 <filename>COPYLEFT_RECIPE_TYPES</filename> is set
2800 by the
2801 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2802 class, which is inherited by the
2803 <filename>archiver</filename> class.
2804 </para>
2805 </glossdef>
2806 </glossentry>
2807
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002808 <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm>
2809 <info>
2810 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."
2811 </info>
2812 <glossdef>
2813 <para role="glossdeffirst">
2814<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2815 If set to "1" along with the
2816 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
2817 variable, the OpenEmbedded build system copies
2818 into the image the license files, which are located in
2819 <filename>/usr/share/common-licenses</filename>,
2820 for each package.
2821 The license files are placed
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002822 in directories within the image itself during build time.
2823 <note>
2824 The <filename>COPY_LIC_DIRS</filename> does not
2825 offer a path for adding licenses for newly installed
2826 packages to an image, which might be most suitable
2827 for read-only filesystems that cannot be upgraded.
2828 See the
2829 <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link>
2830 variable for additional information.
2831 You can also reference the
2832 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002833 section in the Yocto Project Development Tasks Manual
2834 for information on providing license text.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002835 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002836 </para>
2837 </glossdef>
2838 </glossentry>
2839
2840 <glossentry id='var-COPY_LIC_MANIFEST'><glossterm>COPY_LIC_MANIFEST</glossterm>
2841 <info>
2842 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."
2843 </info>
2844 <glossdef>
2845 <para role="glossdeffirst">
2846<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2847 If set to "1", the OpenEmbedded build system copies
2848 the license manifest for the image to
2849 <filename>/usr/share/common-licenses/license.manifest</filename>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002850 within the image itself during build time.
2851 <note>
2852 The <filename>COPY_LIC_MANIFEST</filename> does not
2853 offer a path for adding licenses for newly installed
2854 packages to an image, which might be most suitable
2855 for read-only filesystems that cannot be upgraded.
2856 See the
2857 <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link>
2858 variable for additional information.
2859 You can also reference the
2860 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002861 section in the Yocto Project Development Tasks Manual
2862 for information on providing license text.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002863 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002864 </para>
2865 </glossdef>
2866 </glossentry>
2867
2868 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
2869 <info>
2870 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."
2871 </info>
2872 <glossdef>
2873 <para role="glossdeffirst">
2874<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2875 Specifies the list of packages to be added to the image.
2876 You should only set this variable in the
2877 <filename>local.conf</filename> configuration file found
2878 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002879 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002880 </para>
2881
2882 <para>
2883 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
2884 </para>
2885 </glossdef>
2886 </glossentry>
2887
2888 <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
2889 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002890 COREBASE[doc] = "Specifies the parent directory of the OpenEmbedded-Core Metadata layer (i.e. meta)."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002891 </info>
2892 <glossdef>
2893 <para role="glossdeffirst">
2894<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -04002895 Specifies the parent directory of the OpenEmbedded-Core
2896 Metadata layer (i.e. <filename>meta</filename>).
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002897 </para>
2898
2899 <para>
2900 It is an important distinction that
2901 <filename>COREBASE</filename> points to the parent of this
2902 layer and not the layer itself.
2903 Consider an example where you have cloned the Poky Git
2904 repository and retained the <filename>poky</filename>
2905 name for your local copy of the repository.
2906 In this case, <filename>COREBASE</filename> points to
2907 the <filename>poky</filename> folder because it is the
2908 parent directory of the <filename>poky/meta</filename>
2909 layer.
2910 </para>
2911 </glossdef>
2912 </glossentry>
2913
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002914 <glossentry id='var-COREBASE_FILES'><glossterm>COREBASE_FILES</glossterm>
2915 <info>
2916 COREBASE_FILES[doc] = "Lists files from the COREBASE directory that should be copied other than the layers listed in the bblayers.conf file."
2917 </info>
2918 <glossdef>
2919 <para role="glossdeffirst">
2920<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2921 Lists files from the
2922 <link linkend='var-COREBASE'><filename>COREBASE</filename></link>
2923 directory that should be copied other than the layers
2924 listed in the <filename>bblayers.conf</filename> file.
2925 The <filename>COREBASE_FILES</filename> variable exists
2926 for the purpose of copying metadata from the
2927 OpenEmbedded build system into the extensible
2928 SDK.
2929 </para>
2930
2931 <para>
2932 Explicitly listing files in <filename>COREBASE</filename>
2933 is needed because it typically contains build
2934 directories and other files that should not normally
2935 be copied into the extensible SDK.
2936 Consequently, the value of
2937 <filename>COREBASE_FILES</filename> is used in order to
2938 only copy the files that are actually needed.
2939 </para>
2940 </glossdef>
2941 </glossentry>
2942
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002943 <glossentry id='var-CPP'><glossterm>CPP</glossterm>
2944 <info>
2945 CPP[doc] = "Minimum command and arguments to run the C preprocessor."
2946 </info>
2947 <glossdef>
2948 <para role="glossdeffirst">
2949<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2950 The minimal command and arguments used to run the C
2951 preprocessor.
2952 </para>
2953 </glossdef>
2954 </glossentry>
2955
2956 <glossentry id='var-CPPFLAGS'><glossterm>CPPFLAGS</glossterm>
2957 <info>
2958 CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers)."
2959 </info>
2960 <glossdef>
2961 <para role="glossdeffirst">
2962<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2963 Specifies the flags to pass to the C pre-processor
2964 (i.e. to both the C and the C++ compilers).
2965 This variable is exported to an environment
2966 variable and thus made visible to the software being
2967 built during the compilation step.
2968 </para>
2969
2970 <para>
2971 Default initialization for <filename>CPPFLAGS</filename>
2972 varies depending on what is being built:
2973 <itemizedlist>
2974 <listitem><para>
2975 <link linkend='var-TARGET_CPPFLAGS'><filename>TARGET_CPPFLAGS</filename></link>
2976 when building for the target
2977 </para></listitem>
2978 <listitem><para>
2979 <link linkend='var-BUILD_CPPFLAGS'><filename>BUILD_CPPFLAGS</filename></link>
2980 when building for the build host (i.e.
2981 <filename>-native</filename>)
2982 </para></listitem>
2983 <listitem><para>
2984 <link linkend='var-BUILDSDK_CPPFLAGS'><filename>BUILDSDK_CPPFLAGS</filename></link>
2985 when building for an SDK (i.e.
2986 <filename>nativesdk-</filename>)
2987 </para></listitem>
2988 </itemizedlist>
2989 </para>
2990 </glossdef>
2991 </glossentry>
2992
2993 <glossentry id='var-CROSS_COMPILE'><glossterm>CROSS_COMPILE</glossterm>
2994 <info>
2995 CROSS_COMPILE[doc] = "The toolchain binary prefix for the target tools."
2996 </info>
2997 <glossdef>
2998 <para role="glossdeffirst">
2999<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3000 The toolchain binary prefix for the target tools.
3001 The <filename>CROSS_COMPILE</filename> variable is the
3002 same as the
3003 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
3004 variable.
3005 <note>
3006 The OpenEmbedded build system sets the
3007 <filename>CROSS_COMPILE</filename> variable only in
3008 certain contexts (e.g. when building for kernel
3009 and kernel module recipes).
3010 </note>
3011 </para>
3012 </glossdef>
3013 </glossentry>
3014
3015 <glossentry id='var-CVSDIR'><glossterm>CVSDIR</glossterm>
3016 <info>
3017 CVSDIR[doc] = "The directory where cvs checkouts will be stored in."
3018 </info>
3019 <glossdef>
3020 <para role="glossdeffirst">
3021<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3022 The directory in which files checked out under the
3023 CVS system are stored.
3024 </para>
3025 </glossdef>
3026 </glossentry>
3027
3028 <glossentry id='var-CXX'><glossterm>CXX</glossterm>
3029 <info>
3030 CXX[doc] = "Minimum command and arguments to run the C++ compiler."
3031 </info>
3032 <glossdef>
3033 <para role="glossdeffirst">
3034<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3035 The minimal command and arguments used to run the C++
3036 compiler.
3037 </para>
3038 </glossdef>
3039 </glossentry>
3040
3041 <glossentry id='var-CXXFLAGS'><glossterm>CXXFLAGS</glossterm>
3042 <info>
3043 CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler."
3044 </info>
3045 <glossdef>
3046 <para role="glossdeffirst">
3047<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3048 Specifies the flags to pass to the C++ compiler.
3049 This variable is exported to an environment
3050 variable and thus made visible to the software being
3051 built during the compilation step.
3052 </para>
3053
3054 <para>
3055 Default initialization for <filename>CXXFLAGS</filename>
3056 varies depending on what is being built:
3057 <itemizedlist>
3058 <listitem><para>
3059 <link linkend='var-TARGET_CXXFLAGS'><filename>TARGET_CXXFLAGS</filename></link>
3060 when building for the target
3061 </para></listitem>
3062 <listitem><para>
3063 <link linkend='var-BUILD_CXXFLAGS'><filename>BUILD_CXXFLAGS</filename></link>
3064 when building for the build host (i.e.
3065 <filename>-native</filename>)
3066 </para></listitem>
3067 <listitem><para>
3068 <link linkend='var-BUILDSDK_CXXFLAGS'><filename>BUILDSDK_CXXFLAGS</filename></link>
3069 when building for an SDK (i.e.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003070 <filename>nativesdk-</filename>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003071 </para></listitem>
3072 </itemizedlist>
3073 </para>
3074 </glossdef>
3075 </glossentry>
3076
3077 </glossdiv>
3078
3079 <glossdiv id='var-glossary-d'><title>D</title>
3080
3081 <glossentry id='var-D'><glossterm>D</glossterm>
3082 <info>
3083 D[doc] = "The destination directory."
3084 </info>
3085 <glossdef>
3086 <para role="glossdeffirst">
3087<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3088 The destination directory.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003089 The location in the
3090 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003091 where components are installed by the
3092 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
3093 task.
3094 This location defaults to:
3095 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003096 ${WORKDIR}/image
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003097 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003098 <note><title>Caution</title>
3099 Tasks that read from or write to this directory should
3100 run under
Brad Bishop316dfdd2018-06-25 12:45:53 -04003101 <ulink url='&YOCTO_DOCS_OM_URL;#fakeroot-and-pseudo'>fakeroot</ulink>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003102 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003103 </para>
3104 </glossdef>
3105 </glossentry>
3106
3107 <glossentry id='var-DATE'><glossterm>DATE</glossterm>
3108 <info>
3109 DATE[doc] = "The date the build was started using YMD format."
3110 </info>
3111 <glossdef>
3112 <para role="glossdeffirst">
3113<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3114 The date the build was started.
3115 Dates appear using the year, month, and day (YMD) format
3116 (e.g. "20150209" for February 9th, 2015).
3117 </para>
3118 </glossdef>
3119 </glossentry>
3120
3121 <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
3122 <info>
3123 DATETIME[doc] = "The date and time the build was started."
3124 </info>
3125 <glossdef>
3126 <para role="glossdeffirst">
3127<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3128 The date and time on which the current build started.
3129 The format is suitable for timestamps.
3130 </para>
3131 </glossdef>
3132 </glossentry>
3133
3134 <glossentry id='var-DEBIAN_NOAUTONAME'><glossterm>DEBIAN_NOAUTONAME</glossterm>
3135 <info>
3136 DEBIAN_NOAUTONAME[doc] = "Prevents a particular package from being renamed according to Debian package naming."
3137 </info>
3138 <glossdef>
3139 <para role="glossdeffirst">
3140<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3141 When the
3142 <link linkend='ref-classes-debian'><filename>debian</filename></link>
3143 class is inherited, which is the default behavior,
3144 <filename>DEBIAN_NOAUTONAME</filename> specifies a
3145 particular package should not be renamed according to
3146 Debian library package naming.
3147 You must use the package name as an override when you
3148 set this variable.
3149 Here is an example from the <filename>fontconfig</filename>
3150 recipe:
3151 <literallayout class='monospaced'>
3152 DEBIAN_NOAUTONAME_fontconfig-utils = "1"
3153 </literallayout>
3154 </para>
3155 </glossdef>
3156 </glossentry>
3157
3158 <glossentry id='var-DEBIANNAME'><glossterm>DEBIANNAME</glossterm>
3159 <info>
3160 DEBIANNAME[doc] = "Allows you to override the library name for an individual package for Debian library package renaming."
3161 </info>
3162 <glossdef>
3163 <para role="glossdeffirst">
3164<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3165 When the
3166 <link linkend='ref-classes-debian'><filename>debian</filename></link>
3167 class is inherited, which is the default behavior,
3168 <filename>DEBIANNAME</filename> allows you to override the
3169 library name for an individual package.
3170 Overriding the library name in these cases is rare.
3171 You must use the package name as an override when you
3172 set this variable.
3173 Here is an example from the <filename>dbus</filename>
3174 recipe:
3175 <literallayout class='monospaced'>
3176 DEBIANNAME_${PN} = "dbus-1"
3177 </literallayout>
3178 </para>
3179 </glossdef>
3180 </glossentry>
3181
3182 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
3183 <info>
3184 DEBUG_BUILD[doc] = "Specifies to build packages with debugging information. This influences the value of the SELECTED_OPTIMIZATION variable."
3185 </info>
3186 <glossdef>
3187 <para role="glossdeffirst">
3188<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3189 Specifies to build packages with debugging information.
3190 This influences the value of the
3191 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
3192 variable.
3193 </para>
3194 </glossdef>
3195 </glossentry>
3196
3197 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
3198 <info>
3199 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'."
3200 </info>
3201 <glossdef>
3202 <para role="glossdeffirst">
3203<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3204 The options to pass in
3205 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
3206 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
3207 a system for debugging.
3208 This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
3209 </para>
3210 </glossdef>
3211 </glossentry>
3212
3213 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
3214 <info>
3215 DEFAULT_PREFERENCE[doc] = "Specifies a weak bias for recipe selection priority."
3216 </info>
3217 <glossdef>
3218 <para role="glossdeffirst">
3219<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3220 Specifies a weak bias for recipe selection priority.
3221 </para>
3222
3223 <para>
3224 The most common usage of this is variable is to set
3225 it to "-1" within a recipe for a development version of a
3226 piece of software.
3227 Using the variable in this way causes the stable version
3228 of the recipe to build by default in the absence of
3229 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
3230 being used to build the development version.
3231 </para>
3232
3233 <note>
3234 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
3235 is weak and is overridden by
3236 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
3237 if that variable is different between two layers
3238 that contain different versions of the same recipe.
3239 </note>
3240 </glossdef>
3241 </glossentry>
3242
3243 <glossentry id='var-DEFAULTTUNE'><glossterm>DEFAULTTUNE</glossterm>
3244 <info>
3245 DEFAULTTUNE[doc] = "The default CPU and Application Binary Interface (ABI) tunings (i.e. the "tune") used by the OpenEmbedded build system."
3246 </info>
3247 <glossdef>
3248 <para role="glossdeffirst">
3249<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3250 The default CPU and Application Binary Interface (ABI)
3251 tunings (i.e. the "tune") used by the OpenEmbedded build
3252 system.
3253 The <filename>DEFAULTTUNE</filename> helps define
3254 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
3255 </para>
3256
3257 <para>
3258 The default tune is either implicitly or explicitly set
3259 by the machine
3260 (<link linkend='var-MACHINE'><filename>MACHINE</filename></link>).
3261 However, you can override the setting using available tunes
3262 as defined with
3263 <link linkend='var-AVAILTUNES'><filename>AVAILTUNES</filename></link>.
3264 </para>
3265 </glossdef>
3266 </glossentry>
3267
3268 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
3269 <info>
3270 DEPENDS[doc] = "Lists a recipe's build-time dependencies (i.e. other recipe files)."
3271 </info>
3272 <glossdef>
3273 <para role="glossdeffirst">
3274<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003275 Lists a recipe's build-time dependencies.
3276 These are dependencies on other recipes whose
3277 contents (e.g. headers and shared libraries) are needed
3278 by the recipe at build time.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003279 </para>
3280
3281 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003282 As an example, consider a recipe <filename>foo</filename>
3283 that contains the following assignment:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003284 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003285 DEPENDS = "bar"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003286 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003287 The practical effect of the previous assignment is that
3288 all files installed by bar will be available in the
3289 appropriate staging sysroot, given by the
3290 <link linkend='var-STAGING_DIR'><filename>STAGING_DIR*</filename></link>
3291 variables, by the time the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003292 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003293 task for <filename>foo</filename> runs.
3294 This mechanism is implemented by having
3295 <filename>do_configure</filename> depend on the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003296 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003297 task of each recipe listed in <filename>DEPENDS</filename>,
3298 through a
3299 <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>
3300 declaration in the
3301 <link linkend='ref-classes-base'><filename>base</filename></link>
3302 class.
3303 <note>
3304 It seldom is necessary to reference, for example,
3305 <filename>STAGING_DIR_HOST</filename> explicitly.
3306 The standard classes and build-related variables are
3307 configured to automatically use the appropriate staging
3308 sysroots.
3309 </note>
3310 As another example, <filename>DEPENDS</filename> can also
3311 be used to add utilities that run on the build machine
3312 during the build.
3313 For example, a recipe that makes use of a code generator
3314 built by the recipe <filename>codegen</filename> might have
3315 the following:
3316 <literallayout class='monospaced'>
3317 DEPENDS = "codegen-native"
3318 </literallayout>
3319 For more information, see the
3320 <link linkend='ref-classes-native'><filename>native</filename></link>
3321 class and the
3322 <link linkend='var-EXTRANATIVEPATH'><filename>EXTRANATIVEPATH</filename></link>
3323 variable.
3324 <note>
3325 <title>Notes</title>
3326 <itemizedlist>
3327 <listitem><para>
3328 <filename>DEPENDS</filename> is a list of
3329 recipe names.
3330 Or, to be more precise, it is a list of
3331 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
3332 names, which usually match recipe names.
3333 Putting a package name such as "foo-dev" in
3334 <filename>DEPENDS</filename> does not make
3335 sense.
3336 Use "foo" instead, as this will put files
3337 from all the packages that make up
3338 <filename>foo</filename>, which includes
3339 those from <filename>foo-dev</filename>, into
3340 the sysroot.
3341 </para></listitem>
3342 <listitem><para>
3343 One recipe having another recipe in
3344 <filename>DEPENDS</filename> does not by itself
3345 add any runtime dependencies between the
3346 packages produced by the two recipes.
3347 However, as explained in the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003348 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
3349 section in the Yocto Project Overview and
3350 Concepts Manual, runtime dependencies will
3351 often be added automatically, meaning
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003352 <filename>DEPENDS</filename> alone is
3353 sufficient for most recipes.
3354 </para></listitem>
3355 <listitem><para>
3356 Counterintuitively,
3357 <filename>DEPENDS</filename> is often necessary
3358 even for recipes that install precompiled
3359 components.
3360 For example, if <filename>libfoo</filename>
3361 is a precompiled library that links against
3362 <filename>libbar</filename>, then
3363 linking against <filename>libfoo</filename>
3364 requires both <filename>libfoo</filename>
3365 and <filename>libbar</filename> to be available
3366 in the sysroot.
3367 Without a <filename>DEPENDS</filename> from the
3368 recipe that installs <filename>libfoo</filename>
3369 to the recipe that installs
3370 <filename>libbar</filename>, other recipes might
3371 fail to link against
3372 <filename>libfoo</filename>.
3373 </para></listitem>
3374 </itemizedlist>
3375 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003376 </para>
3377
3378 <para>
3379 For information on runtime dependencies, see the
3380 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
3381 variable.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003382 You can also see the
3383 "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
3384 "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
3385 sections in the BitBake User Manual for additional
3386 information on tasks and dependencies.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003387 </para>
3388 </glossdef>
3389 </glossentry>
3390
3391 <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
3392 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003393 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003394 </info>
3395 <glossdef>
3396 <para role="glossdeffirst">
3397<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3398 Points to the general area that the OpenEmbedded build
Brad Bishop316dfdd2018-06-25 12:45:53 -04003399 system uses to place images, packages, SDKs, and other output
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003400 files that are ready to be used outside of the build system.
3401 By default, this directory resides within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003402 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003403 as <filename>${TMPDIR}/deploy</filename>.
3404 </para>
3405
3406 <para>
3407 For more information on the structure of the Build
3408 Directory, see
3409 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
3410 section.
3411 For more detail on the contents of the
3412 <filename>deploy</filename> directory, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003413 "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>",
3414 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>",
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003415 and
Brad Bishop316dfdd2018-06-25 12:45:53 -04003416 "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
3417 sections all in the Yocto Project Overview and Concepts
3418 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003419 </para>
3420 </glossdef>
3421 </glossentry>
3422
3423 <glossentry id='var-DEPLOY_DIR_DEB'><glossterm>DEPLOY_DIR_DEB</glossterm>
3424 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003425 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003426 </info>
3427 <glossdef>
3428 <para role="glossdeffirst">
3429<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3430 Points to the area that the OpenEmbedded build system uses
3431 to place Debian packages that are ready to be used outside
3432 of the build system.
3433 This variable applies only when
3434 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3435 contains "package_deb".
3436 </para>
3437
3438 <para>
3439 The BitBake configuration file initially defines the
3440 <filename>DEPLOY_DIR_DEB</filename> variable as a
3441 sub-folder of
3442 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3443 <literallayout class='monospaced'>
3444 DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
3445 </literallayout>
3446 </para>
3447
3448 <para>
3449 The
3450 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>
3451 class uses the
3452 <filename>DEPLOY_DIR_DEB</filename> variable to make sure
3453 the
3454 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>
3455 task writes Debian packages into the appropriate folder.
3456 For more information on how packaging works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003457 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3458 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003459 </para>
3460 </glossdef>
3461 </glossentry>
3462
3463 <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
3464 <info>
3465 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."
3466 </info>
3467 <glossdef>
3468 <para role="glossdeffirst">
3469<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3470 Points to the area that the OpenEmbedded build system uses
3471 to place images and other associated output files that are
3472 ready to be deployed onto the target machine.
3473 The directory is machine-specific as it contains the
3474 <filename>${MACHINE}</filename> name.
3475 By default, this directory resides within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003476 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003477 as <filename>${DEPLOY_DIR}/images/${MACHINE}/</filename>.
3478 </para>
3479
3480 <para>
3481 For more information on the structure of the Build
3482 Directory, see
3483 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
3484 section.
3485 For more detail on the contents of the
3486 <filename>deploy</filename> directory, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003487 "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
3488 and
3489 "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
3490 sections both in the Yocto Project Overview and Concepts
3491 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003492 </para>
3493 </glossdef>
3494 </glossentry>
3495
3496 <glossentry id='var-DEPLOY_DIR_IPK'><glossterm>DEPLOY_DIR_IPK</glossterm>
3497 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003498 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003499 </info>
3500 <glossdef>
3501 <para role="glossdeffirst">
3502<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3503 Points to the area that the OpenEmbedded build system uses
3504 to place IPK packages that are ready to be used outside of
3505 the build system.
3506 This variable applies only when
3507 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3508 contains "package_ipk".
3509 </para>
3510
3511 <para>
3512 The BitBake configuration file initially defines this
3513 variable as a sub-folder of
3514 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3515 <literallayout class='monospaced'>
3516 DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
3517 </literallayout>
3518 </para>
3519
3520 <para>
3521 The
3522 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>
3523 class uses the
3524 <filename>DEPLOY_DIR_IPK</filename> variable to make sure
3525 the
3526 <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
3527 task writes IPK packages into the appropriate folder.
3528 For more information on how packaging works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003529 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3530 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003531 </para>
3532 </glossdef>
3533 </glossentry>
3534
3535 <glossentry id='var-DEPLOY_DIR_RPM'><glossterm>DEPLOY_DIR_RPM</glossterm>
3536 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003537 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003538 </info>
3539 <glossdef>
3540 <para role="glossdeffirst">
3541<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3542 Points to the area that the OpenEmbedded build system uses
3543 to place RPM packages that are ready to be used outside
3544 of the build system.
3545 This variable applies only when
3546 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3547 contains "package_rpm".
3548 </para>
3549
3550 <para>
3551 The BitBake configuration file initially defines this
3552 variable as a sub-folder of
3553 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3554 <literallayout class='monospaced'>
3555 DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
3556 </literallayout>
3557 </para>
3558
3559 <para>
3560 The
3561 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>
3562 class uses the
3563 <filename>DEPLOY_DIR_RPM</filename> variable to make sure
3564 the
3565 <link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link>
3566 task writes RPM packages into the appropriate folder.
3567 For more information on how packaging works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003568 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3569 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003570 </para>
3571 </glossdef>
3572 </glossentry>
3573
3574 <glossentry id='var-DEPLOY_DIR_TAR'><glossterm>DEPLOY_DIR_TAR</glossterm>
3575 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003576 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003577 </info>
3578 <glossdef>
3579 <para role="glossdeffirst">
3580<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3581 Points to the area that the OpenEmbedded build system uses
3582 to place tarballs that are ready to be used outside of
3583 the build system.
3584 This variable applies only when
3585 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3586 contains "package_tar".
3587 </para>
3588
3589 <para>
3590 The BitBake configuration file initially defines this
3591 variable as a sub-folder of
3592 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3593 <literallayout class='monospaced'>
3594 DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"
3595 </literallayout>
3596 </para>
3597
3598 <para>
3599 The
3600 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
3601 class uses the
3602 <filename>DEPLOY_DIR_TAR</filename> variable to make sure
3603 the
3604 <link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>
3605 task writes TAR packages into the appropriate folder.
3606 For more information on how packaging works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003607 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3608 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003609 </para>
3610 </glossdef>
3611 </glossentry>
3612
3613 <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm>
3614 <info>
3615 DEPLOYDIR[doc] = "For recipes that inherit the deploy class, the DEPLOYDIR points to a temporary work area for deployed files."
3616 </info>
3617 <glossdef>
3618 <para role="glossdeffirst">
3619<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3620 When inheriting the
3621 <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
3622 class, the <filename>DEPLOYDIR</filename> points to a
3623 temporary work area for deployed files that is set in the
3624 <filename>deploy</filename> class as follows:
3625 <literallayout class='monospaced'>
3626 DEPLOYDIR = "${WORKDIR}/deploy-${<link linkend='var-PN'><filename>PN</filename></link>}"
3627 </literallayout>
3628 </para>
3629
3630 <para>
3631 Recipes inheriting the <filename>deploy</filename> class
3632 should copy files to be deployed into
3633 <filename>DEPLOYDIR</filename>, and the class will take
3634 care of copying them into
3635 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
3636 afterwards.
3637 </para>
3638 </glossdef>
3639 </glossentry>
3640
3641 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
3642 <info>
3643 DESCRIPTION[doc] = "The package description used by package managers. If not set, DESCRIPTION takes the value of the SUMMARY variable."
3644 </info>
3645 <glossdef>
3646 <para role="glossdeffirst">
3647<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3648 The package description used by package managers.
3649 If not set, <filename>DESCRIPTION</filename> takes
3650 the value of the
3651 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
3652 variable.
3653 </para>
3654 </glossdef>
3655 </glossentry>
3656
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003657 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
3658 <info>
3659 DISTRO[doc] = "The short name of the distribution. If the variable is blank, meta/conf/distro/defaultsetup.conf will be used."
3660 </info>
3661 <glossdef>
3662 <para role="glossdeffirst">
3663<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3664 The short name of the distribution.
Brad Bishopd5ae7d92018-06-14 09:52:03 -07003665 For information on the long name of the distribution, see
3666 the
3667 <link linkend='var-DISTRO_NAME'><filename>DISTRO_NAME</filename></link>
3668 variable.
3669 </para>
3670
3671 <para>
3672 The <filename>DISTRO</filename> variable corresponds to a
3673 distribution configuration file whose root name is the
3674 same as the variable's argument and whose filename
3675 extension is <filename>.conf</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003676 For example, the distribution configuration file for the
3677 Poky distribution is named <filename>poky.conf</filename>
3678 and resides in the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003679 <filename>meta-poky/conf/distro</filename> directory of
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003680 the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003681 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003682 </para>
3683
3684 <para>
3685 Within that <filename>poky.conf</filename> file, the
3686 <filename>DISTRO</filename> variable is set as follows:
3687 <literallayout class='monospaced'>
3688 DISTRO = "poky"
3689 </literallayout>
3690 </para>
3691
3692 <para>
3693 Distribution configuration files are located in a
3694 <filename>conf/distro</filename> directory within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003695 <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003696 that contains the distribution configuration.
3697 The value for <filename>DISTRO</filename> must not contain
3698 spaces, and is typically all lower-case.
3699 <note>
Brad Bishopd5ae7d92018-06-14 09:52:03 -07003700 If the <filename>DISTRO</filename> variable is blank,
3701 a set of default configurations are used, which are
3702 specified within
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003703 <filename>meta/conf/distro/defaultsetup.conf</filename>
3704 also in the Source Directory.
3705 </note>
3706 </para>
3707 </glossdef>
3708 </glossentry>
3709
3710 <glossentry id='var-DISTRO_CODENAME'><glossterm>DISTRO_CODENAME</glossterm>
3711 <info>
3712 DISTRO_CODENAME[doc] = "Specifies a codename for the distribution being built."
3713 </info>
3714 <glossdef>
3715 <para role="glossdeffirst">
3716<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3717 Specifies a codename for the distribution being built.
3718 </para>
3719 </glossdef>
3720 </glossentry>
3721
3722 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
3723 <info>
3724 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."
3725 </info>
3726 <glossdef>
3727 <para role="glossdeffirst">
3728<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3729 Specifies a list of distro-specific packages to add to all images.
3730 This variable takes affect through
3731 <filename>packagegroup-base</filename> so the
3732 variable only really applies to the more full-featured
3733 images that include <filename>packagegroup-base</filename>.
3734 You can use this variable to keep distro policy out of
3735 generic images.
3736 As with all other distro variables, you set this variable
3737 in the distro <filename>.conf</filename> file.
3738 </para>
3739 </glossdef>
3740 </glossentry>
3741
3742 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
3743 <info>
3744 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."
3745 </info>
3746 <glossdef>
3747 <para role="glossdeffirst">
3748<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3749 Specifies a list of distro-specific packages to add to all images
3750 if the packages exist.
3751 The packages might not exist or be empty (e.g. kernel modules).
3752 The list of packages are automatically installed but you can
3753 remove them.
3754 </para>
3755 </glossdef>
3756 </glossentry>
3757
3758 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
3759 <info>
3760 DISTRO_FEATURES[doc] = "The features enabled for the distribution."
3761 </info>
3762 <glossdef>
3763 <para role="glossdeffirst">
3764<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3765 The software support you want in your distribution for
3766 various features.
3767 You define your distribution features in the distribution
3768 configuration file.
3769 </para>
3770
3771 <para>
3772 In most cases, the presence or absence of a feature in
3773 <filename>DISTRO_FEATURES</filename> is translated to the
3774 appropriate option supplied to the configure script
3775 during the
3776 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
3777 task for recipes that optionally support the feature.
3778 For example, specifying "x11" in
3779 <filename>DISTRO_FEATURES</filename>, causes
3780 every piece of software built for the target that can
3781 optionally support X11 to have its X11 support enabled.
3782 </para>
3783
3784 <para>
3785 Two more examples are Bluetooth and NFS support.
3786 For a more complete list of features that ships with the
3787 Yocto Project and that you can provide with this variable,
3788 see the
3789 "<link linkend='ref-features-distro'>Distro Features</link>"
3790 section.
3791 </para>
3792 </glossdef>
3793 </glossentry>
3794
3795 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
3796 <info>
3797 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."
3798 </info>
3799 <glossdef>
3800 <para role="glossdeffirst">
3801<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3802 Features to be added to
3803 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
3804 if not also present in
3805 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
3806 </para>
3807
3808 <para>
3809 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
3810 It is not intended to be user-configurable.
3811 It is best to just reference the variable to see which distro features are
3812 being backfilled for all distro configurations.
Andrew Geissler82c905d2020-04-13 13:39:40 -05003813 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003814 more information.
3815 </para>
3816 </glossdef>
3817 </glossentry>
3818
3819 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
3820 <info>
3821 DISTRO_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from DISTRO_FEATURES_BACKFILL that should not be backfilled (i.e. added to DISTRO_FEATURES) during the build."
3822 </info>
3823 <glossdef>
3824 <para role="glossdeffirst">
3825<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3826 Features from
3827 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
3828 that should not be backfilled (i.e. added to
3829 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
3830 during the build.
3831 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
3832 more information.
3833 </para>
3834 </glossdef>
3835 </glossentry>
3836
3837 <glossentry id='var-DISTRO_FEATURES_DEFAULT'><glossterm>DISTRO_FEATURES_DEFAULT</glossterm>
3838 <info>
3839 DISTRO_FEATURES_DEFAULT[doc] = "Provides the default list of distro features with the exception of any libc-specific features."
3840 </info>
3841 <glossdef>
3842 <para role="glossdeffirst">
3843<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3844 A convenience variable that gives you the default
3845 list of distro features with the exception of any
3846 features specific to the C library
3847 (<filename>libc</filename>).
3848 </para>
3849
3850 <para>
3851 When creating a custom distribution, you might find it
3852 useful to be able to reuse the default
3853 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3854 options without the need to write out the full set.
3855 Here is an example that uses
3856 <filename>DISTRO_FEATURES_DEFAULT</filename> from a
3857 custom distro configuration file:
3858 <literallayout class='monospaced'>
Brad Bishop19323692019-04-05 15:28:33 -04003859 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003860 </literallayout>
3861 </para>
3862 </glossdef>
3863 </glossentry>
3864
Brad Bishop6e60e8b2018-02-01 10:27:11 -05003865 <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVE'><glossterm>DISTRO_FEATURES_FILTER_NATIVE</glossterm>
3866 <info>
3867 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."
3868 </info>
3869 <glossdef>
3870 <para role="glossdeffirst">
3871<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3872 Specifies a list of features that if present in
3873 the target
3874 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3875 value should be included in
3876 <filename>DISTRO_FEATURES</filename> when building native
3877 recipes.
3878 This variable is used in addition to the features
3879 filtered using the
3880 <link linkend='var-DISTRO_FEATURES_NATIVE'><filename>DISTRO_FEATURES_NATIVE</filename></link>
3881 variable.
3882 </para>
3883 </glossdef>
3884 </glossentry>
3885
3886 <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVESDK'><glossterm>DISTRO_FEATURES_FILTER_NATIVESDK</glossterm>
3887 <info>
3888 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."
3889 </info>
3890 <glossdef>
3891 <para role="glossdeffirst">
3892<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3893 Specifies a list of features that if present in the target
3894 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3895 value should be included in
3896 <filename>DISTRO_FEATURES</filename> when building
3897 nativesdk recipes.
3898 This variable is used in addition to the features
3899 filtered using the
3900 <link linkend='var-DISTRO_FEATURES_NATIVESDK'><filename>DISTRO_FEATURES_NATIVESDK</filename></link>
3901 variable.
3902 </para>
3903 </glossdef>
3904 </glossentry>
3905
Brad Bishop19323692019-04-05 15:28:33 -04003906<!--
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003907 <glossentry id='var-DISTRO_FEATURES_LIBC'><glossterm>DISTRO_FEATURES_LIBC</glossterm>
3908 <info>
3909 DISTRO_FEATURES_LIBC[doc] = "Specifies the list of distro features that are specific to the C library (libc)."
3910 </info>
3911 <glossdef>
3912 <para role="glossdeffirst">
Brad Bishop19323692019-04-05 15:28:33 -04003913 <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" />
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003914 A convenience variable that specifies the list of distro
3915 features that are specific to the C library
3916 (<filename>libc</filename>).
3917 Typically, these features are prefixed with "libc-" and
3918 control which features are enabled at during the build
3919 within the C library itself.
3920 </para>
3921 </glossdef>
3922 </glossentry>
Brad Bishop19323692019-04-05 15:28:33 -04003923-->
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003924
Brad Bishop6e60e8b2018-02-01 10:27:11 -05003925 <glossentry id='var-DISTRO_FEATURES_NATIVE'><glossterm>DISTRO_FEATURES_NATIVE</glossterm>
3926 <info>
3927 DISTRO_FEATURES_NATIVE[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building native recipes."
3928 </info>
3929 <glossdef>
3930 <para role="glossdeffirst">
3931<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3932 Specifies a list of features that should be included in
3933 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3934 when building native recipes.
3935 This variable is used in addition to the features
3936 filtered using the
3937 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVE'><filename>DISTRO_FEATURES_FILTER_NATIVE</filename></link>
3938 variable.
3939 </para>
3940 </glossdef>
3941 </glossentry>
3942
3943 <glossentry id='var-DISTRO_FEATURES_NATIVESDK'><glossterm>DISTRO_FEATURES_NATIVESDK</glossterm>
3944 <info>
3945 DISTRO_FEATURES_NATIVESDK[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building nativesdk recipes."
3946 </info>
3947 <glossdef>
3948 <para role="glossdeffirst">
3949<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3950 Specifies a list of features that should be included in
3951 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3952 when building nativesdk recipes.
3953 This variable is used in addition to the features
3954 filtered using the
3955 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVESDK'><filename>DISTRO_FEATURES_FILTER_NATIVESDK</filename></link>
3956 variable.
3957 </para>
3958 </glossdef>
3959 </glossentry>
3960
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003961 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
3962 <info>
3963 DISTRO_NAME[doc] = "The long name of the distribution."
3964 </info>
3965 <glossdef>
3966 <para role="glossdeffirst">
3967<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3968 The long name of the distribution.
Brad Bishopd5ae7d92018-06-14 09:52:03 -07003969 For information on the short name of the distribution, see
3970 the
3971 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
3972 variable.
3973 </para>
3974
3975 <para>
3976 The <filename>DISTRO_NAME</filename> variable corresponds
3977 to a distribution configuration file whose root name is the
3978 same as the variable's argument and whose filename
3979 extension is <filename>.conf</filename>.
3980 For example, the distribution configuration file for the
3981 Poky distribution is named <filename>poky.conf</filename>
3982 and resides in the
3983 <filename>meta-poky/conf/distro</filename> directory of
3984 the
3985 <link linkend='source-directory'>Source Directory</link>.
3986 </para>
3987
3988 <para>
3989 Within that <filename>poky.conf</filename> file, the
3990 <filename>DISTRO_NAME</filename> variable is set as
3991 follows:
3992 <literallayout class='monospaced'>
3993 DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
3994 </literallayout>
3995 </para>
3996
3997 <para>
3998 Distribution configuration files are located in a
3999 <filename>conf/distro</filename> directory within the
4000 <link linkend='metadata'>Metadata</link>
4001 that contains the distribution configuration.
4002 <note>
4003 If the <filename>DISTRO_NAME</filename> variable is
4004 blank, a set of default configurations are used, which
4005 are specified within
4006 <filename>meta/conf/distro/defaultsetup.conf</filename>
4007 also in the Source Directory.
4008 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004009 </para>
4010 </glossdef>
4011 </glossentry>
4012
4013 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
4014 <info>
4015 DISTRO_VERSION[doc] = "The version of the distribution."
4016 </info>
4017 <glossdef>
4018 <para role="glossdeffirst">
4019<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4020 The version of the distribution.
4021 </para>
4022 </glossdef>
4023 </glossentry>
4024
4025 <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
4026 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004027 DISTROOVERRIDES[doc] = "A colon-separated list of overrides specific to the current distribution."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004028 </info>
4029 <glossdef>
4030 <para role="glossdeffirst">
4031<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004032 A colon-separated list of overrides specific to the
4033 current distribution.
4034 By default, this list includes the value of
4035 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>.
4036 </para>
4037
4038 <para>
4039 You can extend <filename>DISTROOVERRIDES</filename>
4040 to add extra overrides that should apply to
4041 the distribution.
4042 </para>
4043
4044 <para>
4045 The underlying mechanism behind
4046 <filename>DISTROOVERRIDES</filename> is simply that it
4047 is included in the default value of
4048 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004049 </para>
4050 </glossdef>
4051 </glossentry>
4052
4053 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
4054 <info>
4055 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."
4056 </info>
4057 <glossdef>
4058 <para role="glossdeffirst">
4059<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4060 The central download directory used by the build process to
4061 store downloads.
4062 By default, <filename>DL_DIR</filename> gets files
4063 suitable for mirroring for everything except Git
4064 repositories.
4065 If you want tarballs of Git repositories, use the
4066 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
4067 variable.
4068 </para>
4069
4070 <para>
4071 You can set this directory by defining the
4072 <filename>DL_DIR</filename> variable in the
4073 <filename>conf/local.conf</filename> file.
4074 This directory is self-maintaining and you should not have
4075 to touch it.
4076 By default, the directory is <filename>downloads</filename>
4077 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004078 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004079 <literallayout class='monospaced'>
4080 #DL_DIR ?= "${TOPDIR}/downloads"
4081 </literallayout>
4082 To specify a different download directory, simply remove
4083 the comment from the line and provide your directory.
4084 </para>
4085
4086 <para>
4087 During a first build, the system downloads many different
4088 source code tarballs from various upstream projects.
4089 Downloading can take a while, particularly if your network
4090 connection is slow.
4091 Tarballs are all stored in the directory defined by
4092 <filename>DL_DIR</filename> and the build system looks there
4093 first to find source tarballs.
4094 <note>
4095 When wiping and rebuilding, you can preserve this
4096 directory to speed up this part of subsequent
4097 builds.
4098 </note>
4099 </para>
4100
4101 <para>
4102 You can safely share this directory between multiple builds
4103 on the same development machine.
4104 For additional information on how the build process gets
4105 source files when working behind a firewall or proxy server,
4106 see this specific question in the
4107 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
4108 chapter.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05004109 You can also refer to the
4110 "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
4111 Wiki page.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004112 </para>
4113 </glossdef>
4114 </glossentry>
4115
4116 <glossentry id='var-DOC_COMPRESS'><glossterm>DOC_COMPRESS</glossterm>
4117 <info>
4118 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."
4119 </info>
4120 <glossdef>
4121 <para role="glossdeffirst">
4122<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4123 When inheriting the
4124 <link linkend='ref-classes-compress_doc'><filename>compress_doc</filename></link>
4125 class, this variable sets the compression policy used when
4126 the OpenEmbedded build system compresses man pages and info
4127 pages.
4128 By default, the compression method used is gz (gzip).
4129 Other policies available are xz and bz2.
4130 </para>
4131
4132 <para>
4133 For information on policies and on how to use this
4134 variable, see the comments in the
4135 <filename>meta/classes/compress_doc.bbclass</filename> file.
4136 </para>
4137 </glossdef>
4138 </glossentry>
4139
4140 </glossdiv>
4141
4142 <glossdiv id='var-glossary-e'><title>E</title>
4143
4144 <glossentry id='var-EFI_PROVIDER'><glossterm>EFI_PROVIDER</glossterm>
4145 <info>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004146 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004147 </info>
4148 <glossdef>
4149 <para role="glossdeffirst">
4150<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4151 When building bootable images (i.e. where
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004152 <filename>hddimg</filename>, <filename>iso</filename>,
4153 or <filename>wic.vmdk</filename> is in
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004154 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>),
4155 the <filename>EFI_PROVIDER</filename> variable specifies
4156 the EFI bootloader to use.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004157 The default is "grub-efi", but "systemd-boot" can be used
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004158 instead.
4159 </para>
4160
4161 <para>
4162 See the
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004163 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05004164 and
4165 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
4166 classes for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004167 </para>
4168 </glossdef>
4169 </glossentry>
4170
4171 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
4172 <info>
4173 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."
4174 </info>
4175 <glossdef>
4176 <para role="glossdeffirst">
4177<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4178 Variable that controls which locales for
4179 <filename>glibc</filename> are generated during the
4180 build (useful if the target device has 64Mbytes
4181 of RAM or less).
4182 </para>
4183 </glossdef>
4184 </glossentry>
4185
4186 <glossentry id='var-ERR_REPORT_DIR'><glossterm>ERR_REPORT_DIR</glossterm>
4187 <info>
4188 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."
4189 </info>
4190 <glossdef>
4191 <para role="glossdeffirst">
4192<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4193 When used with the
4194 <link linkend='ref-classes-report-error'><filename>report-error</filename></link>
4195 class, specifies the path used for storing the debug files
4196 created by the
4197 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
4198 which allows you to submit build errors you encounter to a
4199 central database.
4200 By default, the value of this variable is
4201 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
4202 </para>
4203
4204 <para>
4205 You can set <filename>ERR_REPORT_DIR</filename> to the path
4206 you want the error reporting tool to store the debug files
4207 as follows in your <filename>local.conf</filename> file:
4208 <literallayout class='monospaced'>
4209 ERR_REPORT_DIR = "<replaceable>path</replaceable>"
4210 </literallayout>
4211 </para>
4212 </glossdef>
4213 </glossentry>
4214
4215 <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
4216 <info>
4217 ERROR_QA[doc] = "Specifies the quality assurance checks whose failures are reported as errors by the OpenEmbedded build system."
4218 </info>
4219 <glossdef>
4220 <para role="glossdeffirst">
4221<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4222 Specifies the quality assurance checks whose failures are
4223 reported as errors by the OpenEmbedded build system.
4224 You set this variable in your distribution configuration
4225 file.
4226 For a list of the checks you can control with this variable,
4227 see the
4228 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
4229 section.
4230 </para>
4231 </glossdef>
4232 </glossentry>
4233
Patrick Williamsf1e5d692016-03-30 15:21:19 -05004234 <glossentry id='var-EXCLUDE_FROM_SHLIBS'><glossterm>EXCLUDE_FROM_SHLIBS</glossterm>
4235 <info>
4236 EXCLUDE_FROM_SHLIBS[doc] = "Causes the OpenEmbedded build system's shared libraries resolver to exclude an entire package when scanning for shared libraries."
4237 </info>
4238 <glossdef>
4239 <para role="glossdeffirst">
4240<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4241 Triggers the OpenEmbedded build system's shared libraries
4242 resolver to exclude an entire package when scanning for
4243 shared libraries.
4244 <note>
4245 The shared libraries resolver's functionality results
4246 in part from the internal function
4247 <filename>package_do_shlibs</filename>, which is part of
4248 the
4249 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
4250 task.
4251 You should be aware that the shared libraries resolver
4252 might implicitly define some dependencies between
4253 packages.
4254 </note>
4255 The <filename>EXCLUDE_FROM_SHLIBS</filename> variable is
4256 similar to the
4257 <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
4258 variable, which excludes a package's particular libraries
4259 only and not the whole package.
4260 </para>
4261
4262 <para>
4263 Use the
4264 <filename>EXCLUDE_FROM_SHLIBS</filename> variable by
4265 setting it to "1" for a particular package:
4266 <literallayout class='monospaced'>
4267 EXCLUDE_FROM_SHLIBS = "1"
4268 </literallayout>
4269 </para>
4270 </glossdef>
4271 </glossentry>
4272
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004273 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
4274 <info>
4275 EXCLUDE_FROM_WORLD[doc] = "Directs BitBake to exclude a recipe from world builds (i.e. bitbake world)."
4276 </info>
4277 <glossdef>
4278 <para role="glossdeffirst">
4279<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4280 Directs BitBake to exclude a recipe from world builds (i.e.
4281 <filename>bitbake world</filename>).
4282 During world builds, BitBake locates, parses and builds all
4283 recipes found in every layer exposed in the
4284 <filename>bblayers.conf</filename> configuration file.
4285 </para>
4286
4287 <para>
4288 To exclude a recipe from a world build using this variable,
4289 set the variable to "1" in the recipe.
4290 </para>
4291
4292 <note>
4293 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
4294 may still be built during a world build in order to satisfy
4295 dependencies of other recipes.
4296 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
4297 only ensures that the recipe is not explicitly added
4298 to the list of build targets in a world build.
4299 </note>
4300 </glossdef>
4301 </glossentry>
4302
4303 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
4304 <info>
4305 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."
4306 </info>
4307 <glossdef>
4308 <para role="glossdeffirst">
4309<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4310 Used with file and pathnames to create a prefix for a recipe's
4311 version based on the recipe's
4312 <link linkend='var-PE'><filename>PE</filename></link> value.
4313 If <filename>PE</filename> is set and greater than zero for a recipe,
4314 <filename>EXTENDPE</filename> becomes that value (e.g if
4315 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
4316 becomes "1_").
4317 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
4318 zero, <filename>EXTENDPE</filename> becomes "".</para>
4319 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
4320 variable for an example.
4321 </para>
4322 </glossdef>
4323 </glossentry>
4324
4325 <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
4326 <info>
4327 EXTENDPKGV[doc] = "The full package version specification as it appears on the final packages produced by a recipe."
4328 </info>
4329 <glossdef>
4330 <para role="glossdeffirst">
4331<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4332 The full package version specification as it appears on the
4333 final packages produced by a recipe.
4334 The variable's value is normally used to fix a runtime
4335 dependency to the exact same version of another package
4336 in the same recipe:
4337 <literallayout class='monospaced'>
4338 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
4339 </literallayout>
4340 </para>
4341
4342 <para>
4343 The dependency relationships are intended to force the
4344 package manager to upgrade these types of packages in
4345 lock-step.
4346 </para>
4347 </glossdef>
4348 </glossentry>
4349
4350 <glossentry id='var-EXTERNAL_KERNEL_TOOLS'><glossterm>EXTERNAL_KERNEL_TOOLS</glossterm>
4351 <info>
4352 EXTERNAL_KERNEL_TOOLS[doc] = "Indicates kernel tools are external to the source tree."
4353 </info>
4354 <glossdef>
4355 <para role="glossdeffirst">
4356<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4357 When set, the <filename>EXTERNAL_KERNEL_TOOLS</filename>
4358 variable indicates that these tools are not in the
4359 source tree.
4360 </para>
4361
4362 <para>
4363 When kernel tools are available in the tree, they are
4364 preferred over any externally installed tools.
4365 Setting the <filename>EXTERNAL_KERNEL_TOOLS</filename>
4366 variable tells the OpenEmbedded build system to prefer
4367 the installed external tools.
4368 See the
4369 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
4370 class in <filename>meta/classes</filename> to see how
4371 the variable is used.
4372 </para>
4373 </glossdef>
4374 </glossentry>
4375
4376 <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
4377 <info>
4378 EXTERNALSRC[doc] = "If externalsrc.bbclass is inherited, this variable points to the source tree, which is outside of the OpenEmbedded build system."
4379 </info>
4380 <glossdef>
4381 <para role="glossdeffirst">
4382<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4383 When inheriting the
4384 <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link>
4385 class, this variable points to the source tree, which is
4386 outside of the OpenEmbedded build system.
4387 When set, this variable sets the
4388 <link linkend='var-S'><filename>S</filename></link>
4389 variable, which is what the OpenEmbedded build system uses
4390 to locate unpacked recipe source code.
4391 </para>
4392
4393 <para>
4394 For more information on
4395 <filename>externalsrc.bbclass</filename>, see the
4396 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
4397 section.
4398 You can also find information on how to use this variable
4399 in the
4400 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004401 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004402 </para>
4403 </glossdef>
4404 </glossentry>
4405
4406 <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
4407 <info>
4408 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."
4409 </info>
4410 <glossdef>
4411 <para role="glossdeffirst">
4412<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4413 When inheriting the
4414 <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link>
4415 class, this variable points to the directory in which the
4416 recipe's source code is built, which is outside of the
4417 OpenEmbedded build system.
4418 When set, this variable sets the
4419 <link linkend='var-B'><filename>B</filename></link>
4420 variable, which is what the OpenEmbedded build system uses
4421 to locate the Build Directory.
4422 </para>
4423
4424 <para>
4425 For more information on
4426 <filename>externalsrc.bbclass</filename>, see the
4427 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
4428 section.
4429 You can also find information on how to use this variable
4430 in the
4431 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004432 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004433 </para>
4434 </glossdef>
4435 </glossentry>
4436
4437 <glossentry id='var-EXTRA_AUTORECONF'><glossterm>EXTRA_AUTORECONF</glossterm>
4438 <info>
4439 EXTRA_AUTORECONF[doc] = "Extra options passed to the autoreconf command, which is executed during do_configure."
4440 </info>
4441 <glossdef>
4442 <para role="glossdeffirst">
4443<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4444 For recipes inheriting the
4445 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
4446 class, you can use <filename>EXTRA_AUTORECONF</filename> to
4447 specify extra options to pass to the
4448 <filename>autoreconf</filename> command that is
4449 executed during the
4450 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
4451 task.
4452 </para>
4453
4454 <para>
4455 The default value is "--exclude=autopoint".
4456 </para>
4457 </glossdef>
4458 </glossentry>
4459
4460 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
4461 <info>
4462 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."
4463 </info>
4464 <glossdef>
4465 <para role="glossdeffirst">
4466<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4467 A list of additional features to include in an image.
4468 When listing more than one feature, separate them with
4469 a space.
4470 </para>
4471
4472 <para>
4473 Typically, you configure this variable in your
4474 <filename>local.conf</filename> file, which is found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004475 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004476 Although you can use this variable from within a recipe,
4477 best practices dictate that you do not.
4478 <note>
4479 To enable primary features from within the image
4480 recipe, use the
4481 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
4482 variable.
4483 </note>
4484 </para>
4485
4486 <para>
4487 Here are some examples of features you can add:
4488 <literallayout class='monospaced'>
4489"dbg-pkgs" - Adds -dbg packages for all installed packages
4490 including symbol information for debugging and
4491 profiling.
4492
4493"debug-tweaks" - Makes an image suitable for debugging.
4494 For example, allows root logins without
4495 passwords and enables post-installation
4496 logging. See the 'allow-empty-password'
4497 and 'post-install-logging' features in
4498 the "<link linkend='ref-features-image'>Image Features</link>" section for
4499 more information.
4500
4501"dev-pkgs" - Adds -dev packages for all installed packages.
4502 This is useful if you want to develop against
4503 the libraries in the image.
4504
4505"read-only-rootfs" - Creates an image whose root
4506 filesystem is read-only. See the
4507 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
4508 section in the Yocto Project
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004509 Development Tasks Manual for
4510 more information
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004511
4512"tools-debug" - Adds debugging tools such as gdb and
4513 strace.
4514
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004515"tools-sdk" - Adds development tools such as gcc, make,
4516 pkgconfig and so forth.
4517
4518"tools-testapps" - Adds useful testing tools such as
4519 ts_print, aplay, arecord and so
4520 forth.
4521
4522 </literallayout>
4523 </para>
4524
4525 <para>
4526 For a complete list of image features that ships with the
4527 Yocto Project, see the
4528 "<link linkend="ref-features-image">Image Features</link>"
4529 section.
4530 </para>
4531
4532 <para>
4533 For an example that shows how to customize your image by
4534 using this variable, see the
4535 "<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>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004536 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004537 </para>
4538 </glossdef>
4539 </glossentry>
4540
4541 <glossentry id='var-EXTRA_IMAGECMD'><glossterm>EXTRA_IMAGECMD</glossterm>
4542 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04004543 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004544 </info>
4545 <glossdef>
4546 <para role="glossdeffirst">
4547<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4548 Specifies additional options for the image
4549 creation command that has been specified in
4550 <link linkend='var-IMAGE_CMD'><filename>IMAGE_CMD</filename></link>.
Brad Bishop316dfdd2018-06-25 12:45:53 -04004551 When setting this variable, use an override for the
4552 associated image type.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004553 Here is an example:
4554 <literallayout class='monospaced'>
4555 EXTRA_IMAGECMD_ext3 ?= "-i 4096"
4556 </literallayout>
4557 </para>
4558 </glossdef>
4559 </glossentry>
4560
4561 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
4562 <info>
4563 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."
4564 </info>
4565 <glossdef>
4566 <para role="glossdeffirst">
4567<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4568 A list of recipes to build that do not provide packages
4569 for installing into the root filesystem.
4570 </para>
4571
4572 <para>
4573 Sometimes a recipe is required to build the final image but is not
4574 needed in the root filesystem.
4575 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
4576 list these recipes and thus specify the dependencies.
4577 A typical example is a required bootloader in a machine configuration.
4578 </para>
4579
4580 <note>
4581 To add packages to the root filesystem, see the various
4582 <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
4583 and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
4584 variables.
4585 </note>
4586 </glossdef>
4587 </glossentry>
4588
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004589 <glossentry id='var-EXTRANATIVEPATH'><glossterm>EXTRANATIVEPATH</glossterm>
4590 <info>
4591 EXTRANATIVEPATH[doc] = "A list of subdirectories of ${STAGING_BINDIR_NATIVE} added to the beginning of the environment variable PATH."
4592 </info>
4593 <glossdef>
4594 <para role="glossdeffirst">
4595<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4596 A list of subdirectories of
4597 <filename>${</filename><link linkend='var-STAGING_BINDIR_NATIVE'><filename>STAGING_BINDIR_NATIVE</filename></link><filename>}</filename>
4598 added to the beginning of the environment variable
4599 <filename>PATH</filename>.
4600 As an example, the following prepends
4601 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:"
4602 to <filename>PATH</filename>:
4603 <literallayout class='monospaced'>
4604 EXTRANATIVEPATH = "foo bar"
4605 </literallayout>
4606 </para>
4607 </glossdef>
4608 </glossentry>
4609
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004610 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
4611 <info>
4612 EXTRA_OECMAKE[doc] = "Additional cmake options."
4613 </info>
4614 <glossdef>
4615 <para role="glossdeffirst">
4616<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08004617 Additional
4618 <ulink url='https://cmake.org/overview/'>CMake</ulink>
4619 options.
4620 See the
4621 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
4622 class for additional information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004623 </para>
4624 </glossdef>
4625 </glossentry>
4626
4627 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
4628 <info>
4629 EXTRA_OECONF[doc] = "Additional configure script options."
4630 </info>
4631 <glossdef>
4632 <para role="glossdeffirst">
4633<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4634 Additional <filename>configure</filename> script options.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004635 See
4636 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>
4637 for additional information on passing configure script
4638 options.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004639 </para>
4640 </glossdef>
4641 </glossentry>
4642
4643 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
4644 <info>
4645 EXTRA_OEMAKE[doc] = "Additional GNU make options."
4646 </info>
4647 <glossdef>
4648 <para role="glossdeffirst">
4649<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4650 Additional GNU <filename>make</filename> options.
4651 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05004652
4653 <para>
4654 Because the <filename>EXTRA_OEMAKE</filename> defaults to
4655 "", you need to set the variable to specify any required
4656 GNU options.
4657 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004658
4659 <para>
4660 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
4661 and
4662 <link linkend='var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></link>
4663 also make use of
4664 <filename>EXTRA_OEMAKE</filename> to pass the required
4665 flags.
4666 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004667 </glossdef>
4668 </glossentry>
4669
4670 <glossentry id='var-EXTRA_OESCONS'><glossterm>EXTRA_OESCONS</glossterm>
4671 <info>
4672 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."
4673 </info>
4674 <glossdef>
4675 <para role="glossdeffirst">
4676<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4677 When inheriting the
4678 <link linkend='ref-classes-scons'><filename>scons</filename></link>
4679 class, this variable specifies additional configuration
4680 options you want to pass to the
4681 <filename>scons</filename> command line.
4682 </para>
4683 </glossdef>
4684 </glossentry>
4685
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004686 <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm>
4687 <info>
4688 EXTRA_USERS_PARAMS[doc] = "When a recipe inherits the extrausers class, this variable provides image level user and group operations."
4689 </info>
4690 <glossdef>
4691 <para role="glossdeffirst">
4692<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4693 When inheriting the
4694 <link linkend='ref-classes-extrausers'><filename>extrausers</filename></link>
4695 class, this variable provides image level user and group
4696 operations.
4697 This is a more global method of providing user and group
4698 configuration as compared to using the
4699 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
4700 class, which ties user and group configurations to a
4701 specific recipe.
4702 </para>
4703
4704 <para>
4705 The set list of commands you can configure using the
4706 <filename>EXTRA_USERS_PARAMS</filename> is shown in the
4707 <filename>extrausers</filename> class.
4708 These commands map to the normal Unix commands of the same
4709 names:
4710 <literallayout class='monospaced'>
4711 # EXTRA_USERS_PARAMS = "\
4712 # useradd -p '' tester; \
4713 # groupadd developers; \
4714 # userdel nobody; \
4715 # groupdel -g video; \
4716 # groupmod -g 1020 developers; \
4717 # usermod -s /bin/sh tester; \
4718 # "
4719 </literallayout>
4720 </para>
4721 </glossdef>
4722 </glossentry>
4723
4724 </glossdiv>
4725
4726 <glossdiv id='var-glossary-f'><title>F</title>
4727
4728 <glossentry id='var-FEATURE_PACKAGES'><glossterm>FEATURE_PACKAGES</glossterm>
4729 <info>
4730 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."
4731 </info>
4732 <glossdef>
4733 <para role="glossdeffirst">
4734<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4735 Defines one or more packages to include in an image when
4736 a specific item is included in
4737 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
4738 When setting the value, <filename>FEATURE_PACKAGES</filename>
4739 should have the name of the feature item as an override.
4740 Here is an example:
4741 <literallayout class='monospaced'>
4742 FEATURE_PACKAGES_widget = "<replaceable>package1</replaceable> <replaceable>package2</replaceable>"
4743 </literallayout>
4744 </para>
4745
4746 <para>
4747 In this example, if "widget" were added to
4748 <filename>IMAGE_FEATURES</filename>, <replaceable>package1</replaceable> and
4749 <replaceable>package2</replaceable> would be included in the image.
4750 <note>
4751 Packages installed by features defined through
4752 <filename>FEATURE_PACKAGES</filename> are often package
4753 groups.
4754 While similarly named, you should not confuse the
4755 <filename>FEATURE_PACKAGES</filename> variable with
4756 package groups, which are discussed elsewhere in the
4757 documentation.
4758 </note>
4759 </para>
4760 </glossdef>
4761 </glossentry>
4762
4763 <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm>
4764 <info>
4765 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."
4766 </info>
4767 <glossdef>
4768 <para role="glossdeffirst">
4769<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4770 Points to the base URL of the server and location within
4771 the document-root that provides the metadata and
4772 packages required by OPKG to support runtime package
4773 management of IPK packages.
4774 You set this variable in your
4775 <filename>local.conf</filename> file.
4776 </para>
4777
4778 <para>
4779 Consider the following example:
4780 <literallayout class='monospaced'>
4781 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
4782 </literallayout>
4783 This example assumes you are serving your packages over
4784 HTTP and your databases are located in a directory
4785 named <filename>BOARD-dir</filename>, which is underneath
4786 your HTTP server's document-root.
4787 In this case, the OpenEmbedded build system generates a set
4788 of configuration files for you in your target that work
4789 with the feed.
4790 </para>
4791 </glossdef>
4792 </glossentry>
4793
4794 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
4795 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004796 FILES[doc] = "The list of directories or files that are placed in a package."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004797 </info>
4798 <glossdef>
4799 <para role="glossdeffirst">
4800<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004801 The list of files and directories that are placed in a
4802 package.
4803 The
4804 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
4805 variable lists the packages generated by a recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004806 </para>
4807
4808 <para>
4809 To use the <filename>FILES</filename> variable, provide a
4810 package name override that identifies the resulting package.
4811 Then, provide a space-separated list of files or paths
4812 that identify the files you want included as part of the
4813 resulting package.
4814 Here is an example:
4815 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004816 FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004817 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08004818 <note><title>Notes</title>
4819 <itemizedlist>
4820 <listitem><para>
4821 When specifying files or paths, you can pattern
4822 match using Python's
4823 <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>
4824 syntax.
4825 For details on the syntax, see the
4826 documentation by following the previous link.
4827 </para></listitem>
4828 <listitem><para>
4829 When specifying paths as part of the
4830 <filename>FILES</filename> variable, it is
4831 good practice to use appropriate path
4832 variables.
4833 For example, use <filename>${sysconfdir}</filename>
4834 rather than <filename>/etc</filename>, or
4835 <filename>${bindir}</filename> rather than
4836 <filename>/usr/bin</filename>.
4837 You can find a list of these variables at the
4838 top of the
4839 <filename>meta/conf/bitbake.conf</filename>
4840 file in the
4841 <link linkend='source-directory'>Source Directory</link>.
4842 You will also find the default values of the
4843 various <filename>FILES_*</filename> variables
4844 in this file.
4845 </para></listitem>
4846 </itemizedlist>
4847 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004848 </para>
4849
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004850 <para>
4851 If some of the files you provide with the
4852 <filename>FILES</filename> variable are editable and you
4853 know they should not be overwritten during the package
4854 update process by the Package Management System (PMS), you
4855 can identify these files so that the PMS will not
4856 overwrite them.
4857 See the
4858 <link linkend='var-CONFFILES'><filename>CONFFILES</filename></link>
4859 variable for information on how to identify these files to
4860 the PMS.
4861 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004862 </glossdef>
4863 </glossentry>
4864
4865 <glossentry id='var-FILES_SOLIBSDEV'><glossterm>FILES_SOLIBSDEV</glossterm>
4866 <info>
4867 FILES_SOLIBSDEV[doc] = "Defines the full path name of the development symbolic link (symlink) for shared libraries on the target platform."
4868 </info>
4869 <glossdef>
4870 <para role="glossdeffirst">
4871<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4872 Defines the file specification to match
4873 <link linkend='var-SOLIBSDEV'><filename>SOLIBSDEV</filename></link>.
4874 In other words, <filename>FILES_SOLIBSDEV</filename>
4875 defines the full path name of the development symbolic link
4876 (symlink) for shared libraries on the target platform.
4877 </para>
4878
4879 <para>
4880 The following statement from the
4881 <filename>bitbake.conf</filename> shows how it is set:
4882 <literallayout class='monospaced'>
4883 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
4884 </literallayout>
4885 </para>
4886 </glossdef>
4887 </glossentry>
4888
4889 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
4890 <info>
4891 FILESEXTRAPATHS[doc] = "Extends the search path the OpenEmbedded build system uses when looking for files and patches as it processes recipes and append files."
4892 </info>
4893 <glossdef>
4894 <para role="glossdeffirst">
4895<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4896 Extends the search path the OpenEmbedded build system uses
4897 when looking for files and patches as it processes recipes
4898 and append files.
4899 The default directories BitBake uses when it processes
4900 recipes are initially defined by the
4901 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4902 variable.
4903 You can extend <filename>FILESPATH</filename> variable
4904 by using <filename>FILESEXTRAPATHS</filename>.
4905 </para>
4906
4907 <para>
4908 Best practices dictate that you accomplish this by using
4909 <filename>FILESEXTRAPATHS</filename> from within a
4910 <filename>.bbappend</filename> file and that you prepend
4911 paths as follows:
4912 <literallayout class='monospaced'>
4913 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
4914 </literallayout>
4915 In the above example, the build system first looks for files
4916 in a directory that has the same name as the corresponding
4917 append file.
4918 <note>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004919 <para>When extending
4920 <filename>FILESEXTRAPATHS</filename>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004921 be sure to use the immediate expansion
4922 (<filename>:=</filename>) operator.
4923 Immediate expansion makes sure that BitBake evaluates
4924 <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
4925 at the time the directive is encountered rather than at
4926 some later time when expansion might result in a
4927 directory that does not contain the files you need.
4928 </para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004929
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004930 <para>Also, include the trailing separating colon
4931 character if you are prepending.
4932 The trailing colon character is necessary because you
4933 are directing BitBake to extend the path by prepending
4934 directories to the search path.</para>
4935 </note>
4936 Here is another common use:
4937 <literallayout class='monospaced'>
4938 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
4939 </literallayout>
4940 In this example, the build system extends the
4941 <filename>FILESPATH</filename> variable to include a
4942 directory named <filename>files</filename> that is in the
4943 same directory as the corresponding append file.
4944 </para>
4945
4946 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004947 This next example specifically adds three paths:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004948 <literallayout class='monospaced'>
4949 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
4950 </literallayout>
4951 </para>
4952
4953 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004954 A final example shows how you can extend the search path
4955 and include a
4956 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>-specific
4957 override, which is useful in a BSP layer:
4958 <literallayout class='monospaced'>
4959 FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:"
4960 </literallayout>
4961 The previous statement appears in the
4962 <filename>linux-yocto-dev.bbappend</filename> file, which
4963 is found in the Yocto Project
Brad Bishop316dfdd2018-06-25 12:45:53 -04004964 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004965 in
4966 <filename>meta-intel/common/recipes-kernel/linux</filename>.
4967 Here, the machine override is a special
4968 <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
4969 definition for multiple <filename>meta-intel</filename>
4970 machines.
4971 <note>
4972 For a layer that supports a single BSP, the override
4973 could just be the value of <filename>MACHINE</filename>.
4974 </note>
4975 </para>
4976
4977 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004978 By prepending paths in <filename>.bbappend</filename>
4979 files, you allow multiple append files that reside in
4980 different layers but are used for the same recipe to
4981 correctly extend the path.
4982 </para>
4983 </glossdef>
4984 </glossentry>
4985
4986 <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
4987 <info>
4988 FILESOVERRIDES[doc] = "A subset of OVERRIDES used by the OpenEmbedded build system for creating FILESPATH."
4989 </info>
4990 <glossdef>
4991 <para role="glossdeffirst">
4992<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4993 A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
4994 used by the OpenEmbedded build system for creating
4995 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
Brad Bishop19323692019-04-05 15:28:33 -04004996 The <filename>FILESOVERRIDES</filename> variable uses
4997 overrides to automatically extend the
4998 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4999 variable.
5000 For an example of how that works, see the
5001 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
5002 variable description.
5003 Additionally, you find more information on how overrides
5004 are handled in the
5005 "<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"
5006 section of the BitBake User Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005007 </para>
5008
5009 <para>
5010 By default, the <filename>FILESOVERRIDES</filename>
5011 variable is defined as:
5012 <literallayout class='monospaced'>
5013 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
5014 </literallayout>
5015
5016 <note>
5017 Do not hand-edit the <filename>FILESOVERRIDES</filename>
5018 variable.
5019 The values match up with expected overrides and are
5020 used in an expected manner by the build system.
5021 </note>
5022 </para>
5023 </glossdef>
5024 </glossentry>
5025
5026 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
5027 <info>
5028 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."
5029 </info>
5030 <glossdef>
5031 <para role="glossdeffirst">
5032<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop19323692019-04-05 15:28:33 -04005033 The default set of directories the OpenEmbedded build
5034 system uses when searching for patches and files.
5035 </para>
5036
5037 <para>
5038 During the build process, BitBake searches each directory
5039 in <filename>FILESPATH</filename> in the specified order
5040 when looking for files and patches specified by each
Brad Bishop316dfdd2018-06-25 12:45:53 -04005041 <filename>file://</filename> URI in a recipe's
5042 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
5043 statements.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005044 </para>
5045
5046 <para>
5047 The default value for the <filename>FILESPATH</filename>
5048 variable is defined in the <filename>base.bbclass</filename>
5049 class found in <filename>meta/classes</filename> in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005050 <link linkend='source-directory'>Source Directory</link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005051 <literallayout class='monospaced'>
5052 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
5053 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
5054 </literallayout>
Brad Bishop19323692019-04-05 15:28:33 -04005055 The <filename>FILESPATH</filename> variable is automatically
5056 extended using the overrides from the
5057 <link linkend='var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></link>
5058 variable.
5059 <note><title>Notes</title>
5060 <itemizedlist>
5061 <listitem><para>
5062 Do not hand-edit the
5063 <filename>FILESPATH</filename> variable.
5064 If you want the build system to look in
5065 directories other than the defaults, extend the
5066 <filename>FILESPATH</filename> variable by
5067 using the
5068 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
5069 variable.
5070 </para></listitem>
5071 <listitem><para>
5072 Be aware that the default
5073 <filename>FILESPATH</filename> directories do
5074 not map to directories in custom layers
5075 where append files
5076 (<filename>.bbappend</filename>) are used.
5077 If you want the build system to find patches
5078 or files that reside with your append files,
5079 you need to extend the
5080 <filename>FILESPATH</filename> variable by
5081 using the <filename>FILESEXTRAPATHS</filename>
5082 variable.
5083 </para></listitem>
5084 </itemizedlist>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005085 </note>
Brad Bishop19323692019-04-05 15:28:33 -04005086 </para>
5087
5088 <para>
5089 You can take advantage of this searching behavior in
5090 useful ways.
5091 For example, consider a case where the following
5092 directory structure exists for general and machine-specific
5093 configurations:
5094 <literallayout class='monospaced'>
5095 files/defconfig
5096 files/MACHINEA/defconfig
5097 files/MACHINEB/defconfig
5098 </literallayout>
5099 Also in the example, the <filename>SRC_URI</filename>
5100 statement contains "file://defconfig".
5101 Given this scenario, you can set
5102 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
5103 to "MACHINEA" and cause the build system to use files
5104 from <filename>files/MACHINEA</filename>.
5105 Set <filename>MACHINE</filename> to "MACHINEB" and the
5106 build system uses files from
5107 <filename>files/MACHINEB</filename>.
5108 Finally, for any machine other than "MACHINEA" and
5109 "MACHINEB", the build system uses files from
5110 <filename>files/defconfig</filename>.
Brad Bishop316dfdd2018-06-25 12:45:53 -04005111 </para>
5112
5113 <para>
5114 You can find out more about the patching process in the
5115 "<ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>Patching</ulink>"
5116 section in the Yocto Project Overview and Concepts Manual
5117 and the
5118 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code'>Patching Code</ulink>"
5119 section in the Yocto Project Development Tasks Manual.
5120 See the
5121 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
5122 task as well.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005123 </para>
5124 </glossdef>
5125 </glossentry>
5126
5127 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
5128 <info>
5129 FILESYSTEM_PERMS_TABLES[doc] = "Allows you to define your own file permissions settings table as part of your configuration for the packaging process."
5130 </info>
5131 <glossdef>
5132 <para role="glossdeffirst">
5133<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5134 Allows you to define your own file permissions settings table as part of
5135 your configuration for the packaging process.
5136 For example, suppose you need a consistent set of custom permissions for
5137 a set of groups and users across an entire work project.
5138 It is best to do this in the packages themselves but this is not always
5139 possible.
5140 </para>
5141
5142 <para>
5143 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
5144 is located in the <filename>meta/files</filename> folder in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005145 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005146 If you create your own file permissions setting table, you should place it in your
5147 layer or the distro's layer.
5148 </para>
5149
5150 <para>
5151 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
5152 <filename>conf/local.conf</filename> file, which is found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005153 <link linkend='build-directory'>Build Directory</link>, to
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005154 point to your custom <filename>fs-perms.txt</filename>.
5155 You can specify more than a single file permissions setting table.
5156 The paths you specify to these files must be defined within the
5157 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
5158 </para>
5159
5160 <para>
5161 For guidance on how to create your own file permissions settings table file,
5162 examine the existing <filename>fs-perms.txt</filename>.
5163 </para>
5164 </glossdef>
5165 </glossentry>
5166
5167 <glossentry id='var-FONT_EXTRA_RDEPENDS'><glossterm>FONT_EXTRA_RDEPENDS</glossterm>
5168 <info>
5169 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'."
5170 </info>
5171 <glossdef>
5172 <para role="glossdeffirst">
5173<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5174 When inheriting the
5175 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
5176 class, this variable specifies the runtime dependencies
5177 for font packages.
5178 By default, the <filename>FONT_EXTRA_RDEPENDS</filename>
5179 is set to "fontconfig-utils".
5180 </para>
5181 </glossdef>
5182 </glossentry>
5183
5184 <glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm>
5185 <info>
5186 FONT_PACKAGES[doc] = "When a recipe inherits the fontcache class, this variable identifies packages containing font files that need to be cached by Fontconfig."
5187 </info>
5188 <glossdef>
5189 <para role="glossdeffirst">
5190<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5191 When inheriting the
5192 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
5193 class, this variable identifies packages containing font
5194 files that need to be cached by Fontconfig.
5195 By default, the <filename>fontcache</filename> class assumes
5196 that fonts are in the recipe's main package
5197 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
5198 Use this variable if fonts you need are in a package
5199 other than that main package.
5200 </para>
5201 </glossdef>
5202 </glossentry>
5203
Patrick Williamsc0f7c042017-02-23 20:41:17 -06005204 <glossentry id='var-FORCE_RO_REMOVE'><glossterm>FORCE_RO_REMOVE</glossterm>
5205 <info>
5206 FORCE_RO_REMOVE[doc] = "Forces the removal of the packages listed in ROOTFS_RO_UNNEEDED during the generation of the root filesystem."
5207 </info>
5208 <glossdef>
5209 <para role="glossdeffirst">
5210<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5211 Forces the removal of the packages listed in
5212 <filename>ROOTFS_RO_UNNEEDED</filename> during the
5213 generation of the root filesystem.
5214 </para>
5215
5216 <para>
5217 Set the variable to "1" to force the removal of these
5218 packages.
5219 </para>
5220 </glossdef>
5221 </glossentry>
5222
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005223 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
5224 <info>
5225 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'."
5226 </info>
5227 <glossdef>
5228 <para role="glossdeffirst">
5229<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5230 The options to pass in
5231 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
5232 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
5233 when compiling an optimized system.
5234 This variable defaults to
5235 "-O2 -pipe ${DEBUG_FLAGS}".
5236 </para>
5237 </glossdef>
5238 </glossentry>
5239 </glossdiv>
5240
5241 <glossdiv id='var-glossary-g'><title>G</title>
5242
Brad Bishop316dfdd2018-06-25 12:45:53 -04005243 <glossentry id='var-GCCPIE'><glossterm>GCCPIE</glossterm>
5244 <info>
5245 GCCPIE[doc] = "Enables Position Independent Executables (PIE) within the GNU C Compiler (GCC)."
5246 </info>
5247 <glossdef>
5248 <para role="glossdeffirst">
5249<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5250 Enables Position Independent Executables (PIE) within the
5251 GNU C Compiler (GCC).
5252 Enabling PIE in the GCC makes Return Oriented Programming
5253 (ROP) attacks much more difficult to
5254 execute.
5255 </para>
5256
5257 <para>
5258 By default the <filename>security_flags.inc</filename>
5259 file enables PIE by setting the variable as follows:
5260 <literallayout class='monospaced'>
5261 GCCPIE ?= "--enable-default-pie"
5262 </literallayout>
5263 </para>
5264 </glossdef>
5265 </glossentry>
5266
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08005267 <glossentry id='var-GCCVERSION'><glossterm>GCCVERSION</glossterm>
5268 <info>
5269 GCCVERSION[doc] = "Specifies the default version of the GNU C Compiler (GCC) to use."
5270 </info>
5271 <glossdef>
5272 <para role="glossdeffirst">
5273<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5274 Specifies the default version of the GNU C Compiler (GCC)
5275 used for compilation.
5276 By default, <filename>GCCVERSION</filename> is set to
5277 "8.x" in the
5278 <filename>meta/conf/distro/include/tcmode-default.inc</filename>
5279 include file:
5280 <literallayout class='monospaced'>
5281 GCCVERSION ?= "8.%"
5282 </literallayout>
5283 You can override this value by setting it in a configuration
5284 file such as the <filename>local.conf</filename>.
5285 </para>
5286 </glossdef>
5287 </glossentry>
5288
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005289 <glossentry id='var-GDB'><glossterm>GDB</glossterm>
5290 <info>
5291 GDB[doc] = "The minimal command and arguments to run the GNU Debugger."
5292 </info>
5293 <glossdef>
5294 <para role="glossdeffirst">
5295<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5296 The minimal command and arguments to run the GNU Debugger.
5297 </para>
5298 </glossdef>
5299 </glossentry>
5300
5301 <glossentry id='var-GITDIR'><glossterm>GITDIR</glossterm>
5302 <info>
5303 GITDIR[doc] = "The directory where Git clones will be stored."
5304 </info>
5305 <glossdef>
5306 <para role="glossdeffirst">
5307<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5308 The directory in which a local copy of a Git repository
5309 is stored when it is cloned.
5310 </para>
5311 </glossdef>
5312 </glossentry>
5313
5314 <glossentry id='var-GLIBC_GENERATE_LOCALES'><glossterm>GLIBC_GENERATE_LOCALES</glossterm>
5315 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04005316 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005317 </info>
5318 <glossdef>
5319 <para role="glossdeffirst">
5320<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5321 Specifies the list of GLIBC locales to generate should you
Brad Bishop316dfdd2018-06-25 12:45:53 -04005322 not wish to generate all LIBC locals, which can be time
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005323 consuming.
5324 <note>
5325 If you specifically remove the locale
5326 <filename>en_US.UTF-8</filename>, you must set
5327 <link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link>
5328 appropriately.
5329 </note>
5330 </para>
5331
5332 <para>
5333 You can set <filename>GLIBC_GENERATE_LOCALES</filename>
5334 in your <filename>local.conf</filename> file.
5335 By default, all locales are generated.
5336 <literallayout class='monospaced'>
5337 GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
5338 </literallayout>
5339 </para>
5340 </glossdef>
5341 </glossentry>
5342
5343 <glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm>
5344 <info>
5345 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."
5346 </info>
5347 <glossdef>
5348 <para role="glossdeffirst">
5349<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5350 When inheriting the
5351 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
5352 class, this variable
5353 specifies for a package what parameters should be passed
5354 to the <filename>groupadd</filename> command
5355 if you wish to add a group to the system when the package
5356 is installed.
5357 </para>
5358
5359 <para>
5360 Here is an example from the <filename>dbus</filename>
5361 recipe:
5362 <literallayout class='monospaced'>
5363 GROUPADD_PARAM_${PN} = "-r netdev"
5364 </literallayout>
5365 For information on the standard Linux shell command
5366 <filename>groupadd</filename>, see
5367 <ulink url='http://linux.die.net/man/8/groupadd'></ulink>.
5368 </para>
5369 </glossdef>
5370 </glossentry>
5371
5372 <glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm>
5373 <info>
5374 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."
5375 </info>
5376 <glossdef>
5377 <para role="glossdeffirst">
5378<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5379 When inheriting the
5380 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
5381 class, this variable
5382 specifies for a package what parameters should be passed
5383 to the <filename>groupmems</filename> command
5384 if you wish to modify the members of a group when the
5385 package is installed.
5386 </para>
5387
5388 <para>
5389 For information on the standard Linux shell command
5390 <filename>groupmems</filename>, see
5391 <ulink url='http://linux.die.net/man/8/groupmems'></ulink>.
5392 </para>
5393 </glossdef>
5394 </glossentry>
5395
5396 <glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm>
5397 <info>
5398 GRUB_GFXSERIAL[doc] = "Configures the GNU GRand Unified Bootloader (GRUB) to have graphics and serial in the boot menu."
5399 </info>
5400 <glossdef>
5401 <para role="glossdeffirst">
5402<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5403 Configures the GNU GRand Unified Bootloader (GRUB) to have
5404 graphics and serial in the boot menu.
5405 Set this variable to "1" in your
5406 <filename>local.conf</filename> or distribution
5407 configuration file to enable graphics and serial
5408 in the menu.
5409 </para>
5410
5411 <para>
5412 See the
5413 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5414 class for more information on how this variable is used.
5415 </para>
5416 </glossdef>
5417 </glossentry>
5418
5419 <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm>
5420 <info>
5421 GRUB_OPTS[doc] = "Additional options to add to the GNU GRand Unified Bootloader (GRUB) configuration."
5422 </info>
5423 <glossdef>
5424 <para role="glossdeffirst">
5425<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5426 Additional options to add to the GNU GRand Unified
5427 Bootloader (GRUB) configuration.
5428 Use a semi-colon character (<filename>;</filename>) to
5429 separate multiple options.
5430 </para>
5431
5432 <para>
5433 The <filename>GRUB_OPTS</filename> variable is optional.
5434 See the
5435 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5436 class for more information on how this variable is used.
5437 </para>
5438 </glossdef>
5439 </glossentry>
5440
5441 <glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm>
5442 <info>
5443 GRUB_TIMEOUT[doc] = "Specifies the timeout before executing the default LABEL in the GNU GRand Unified Bootloader (GRUB)."
5444 </info>
5445 <glossdef>
5446 <para role="glossdeffirst">
5447<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5448 Specifies the timeout before executing the default
5449 <filename>LABEL</filename> in the GNU GRand Unified
5450 Bootloader (GRUB).
5451 </para>
5452
5453 <para>
5454 The <filename>GRUB_TIMEOUT</filename> variable is optional.
5455 See the
5456 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5457 class for more information on how this variable is used.
5458 </para>
5459 </glossdef>
5460 </glossentry>
5461
5462 <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm>
5463 <info>
5464 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."
5465 </info>
5466 <glossdef>
5467 <para role="glossdeffirst">
5468<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5469 When inheriting the
5470 <link linkend='ref-classes-gtk-immodules-cache'><filename>gtk-immodules-cache</filename></link>
5471 class, this variable specifies the packages that contain the
5472 GTK+ input method modules being installed when the modules
5473 are in packages other than the main package.
5474 </para>
5475 </glossdef>
5476 </glossentry>
5477
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005478 </glossdiv>
5479
5480 <glossdiv id='var-glossary-h'><title>H</title>
5481
5482 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
5483 <info>
5484 HOMEPAGE[doc] = "Website where more information about the software the recipe is building can be found."
5485 </info>
5486 <glossdef>
5487 <para role="glossdeffirst">
5488<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5489 Website where more information about the software the recipe is building
5490 can be found.
5491 </para>
5492 </glossdef>
5493 </glossentry>
5494
5495 <glossentry id='var-HOST_ARCH'><glossterm>HOST_ARCH</glossterm>
5496 <info>
5497 HOST_ARCH[doc] = "The name of the target architecture. Normally same as the TARGET_ARCH."
5498
5499 </info>
5500 <glossdef>
5501 <para role="glossdeffirst">
5502<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5503 The name of the target architecture, which is normally
5504 the same as
5505 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
5506 The OpenEmbedded build system supports many
5507 architectures.
5508 Here is an example list of architectures supported.
5509 This list is by no means complete as the architecture
5510 is configurable:
5511 <literallayout class='monospaced'>
5512 arm
5513 i586
5514 x86_64
5515 powerpc
5516 powerpc64
5517 mips
5518 mipsel
5519 </literallayout>
5520 </para>
5521 </glossdef>
5522 </glossentry>
5523
5524 <glossentry id='var-HOST_CC_ARCH'><glossterm>HOST_CC_ARCH</glossterm>
5525 <info>
5526 HOST_CC_ARCH[doc] = "The name of the host architecture. Normally same as the TARGET_CC_ARCH."
5527 </info>
5528 <glossdef>
5529 <para role="glossdeffirst">
5530<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5531 Specifies architecture-specific compiler flags that are
5532 passed to the C compiler.
5533 </para>
5534
5535 <para>
5536 Default initialization for <filename>HOST_CC_ARCH</filename>
5537 varies depending on what is being built:
5538 <itemizedlist>
5539 <listitem><para>
5540 <link linkend='var-TARGET_CC_ARCH'><filename>TARGET_CC_ARCH</filename></link>
5541 when building for the target
5542 </para></listitem>
5543 <listitem><para>
5544 <filename>BUILD_CC_ARCH</filename>
5545 when building for the build host (i.e.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05005546 <filename>-native</filename>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005547 </para></listitem>
5548 <listitem><para>
5549 <filename>BUILDSDK_CC_ARCH</filename>
5550 when building for an SDK (i.e.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05005551 <filename>nativesdk-</filename>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005552 </para></listitem>
5553 </itemizedlist>
5554 </para>
5555 </glossdef>
5556 </glossentry>
5557
5558 <glossentry id='var-HOST_OS'><glossterm>HOST_OS</glossterm>
5559 <info>
5560 HOST_OS[doc] = "The name of the target operating system. Normally the same as the TARGET_OS."
5561 </info>
5562 <glossdef>
5563 <para role="glossdeffirst">
5564<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5565 Specifies the name of the target operating system, which
5566 is normally the same as the
5567 <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>.
5568 The variable can be set to "linux" for <filename>glibc</filename>-based systems and
Brad Bishop37a0e4d2017-12-04 01:01:44 -05005569 to "linux-musl" for <filename>musl</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005570 For ARM/EABI targets, there are also "linux-gnueabi" and
Brad Bishop37a0e4d2017-12-04 01:01:44 -05005571 "linux-musleabi" values possible.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005572 </para>
5573 </glossdef>
5574 </glossentry>
5575
5576 <glossentry id='var-HOST_PREFIX'><glossterm>HOST_PREFIX</glossterm>
5577 <info>
5578 HOST_PREFIX[doc] = "The prefix for the cross compile toolchain. Normally same as the TARGET_PREFIX."
5579 </info>
5580 <glossdef>
5581 <para role="glossdeffirst">
5582<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5583 Specifies the prefix for the cross-compile toolchain.
5584 <filename>HOST_PREFIX</filename> is normally the same as
5585 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>.
5586 </para>
5587 </glossdef>
5588 </glossentry>
5589
5590 <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
5591 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04005592 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005593 </info>
5594 <glossdef>
5595 <para role="glossdeffirst">
5596<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5597 Specifies the system, including the architecture and the
5598 operating system, for which the build is occurring
5599 in the context of the current recipe.
5600 </para>
5601
5602 <para>
5603 The OpenEmbedded build system automatically sets this
5604 variable based on
5605 <link linkend='var-HOST_ARCH'><filename>HOST_ARCH</filename></link>,
5606 <link linkend='var-HOST_VENDOR'><filename>HOST_VENDOR</filename></link>,
5607 and
5608 <link linkend='var-HOST_OS'><filename>HOST_OS</filename></link>
5609 variables.
5610 <note>
5611 You do not need to set the variable yourself.
5612 </note>
5613 </para>
5614
5615 <para>
5616 Consider these two examples:
5617 <itemizedlist>
5618 <listitem><para>Given a native recipe on a 32-bit
5619 x86 machine running Linux, the value is
5620 "i686-linux".
5621 </para></listitem>
5622 <listitem><para>Given a recipe being built for a
5623 little-endian MIPS target running Linux,
5624 the value might be "mipsel-linux".
5625 </para></listitem>
5626 </itemizedlist>
5627 </para>
5628 </glossdef>
5629 </glossentry>
5630
Brad Bishop6e60e8b2018-02-01 10:27:11 -05005631 <glossentry id='var-HOSTTOOLS'><glossterm>HOSTTOOLS</glossterm>
5632 <info>
5633 HOSTTOOLS[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks."
5634 </info>
5635 <glossdef>
5636 <para role="glossdeffirst">
5637<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5638 A space-separated list (filter) of tools on the build host
5639 that should be allowed to be called from within build tasks.
5640 Using this filter helps reduce the possibility of host
5641 contamination.
5642 If a tool specified in the value of
5643 <filename>HOSTTOOLS</filename> is not found on the
5644 build host, the OpenEmbedded build system produces
5645 an error and the build is not started.
5646 </para>
5647
5648 <para>
5649 For additional information, see
5650 <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link>.
5651 </para>
5652 </glossdef>
5653 </glossentry>
5654
5655 <glossentry id='var-HOSTTOOLS_NONFATAL'><glossterm>HOSTTOOLS_NONFATAL</glossterm>
5656 <info>
5657 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."
5658 </info>
5659 <glossdef>
5660 <para role="glossdeffirst">
5661<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5662 A space-separated list (filter) of tools on the build host
5663 that should be allowed to be called from within build tasks.
5664 Using this filter helps reduce the possibility of host
5665 contamination.
5666 Unlike
5667 <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link>,
Brad Bishop316dfdd2018-06-25 12:45:53 -04005668 the OpenEmbedded build system does not produce an error
Brad Bishop6e60e8b2018-02-01 10:27:11 -05005669 if a tool specified in the value of
5670 <filename>HOSTTOOLS_NONFATAL</filename> is not found on the
5671 build host.
5672 Thus, you can use <filename>HOSTTOOLS_NONFATAL</filename>
5673 to filter optional host tools.
5674 </para>
5675 </glossdef>
5676 </glossentry>
5677
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005678 <glossentry id='var-HOST_VENDOR'><glossterm>HOST_VENDOR</glossterm>
5679 <info>
5680 HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR."
5681 </info>
5682 <glossdef>
5683 <para role="glossdeffirst">
5684<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5685 Specifies the name of the vendor.
5686 <filename>HOST_VENDOR</filename> is normally the same as
Brad Bishop316dfdd2018-06-25 12:45:53 -04005687 <link linkend='var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005688 </para>
5689 </glossdef>
5690 </glossentry>
5691
5692 </glossdiv>
5693
5694 <glossdiv id='var-glossary-i'><title>I</title>
5695
5696 <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm>
5697 <info>
5698 ICECC_DISABLED[doc] = "Disables or enables the icecc (Icecream) function."
5699 </info>
5700 <glossdef>
5701 <para role="glossdeffirst">
5702<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5703 Disables or enables the <filename>icecc</filename>
5704 (Icecream) function.
5705 For more information on this function and best practices
5706 for using this variable, see the
5707 "<link linkend='ref-classes-icecc'><filename>icecc.bbclass</filename></link>"
5708 section.
5709 </para>
5710
5711 <para>
5712 Setting this variable to "1" in your
5713 <filename>local.conf</filename> disables the function:
5714 <literallayout class='monospaced'>
5715 ICECC_DISABLED ??= "1"
5716 </literallayout>
5717 To enable the function, set the variable as follows:
5718 <literallayout class='monospaced'>
5719 ICECC_DISABLED = ""
5720 </literallayout>
5721 </para>
5722 </glossdef>
5723 </glossentry>
5724
5725 <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm>
5726 <info>
5727 ICECC_ENV_EXEC[doc] = "Points to the icecc-create-env script that you provide."
5728 </info>
5729 <glossdef>
5730 <para role="glossdeffirst">
5731<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5732 Points to the <filename>icecc-create-env</filename> script
5733 that you provide.
5734 This variable is used by the
5735 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5736 class.
5737 You set this variable in your
5738 <filename>local.conf</filename> file.
5739 </para>
5740
5741 <para>
5742 If you do not point to a script that you provide, the
5743 OpenEmbedded build system uses the default script provided
5744 by the <filename>icecc-create-env.bb</filename> recipe,
5745 which is a modified version and not the one that comes with
5746 <filename>icecc</filename>.
5747 </para>
5748 </glossdef>
5749 </glossentry>
5750
5751 <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm>
5752 <info>
5753 ICECC_PARALLEL_MAKE[doc] = "Extra options passed to the make command during the do_compile task that specify parallel compilation."
5754 </info>
5755 <glossdef>
5756 <para role="glossdeffirst">
5757<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5758 Extra options passed to the <filename>make</filename>
5759 command during the
5760 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
5761 task that specify parallel compilation.
5762 This variable usually takes the form of
5763 "-j <replaceable>x</replaceable>", where
5764 <replaceable>x</replaceable> represents the maximum
5765 number of parallel threads <filename>make</filename> can
5766 run.
5767 <note>
5768 The options passed affect builds on all enabled
5769 machines on the network, which are machines running the
5770 <filename>iceccd</filename> daemon.
5771 </note>
5772 </para>
5773
5774 <para>
5775 If your enabled machines support multiple cores,
5776 coming up with the maximum number of parallel threads
5777 that gives you the best performance could take some
5778 experimentation since machine speed, network lag,
5779 available memory, and existing machine loads can all
5780 affect build time.
5781 Consequently, unlike the
5782 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
5783 variable, there is no rule-of-thumb for setting
5784 <filename>ICECC_PARALLEL_MAKE</filename> to achieve
5785 optimal performance.
5786 </para>
5787
5788 <para>
5789 If you do not set <filename>ICECC_PARALLEL_MAKE</filename>,
5790 the build system does not use it (i.e. the system does
5791 not detect and assign the number of cores as is done with
5792 <filename>PARALLEL_MAKE</filename>).
5793 </para>
5794 </glossdef>
5795 </glossentry>
5796
5797 <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm>
5798 <info>
5799 ICECC_PATH[doc] = "The location of the icecc binary."
5800 </info>
5801 <glossdef>
5802 <para role="glossdeffirst">
5803<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5804 The location of the <filename>icecc</filename> binary.
5805 You can set this variable in your
5806 <filename>local.conf</filename> file.
5807 If your <filename>local.conf</filename> file does not define
5808 this variable, the
5809 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5810 class attempts to define it by locating
5811 <filename>icecc</filename> using <filename>which</filename>.
5812 </para>
5813 </glossdef>
5814 </glossentry>
5815
5816 <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm>
5817 <info>
5818 ICECC_USER_CLASS_BL[doc] = "Identifies user classes that you do not want the Icecream distributed compile support to consider."
5819 </info>
5820 <glossdef>
5821 <para role="glossdeffirst">
5822<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5823 Identifies user classes that you do not want the
5824 Icecream distributed compile support to consider.
5825 This variable is used by the
5826 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5827 class.
5828 You set this variable in your
5829 <filename>local.conf</filename> file.
5830 </para>
5831
5832 <para>
5833 When you list classes using this variable, you are
5834 "blacklisting" them from distributed compilation across
5835 remote hosts.
5836 Any classes you list will be distributed and compiled
5837 locally.
5838 </para>
5839 </glossdef>
5840 </glossentry>
5841
5842 <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm>
5843 <info>
5844 ICECC_USER_PACKAGE_BL[doc] = "Identifies user recipes that you do not want the Icecream distributed compile support to consider."
5845 </info>
5846 <glossdef>
5847 <para role="glossdeffirst">
5848<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5849 Identifies user recipes that you do not want the
5850 Icecream distributed compile support to consider.
5851 This variable is used by the
5852 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5853 class.
5854 You set this variable in your
5855 <filename>local.conf</filename> file.
5856 </para>
5857
5858 <para>
5859 When you list packages using this variable, you are
5860 "blacklisting" them from distributed compilation across
5861 remote hosts.
5862 Any packages you list will be distributed and compiled
5863 locally.
5864 </para>
5865 </glossdef>
5866 </glossentry>
5867
5868 <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm>
5869 <info>
5870 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."
5871 </info>
5872 <glossdef>
5873 <para role="glossdeffirst">
5874<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5875 Identifies user recipes that use an empty
5876 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
5877 variable that you want to force remote distributed
5878 compilation on using the Icecream distributed compile
5879 support.
5880 This variable is used by the
5881 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5882 class.
5883 You set this variable in your
5884 <filename>local.conf</filename> file.
5885 </para>
5886 </glossdef>
5887 </glossentry>
5888
5889 <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
5890 <info>
5891 IMAGE_BASENAME[doc] = "The base name of image output files."
5892 </info>
5893 <glossdef>
5894 <para role="glossdeffirst">
5895<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5896 The base name of image output files.
5897 This variable defaults to the recipe name
5898 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
5899 </para>
5900 </glossdef>
5901 </glossentry>
5902
5903 <glossentry id='var-IMAGE_BOOT_FILES'><glossterm>IMAGE_BOOT_FILES</glossterm>
5904 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04005905 IMAGE_BOOT_FILES[doc] = "A space-separated list of files from ${DEPLOY_DIR_IMAGE} to place in boot partition."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005906 </info>
5907 <glossdef>
5908 <para role="glossdeffirst">
5909<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5910 A space-separated list of files installed into the
Brad Bishop316dfdd2018-06-25 12:45:53 -04005911 boot partition when preparing an image using the Wic tool
5912 with the <filename>bootimg-partition</filename> source
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005913 plugin.
Brad Bishop316dfdd2018-06-25 12:45:53 -04005914 By default, the files are installed under the same name as
5915 the source files.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005916 To change the installed name, separate it from the
5917 original name with a semi-colon (;).
5918 Source files need to be located in
5919 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>.
5920 Here are two examples:
5921
5922 <literallayout class="monospaced">
5923 IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
5924 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
5925 </literallayout>
5926 </para>
5927
5928 <para>
5929 Alternatively, source files can be picked up using
5930 a glob pattern.
Brad Bishop316dfdd2018-06-25 12:45:53 -04005931 In this case, the destination file must have the same name
5932 as the base name of the source file path.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005933 To install files into a directory within the
5934 target location, pass its name after a semi-colon
5935 (;).
5936 Here are two examples:
5937 <literallayout class="monospaced">
5938 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
5939 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"
5940 </literallayout>
5941 The first example installs all files from
5942 <filename>${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles</filename>
5943 into the root of the target partition.
5944 The second example installs the same files into a
5945 <filename>boot</filename> directory within the
5946 target partition.
5947 </para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04005948
5949 <para>
5950 You can find information on how to use the Wic tool in the
5951 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
5952 section of the Yocto Project Development Tasks Manual.
5953 Reference material for Wic is located in the
5954 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>OpenEmbedded Kickstart (.wks) Reference</ulink>"
5955 chapter.
5956 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005957 </glossdef>
5958 </glossentry>
5959
5960 <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
5961 <info>
5962 IMAGE_CLASSES[doc] = "A list of classes that all images should inherit."
5963 </info>
5964 <glossdef>
5965 <para role="glossdeffirst">
5966<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5967 A list of classes that all images should inherit.
5968 You typically use this variable to specify the list of
5969 classes that register the different types of images
5970 the OpenEmbedded build system creates.
5971 </para>
5972
5973 <para>
5974 The default value for <filename>IMAGE_CLASSES</filename> is
5975 <filename>image_types</filename>.
5976 You can set this variable in your
5977 <filename>local.conf</filename> or in a distribution
5978 configuration file.
5979 </para>
5980
5981 <para>
5982 For more information, see
5983 <filename>meta/classes/image_types.bbclass</filename> in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005984 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005985 </para>
5986 </glossdef>
5987 </glossentry>
5988
5989 <glossentry id='var-IMAGE_CMD'><glossterm>IMAGE_CMD</glossterm>
5990 <info>
5991 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)."
5992 </info>
5993 <glossdef>
5994 <para role="glossdeffirst">
5995<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5996 Specifies the command to create the image file for a
5997 specific image type, which corresponds to the value set
5998 set in
5999 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
6000 (e.g. <filename>ext3</filename>,
6001 <filename>btrfs</filename>, and so forth).
6002 When setting this variable, you should use
6003 an override for the associated type.
6004 Here is an example:
6005 <literallayout class='monospaced'>
6006 IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \
6007 --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \
6008 ${EXTRA_IMAGECMD}"
6009 </literallayout>
6010 </para>
6011
6012 <para>
6013 You typically do not need to set this variable unless
6014 you are adding support for a new image type.
6015 For more examples on how to set this variable, see the
6016 <link linkend='ref-classes-image_types'><filename>image_types</filename></link>
6017 class file, which is
6018 <filename>meta/classes/image_types.bbclass</filename>.
6019 </para>
6020 </glossdef>
6021 </glossentry>
6022
6023 <glossentry id='var-IMAGE_DEVICE_TABLES'><glossterm>IMAGE_DEVICE_TABLES</glossterm>
6024 <info>
6025 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."
6026 </info>
6027 <glossdef>
6028 <para role="glossdeffirst">
6029<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6030 Specifies one or more files that contain custom device
6031 tables that are passed to the
6032 <filename>makedevs</filename> command as part of creating
6033 an image.
6034 These files list basic device nodes that should be
6035 created under <filename>/dev</filename> within the image.
6036 If <filename>IMAGE_DEVICE_TABLES</filename> is not set,
6037 <filename>files/device_table-minimal.txt</filename> is
6038 used, which is located by
6039 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
6040 For details on how you should write device table files,
6041 see <filename>meta/files/device_table-minimal.txt</filename>
6042 as an example.
6043 </para>
6044 </glossdef>
6045 </glossentry>
6046
6047 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
6048 <info>
6049 IMAGE_FEATURES[doc] = "The primary list of features to include in an image. Configure this variable in an image recipe."
6050 </info>
6051 <glossdef>
6052 <para role="glossdeffirst">
6053<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6054 The primary list of features to include in an image.
6055 Typically, you configure this variable in an image recipe.
6056 Although you can use this variable from your
6057 <filename>local.conf</filename> file, which is found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006058 <link linkend='build-directory'>Build Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006059 best practices dictate that you do not.
6060 <note>
6061 To enable extra features from outside the image recipe,
6062 use the
6063 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
6064 </note>
6065 </para>
6066
6067 <para>
6068 For a list of image features that ships with the Yocto
6069 Project, see the
6070 "<link linkend="ref-features-image">Image Features</link>"
6071 section.
6072 </para>
6073
6074 <para>
6075 For an example that shows how to customize your image by
6076 using this variable, see the
6077 "<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>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006078 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006079 </para>
6080 </glossdef>
6081 </glossentry>
6082
6083 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
6084 <info>
6085 IMAGE_FSTYPES[doc] = "Formats of root filesystem images that you want to have created."
6086 </info>
6087 <glossdef>
6088 <para role="glossdeffirst">
6089<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6090 Specifies the formats the OpenEmbedded build system uses
6091 during the build when creating the root filesystem.
6092 For example, setting <filename>IMAGE_FSTYPES</filename>
6093 as follows causes the build system to create root
6094 filesystems using two formats: <filename>.ext3</filename>
6095 and <filename>.tar.bz2</filename>:
6096 <literallayout class='monospaced'>
6097 IMAGE_FSTYPES = "ext3 tar.bz2"
6098 </literallayout>
6099 </para>
6100
6101 <para>
6102 For the complete list of supported image formats from which
6103 you can choose, see
6104 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
6105 </para>
6106
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006107 <note><title>Notes</title>
6108 <itemizedlist>
6109 <listitem><para>
Brad Bishop19323692019-04-05 15:28:33 -04006110 If an image recipe uses the "inherit image" line
6111 and you are setting
6112 <filename>IMAGE_FSTYPES</filename> inside the
6113 recipe, you must set
6114 <filename>IMAGE_FSTYPES</filename> prior to
6115 using the "inherit image" line.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006116 </para></listitem>
6117 <listitem><para>
6118 Due to the way the OpenEmbedded build system
6119 processes this variable, you cannot update its
6120 contents by using <filename>_append</filename> or
6121 <filename>_prepend</filename>.
6122 You must use the <filename>+=</filename>
6123 operator to add one or more options to the
6124 <filename>IMAGE_FSTYPES</filename> variable.
6125 </para></listitem>
6126 </itemizedlist>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006127 </note>
6128 </glossdef>
6129 </glossentry>
6130
6131 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
6132 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006133 IMAGE_INSTALL[doc] = "Used by recipes to specify the packages to install into an image through image.bbclass."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006134 </info>
6135 <glossdef>
6136 <para role="glossdeffirst">
6137<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -04006138 Used by recipes to specify the packages to install into an
6139 image through the
6140 <link linkend='ref-classes-image'><filename>image</filename></link>
6141 class.
6142 Use the <filename>IMAGE_INSTALL</filename> variable with
6143 care to avoid ordering issues.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006144 </para>
6145
6146 <para>
6147 Image recipes set <filename>IMAGE_INSTALL</filename>
6148 to specify the packages to install into an image through
6149 <filename>image.bbclass</filename>.
Brad Bishop316dfdd2018-06-25 12:45:53 -04006150 Additionally, "helper" classes such as the
6151 <link linkend='ref-classes-core-image'><filename>core-image</filename></link>
6152 class exist that can take lists used with
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006153 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006154 and turn them into auto-generated entries in
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006155 <filename>IMAGE_INSTALL</filename> in addition to its
6156 default contents.
6157 </para>
6158
6159 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006160 When you use this variable, it is best to use it as follows:
6161 <literallayout class='monospaced'>
6162 IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>"
6163 </literallayout>
6164 Be sure to include the space between the quotation character
6165 and the start of the package name or names.
Brad Bishop316dfdd2018-06-25 12:45:53 -04006166 <note><title>Caution</title>
6167 <itemizedlist>
6168 <listitem><para>
6169 When working with a
6170 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
6171 image, do not use the
6172 <filename>IMAGE_INSTALL</filename> variable to
6173 specify packages for installation.
6174 Instead, use the
6175 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
6176 variable, which allows the initial RAM
6177 filesystem (initramfs) recipe to use a fixed
6178 set of packages and not be affected by
6179 <filename>IMAGE_INSTALL</filename>.
6180 For information on creating an initramfs, see
6181 the
6182 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
6183 section in the Yocto Project Development Tasks
6184 Manual.
6185 </para></listitem>
6186 <listitem><para>
6187 Using <filename>IMAGE_INSTALL</filename> with
6188 the
6189 <ulink url='&YOCTO_DOCS_BB_URL;#appending-and-prepending'><filename>+=</filename></ulink>
6190 BitBake operator within the
6191 <filename>/conf/local.conf</filename> file or
6192 from within an image recipe is not recommended.
6193 Use of this operator in these ways can cause
6194 ordering issues.
6195 Since <filename>core-image.bbclass</filename>
6196 sets <filename>IMAGE_INSTALL</filename> to a
6197 default value using the
6198 <ulink url='&YOCTO_DOCS_BB_URL;#setting-a-default-value'><filename>?=</filename></ulink>
6199 operator, using a <filename>+=</filename>
6200 operation against
6201 <filename>IMAGE_INSTALL</filename> results in
6202 unexpected behavior when used within
6203 <filename>conf/local.conf</filename>.
6204 Furthermore, the same operation from within
6205 an image recipe may or may not succeed
6206 depending on the specific situation.
6207 In both these cases, the behavior is contrary
6208 to how most users expect the
6209 <filename>+=</filename> operator to work.
6210 </para></listitem>
6211 </itemizedlist>
6212 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006213 </para>
6214 </glossdef>
6215 </glossentry>
6216
6217 <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
6218 <info>
6219 IMAGE_LINGUAS[doc] = "Specifies the list of locales to install into the image during the root filesystem construction process."
6220 </info>
6221 <glossdef>
6222 <para role="glossdeffirst">
6223<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6224 Specifies the list of locales to install into the image
6225 during the root filesystem construction process.
6226 The OpenEmbedded build system automatically splits locale
6227 files, which are used for localization, into separate
6228 packages.
6229 Setting the <filename>IMAGE_LINGUAS</filename> variable
6230 ensures that any locale packages that correspond to packages
6231 already selected for installation into the image are also
6232 installed.
6233 Here is an example:
6234 <literallayout class='monospaced'>
6235 IMAGE_LINGUAS = "pt-br de-de"
6236 </literallayout>
6237 </para>
6238
6239 <para>
6240 In this example, the build system ensures any Brazilian
6241 Portuguese and German locale files that correspond to
6242 packages in the image are installed (i.e.
6243 <filename>*-locale-pt-br</filename>
6244 and <filename>*-locale-de-de</filename> as well as
6245 <filename>*-locale-pt</filename>
6246 and <filename>*-locale-de</filename>, since some software
6247 packages only provide locale files by language and not by
6248 country-specific language).
6249 </para>
6250
6251 <para>
6252 See the
6253 <link linkend='var-GLIBC_GENERATE_LOCALES'><filename>GLIBC_GENERATE_LOCALES</filename></link>
6254 variable for information on generating GLIBC locales.
6255 </para>
6256 </glossdef>
6257 </glossentry>
6258
6259 <glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm>
6260 <info>
6261 IMAGE_MANIFEST[doc] = "The manifest file for the image. This file lists all the installed packages that make up the image."
6262 </info>
6263 <glossdef>
6264 <para role="glossdeffirst">
6265<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6266 The manifest file for the image.
6267 This file lists all the installed packages that make up
6268 the image.
6269 The file contains package information on a line-per-package
6270 basis as follows:
6271 <literallayout class='monospaced'>
6272 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
6273 </literallayout>
6274 </para>
6275
6276 <para>
6277 The
6278 <link linkend='ref-classes-image'><filename>image</filename></link>
6279 class defines the manifest file as follows:
6280 <literallayout class='monospaced'>
6281 IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"
6282 </literallayout>
6283 The location is derived using the
6284 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
6285 and
6286 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>
6287 variables.
6288 You can find information on how the image
6289 is created in the
Brad Bishop316dfdd2018-06-25 12:45:53 -04006290 "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
6291 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006292 </para>
6293 </glossdef>
6294 </glossentry>
6295
6296 <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
6297 <info>
6298 IMAGE_NAME[doc] = "The name of the output image files minus the extension."
6299 </info>
6300 <glossdef>
6301 <para role="glossdeffirst">
6302<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6303 The name of the output image files minus the extension.
6304 This variable is derived using the
6305 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
6306 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
6307 and
6308 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
6309 variables:
6310 <literallayout class='monospaced'>
6311 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
6312 </literallayout>
6313 </para>
6314 </glossdef>
6315 </glossentry>
6316
6317 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
6318 <info>
6319 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."
6320 </info>
6321 <glossdef>
6322 <para role="glossdeffirst">
6323<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6324 Defines a multiplier that the build system applies to the initial image
6325 size for cases when the multiplier times the returned disk usage value
6326 for the image is greater than the sum of
6327 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
6328 and
6329 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
6330 The result of the multiplier applied to the initial image size creates
6331 free disk space in the image as overhead.
6332 By default, the build process uses a multiplier of 1.3 for this variable.
6333 This default value results in 30% free disk space added to the image when this
6334 method is used to determine the final generated image size.
6335 You should be aware that post install scripts and the package management
6336 system uses disk space inside this overhead area.
6337 Consequently, the multiplier does not produce an image with
6338 all the theoretical free disk space.
6339 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
6340 for information on how the build system determines the overall image size.
6341 </para>
6342
6343 <para>
6344 The default 30% free disk space typically gives the image enough room to boot
6345 and allows for basic post installs while still leaving a small amount of
6346 free disk space.
6347 If 30% free space is inadequate, you can increase the default value.
6348 For example, the following setting gives you 50% free space added to the image:
6349 <literallayout class='monospaced'>
6350 IMAGE_OVERHEAD_FACTOR = "1.5"
6351 </literallayout>
6352 </para>
6353
6354 <para>
6355 Alternatively, you can ensure a specific amount of free disk space is added
6356 to the image by using the
6357 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
6358 variable.
6359 </para>
6360 </glossdef>
6361 </glossentry>
6362
6363 <glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm>
6364 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006365 IMAGE_PKGTYPE[doc] = "Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the OpenEmbedded build system."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006366 </info>
6367 <glossdef>
6368 <para role="glossdeffirst">
6369<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -04006370 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006371 by the OpenEmbedded build system.
6372 The variable is defined appropriately by the
6373 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
6374 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
6375 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
6376 or
6377 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
6378 class.
6379 <note><title>Warning</title>
6380 The <filename>package_tar</filename> class is broken
6381 and is not supported.
6382 It is recommended that you do not use it.
6383 </note>
6384 </para>
6385
6386 <para>
6387 The
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006388 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_*</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006389 and
6390 <link linkend='ref-classes-image'><filename>image</filename></link>
6391 classes use the <filename>IMAGE_PKGTYPE</filename> for
6392 packaging up images and SDKs.
6393 </para>
6394
6395 <para>
6396 You should not set the <filename>IMAGE_PKGTYPE</filename>
6397 manually.
6398 Rather, the variable is set indirectly through the
6399 appropriate
6400 <link linkend='ref-classes-package'><filename>package_*</filename></link>
6401 class using the
6402 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
6403 variable.
6404 The OpenEmbedded build system uses the first package type
6405 (e.g. DEB, RPM, or IPK) that appears with the variable
6406 <note>
6407 Files using the <filename>.tar</filename> format are
6408 never used as a substitute packaging format for DEB,
6409 RPM, and IPK formatted files for your image or SDK.
6410 </note>
6411 </para>
6412 </glossdef>
6413 </glossentry>
6414
6415 <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
6416 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006417 IMAGE_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system creates the final image output files."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006418 </info>
6419 <glossdef>
6420 <para role="glossdeffirst">
6421<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6422 Specifies a list of functions to call once the
Brad Bishop316dfdd2018-06-25 12:45:53 -04006423 OpenEmbedded build system creates the final image
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006424 output files.
6425 You can specify functions separated by semicolons:
6426 <literallayout class='monospaced'>
6427 IMAGE_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
6428 </literallayout>
6429 </para>
6430
6431 <para>
6432 If you need to pass the root filesystem path to a command
6433 within the function, you can use
6434 <filename>${IMAGE_ROOTFS}</filename>, which points to
6435 the directory that becomes the root filesystem image.
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006436 See the
6437 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
6438 variable for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006439 </para>
6440 </glossdef>
6441 </glossentry>
6442
6443 <glossentry id='var-IMAGE_PREPROCESS_COMMAND'><glossterm>IMAGE_PREPROCESS_COMMAND</glossterm>
6444 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006445 IMAGE_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system creates the final image output files."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006446 </info>
6447 <glossdef>
6448 <para role="glossdeffirst">
6449<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6450 Specifies a list of functions to call before the
Brad Bishop316dfdd2018-06-25 12:45:53 -04006451 OpenEmbedded build system creates the final image
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006452 output files.
6453 You can specify functions separated by semicolons:
6454 <literallayout class='monospaced'>
6455 IMAGE_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
6456 </literallayout>
6457 </para>
6458
6459 <para>
6460 If you need to pass the root filesystem path to a command
6461 within the function, you can use
6462 <filename>${IMAGE_ROOTFS}</filename>, which points to
6463 the directory that becomes the root filesystem image.
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006464 See the
6465 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
6466 variable for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006467 </para>
6468 </glossdef>
6469 </glossentry>
6470
6471 <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
6472 <info>
6473 IMAGE_ROOTFS[doc] = "The location of the root filesystem while it is under construction (i.e. during do_rootfs)."
6474 </info>
6475 <glossdef>
6476 <para role="glossdeffirst">
6477<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6478 The location of the root filesystem while it is under
6479 construction (i.e. during the
6480 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
6481 task).
6482 This variable is not configurable.
6483 Do not change it.
6484 </para>
6485 </glossdef>
6486 </glossentry>
6487
6488 <glossentry id='var-IMAGE_ROOTFS_ALIGNMENT'><glossterm>IMAGE_ROOTFS_ALIGNMENT</glossterm>
6489 <info>
6490 IMAGE_ROOTFS_ALIGNMENT[doc] = "Specifies the alignment for the output image file in Kbytes."
6491 </info>
6492 <glossdef>
6493 <para role="glossdeffirst">
6494<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6495 Specifies the alignment for the output image file in
6496 Kbytes.
6497 If the size of the image is not a multiple of
6498 this value, then the size is rounded up to the nearest
6499 multiple of the value.
6500 The default value is "1".
6501 See
6502 <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
6503 for additional information.
6504 </para>
6505 </glossdef>
6506 </glossentry>
6507
6508 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
6509 <info>
6510 IMAGE_ROOTFS_EXTRA_SPACE[doc] = "Defines additional free disk space created in the image in Kbytes. By default, this variable is set to '0'."
6511 </info>
6512 <glossdef>
6513 <para role="glossdeffirst">
6514<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6515 Defines additional free disk space created in the image in Kbytes.
6516 By default, this variable is set to "0".
6517 This free disk space is added to the image after the build system determines
6518 the image size as described in
6519 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
6520 </para>
6521
6522 <para>
6523 This variable is particularly useful when you want to ensure that a
6524 specific amount of free disk space is available on a device after an image
6525 is installed and running.
6526 For example, to be sure 5 Gbytes of free disk space is available, set the
6527 variable as follows:
6528 <literallayout class='monospaced'>
6529 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
6530 </literallayout>
6531 </para>
6532
6533 <para>
6534 For example, the Yocto Project Build Appliance specifically requests 40 Gbytes
6535 of extra space with the line:
6536 <literallayout class='monospaced'>
6537 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
6538 </literallayout>
6539 </para>
6540 </glossdef>
6541 </glossentry>
6542
6543 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
6544 <info>
6545 IMAGE_ROOTFS_SIZE[doc] = "Defines the size in Kbytes for the generated image."
6546 </info>
6547 <glossdef>
6548 <para role="glossdeffirst">
6549<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6550 Defines the size in Kbytes for the generated image.
6551 The OpenEmbedded build system determines the final size for the generated
6552 image using an algorithm that takes into account the initial disk space used
6553 for the generated image, a requested size for the image, and requested
6554 additional free disk space to be added to the image.
6555 Programatically, the build system determines the final size of the
6556 generated image as follows:
6557 <literallayout class='monospaced'>
6558 if (image-du * overhead) &lt; rootfs-size:
6559 internal-rootfs-size = rootfs-size + xspace
6560 else:
6561 internal-rootfs-size = (image-du * overhead) + xspace
6562
6563 where:
6564
6565 image-du = Returned value of the du command on
6566 the image.
6567
6568 overhead = IMAGE_OVERHEAD_FACTOR
6569
6570 rootfs-size = IMAGE_ROOTFS_SIZE
6571
6572 internal-rootfs-size = Initial root filesystem
6573 size before any modifications.
6574
6575 xspace = IMAGE_ROOTFS_EXTRA_SPACE
6576 </literallayout>
6577 </para>
6578
6579 <para>
6580 See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
6581 and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
6582 variables for related information.
6583<!-- In the above example, <filename>overhead</filename> is defined by the
6584 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
6585 variable, <filename>xspace</filename> is defined by the
6586 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
6587 variable, and <filename>du</filename> is the results of the disk usage command
6588 on the initially generated image. -->
6589 </para>
6590 </glossdef>
6591 </glossentry>
6592
6593 <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm>
6594 <info>
6595 IMAGE_TYPEDEP[doc] = "Specifies a dependency from one image type on another."
6596 </info>
6597 <glossdef>
6598 <para role="glossdeffirst">
6599<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6600 Specifies a dependency from one image type on another.
6601 Here is an example from the
6602 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
6603 class:
6604 <literallayout class='monospaced'>
6605 IMAGE_TYPEDEP_live = "ext3"
6606 </literallayout>
6607 </para>
6608
6609 <para>
6610 In the previous example, the variable ensures that when
6611 "live" is listed with the
6612 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6613 variable, the OpenEmbedded build system produces an
6614 <filename>ext3</filename> image first since one of the
6615 components of the live
6616 image is an <filename>ext3</filename>
6617 formatted partition containing the root
6618 filesystem.
6619 </para>
6620 </glossdef>
6621 </glossentry>
6622
6623 <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
6624 <info>
6625 IMAGE_TYPES[doc] = "Specifies the complete list of supported image types by default."
6626 </info>
6627 <glossdef>
6628 <para role="glossdeffirst">
6629<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6630 Specifies the complete list of supported image types
6631 by default:
6632 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006633 btrfs
Brad Bishop79641f22019-09-10 07:20:22 -04006634 container
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006635 cpio
6636 cpio.gz
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006637 cpio.lz4
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006638 cpio.lzma
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006639 cpio.xz
6640 cramfs
6641 elf
6642 ext2
6643 ext2.bz2
6644 ext2.gz
6645 ext2.lzma
6646 ext3
6647 ext3.gz
6648 ext4
6649 ext4.gz
Brad Bishop79641f22019-09-10 07:20:22 -04006650 f2fs
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006651 hddimg
6652 iso
6653 jffs2
6654 jffs2.sum
6655 multiubi
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006656 squashfs
Brad Bishop79641f22019-09-10 07:20:22 -04006657 squashfs-lz4
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006658 squashfs-lzo
6659 squashfs-xz
6660 tar
6661 tar.bz2
6662 tar.gz
6663 tar.lz4
6664 tar.xz
6665 ubi
6666 ubifs
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006667 wic
6668 wic.bz2
6669 wic.gz
6670 wic.lzma
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006671 </literallayout>
6672 </para>
6673
6674 <para>
6675 For more information about these types of images, see
6676 <filename>meta/classes/image_types*.bbclass</filename>
6677 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006678 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006679 </para>
6680 </glossdef>
6681 </glossentry>
6682
6683 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
6684 <info>
6685 INC_PR[doc] = "Helps define the recipe revision for recipes that share a common include file."
6686 </info>
6687 <glossdef>
6688 <para role="glossdeffirst">
6689<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6690 Helps define the recipe revision for recipes that share
6691 a common <filename>include</filename> file.
6692 You can think of this variable as part of the recipe revision
6693 as set from within an include file.
6694 </para>
6695
6696 <para>
6697 Suppose, for example, you have a set of recipes that
6698 are used across several projects.
6699 And, within each of those recipes the revision
6700 (its <link linkend='var-PR'><filename>PR</filename></link>
6701 value) is set accordingly.
6702 In this case, when the revision of those recipes changes,
6703 the burden is on you to find all those recipes and
6704 be sure that they get changed to reflect the updated
6705 version of the recipe.
6706 In this scenario, it can get complicated when recipes
6707 that are used in many places and provide common functionality
6708 are upgraded to a new revision.
6709 </para>
6710
6711 <para>
6712 A more efficient way of dealing with this situation is
6713 to set the <filename>INC_PR</filename> variable inside
6714 the <filename>include</filename> files that the recipes
6715 share and then expand the <filename>INC_PR</filename>
6716 variable within the recipes to help
6717 define the recipe revision.
6718 </para>
6719
6720 <para>
6721 The following provides an example that shows how to use
6722 the <filename>INC_PR</filename> variable
6723 given a common <filename>include</filename> file that
6724 defines the variable.
6725 Once the variable is defined in the
6726 <filename>include</filename> file, you can use the
6727 variable to set the <filename>PR</filename> values in
6728 each recipe.
6729 You will notice that when you set a recipe's
6730 <filename>PR</filename> you can provide more granular
6731 revisioning by appending values to the
6732 <filename>INC_PR</filename> variable:
6733 <literallayout class='monospaced'>
Brad Bishopb1114e52019-02-13 07:56:10 -05006734 recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
6735 recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
6736 recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
6737 recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006738 </literallayout>
6739 The first line of the example establishes the baseline
6740 revision to be used for all recipes that use the
6741 <filename>include</filename> file.
6742 The remaining lines in the example are from individual
6743 recipes and show how the <filename>PR</filename> value
6744 is set.
6745 </para>
6746 </glossdef>
6747 </glossentry>
6748
6749 <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
6750 <info>
6751 INCOMPATIBLE_LICENSE[doc] = "Specifies a space-separated list of license names (as they would appear in LICENSE) that should be excluded from the build."
6752 </info>
6753 <glossdef>
6754 <para role="glossdeffirst">
6755<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6756 Specifies a space-separated list of license names
6757 (as they would appear in
6758 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
6759 that should be excluded from the build.
6760 Recipes that provide no alternatives to listed incompatible
6761 licenses are not built.
6762 Packages that are individually licensed with the specified
6763 incompatible licenses will be deleted.
6764 </para>
6765
6766 <note>
6767 This functionality is only regularly tested using
6768 the following setting:
6769 <literallayout class='monospaced'>
6770 INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
6771 </literallayout>
6772 Although you can use other settings, you might be required
6773 to remove dependencies on or provide alternatives to
6774 components that are required to produce a functional system
6775 image.
6776 </note>
Andrew Geissler82c905d2020-04-13 13:39:40 -05006777
6778 <note><title>Tips</title>
6779 It is possible to define a list of licenses that are allowed
6780 to be used instead of the licenses that are excluded. To do
6781 this, define a
6782 variable <filename>COMPATIBLE_LICENSES</filename> with the
6783 names of the licences that are allowed. Then
6784 define <filename>INCOMPATIBLE_LICENSE</filename> as:
6785 <literallayout class='monospaced'>
6786 INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}"
6787 </literallayout>
6788 This will result
6789 in <filename>INCOMPATIBLE_LICENSE</filename> containing the
6790 names of all licences
6791 from <link linkend='var-AVAILABLE_LICENSES'><filename>AVAILABLE_LICENSES</filename></link>
6792 except the ones specified
6793 in <filename>COMPATIBLE_LICENSES</filename>, thus only
6794 allowing the latter licences to be used.
6795 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006796 </glossdef>
6797 </glossentry>
6798
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006799 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
6800 <info>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05006801 INHERIT[doc] = "Causes the named class or classes to be inherited globally."
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006802 </info>
6803 <glossdef>
6804 <para role="glossdeffirst">
6805<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop6e60e8b2018-02-01 10:27:11 -05006806 Causes the named class or classes to be inherited globally.
6807 Anonymous functions in the class or classes
6808 are not executed for the
6809 base configuration and in each individual recipe.
6810 The OpenEmbedded build system ignores changes to
6811 <filename>INHERIT</filename> in individual recipes.
6812 </para>
6813
6814 <para>
6815 For more information on <filename>INHERIT</filename>, see
6816 the
6817 "<ulink url="&YOCTO_DOCS_BB_URL;#inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -04006818 section in the Bitbake User Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006819 </para>
6820 </glossdef>
6821 </glossentry>
6822
6823 <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm>
6824 <info>
6825 INHERIT_DISTRO[doc] = "Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable."
6826 </info>
6827 <glossdef>
6828 <para role="glossdeffirst">
6829<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6830 Lists classes that will be inherited at the
6831 distribution level.
6832 It is unlikely that you want to edit this variable.
6833 </para>
6834
6835 <para>
6836 The default value of the variable is set as follows in the
6837 <filename>meta/conf/distro/defaultsetup.conf</filename>
6838 file:
6839 <literallayout class='monospaced'>
6840 INHERIT_DISTRO ?= "debian devshell sstate license"
6841 </literallayout>
6842 </para>
6843 </glossdef>
6844 </glossentry>
6845
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006846 <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
6847 <info>
6848 INHIBIT_DEFAULT_DEPS[doc] = "Prevents the default dependencies, namely the C compiler and standard C library (libc), from being added to DEPENDS."
6849 </info>
6850 <glossdef>
6851 <para role="glossdeffirst">
6852<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6853 Prevents the default dependencies, namely the C compiler
6854 and standard C library (libc), from being added to
6855 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
6856 This variable is usually used within recipes that do not
6857 require any compilation using the C compiler.
6858 </para>
6859
6860 <para>
6861 Set the variable to "1" to prevent the default dependencies
6862 from being added.
6863 </para>
6864 </glossdef>
6865 </glossentry>
6866
6867 <glossentry id='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><glossterm>INHIBIT_PACKAGE_DEBUG_SPLIT</glossterm>
6868 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006869 INHIBIT_PACKAGE_DEBUG_SPLIT[doc] = "If set to "1", prevents the OpenEmbedded build system from splitting out debug information during packaging"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006870 </info>
6871 <glossdef>
6872 <para role="glossdeffirst">
6873<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6874 Prevents the OpenEmbedded build system from splitting
6875 out debug information during packaging.
6876 By default, the build system splits out debugging
6877 information during the
6878 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
6879 task.
6880 For more information on how debug information is split out,
6881 see the
6882 <link linkend='var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></link>
6883 variable.
6884 </para>
6885
6886 <para>
6887 To prevent the build system from splitting out
6888 debug information during packaging, set the
6889 <filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename> variable
6890 as follows:
6891 <literallayout class='monospaced'>
6892 INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
6893 </literallayout>
6894 </para>
6895 </glossdef>
6896 </glossentry>
6897
6898 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
6899 <info>
6900 INHIBIT_PACKAGE_STRIP[doc] = "If set to "1", causes the build to not strip binaries in resulting packages."
6901 </info>
6902 <glossdef>
6903 <para role="glossdeffirst">
6904<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006905 If set to "1", causes the build to not strip binaries in
6906 resulting packages and prevents the
6907 <filename>-dbg</filename> package from containing the
6908 source files.
6909 </para>
6910
6911 <para>
6912 By default, the OpenEmbedded build system strips
6913 binaries and puts the debugging symbols into
6914 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-dbg</filename>.
6915 Consequently, you should not set
6916 <filename>INHIBIT_PACKAGE_STRIP</filename> when you plan
6917 to debug in general.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006918 </para>
6919 </glossdef>
6920 </glossentry>
6921
Brad Bishop19323692019-04-05 15:28:33 -04006922 <glossentry id='var-INHIBIT_SYSROOT_STRIP'><glossterm>INHIBIT_SYSROOT_STRIP</glossterm>
6923 <info>
6924 INHIBIT_SYSROOT_STRIP[doc] = "If set to "1", causes the build to not strip binaries in the resulting sysroot."
6925 </info>
6926 <glossdef>
6927 <para role="glossdeffirst">
6928<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6929 If set to "1", causes the build to not strip binaries in
6930 the resulting sysroot.
6931 </para>
6932
6933 <para>
6934 By default, the OpenEmbedded build system strips
6935 binaries in the resulting sysroot.
6936 When you specifically set the
6937 <filename>INHIBIT_SYSROOT_STRIP</filename> variable to
6938 "1" in your recipe, you inhibit this stripping.
6939 </para>
6940
6941 <para>
6942 If you want to use this variable, include the
6943 <link linkend='ref-classes-staging'><filename>staging</filename></link>
6944 class.
6945 This class uses a <filename>sys_strip()</filename>
6946 function to test for the variable and acts accordingly.
6947 <note>
6948 Use of the <filename>INHIBIT_SYSROOT_STRIP</filename>
6949 variable occurs in rare and special circumstances.
6950 For example, suppose you are building bare-metal
6951 firmware by using an external GCC toolchain.
6952 Furthermore, even if the toolchain's binaries are
6953 strippable, other files exist that are needed for the
6954 build that are not strippable.
6955 </note>
6956 </para>
6957 </glossdef>
6958 </glossentry>
6959
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006960 <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
6961 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006962 INITRAMFS_FSTYPES[doc] = "Defines the format for the output image of an initial RAM filesystem (initramfs), which is used during boot."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006963 </info>
6964 <glossdef>
6965 <para role="glossdeffirst">
6966<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6967 Defines the format for the output image of an initial
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006968 RAM filesystem (initramfs), which is used during boot.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006969 Supported formats are the same as those supported by the
6970 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6971 variable.
6972 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006973
6974 <para>
6975 The default value of this variable, which is set in the
6976 <filename>meta/conf/bitbake.conf</filename> configuration
6977 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006978 <link linkend='source-directory'>Source Directory</link>,
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006979 is "cpio.gz".
6980 The Linux kernel's initramfs mechanism, as opposed to the
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006981 initial RAM filesystem
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006982 <ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink>
6983 mechanism, expects an optionally compressed cpio
6984 archive.
6985 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006986 </glossdef>
6987 </glossentry>
6988
6989 <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>
6990 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006991 INITRAMFS_IMAGE[doc] = "Specifies the PROVIDES name of an image recipe that is used to build an initial RAM filesystem (initramfs) image."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006992 </info>
6993 <glossdef>
6994 <para role="glossdeffirst">
6995<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006996 Specifies the
6997 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
6998 name of an image recipe that is used to build an initial
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006999 RAM filesystem (initramfs) image.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007000 In other words, the <filename>INITRAMFS_IMAGE</filename>
7001 variable causes an additional recipe to be built as
7002 a dependency to whatever root filesystem recipe you
7003 might be using (e.g. <filename>core-image-sato</filename>).
7004 The initramfs image recipe you provide should set
7005 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
7006 to
7007 <link linkend='var-INITRAMFS_FSTYPES'><filename>INITRAMFS_FSTYPES</filename></link>.
7008 </para>
7009
7010 <para>
7011 An initramfs image provides a temporary root filesystem
7012 used for early system initialization (e.g. loading of
7013 modules needed to locate and mount the "real" root
7014 filesystem).
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007015 <note>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007016 See the <filename>meta/recipes-core/images/core-image-minimal-initramfs.bb</filename>
7017 recipe in the
7018 <link linkend='source-directory'>Source Directory</link>
7019 for an example initramfs recipe.
7020 To select this sample recipe as the one built
7021 to provide the initramfs image,
7022 set <filename>INITRAMFS_IMAGE</filename> to
7023 "core-image-minimal-initramfs".
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007024 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007025 </para>
7026
7027 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007028 You can also find more information by referencing the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007029 <filename>meta-poky/conf/local.conf.sample.extended</filename>
Brad Bishop316dfdd2018-06-25 12:45:53 -04007030 configuration file in the Source Directory,
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007031 the
7032 <link linkend='ref-classes-image'><filename>image</filename></link>
7033 class, and the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007034 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007035 class to see how to use the
7036 <filename>INITRAMFS_IMAGE</filename> variable.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007037 </para>
7038
7039 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007040 If <filename>INITRAMFS_IMAGE</filename> is empty, which is
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007041 the default, then no initramfs image is built.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007042 </para>
7043
7044 <para>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007045 For more information, you can also see the
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007046 <link linkend='var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></link>
7047 variable, which allows the generated image to be bundled
7048 inside the kernel image.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007049 Additionally, for information on creating an initramfs
7050 image, see the
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007051 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007052 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007053 </para>
7054 </glossdef>
7055 </glossentry>
7056
7057 <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
7058 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007059 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)."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007060 </info>
7061 <glossdef>
7062 <para role="glossdeffirst">
7063<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7064 Controls whether or not the image recipe specified by
7065 <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007066 is run through an extra pass
7067 (<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>)
7068 during kernel compilation in order to build a single binary
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007069 that contains both the kernel image and the initial RAM
7070 filesystem (initramfs) image.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007071 This makes use of the
7072 <link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link>
7073 kernel feature.
7074 <note>
7075 Using an extra compilation pass to bundle the initramfs
7076 avoids a circular dependency between the kernel recipe and
7077 the initramfs recipe should the initramfs include kernel
7078 modules.
7079 Should that be the case, the initramfs recipe depends on
7080 the kernel for the kernel modules, and the kernel depends
7081 on the initramfs recipe since the initramfs is bundled
7082 inside the kernel image.
7083 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007084 </para>
7085
7086 <para>
7087 The combined binary is deposited into the
7088 <filename>tmp/deploy</filename> directory, which is part
7089 of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007090 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007091 </para>
7092
7093 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007094 Setting the variable to "1" in a configuration file causes the
7095 OpenEmbedded build system to generate a kernel image with the
Brad Bishop316dfdd2018-06-25 12:45:53 -04007096 initramfs specified in <filename>INITRAMFS_IMAGE</filename>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007097 bundled within:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007098 <literallayout class='monospaced'>
7099 INITRAMFS_IMAGE_BUNDLE = "1"
7100 </literallayout>
7101 By default, the
7102 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
7103 class sets this variable to a null string as follows:
7104 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007105 INITRAMFS_IMAGE_BUNDLE ?= ""
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007106 </literallayout>
7107 <note>
7108 You must set the
7109 <filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in
7110 a configuration file.
7111 You cannot set the variable in a recipe file.
7112 </note>
7113 See the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05007114 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007115 file for additional information.
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007116 Also, for information on creating an initramfs, see the
7117 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007118 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007119 </para>
7120 </glossdef>
7121 </glossentry>
7122
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007123 <glossentry id='var-INITRAMFS_LINK_NAME'><glossterm>INITRAMFS_LINK_NAME</glossterm>
7124 <info>
7125 INITRAMFS_LINK_NAME[doc] = "The link name of the initial RAM filesystem image."
7126 </info>
7127 <glossdef>
7128 <para role="glossdeffirst">
7129<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7130 The link name of the initial RAM filesystem image.
7131 This variable is set in the
7132 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7133 file as follows:
7134 <literallayout class='monospaced'>
7135 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"
7136 </literallayout>
7137 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7138 variable, which is set in the same file, has the following
7139 value:
7140 <literallayout class='monospaced'>
7141 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7142 </literallayout>
7143 </para>
7144
7145 <para>
7146 See the
7147 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7148 variable for additional information.
7149 </para>
7150 </glossdef>
7151 </glossentry>
7152
7153 <glossentry id='var-INITRAMFS_NAME'><glossterm>INITRAMFS_NAME</glossterm>
7154 <info>
7155 INITRAMFS_NAME[doc] = "The base name of the initial RAM filesystem image."
7156 </info>
7157 <glossdef>
7158 <para role="glossdeffirst">
7159<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7160 The base name of the initial RAM filesystem image.
7161 This variable is set in the
7162 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7163 file as follows:
7164 <literallayout class='monospaced'>
7165 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"
7166 </literallayout>
7167 The value of the
7168 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7169 variable, which is set in the same file, has the following
7170 value:
7171 <literallayout class='monospaced'>
7172 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7173 </literallayout>
7174 </para>
7175 </glossdef>
7176 </glossentry>
7177
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007178 <glossentry id='var-INITRD'><glossterm>INITRD</glossterm>
7179 <info>
7180 INITRD[doc] = "Indicates a list of filesystem images to concatenate and use as an initial RAM disk (initrd)."
7181 </info>
7182 <glossdef>
7183 <para role="glossdeffirst">
7184<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7185 Indicates list of filesystem images to concatenate and use
7186 as an initial RAM disk (<filename>initrd</filename>).
7187 </para>
7188
7189 <para>
7190 The <filename>INITRD</filename> variable is an optional
7191 variable used with the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05007192 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007193 class.
7194 </para>
7195 </glossdef>
7196 </glossentry>
7197
7198 <glossentry id='var-INITRD_IMAGE'><glossterm>INITRD_IMAGE</glossterm>
7199 <info>
7200 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."
7201 </info>
7202 <glossdef>
7203 <para role="glossdeffirst">
7204<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7205 When building a "live" bootable image (i.e. when
7206 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
7207 contains "live"), <filename>INITRD_IMAGE</filename>
7208 specifies the image recipe that should be built
7209 to provide the initial RAM disk image.
7210 The default value is "core-image-minimal-initramfs".
7211 </para>
7212
7213 <para>
7214 See the
7215 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
7216 class for more information.
7217 </para>
7218 </glossdef>
7219 </glossentry>
7220
7221 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
7222 <info>
7223 INITSCRIPT_NAME[doc] = "The filename of the initialization script as installed to ${sysconfdir}/init.d."
7224 </info>
7225 <glossdef>
7226 <para role="glossdeffirst">
7227<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7228 The filename of the initialization script as installed to
7229 <filename>${sysconfdir}/init.d</filename>.
7230 </para>
7231
7232 <para>
7233 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
7234 The variable is mandatory.
7235 </para>
7236 </glossdef>
7237 </glossentry>
7238
7239 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
7240 <info>
7241 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."
7242 </info>
7243 <glossdef>
7244 <para role="glossdeffirst">
7245<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7246 A list of the packages that contain initscripts.
7247 If multiple packages are specified, you need to append the package name
7248 to the other <filename>INITSCRIPT_*</filename> as an override.
7249 </para>
7250
7251 <para>
7252 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
7253 The variable is optional and defaults to the
7254 <link linkend='var-PN'><filename>PN</filename></link> variable.
7255 </para>
7256 </glossdef>
7257 </glossentry>
7258
7259 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
7260 <info>
7261 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."
7262 </info>
7263 <glossdef>
7264 <para role="glossdeffirst">
7265<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7266 Specifies the options to pass to <filename>update-rc.d</filename>.
7267 Here is an example:
7268 <literallayout class='monospaced'>
7269 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
7270 </literallayout>
7271 </para>
7272
7273 <para>
7274 In this example, the script has a runlevel of 99,
7275 starts the script in initlevels 2 and 5, and
7276 stops the script in levels 0, 1 and 6.
7277 </para>
7278
7279 <para>
7280 The variable's default value is "defaults", which is
7281 set in the
7282 <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
7283 class.
7284 </para>
7285
7286 <para>
7287 The value in
7288 <filename>INITSCRIPT_PARAMS</filename> is passed through
7289 to the <filename>update-rc.d</filename> command.
7290 For more information on valid parameters, please see the
7291 <filename>update-rc.d</filename> manual page at
7292 <ulink url='http://www.tin.org/bin/man.cgi?section=8&amp;topic=update-rc.d'></ulink>.
7293 </para>
7294 </glossdef>
7295 </glossentry>
7296
7297 <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
7298 <info>
7299 INSANE_SKIP[doc] = "Specifies the QA checks to skip for a specific package within a recipe."
7300 </info>
7301 <glossdef>
7302 <para role="glossdeffirst">
7303<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7304 Specifies the QA checks to skip for a specific package
7305 within a recipe.
7306 For example, to skip the check for symbolic link
7307 <filename>.so</filename> files in the main package of a
7308 recipe, add the following to the recipe.
7309 The package name override must be used, which in this
7310 example is <filename>${PN}</filename>:
7311 <literallayout class='monospaced'>
7312 INSANE_SKIP_${PN} += "dev-so"
7313 </literallayout>
7314 </para>
7315
7316 <para>
7317 See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
7318 section for a list of the valid QA checks you can
7319 specify using this variable.
7320 </para>
7321 </glossdef>
7322 </glossentry>
7323
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05007324 <glossentry id='var-INSTALL_TIMEZONE_FILE'><glossterm>INSTALL_TIMEZONE_FILE</glossterm>
7325 <info>
7326 INSTALL_TIMEZONE_FILE[doc] = "Enables installation of the /etc/timezone file."
7327 </info>
7328 <glossdef>
7329 <para role="glossdeffirst">
7330<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7331 By default, the <filename>tzdata</filename> recipe packages
7332 an <filename>/etc/timezone</filename> file.
7333 Set the <filename>INSTALL_TIMEZONE_FILE</filename>
7334 variable to "0" at the configuration level to disable this
7335 behavior.
7336 </para>
7337 </glossdef>
7338 </glossentry>
7339
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007340 <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
7341 <info>
7342 IPK_FEED_URIS[doc] = "List of ipkg feed records to put into generated image."
7343 </info>
7344 <glossdef>
7345 <para role="glossdeffirst">
7346<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7347 When the IPK backend is in use and package management
7348 is enabled on the target, you can use this variable to
7349 set up <filename>opkg</filename> in the target image
7350 to point to package feeds on a nominated server.
7351 Once the feed is established, you can perform
7352 installations or upgrades using the package manager
7353 at runtime.
7354 </para>
7355 </glossdef>
7356 </glossentry>
7357
7358<!--
7359 <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
7360 <glossdef>
7361 <para>
7362 An environment variable that defines the directory where
7363 post installation hooks are installed for the
7364 post install environment.
7365 This variable is fixed as follows:
7366 <literallayout class='monospaced'>
7367 ${WORKDIR}/intercept_scripts
7368 </literallayout>
7369 </para>
7370
7371 <para>
7372 After installation of a target's root filesystem,
7373 post installation scripts, which are essentially bash scripts,
7374 are all executed just a single time.
7375 Limiting execution of these scripts minimizes installation
7376 time that would be lengthened due to certain packages
7377 triggering redundant operations.
7378 For example, consider the installation of font packages
7379 as a common example.
7380 Without limiting the execution of post installation scripts,
7381 all font directories would be rescanned to create the
7382 cache after each individual font package was installed.
7383 </para>
7384
7385 <para>
7386 Do not edit the <filename>INTERCEPT_DIR</filename>
7387 variable.
7388 </para>
7389 </glossdef>
7390 </glossentry>
7391-->
7392
7393 </glossdiv>
7394
7395<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
7396<!-- </glossdiv>-->
7397
7398 <glossdiv id='var-glossary-k'><title>K</title>
7399
7400 <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
7401 <info>
7402 KARCH[doc] = "Defines the kernel architecture used when assembling the configuration. You define the KARCH variable in the BSP Descriptions."
7403 </info>
7404 <glossdef>
7405 <para role="glossdeffirst">
7406<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7407 Defines the kernel architecture used when assembling
7408 the configuration.
7409 Architectures supported for this release are:
7410 <literallayout class='monospaced'>
7411 powerpc
7412 i386
7413 x86_64
7414 arm
7415 qemu
7416 mips
7417 </literallayout>
7418 </para>
7419
7420 <para>
7421 You define the <filename>KARCH</filename> variable in the
7422 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
7423 </para>
7424 </glossdef>
7425 </glossentry>
7426
7427 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
7428 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04007429 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007430 </info>
7431 <glossdef>
7432 <para role="glossdeffirst">
7433<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7434 A regular expression used by the build process to explicitly
7435 identify the kernel branch that is validated, patched,
7436 and configured during a build.
7437 You must set this variable to ensure the exact kernel
7438 branch you want is being used by the build process.
7439 </para>
7440
7441 <para>
7442 Values for this variable are set in the kernel's recipe
7443 file and the kernel's append file.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007444 For example, if you are using the
7445 <filename>linux-yocto_4.12</filename> kernel, the kernel
7446 recipe file is the
7447 <filename>meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007448 file.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007449 <filename>KBRANCH</filename> is set as follows in that
7450 kernel recipe file:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007451 <literallayout class='monospaced'>
7452 KBRANCH ?= "standard/base"
7453 </literallayout>
7454 </para>
7455
7456 <para>
7457 This variable is also used from the kernel's append file
7458 to identify the kernel branch specific to a particular
7459 machine or target hardware.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007460 Continuing with the previous kernel example, the kernel's
7461 append file (i.e.
7462 <filename>linux-yocto_4.12.bbappend</filename>) is located
7463 in the BSP layer for a given machine.
7464 For example, the append file for the Beaglebone,
7465 EdgeRouter, and generic versions of both 32 and 64-bit IA
7466 machines (<filename>meta-yocto-bsp</filename>) is named
7467 <filename>meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend</filename>.
7468 Here are the related statements from that append file:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007469 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007470 KBRANCH_genericx86 = "standard/base"
7471 KBRANCH_genericx86-64 = "standard/base"
7472 KBRANCH_edgerouter = "standard/edgerouter"
7473 KBRANCH_beaglebone = "standard/beaglebone"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007474 </literallayout>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007475 The <filename>KBRANCH</filename> statements identify
7476 the kernel branch to use when building for each
7477 supported BSP.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007478 </para>
7479 </glossdef>
7480 </glossentry>
7481
7482 <glossentry id='var-KBUILD_DEFCONFIG'><glossterm>KBUILD_DEFCONFIG</glossterm>
7483 <info>
7484 KBUILD_DEFCONFIG[doc] = "Specifies an "in-tree" kernel configuration file for use during a kernel build."
7485 </info>
7486 <glossdef>
7487 <para role="glossdeffirst">
7488<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7489 When used with the
7490 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
7491 class, specifies an "in-tree" kernel configuration file
7492 for use during a kernel build.
7493 </para>
7494
7495 <para>
7496 Typically, when using a <filename>defconfig</filename> to
7497 configure a kernel during a build, you place the
7498 file in your layer in the same manner as you would
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007499 place patch files and configuration fragment files (i.e.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007500 "out-of-tree").
7501 However, if you want to use a <filename>defconfig</filename>
7502 file that is part of the kernel tree (i.e. "in-tree"),
7503 you can use the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007504 <filename>KBUILD_DEFCONFIG</filename> variable and append
7505 the
7506 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
7507 variable to point to the <filename>defconfig</filename>
7508 file.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007509 </para>
7510
7511 <para>
7512 To use the variable, set it in the append file for your
7513 kernel recipe using the following form:
7514 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007515 KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007516 </literallayout>
7517 Here is an example from a "raspberrypi2"
7518 <filename>KMACHINE</filename> build that uses a
7519 <filename>defconfig</filename> file named
7520 "bcm2709_defconfig":
7521 <literallayout class='monospaced'>
7522 KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig"
7523 </literallayout>
7524 As an alternative, you can use the following within your
7525 append file:
7526 <literallayout class='monospaced'>
7527 KBUILD_DEFCONFIG_pn-linux-yocto ?= <replaceable>defconfig_file</replaceable>
7528 </literallayout>
7529 For more information on how to use the
7530 <filename>KBUILD_DEFCONFIG</filename> variable, see the
7531 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-an-in-tree-defconfig-file'>Using an "In-Tree" <filename>defconfig</filename> File</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -04007532 section in the Yocto Project Linux Kernel Development
7533 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007534 </para>
7535 </glossdef>
7536 </glossentry>
7537
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007538 <glossentry id='var-KERNEL_ALT_IMAGETYPE'><glossterm>KERNEL_ALT_IMAGETYPE</glossterm>
7539 <info>
7540 KERNEL_ALT_IMAGETYPE[doc] = "Specifies an alternate kernel image type for creation."
7541 </info>
7542 <glossdef>
7543 <para role="glossdeffirst">
7544<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7545 Specifies an alternate kernel image type for creation in
7546 addition to the kernel image type specified using the
7547 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
7548 variable.
7549 </para>
7550 </glossdef>
7551 </glossentry>
7552
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007553 <glossentry id='var-KERNEL_ARTIFACT_NAME'><glossterm>KERNEL_ARTIFACT_NAME</glossterm>
7554 <info>
7555 KERNEL_ARTIFACT_NAME[doc] = "Specifies the name of all of the build artifacts."
7556 </info>
7557 <glossdef>
7558 <para role="glossdeffirst">
7559<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7560 Specifies the name of all of the build artifacts.
7561 You can change the name of the artifacts by changing the
7562 <filename>KERNEL_ARTIFACT_NAME</filename> variable.
7563 </para>
7564
7565 <para>
7566 The value of <filename>KERNEL_ARTIFACT_NAME</filename>,
7567 which is set in the
7568 <filename> meta/classes/kernel-artifact-names.bbclass</filename>
7569 file, has the following default value:
7570 <literallayout class='monospaced'>
7571 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7572 </literallayout>
7573 </para>
7574
7575 <para>
7576 See the
7577 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
7578 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
7579 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
7580 and
7581 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7582 variables for additional information.
7583 <note>
7584 The <filename>IMAGE_VERSION_SUFFIX</filename> variable
7585 is set to
7586 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>.
7587 </note>
7588 </para>
7589 </glossdef>
7590 </glossentry>
7591
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007592 <glossentry id='var-KERNEL_CLASSES'><glossterm>KERNEL_CLASSES</glossterm>
7593 <info>
7594 KERNEL_CLASSES[doc] = "A list of classes defining kernel image types that kernel class should inherit."
7595 </info>
7596 <glossdef>
7597 <para role="glossdeffirst">
7598<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7599 A list of classes defining kernel image types that the
7600 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
7601 class should inherit.
7602 You typically append this variable to enable extended image
7603 types.
7604 An example is the "kernel-fitimage", which enables
7605 fitImage support and resides in
7606 <filename>meta/classes/kernel-fitimage.bbclass</filename>.
7607 You can register custom kernel image types with the
7608 <filename>kernel</filename> class using this variable.
7609 </para>
7610 </glossdef>
7611 </glossentry>
7612
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007613 <glossentry id='var-KERNEL_DEVICETREE'><glossterm>KERNEL_DEVICETREE</glossterm>
7614 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04007615 KERNEL_DEVICETREE[doc] = "Specifies the name of the generated Linux kernel device tree (i.e. the .dtb) file."
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007616 </info>
7617 <glossdef>
7618 <para role="glossdeffirst">
7619<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7620 Specifies the name of the generated Linux kernel device tree
7621 (i.e. the <filename>.dtb</filename>) file.
7622 <note>
7623 Legacy support exists for specifying the full path
7624 to the device tree.
7625 However, providing just the <filename>.dtb</filename>
7626 file is preferred.
7627 </note>
Brad Bishop79641f22019-09-10 07:20:22 -04007628 In order to use this variable, the
7629 <link linkend='ref-classes-kernel-devicetree'><filename>kernel-devicetree</filename></link>
7630 class must be inherited.
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007631 </para>
7632 </glossdef>
7633 </glossentry>
7634
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007635 <glossentry id='var-KERNEL_DTB_LINK_NAME'><glossterm>KERNEL_DTB_LINK_NAME</glossterm>
7636 <info>
7637 KERNEL_DTB_LINK_NAME[doc] = "The link name of the kernel device tree binary (DTB)."
7638 </info>
7639 <glossdef>
7640 <para role="glossdeffirst">
7641<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7642 The link name of the kernel device tree binary (DTB).
7643 This variable is set in the
7644 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7645 file as follows:
7646 <literallayout class='monospaced'>
7647 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7648 </literallayout>
7649 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7650 variable, which is set in the same file, has the following
7651 value:
7652 <literallayout class='monospaced'>
7653 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7654 </literallayout>
7655 </para>
7656
7657 <para>
7658 See the
7659 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7660 variable for additional information.
7661 </para>
7662 </glossdef>
7663 </glossentry>
7664
7665 <glossentry id='var-KERNEL_DTB_NAME'><glossterm>KERNEL_DTB_NAME</glossterm>
7666 <info>
7667 KERNEL_DTB_NAME[doc] = "The base name of the kernel device tree binary (DTB)."
7668 </info>
7669 <glossdef>
7670 <para role="glossdeffirst">
7671<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7672 The base name of the kernel device tree binary (DTB).
7673 This variable is set in the
7674 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7675 file as follows:
7676 <literallayout class='monospaced'>
7677 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7678 </literallayout>
7679 The value of the
7680 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7681 variable, which is set in the same file, has the following
7682 value:
7683 <literallayout class='monospaced'>
7684 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7685 </literallayout>
7686 </para>
7687 </glossdef>
7688 </glossentry>
7689
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007690 <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
7691 <info>
7692 KERNEL_EXTRA_ARGS[doc] = "Specifies additional make command-line arguments the OpenEmbedded build system passes on when compiling the kernel."
7693 </info>
7694 <glossdef>
7695 <para role="glossdeffirst">
7696<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7697 Specifies additional <filename>make</filename>
7698 command-line arguments the OpenEmbedded build system
7699 passes on when compiling the kernel.
7700 </para>
7701 </glossdef>
7702 </glossentry>
7703
7704 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
7705 <info>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007706 KERNEL_FEATURES[doc] = "Includes additional kernel metadata. The metadata you add through this variable includes config fragments and features descriptions."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007707 </info>
7708 <glossdef>
7709 <para role="glossdeffirst">
7710<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007711 Includes additional kernel metadata.
7712 In the OpenEmbedded build system, the default Board Support
7713 Packages (BSPs)
7714 <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007715 is provided through
7716 the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007717 and
7718 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>
7719 variables.
7720 You can use the <filename>KERNEL_FEATURES</filename>
7721 variable from within the kernel recipe or kernel append
7722 file to further add metadata for all BSPs or specific
7723 BSPs.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007724 </para>
7725
7726 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007727 The metadata you add through this variable includes config
7728 fragments and features descriptions,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007729 which usually includes patches as well as config fragments.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007730 You typically override the
7731 <filename>KERNEL_FEATURES</filename> variable for a
7732 specific machine.
7733 In this way, you can provide validated, but optional,
7734 sets of kernel configurations and features.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007735 </para>
7736
7737 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007738 For example, the following example from the
7739 <filename>linux-yocto-rt_4.12</filename> kernel recipe
7740 adds "netfilter" and "taskstats" features to all BSPs
7741 as well as "virtio" configurations to all QEMU machines.
7742 The last two statements add specific configurations to
7743 targeted machine types:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007744 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007745 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
7746 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007747 KERNEL_FEATURES_append_qemuall = " cfg/virtio.scc"
7748 KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"
7749 KERNEL_FEATURES_append_qemux86-64 = " cfg/sound.scc" </literallayout></para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007750 </glossdef>
7751 </glossentry>
7752
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007753 <glossentry id='var-KERNEL_FIT_LINK_NAME'><glossterm>KERNEL_FIT_LINK_NAME</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007754 <info>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007755 KERNEL_FIT_LINK_NAME[doc] = "The link name of the kernel flattened image tree (FIT) image."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007756 </info>
7757 <glossdef>
7758 <para role="glossdeffirst">
7759<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007760 The link name of the kernel flattened image tree (FIT) image.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007761 This variable is set in the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007762 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7763 file as follows:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007764 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007765 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7766 </literallayout>
7767 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7768 variable, which is set in the same file, has the following
7769 value:
7770 <literallayout class='monospaced'>
7771 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007772 </literallayout>
7773 </para>
7774
7775 <para>
7776 See the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007777 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7778 variable for additional information.
7779 </para>
7780 </glossdef>
7781 </glossentry>
7782
7783 <glossentry id='var-KERNEL_FIT_NAME'><glossterm>KERNEL_FIT_NAME</glossterm>
7784 <info>
7785 KERNEL_FIT_NAME[doc] = "The base name of the kernel flattened image tree (FIT) image."
7786 </info>
7787 <glossdef>
7788 <para role="glossdeffirst">
7789<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7790 The base name of the kernel flattened image tree (FIT) image.
7791 This variable is set in the
7792 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7793 file as follows:
7794 <literallayout class='monospaced'>
7795 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7796 </literallayout>
7797 The value of the
7798 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7799 variable, which is set in the same file, has the following
7800 value:
7801 <literallayout class='monospaced'>
7802 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7803 </literallayout>
7804 </para>
7805 </glossdef>
7806 </glossentry>
7807
7808 <glossentry id='var-KERNEL_IMAGE_LINK_NAME'><glossterm>KERNEL_IMAGE_LINK_NAME</glossterm>
7809 <info>
7810 KERNEL_IMAGE_LINK_NAME[doc] = "The link name for the kernel image."
7811 </info>
7812 <glossdef>
7813 <para role="glossdeffirst">
7814<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7815 The link name for the kernel image.
7816 This variable is set in the
7817 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7818 file as follows:
7819 <literallayout class='monospaced'>
7820 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7821 </literallayout>
7822 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7823 variable, which is set in the same file, has the following
7824 value:
7825 <literallayout class='monospaced'>
7826 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7827 </literallayout>
7828 </para>
7829
7830 <para>
7831 See the
7832 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7833 variable for additional information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007834 </para>
7835 </glossdef>
7836 </glossentry>
7837
7838 <glossentry id='var-KERNEL_IMAGE_MAXSIZE'><glossterm>KERNEL_IMAGE_MAXSIZE</glossterm>
7839 <info>
7840 KERNEL_IMAGE_MAXSIZE[doc] = "The maximum allowable size in kilobytes of the kernel image file."
7841 </info>
7842 <glossdef>
7843 <para role="glossdeffirst">
7844<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7845 Specifies the maximum size of the kernel image file in
7846 kilobytes.
7847 If <filename>KERNEL_IMAGE_MAXSIZE</filename> is set,
7848 the size of the kernel image file is checked against
7849 the set value during the
7850 <link linkend='ref-tasks-sizecheck'><filename>do_sizecheck</filename></link>
7851 task.
7852 The task fails if the kernel image file is larger than
7853 the setting.
7854 </para>
7855
7856 <para>
7857 <filename>KERNEL_IMAGE_MAXSIZE</filename> is useful for
7858 target devices that have a limited amount of space in
7859 which the kernel image must be stored.
7860 </para>
7861
7862 <para>
7863 By default, this variable is not set, which means the
7864 size of the kernel image is not checked.
7865 </para>
7866 </glossdef>
7867 </glossentry>
7868
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007869 <glossentry id='var-KERNEL_IMAGE_NAME'><glossterm>KERNEL_IMAGE_NAME</glossterm>
7870 <info>
7871 KERNEL_IMAGE_NAME[doc] = "The base name of the kernel image."
7872 </info>
7873 <glossdef>
7874 <para role="glossdeffirst">
7875<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7876 The base name of the kernel image.
7877 This variable is set in the
7878 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7879 file as follows:
7880 <literallayout class='monospaced'>
7881 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7882 </literallayout>
7883 The value of the
7884 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7885 variable, which is set in the same file, has the following
7886 value:
7887 <literallayout class='monospaced'>
7888 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7889 </literallayout>
7890 </para>
7891 </glossdef>
7892 </glossentry>
7893
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007894 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
7895 <info>
7896 KERNEL_IMAGETYPE[doc] = "The type of kernel to build for a device, usually set by the machine configuration files and defaults to 'zImage'."
7897 </info>
7898 <glossdef>
7899 <para role="glossdeffirst">
7900<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7901 The type of kernel to build for a device, usually set by the
7902 machine configuration files and defaults to "zImage".
7903 This variable is used
7904 when building the kernel and is passed to <filename>make</filename> as the target to
7905 build.
7906 </para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007907
7908 <para>
7909 If you want to build an alternate kernel image type, use the
7910 <link linkend='var-KERNEL_ALT_IMAGETYPE'><filename>KERNEL_ALT_IMAGETYPE</filename></link>
7911 variable.
7912 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007913 </glossdef>
7914 </glossentry>
7915
7916 <glossentry id='var-KERNEL_MODULE_AUTOLOAD'><glossterm>KERNEL_MODULE_AUTOLOAD</glossterm>
7917 <info>
7918 KERNEL_MODULE_AUTOLOAD[doc] = "Lists kernel modules that need to be auto-loaded during boot"
7919 </info>
7920 <glossdef>
7921 <para role="glossdeffirst">
7922<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7923 Lists kernel modules that need to be auto-loaded during
7924 boot.
7925 <note>
7926 This variable replaces the deprecated
7927 <link linkend='var-module_autoload'><filename>module_autoload</filename></link>
7928 variable.
7929 </note>
7930 </para>
7931
7932 <para>
7933 You can use the <filename>KERNEL_MODULE_AUTOLOAD</filename>
7934 variable anywhere that it can be
7935 recognized by the kernel recipe or by an out-of-tree kernel
7936 module recipe (e.g. a machine configuration file, a
7937 distribution configuration file, an append file for the
7938 recipe, or the recipe itself).
7939 </para>
7940
7941 <para>
7942 Specify it as follows:
7943 <literallayout class='monospaced'>
7944 KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name1</replaceable> <replaceable>module_name2</replaceable> <replaceable>module_name3</replaceable>"
7945 </literallayout>
7946 </para>
7947
7948 <para>
7949 Including <filename>KERNEL_MODULE_AUTOLOAD</filename> causes
7950 the OpenEmbedded build system to populate the
7951 <filename>/etc/modules-load.d/modname.conf</filename>
7952 file with the list of modules to be auto-loaded on boot.
7953 The modules appear one-per-line in the file.
7954 Here is an example of the most common use case:
7955 <literallayout class='monospaced'>
7956 KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name</replaceable>"
7957 </literallayout>
7958 </para>
7959
7960 <para>
7961 For information on how to populate the
7962 <filename>modname.conf</filename> file with
7963 <filename>modprobe.d</filename> syntax lines, see the
7964 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
7965 variable.
7966 </para>
7967 </glossdef>
7968 </glossentry>
7969
7970 <glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm>KERNEL_MODULE_PROBECONF</glossterm>
7971 <info>
7972 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."
7973 </info>
7974 <glossdef>
7975 <para role="glossdeffirst">
7976<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7977 Provides a list of modules for which the OpenEmbedded
7978 build system expects to find
7979 <filename>module_conf_</filename><replaceable>modname</replaceable>
7980 values that specify configuration for each of the modules.
7981 For information on how to provide those module
7982 configurations, see the
7983 <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
7984 variable.
7985 </para>
7986 </glossdef>
7987 </glossentry>
7988
7989 <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
7990 <info>
7991 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)."
7992 </info>
7993 <glossdef>
7994 <para role="glossdeffirst">
7995<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7996 The location of the kernel sources.
7997 This variable is set to the value of the
7998 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
7999 within the
8000 <link linkend='ref-classes-module'><filename>module</filename></link>
8001 class.
8002 For information on how this variable is used, see the
8003 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -04008004 section in the Yocto Project Linux Kernel Development
8005 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008006 </para>
8007
8008 <para>
8009 To help maximize compatibility with out-of-tree drivers
8010 used to build modules, the OpenEmbedded build system also
8011 recognizes and uses the
8012 <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
8013 variable, which is identical to the
8014 <filename>KERNEL_PATH</filename> variable.
8015 Both variables are common variables used by external
8016 Makefiles to point to the kernel source directory.
8017 </para>
8018 </glossdef>
8019 </glossentry>
8020
8021 <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
8022 <info>
8023 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)."
8024 </info>
8025 <glossdef>
8026 <para role="glossdeffirst">
8027<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8028 The location of the kernel sources.
8029 This variable is set to the value of the
8030 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
8031 within the
8032 <link linkend='ref-classes-module'><filename>module</filename></link>
8033 class.
8034 For information on how this variable is used, see the
8035 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -04008036 section in the Yocto Project Linux Kernel Development
8037 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008038 </para>
8039
8040 <para>
8041 To help maximize compatibility with out-of-tree drivers
8042 used to build modules, the OpenEmbedded build system also
8043 recognizes and uses the
8044 <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
8045 variable, which is identical to the
8046 <filename>KERNEL_SRC</filename> variable.
8047 Both variables are common variables used by external
8048 Makefiles to point to the kernel source directory.
8049 </para>
8050 </glossdef>
8051 </glossentry>
8052
Patrick Williamsf1e5d692016-03-30 15:21:19 -05008053 <glossentry id='var-KERNEL_VERSION'><glossterm>KERNEL_VERSION</glossterm>
8054 <info>
8055 KERNEL_VERSION[doc] = "Specifies the version of the kernel as extracted from version.h or utsrelease.h within the kernel sources."
8056 </info>
8057 <glossdef>
8058 <para role="glossdeffirst">
8059<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8060 Specifies the version of the kernel as extracted from
8061 <filename>version.h</filename> or
8062 <filename>utsrelease.h</filename> within the kernel sources.
8063 Effects of setting this variable do not take affect until
8064 the kernel has been configured.
8065 Consequently, attempting to refer to this variable in
8066 contexts prior to configuration will not work.
8067 </para>
8068 </glossdef>
8069 </glossentry>
8070
8071 <glossentry id='var-KERNELDEPMODDEPEND'><glossterm>KERNELDEPMODDEPEND</glossterm>
8072 <info>
8073 KERNELDEPMODDEPEND[doc] = "Specifies whether or not to use the data referenced through the PKGDATA_DIR directory."
8074 </info>
8075 <glossdef>
8076 <para role="glossdeffirst">
8077<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8078 Specifies whether the data referenced through
8079 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
8080 is needed or not.
8081 The <filename>KERNELDEPMODDEPEND</filename> does not
8082 control whether or not that data exists,
8083 but simply whether or not it is used.
8084 If you do not need to use the data, set the
8085 <filename>KERNELDEPMODDEPEND</filename> variable in your
8086 <filename>initramfs</filename> recipe.
8087 Setting the variable there when the data is not needed
8088 avoids a potential dependency loop.
8089 </para>
8090 </glossdef>
8091 </glossentry>
8092
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008093 <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
8094 <info>
8095 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."
8096 </info>
8097 <glossdef>
8098 <para role="glossdeffirst">
8099<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8100 Provides a short description of a configuration fragment.
8101 You use this variable in the <filename>.scc</filename>
8102 file that describes a configuration fragment file.
8103 Here is the variable used in a file named
8104 <filename>smp.scc</filename> to describe SMP being
8105 enabled:
8106 <literallayout class='monospaced'>
8107 define KFEATURE_DESCRIPTION "Enable SMP"
8108 </literallayout>
8109 </para>
8110 </glossdef>
8111 </glossentry>
8112
8113 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
8114 <info>
8115 KMACHINE[doc] = "The machine as known by the kernel."
8116 </info>
8117 <glossdef>
8118 <para role="glossdeffirst">
8119<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8120 The machine as known by the kernel.
8121 Sometimes the machine name used by the kernel does not
8122 match the machine name used by the OpenEmbedded build
8123 system.
8124 For example, the machine name that the OpenEmbedded build
8125 system understands as
8126 <filename>core2-32-intel-common</filename> goes by a
8127 different name in the Linux Yocto kernel.
8128 The kernel understands that machine as
8129 <filename>intel-core2-32</filename>.
8130 For cases like these, the <filename>KMACHINE</filename>
8131 variable maps the kernel machine name to the OpenEmbedded
8132 build system machine name.
8133 </para>
8134
8135 <para>
8136 These mappings between different names occur in the
8137 Yocto Linux Kernel's <filename>meta</filename> branch.
8138 As an example take a look in the
8139 <filename>common/recipes-kernel/linux/linux-yocto_3.19.bbappend</filename>
8140 file:
8141 <literallayout class='monospaced'>
8142 LINUX_VERSION_core2-32-intel-common = "3.19.0"
8143 COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}"
8144 SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"
8145 SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
8146 KMACHINE_core2-32-intel-common = "intel-core2-32"
8147 KBRANCH_core2-32-intel-common = "standard/base"
8148 KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"
8149 </literallayout>
8150 The <filename>KMACHINE</filename> statement says that
8151 the kernel understands the machine name as
8152 "intel-core2-32".
8153 However, the OpenEmbedded build system understands the
8154 machine as "core2-32-intel-common".
8155 </para>
8156
8157 </glossdef>
8158 </glossentry>
8159
8160 <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
8161 <info>
8162 KTYPE[doc] = "Defines the kernel type to be used in assembling the configuration."
8163 </info>
8164 <glossdef>
8165 <para role="glossdeffirst">
8166<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8167 Defines the kernel type to be used in assembling the
8168 configuration.
8169 The linux-yocto recipes define "standard", "tiny",
8170 and "preempt-rt" kernel types.
8171 See the
8172 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
8173 section in the Yocto Project Linux Kernel Development
8174 Manual for more information on kernel types.
8175 </para>
8176
8177 <para>
8178 You define the <filename>KTYPE</filename> variable in the
8179 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
8180 The value you use must match the value used for the
8181 <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
8182 value used by the kernel recipe.
8183 </para>
8184 </glossdef>
8185 </glossentry>
8186 </glossdiv>
8187
8188 <glossdiv id='var-glossary-l'><title>L</title>
8189
8190 <glossentry id='var-LABELS'><glossterm>LABELS</glossterm>
8191 <info>
8192 LABELS[doc] = "Provides a list of targets for automatic configuration."
8193 </info>
8194 <glossdef>
8195 <para role="glossdeffirst">
8196<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8197 Provides a list of targets for automatic configuration.
8198 </para>
8199
8200 <para>
8201 See the
8202 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
8203 class for more information on how this variable is used.
8204 </para>
8205 </glossdef>
8206 </glossentry>
8207
8208 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
8209 <info>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05008210 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008211 </info>
8212 <glossdef>
8213 <para role="glossdeffirst">
8214<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop6e60e8b2018-02-01 10:27:11 -05008215 Lists the layers, separated by spaces, on which this
8216 recipe depends.
8217 Optionally, you can specify a specific layer version for a
8218 dependency by adding it to the end of the layer name.
8219 Here is an example:
8220 <literallayout class='monospaced'>
8221 LAYERDEPENDS_mylayer = "anotherlayer (=3)"
8222 </literallayout>
8223 In this previous example, version 3 of "anotherlayer"
8224 is compared against
8225 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>.
8226 </para>
8227
8228 <para>
8229 An error is produced if any dependency is missing or
8230 the version numbers (if specified) do not match exactly.
8231 This variable is used in the
8232 <filename>conf/layer.conf</filename> file and must be
8233 suffixed with the name of the specific layer (e.g.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008234 <filename>LAYERDEPENDS_mylayer</filename>).
8235 </para>
8236 </glossdef>
8237 </glossentry>
8238
8239 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
8240 <info>
8241 LAYERDIR[doc] = "When used inside the layer.conf configuration file, this variable provides the path of the current layer."
8242 </info>
8243 <glossdef>
8244 <para role="glossdeffirst">
8245<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8246 When used inside the <filename>layer.conf</filename> configuration
8247 file, this variable provides the path of the current layer.
8248 This variable is not available outside of <filename>layer.conf</filename>
8249 and references are expanded immediately when parsing of the file completes.
8250 </para>
8251 </glossdef>
8252 </glossentry>
8253
Brad Bishop6e60e8b2018-02-01 10:27:11 -05008254 <glossentry id='var-LAYERRECOMMENDS'><glossterm>LAYERRECOMMENDS</glossterm>
8255 <info>
8256 LAYERRECOMMENDS[doc] = "Lists the layers, separated by spaces, recommended for use with this layer."
8257 </info>
8258 <glossdef>
8259 <para role="glossdeffirst">
8260<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8261 Lists the layers, separated by spaces, recommended for
8262 use with this layer.
8263 </para>
8264
8265 <para>
8266 Optionally, you can specify a specific layer version for a
8267 recommendation by adding the version to the end of the
8268 layer name.
8269 Here is an example:
8270 <literallayout class='monospaced'>
8271 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"
8272 </literallayout>
8273 In this previous example, version 3 of "anotherlayer" is
8274 compared against
8275 <filename>LAYERVERSION_anotherlayer</filename>.
8276 </para>
8277
8278 <para>
8279 This variable is used in the
8280 <filename>conf/layer.conf</filename> file and must be
8281 suffixed with the name of the specific layer (e.g.
8282 <filename>LAYERRECOMMENDS_mylayer</filename>).
8283 </para>
8284 </glossdef>
8285 </glossentry>
8286
Brad Bishop316dfdd2018-06-25 12:45:53 -04008287 <glossentry id='var-LAYERSERIES_COMPAT'><glossterm>LAYERSERIES_COMPAT</glossterm>
8288 <info>
8289 LAYERSERIES_COMPAT[doc] = "Lists the OpenEmbedded-Core versions for which a layer is compatible."
8290 </info>
8291 <glossdef>
8292 <para role="glossdeffirst">
8293<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8294 Lists the versions of the
8295 <link linkend='oe-core'>OpenEmbedded-Core</link> for which
8296 a layer is compatible.
8297 Using the <filename>LAYERSERIES_COMPAT</filename> variable
8298 allows the layer maintainer to indicate which combinations
8299 of the layer and OE-Core can be expected to work.
8300 The variable gives the system a way to detect when a layer
8301 has not been tested with new releases of OE-Core (e.g.
8302 the layer is not maintained).
8303 </para>
8304
8305 <para>
8306 To specify the OE-Core versions for which a layer is
8307 compatible, use this variable in your layer's
8308 <filename>conf/layer.conf</filename> configuration file.
8309 For the list, use the Yocto Project
8310 <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Release Name</ulink>
8311 (e.g. &DISTRO_NAME_NO_CAP;).
8312 To specify multiple OE-Core versions for the layer,
8313 use a space-separated list:
8314 <literallayout class='monospaced'>
8315 LAYERSERIES_COMPAT_<replaceable>layer_root_name</replaceable> = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;"
8316 </literallayout>
8317 <note>
8318 Setting <filename>LAYERSERIES_COMPAT</filename> is
8319 required by the Yocto Project Compatible version 2
8320 standard.
8321 The OpenEmbedded build system produces a warning if
8322 the variable is not set for any given layer.
8323 </note>
8324 </para>
8325
8326 <para>
8327 See the
8328 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-layer'>Creating Your Own Layer</ulink>"
8329 section in the Yocto Project Development Tasks Manual.
8330 </para>
8331 </glossdef>
8332 </glossentry>
8333
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008334 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
8335 <info>
8336 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."
8337 </info>
8338 <glossdef>
8339 <para role="glossdeffirst">
8340<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8341 Optionally specifies the version of a layer as a single number.
8342 You can use this within
8343 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
8344 for another layer in order to depend on a specific version
8345 of the layer.
8346 This variable is used in the <filename>conf/layer.conf</filename> file
8347 and must be suffixed with the name of the specific layer (e.g.
8348 <filename>LAYERVERSION_mylayer</filename>).
8349 </para>
8350 </glossdef>
8351 </glossentry>
8352
8353 <glossentry id='var-LD'><glossterm>LD</glossterm>
8354 <info>
8355 LD[doc] = "Minimal command and arguments to run the linker."
8356 </info>
8357 <glossdef>
8358 <para role="glossdeffirst">
8359<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8360 The minimal command and arguments used to run the
8361 linker.
8362 </para>
8363 </glossdef>
8364 </glossentry>
8365
8366 <glossentry id='var-LDFLAGS'><glossterm>LDFLAGS</glossterm>
8367 <info>
8368 LDFLAGS[doc] = "Specifies the flags to pass to the linker."
8369 </info>
8370 <glossdef>
8371 <para role="glossdeffirst">
8372<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8373 Specifies the flags to pass to the linker.
8374 This variable is exported to an environment
8375 variable and thus made visible to the software being
8376 built during the compilation step.
8377 </para>
8378
8379 <para>
8380 Default initialization for <filename>LDFLAGS</filename>
8381 varies depending on what is being built:
8382 <itemizedlist>
8383 <listitem><para>
8384 <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link>
8385 when building for the target
8386 </para></listitem>
8387 <listitem><para>
8388 <link linkend='var-BUILD_LDFLAGS'><filename>BUILD_LDFLAGS</filename></link>
8389 when building for the build host (i.e.
8390 <filename>-native</filename>)
8391 </para></listitem>
8392 <listitem><para>
8393 <link linkend='var-BUILDSDK_LDFLAGS'><filename>BUILDSDK_LDFLAGS</filename></link>
8394 when building for an SDK (i.e.
8395 <filename>nativesdk-</filename>)
8396 </para></listitem>
8397 </itemizedlist>
8398 </para>
8399 </glossdef>
8400 </glossentry>
8401
8402 <glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>
8403 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04008404 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008405 </info>
8406 <glossdef>
8407 <para role="glossdeffirst">
8408<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8409 Specifies the lead (or primary) compiled library file
Brad Bishop316dfdd2018-06-25 12:45:53 -04008410 (i.e. <filename>.so</filename>) that the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008411 <link linkend='ref-classes-debian'><filename>debian</filename></link>
8412 class applies its naming policy to given a recipe that
8413 packages multiple libraries.
8414 </para>
8415
8416 <para>
8417 This variable works in conjunction with the
8418 <filename>debian</filename> class.
8419 </para>
8420 </glossdef>
8421 </glossentry>
8422
8423 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
8424 <info>
8425 LIC_FILES_CHKSUM[doc] = "Checksums of the license text in the recipe source code."
8426 </info>
8427 <glossdef>
8428 <para role="glossdeffirst">
8429<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8430 Checksums of the license text in the recipe source code.
8431 </para>
8432
8433 <para>
8434 This variable tracks changes in license text of the source
8435 code files.
8436 If the license text is changed, it will trigger a build
8437 failure, which gives the developer an opportunity to review any
8438 license change.
8439 </para>
8440
8441 <para>
8442 This variable must be defined for all recipes (unless
8443 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8444 is set to "CLOSED").</para>
8445 <para>For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04008446 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
8447 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008448 </para>
8449 </glossdef>
8450 </glossentry>
8451
8452 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
8453 <info>
8454 LICENSE[doc] = "The list of source licenses for the recipe. The logical operators &amp;, '|', and parentheses can be used."
8455 </info>
8456 <glossdef>
8457 <para role="glossdeffirst">
8458<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8459 The list of source licenses for the recipe.
8460 Follow these rules:
8461 <itemizedlist>
8462 <listitem><para>Do not use spaces within individual
8463 license names.</para></listitem>
8464 <listitem><para>Separate license names using
8465 | (pipe) when there is a choice between licenses.
8466 </para></listitem>
8467 <listitem><para>Separate license names using
8468 &amp; (ampersand) when multiple licenses exist
8469 that cover different parts of the source.
8470 </para></listitem>
8471 <listitem><para>You can use spaces between license
8472 names.</para></listitem>
8473 <listitem><para>For standard licenses, use the names
8474 of the files in
8475 <filename>meta/files/common-licenses/</filename>
8476 or the
8477 <link linkend='var-SPDXLICENSEMAP'><filename>SPDXLICENSEMAP</filename></link>
8478 flag names defined in
8479 <filename>meta/conf/licenses.conf</filename>.
8480 </para></listitem>
8481 </itemizedlist>
8482 </para>
8483
8484 <para>
8485 Here are some examples:
8486 <literallayout class='monospaced'>
8487 LICENSE = "LGPLv2.1 | GPLv3"
8488 LICENSE = "MPL-1 &amp; LGPLv2.1"
8489 LICENSE = "GPLv2+"
8490 </literallayout>
8491 The first example is from the recipes for Qt, which the user
8492 may choose to distribute under either the LGPL version
8493 2.1 or GPL version 3.
8494 The second example is from Cairo where two licenses cover
8495 different parts of the source code.
8496 The final example is from <filename>sysstat</filename>,
8497 which presents a single license.
8498 </para>
8499
8500 <para>
8501 You can also specify licenses on a per-package basis to
8502 handle situations where components of the output have
8503 different licenses.
8504 For example, a piece of software whose code is
8505 licensed under GPLv2 but has accompanying documentation
8506 licensed under the GNU Free Documentation License 1.2 could
8507 be specified as follows:
8508 <literallayout class='monospaced'>
8509 LICENSE = "GFDL-1.2 &amp; GPLv2"
8510 LICENSE_${PN} = "GPLv2"
8511 LICENSE_${PN}-doc = "GFDL-1.2"
8512 </literallayout>
8513 </para>
8514 </glossdef>
8515 </glossentry>
8516
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05008517 <glossentry id='var-LICENSE_CREATE_PACKAGE'><glossterm>LICENSE_CREATE_PACKAGE</glossterm>
8518 <info>
8519 LICENSE_CREATE_PACKAGE[doc] = "Creates an extra package (i.e. ${PN}-lic) for each recipe and adds that package to the RRECOMMENDS+${PN}."
8520 </info>
8521 <glossdef>
8522 <para role="glossdeffirst">
8523<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8524 Setting <filename>LICENSE_CREATE_PACKAGE</filename>
8525 to "1" causes the OpenEmbedded build system to create
8526 an extra package (i.e.
8527 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-lic</filename>)
8528 for each recipe and to add those packages to the
8529 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link><filename>_${PN}</filename>.
8530 </para>
8531
8532 <para>
8533 The <filename>${PN}-lic</filename> package installs a
8534 directory in <filename>/usr/share/licenses</filename>
8535 named <filename>${PN}</filename>, which is the recipe's
8536 base name, and installs files in that directory that
8537 contain license and copyright information (i.e. copies of
8538 the appropriate license files from
8539 <filename>meta/common-licenses</filename> that match the
8540 licenses specified in the
8541 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8542 variable of the recipe metadata and copies of files marked
8543 in
8544 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
8545 as containing license text).
8546 </para>
8547
8548 <para>
8549 For related information on providing license text, see the
8550 <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
8551 variable, the
8552 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
8553 variable, and the
8554 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008555 section in the Yocto Project Development Tasks Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05008556 </para>
8557 </glossdef>
8558 </glossentry>
8559
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008560 <glossentry id='var-LICENSE_FLAGS'><glossterm>LICENSE_FLAGS</glossterm>
8561 <info>
8562 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."
8563 </info>
8564 <glossdef>
8565 <para role="glossdeffirst">
8566<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8567 Specifies additional flags for a recipe you must
8568 whitelist through
8569 <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
8570 in order to allow the recipe to be built.
8571 When providing multiple flags, separate them with
8572 spaces.
8573 </para>
8574
8575 <para>
8576 This value is independent of
8577 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8578 and is typically used to mark recipes that might
8579 require additional licenses in order to be used in a
8580 commercial product.
8581 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04008582 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8583 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008584 </para>
8585 </glossdef>
8586 </glossentry>
8587
8588 <glossentry id='var-LICENSE_FLAGS_WHITELIST'><glossterm>LICENSE_FLAGS_WHITELIST</glossterm>
8589 <info>
8590 LICENSE_FLAGS_WHITELIST[doc] = "Lists license flags that when specified in LICENSE_FLAGS within a recipe should not prevent that recipe from being built."
8591 </info>
8592 <glossdef>
8593 <para role="glossdeffirst">
8594<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8595 Lists license flags that when specified in
8596 <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
8597 within a recipe should not prevent that recipe from being
8598 built.
8599 This practice is otherwise known as "whitelisting"
8600 license flags.
8601 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04008602 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8603 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008604 </para>
8605 </glossdef>
8606 </glossentry>
8607
8608 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
8609 <info>
8610 LICENSE_PATH[doc] = "Path to additional licenses used during the build."
8611 </info>
8612 <glossdef>
8613 <para role="glossdeffirst">
8614<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8615 Path to additional licenses used during the build.
8616 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
8617 to define the directory that holds common license text used during the build.
8618 The <filename>LICENSE_PATH</filename> variable allows you to extend that
8619 location to other areas that have additional licenses:
8620 <literallayout class='monospaced'>
8621 LICENSE_PATH += "<replaceable>path-to-additional-common-licenses</replaceable>"
8622 </literallayout>
8623 </para>
8624 </glossdef>
8625 </glossentry>
8626
8627 <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
8628 <info>
8629 LINUX_KERNEL_TYPE[doc] = "Defines the kernel type to be used in assembling the configuration."
8630 </info>
8631 <glossdef>
8632 <para role="glossdeffirst">
8633<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8634 Defines the kernel type to be used in assembling the
8635 configuration.
8636 The linux-yocto recipes define "standard", "tiny", and
8637 "preempt-rt" kernel types.
8638 See the
8639 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
8640 section in the Yocto Project Linux Kernel Development
8641 Manual for more information on kernel types.
8642 </para>
8643
8644 <para>
8645 If you do not specify a
8646 <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
8647 "standard".
8648 Together with
8649 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
8650 the <filename>LINUX_KERNEL_TYPE</filename> variable
8651 defines the search
8652 arguments used by the kernel tools to find the appropriate
8653 description within the kernel
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008654 <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008655 with which to build out the sources and configuration.
8656 </para>
8657 </glossdef>
8658 </glossentry>
8659
8660 <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
8661 <info>
8662 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."
8663 </info>
8664 <glossdef>
8665 <para role="glossdeffirst">
8666<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8667 The Linux version from <filename>kernel.org</filename>
8668 on which the Linux kernel image being built using the
8669 OpenEmbedded build system is based.
8670 You define this variable in the kernel recipe.
8671 For example, the <filename>linux-yocto-3.4.bb</filename>
8672 kernel recipe found in
8673 <filename>meta/recipes-kernel/linux</filename>
8674 defines the variables as follows:
8675 <literallayout class='monospaced'>
8676 LINUX_VERSION ?= "3.4.24"
8677 </literallayout>
8678 </para>
8679
8680 <para>
8681 The <filename>LINUX_VERSION</filename> variable is used to
8682 define <link linkend='var-PV'><filename>PV</filename></link>
8683 for the recipe:
8684 <literallayout class='monospaced'>
8685 PV = "${LINUX_VERSION}+git${SRCPV}"
8686 </literallayout>
8687 </para>
8688 </glossdef>
8689 </glossentry>
8690
8691 <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
8692 <info>
8693 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."
8694 </info>
8695 <glossdef>
8696 <para role="glossdeffirst">
8697<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8698 A string extension compiled into the version
8699 string of the Linux kernel built with the OpenEmbedded
8700 build system.
8701 You define this variable in the kernel recipe.
8702 For example, the linux-yocto kernel recipes all define
8703 the variable as follows:
8704 <literallayout class='monospaced'>
8705 LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
8706 </literallayout>
8707 </para>
8708
8709 <para>
8710 Defining this variable essentially sets the
8711 Linux kernel configuration item
8712 <filename>CONFIG_LOCALVERSION</filename>, which is visible
8713 through the <filename>uname</filename> command.
8714 Here is an example that shows the extension assuming it
8715 was set as previously shown:
8716 <literallayout class='monospaced'>
8717 $ uname -r
8718 3.7.0-rc8-custom
8719 </literallayout>
8720 </para>
8721 </glossdef>
8722 </glossentry>
8723
8724 <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
8725 <info>
8726 LOG_DIR[doc] = "Specifies the directory to which the OpenEmbedded build system writes overall log files. The default directory is ${TMPDIR}/log"
8727 </info>
8728 <glossdef>
8729 <para role="glossdeffirst">
8730<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8731 Specifies the directory to which the OpenEmbedded build
8732 system writes overall log files.
8733 The default directory is <filename>${TMPDIR}/log</filename>.
8734 </para>
8735
8736 <para>
8737 For the directory containing logs specific to each task,
8738 see the <link linkend='var-T'><filename>T</filename></link>
8739 variable.
8740 </para>
8741 </glossdef>
8742 </glossentry>
8743
8744 </glossdiv>
8745
8746 <glossdiv id='var-glossary-m'><title>M</title>
8747
8748 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
8749 <info>
8750 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."
8751 </info>
8752 <glossdef>
8753 <para role="glossdeffirst">
8754<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8755 Specifies the target device for which the image is built.
8756 You define <filename>MACHINE</filename> in the
8757 <filename>local.conf</filename> file found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008758 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008759 By default, <filename>MACHINE</filename> is set to
8760 "qemux86", which is an x86-based architecture machine to
8761 be emulated using QEMU:
8762 <literallayout class='monospaced'>
8763 MACHINE ?= "qemux86"
8764 </literallayout>
8765 </para>
8766
8767 <para>
8768 The variable corresponds to a machine configuration file of the
8769 same name, through which machine-specific configurations are set.
8770 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
8771 exists the corresponding <filename>qemux86.conf</filename> machine
8772 configuration file, which can be found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008773 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008774 in <filename>meta/conf/machine</filename>.
8775 </para>
8776
8777 <para>
8778 The list of machines supported by the Yocto Project as
8779 shipped include the following:
8780 <literallayout class='monospaced'>
8781 MACHINE ?= "qemuarm"
8782 MACHINE ?= "qemuarm64"
8783 MACHINE ?= "qemumips"
8784 MACHINE ?= "qemumips64"
8785 MACHINE ?= "qemuppc"
8786 MACHINE ?= "qemux86"
8787 MACHINE ?= "qemux86-64"
8788 MACHINE ?= "genericx86"
8789 MACHINE ?= "genericx86-64"
8790 MACHINE ?= "beaglebone"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008791 MACHINE ?= "edgerouter"
8792 </literallayout>
8793 The last five are Yocto Project reference hardware boards, which
8794 are provided in the <filename>meta-yocto-bsp</filename> layer.
8795 <note>Adding additional Board Support Package (BSP) layers
8796 to your configuration adds new possible settings for
8797 <filename>MACHINE</filename>.
8798 </note>
8799 </para>
8800 </glossdef>
8801 </glossentry>
8802
8803 <glossentry id='var-MACHINE_ARCH'><glossterm>MACHINE_ARCH</glossterm>
8804 <info>
8805 MACHINE_ARCH[doc] = "Specifies the name of the machine-specific architecture. This variable is set automatically from MACHINE or TUNE_PKGARCH."
8806 </info>
8807 <glossdef>
8808 <para role="glossdeffirst">
8809<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8810 Specifies the name of the machine-specific architecture.
8811 This variable is set automatically from
8812 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
8813 or
8814 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>.
8815 You should not hand-edit the
8816 <filename>MACHINE_ARCH</filename> variable.
8817 </para>
8818 </glossdef>
8819 </glossentry>
8820
8821 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
8822 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04008823 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008824 </info>
8825 <glossdef>
8826 <para role="glossdeffirst">
8827<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8828 A list of required machine-specific packages to install as part of
8829 the image being built.
8830 The build process depends on these packages being present.
Brad Bishop316dfdd2018-06-25 12:45:53 -04008831 Furthermore, because this is a "machine-essential" variable, the list of
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008832 packages are essential for the machine to boot.
8833 The impact of this variable affects images based on
8834 <filename>packagegroup-core-boot</filename>,
8835 including the <filename>core-image-minimal</filename> image.
8836 </para>
8837
8838 <para>
8839 This variable is similar to the
8840 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
8841 variable with the exception that the image being built has a build
8842 dependency on the variable's list of packages.
8843 In other words, the image will not build if a file in this list is not found.
8844 </para>
8845
8846 <para>
8847 As an example, suppose the machine for which you are building requires
8848 <filename>example-init</filename> to be run during boot to initialize the hardware.
8849 In this case, you would use the following in the machine's
8850 <filename>.conf</filename> configuration file:
8851 <literallayout class='monospaced'>
8852 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
8853 </literallayout>
8854 </para>
8855 </glossdef>
8856 </glossentry>
8857
8858 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
8859 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04008860 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008861 </info>
8862 <glossdef>
8863 <para role="glossdeffirst">
8864<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8865 A list of recommended machine-specific packages to install as part of
8866 the image being built.
8867 The build process does not depend on these packages being present.
Brad Bishop316dfdd2018-06-25 12:45:53 -04008868 However, because this is a "machine-essential" variable, the list of
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008869 packages are essential for the machine to boot.
8870 The impact of this variable affects images based on
8871 <filename>packagegroup-core-boot</filename>,
8872 including the <filename>core-image-minimal</filename> image.
8873 </para>
8874
8875 <para>
8876 This variable is similar to the
8877 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
8878 variable with the exception that the image being built does not have a build
8879 dependency on the variable's list of packages.
8880 In other words, the image will still build if a package in this list is not found.
8881 Typically, this variable is used to handle essential kernel modules, whose
8882 functionality may be selected to be built into the kernel rather than as a module,
8883 in which case a package will not be produced.
8884 </para>
8885
8886 <para>
8887 Consider an example where you have a custom kernel where a specific touchscreen
8888 driver is required for the machine to be usable.
8889 However, the driver can be built as a module or
8890 into the kernel depending on the kernel configuration.
8891 If the driver is built as a module, you want it to be installed.
8892 But, when the driver is built into the kernel, you still want the
8893 build to succeed.
8894 This variable sets up a "recommends" relationship so that in the latter case,
8895 the build will not fail due to the missing package.
8896 To accomplish this, assuming the package for the module was called
8897 <filename>kernel-module-ab123</filename>, you would use the
8898 following in the machine's <filename>.conf</filename> configuration
8899 file:
8900 <literallayout class='monospaced'>
8901 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
8902 </literallayout>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05008903 <note>
8904 In this example, the
8905 <filename>kernel-module-ab123</filename> recipe
8906 needs to explicitly set its
8907 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
8908 variable to ensure that BitBake does not use the
8909 kernel recipe's
8910 <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link>
8911 variable to satisfy the dependency.
8912 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008913 </para>
8914
8915 <para>
8916 Some examples of these machine essentials are flash, screen, keyboard, mouse,
8917 or touchscreen drivers (depending on the machine).
8918 </para>
8919 </glossdef>
8920 </glossentry>
8921
8922 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
8923 <info>
8924 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."
8925 </info>
8926 <glossdef>
8927 <para role="glossdeffirst">
8928<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8929 A list of machine-specific packages to install as part of the
8930 image being built that are not essential for the machine to boot.
8931 However, the build process for more fully-featured images
8932 depends on the packages being present.
8933 </para>
8934
8935 <para>
8936 This variable affects all images based on
8937 <filename>packagegroup-base</filename>, which does not include the
8938 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
8939 images.
8940 </para>
8941
8942 <para>
8943 The variable is similar to the
8944 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
8945 variable with the exception that the image being built has a build
8946 dependency on the variable's list of packages.
8947 In other words, the image will not build if a file in this list is not found.
8948 </para>
8949
8950 <para>
8951 An example is a machine that has WiFi capability but is not
8952 essential for the machine to boot the image.
8953 However, if you are building a more fully-featured image, you want to enable
8954 the WiFi.
8955 The package containing the firmware for the WiFi hardware is always
8956 expected to exist, so it is acceptable for the build process to depend upon
8957 finding the package.
8958 In this case, assuming the package for the firmware was called
8959 <filename>wifidriver-firmware</filename>, you would use the following in the
8960 <filename>.conf</filename> file for the machine:
8961 <literallayout class='monospaced'>
8962 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
8963 </literallayout>
8964 </para>
8965 </glossdef>
8966 </glossentry>
8967
8968 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
8969 <info>
8970 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."
8971 </info>
8972 <glossdef>
8973 <para role="glossdeffirst">
8974<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8975 A list of machine-specific packages to install as part of the
8976 image being built that are not essential for booting the machine.
8977 The image being built has no build dependency on this list of packages.
8978 </para>
8979
8980 <para>
8981 This variable affects only images based on
8982 <filename>packagegroup-base</filename>, which does not include the
8983 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
8984 images.
8985 </para>
8986
8987 <para>
8988 This variable is similar to the
8989 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
8990 variable with the exception that the image being built does not have a build
8991 dependency on the variable's list of packages.
8992 In other words, the image will build if a file in this list is not found.
8993 </para>
8994
8995 <para>
8996 An example is a machine that has WiFi capability but is not essential
8997 For the machine to boot the image.
8998 However, if you are building a more fully-featured image, you want to enable
8999 WiFi.
9000 In this case, the package containing the WiFi kernel module will not be produced
9001 if the WiFi driver is built into the kernel, in which case you still want the
9002 build to succeed instead of failing as a result of the package not being found.
9003 To accomplish this, assuming the package for the module was called
9004 <filename>kernel-module-examplewifi</filename>, you would use the
9005 following in the <filename>.conf</filename> file for the machine:
9006 <literallayout class='monospaced'>
9007 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
9008 </literallayout>
9009 </para>
9010 </glossdef>
9011 </glossentry>
9012
9013 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
9014 <info>
9015 MACHINE_FEATURES[doc] = "Specifies the list of hardware features the MACHINE supports."
9016 </info>
9017 <glossdef>
9018 <para role="glossdeffirst">
9019<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9020 Specifies the list of hardware features the
9021 <link linkend='var-MACHINE'><filename>MACHINE</filename></link> is capable
9022 of supporting.
9023 For related information on enabling features, see the
9024 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>,
9025 <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>,
9026 and
9027 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
9028 variables.
9029 </para>
9030
9031 <para>
9032 For a list of hardware features supported by the Yocto
9033 Project as shipped, see the
9034 "<link linkend='ref-features-machine'>Machine Features</link>"
9035 section.
9036 </para>
9037 </glossdef>
9038 </glossentry>
9039
9040 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
9041 <info>
9042 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."
9043 </info>
9044 <glossdef>
9045 <para role="glossdeffirst">
9046<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9047 Features to be added to
9048 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
9049 if not also present in
9050 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
9051 </para>
9052
9053 <para>
9054 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
9055 It is not intended to be user-configurable.
9056 It is best to just reference the variable to see which machine features are
9057 being backfilled for all machine configurations.
Brad Bishop316dfdd2018-06-25 12:45:53 -04009058 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009059 more information.
9060 </para>
9061 </glossdef>
9062 </glossentry>
9063
9064 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
9065 <info>
9066 MACHINE_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from MACHINE_FEATURES_BACKFILL that should not be backfilled (i.e. added to MACHINE_FEATURES) during the build."
9067 </info>
9068 <glossdef>
9069 <para role="glossdeffirst">
9070<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9071 Features from
9072 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
9073 that should not be backfilled (i.e. added to
9074 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
9075 during the build.
Brad Bishop316dfdd2018-06-25 12:45:53 -04009076 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009077 more information.
9078 </para>
9079 </glossdef>
9080 </glossentry>
9081
9082 <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
9083 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009084 MACHINEOVERRIDES[doc] = "A colon-separated list of overrides that apply to the current machine."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009085 </info>
9086 <glossdef>
9087 <para role="glossdeffirst">
9088<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009089 A colon-separated list of overrides that apply to the
9090 current machine.
9091 By default, this list includes the value of
9092 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009093 </para>
9094
9095 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009096 You can extend <filename>MACHINEOVERRIDES</filename>
9097 to add extra overrides that should apply to a machine.
9098 For example, all machines emulated in QEMU (e.g.
9099 <filename>qemuarm</filename>, <filename>qemux86</filename>,
9100 and so forth) include a file named
9101 <filename>meta/conf/machine/include/qemu.inc</filename>
9102 that prepends the following override to
9103 <filename>MACHINEOVERRIDES</filename>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009104 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009105 MACHINEOVERRIDES =. "qemuall:"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009106 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009107 This override allows variables to be overriden for all
9108 machines emulated in QEMU, like in the following example
9109 from the <filename>connman-conf</filename> recipe:
9110 <literallayout class='monospaced'>
9111 SRC_URI_append_qemuall = "file://wired.config \
9112 file://wired-setup \
9113 "
9114 </literallayout>
9115 The underlying mechanism behind
9116 <filename>MACHINEOVERRIDES</filename> is simply that it is
9117 included in the default value of
9118 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009119 </para>
9120 </glossdef>
9121 </glossentry>
9122
9123 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
9124 <info>
9125 MAINTAINER[doc] = "The email address of the distribution maintainer."
9126 </info>
9127 <glossdef>
9128 <para role="glossdeffirst">
9129<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9130 The email address of the distribution maintainer.
9131 </para>
9132 </glossdef>
9133 </glossentry>
9134
9135 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
9136 <info>
9137 MIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."
9138 </info>
9139 <glossdef>
9140 <para role="glossdeffirst">
9141<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9142 Specifies additional paths from which the OpenEmbedded
9143 build system gets source code.
9144 When the build system searches for source code, it first
9145 tries the local download directory.
9146 If that location fails, the build system tries locations
9147 defined by
9148 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
9149 the upstream source, and then locations specified by
9150 <filename>MIRRORS</filename> in that order.
9151 </para>
9152
9153 <para>
9154 Assuming your distribution
9155 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
9156 is "poky", the default value for
9157 <filename>MIRRORS</filename> is defined in the
9158 <filename>conf/distro/poky.conf</filename> file in the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05009159 <filename>meta-poky</filename> Git repository.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009160 </para>
9161 </glossdef>
9162 </glossentry>
9163
9164 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
9165 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04009166 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)."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009167 </info>
9168 <glossdef>
9169 <para role="glossdeffirst">
9170<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9171 Specifies a prefix has been added to
9172 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
Brad Bishop316dfdd2018-06-25 12:45:53 -04009173 of a recipe or package (i.e. a Multilib version).
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009174 The variable is used in places where the prefix needs to be
9175 added to or removed from a the name (e.g. the
9176 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
9177 <filename>MLPREFIX</filename> gets set when a prefix has been
9178 added to <filename>PN</filename>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009179 <note>
9180 The "ML" in <filename>MLPREFIX</filename> stands for
9181 "MultiLib".
9182 This representation is historical and comes from
9183 a time when <filename>nativesdk</filename> was a suffix
9184 rather than a prefix on the recipe name.
9185 When <filename>nativesdk</filename> was turned into a
9186 prefix, it made sense to set
9187 <filename>MLPREFIX</filename> for it as well.
9188 </note>
9189 </para>
9190
9191 <para>
9192 To help understand when <filename>MLPREFIX</filename>
9193 might be needed, consider when
9194 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
9195 is used to provide a <filename>nativesdk</filename> version
9196 of a recipe in addition to the target version.
9197 If that recipe declares build-time dependencies on tasks in
9198 other recipes by using
9199 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>,
9200 then a dependency on "foo" will automatically get rewritten
9201 to a dependency on "nativesdk-foo".
9202 However, dependencies like the following will not get
9203 rewritten automatically:
9204 <literallayout class='monospaced'>
9205 do_foo[depends] += "<replaceable>recipe</replaceable>:do_foo"
9206 </literallayout>
9207 If you want such a dependency to also get transformed,
9208 you can do the following:
9209 <literallayout class='monospaced'>
9210 do_foo[depends] += "${MLPREFIX}<replaceable>recipe</replaceable>:do_foo"
9211 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009212 </para>
9213 </glossdef>
9214 </glossentry>
9215
9216 <glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm>
9217 <info>
9218 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."
9219 </info>
9220 <glossdef>
9221 <para role="glossdeffirst">
9222<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9223 This variable has been replaced by the
9224 <filename>KERNEL_MODULE_AUTOLOAD</filename> variable.
9225 You should replace all occurrences of
9226 <filename>module_autoload</filename> with additions to
9227 <filename>KERNEL_MODULE_AUTOLOAD</filename>, for example:
9228 <literallayout class='monospaced'>
9229 module_autoload_rfcomm = "rfcomm"
9230 </literallayout>
9231 </para>
9232
9233 <para>
9234 should now be replaced with:
9235 <literallayout class='monospaced'>
9236 KERNEL_MODULE_AUTOLOAD += "rfcomm"
9237 </literallayout>
9238 See the
9239 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
9240 variable for more information.
9241 </para>
9242 </glossdef>
9243 </glossentry>
9244
9245 <glossentry id='var-module_conf'><glossterm>module_conf</glossterm>
9246 <info>
9247 module_conf[doc] = "Specifies modprobe.d syntax lines for inclusion in the /etc/modprobe.d/modname.conf file."
9248 </info>
9249 <glossdef>
9250 <para role="glossdeffirst">
9251<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9252 Specifies
9253 <ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink>
9254 syntax lines for inclusion in the
9255 <filename>/etc/modprobe.d/modname.conf</filename> file.
9256 </para>
9257
9258 <para>
9259 You can use this variable anywhere that it can be
9260 recognized by the kernel recipe or out-of-tree kernel
9261 module recipe (e.g. a machine configuration file, a
9262 distribution configuration file, an append file for the
9263 recipe, or the recipe itself).
9264 If you use this variable, you must also be sure to list
9265 the module name in the
9266 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
9267 variable.
9268 </para>
9269
9270 <para>
9271 Here is the general syntax:
9272 <literallayout class='monospaced'>
9273 module_conf_<replaceable>module_name</replaceable> = "<replaceable>modprobe.d-syntax</replaceable>"
9274 </literallayout>
9275 You must use the kernel module name override.
9276 </para>
9277
9278 <para>
9279 Run <filename>man modprobe.d</filename> in the shell to
9280 find out more information on the exact syntax
9281 you want to provide with <filename>module_conf</filename>.
9282 </para>
9283
9284 <para>
9285 Including <filename>module_conf</filename> causes the
9286 OpenEmbedded build system to populate the
9287 <filename>/etc/modprobe.d/modname.conf</filename>
9288 file with <filename>modprobe.d</filename> syntax lines.
9289 Here is an example that adds the options
9290 <filename>arg1</filename> and <filename>arg2</filename>
9291 to a module named <filename>mymodule</filename>:
9292 <literallayout class='monospaced'>
9293 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
9294 </literallayout>
9295 </para>
9296
9297 <para>
9298 For information on how to specify kernel modules to
9299 auto-load on boot, see the
9300 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
9301 variable.
9302 </para>
9303 </glossdef>
9304 </glossentry>
9305
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009306 <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
9307 <info>
9308 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."
9309 </info>
9310 <glossdef>
9311 <para role="glossdeffirst">
9312<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9313 Controls creation of the <filename>modules-*.tgz</filename>
9314 file.
9315 Set this variable to "0" to disable creation of this
9316 file, which contains all of the kernel modules resulting
9317 from a kernel build.
9318 </para>
9319 </glossdef>
9320 </glossentry>
9321
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08009322 <glossentry id='var-MODULE_TARBALL_LINK_NAME'><glossterm>MODULE_TARBALL_LINK_NAME</glossterm>
9323 <info>
9324 MODULE_TARBALL_LINK_NAME[doc] = "The link name of the kernel module tarball."
9325 </info>
9326 <glossdef>
9327 <para role="glossdeffirst">
9328<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9329 The link name of the kernel module tarball.
9330 This variable is set in the
9331 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
9332 file as follows:
9333 <literallayout class='monospaced'>
9334 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
9335 </literallayout>
9336 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
9337 variable, which is set in the same file, has the following
9338 value:
9339 <literallayout class='monospaced'>
9340 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
9341 </literallayout>
9342 </para>
9343
9344 <para>
9345 See the
9346 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
9347 variable for additional information.
9348 </para>
9349 </glossdef>
9350 </glossentry>
9351
9352 <glossentry id='var-MODULE_TARBALL_NAME'><glossterm>MODULE_TARBALL_NAME</glossterm>
9353 <info>
9354 MODULE_TARBALL_NAME[doc] = "The base name of the kernel module tarball."
9355 </info>
9356 <glossdef>
9357 <para role="glossdeffirst">
9358<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9359 The base name of the kernel module tarball.
9360 This variable is set in the
9361 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
9362 file as follows:
9363 <literallayout class='monospaced'>
9364 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"
9365 </literallayout>
9366 The value of the
9367 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
9368 variable, which is set in the same file, has the following
9369 value:
9370 <literallayout class='monospaced'>
9371 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
9372 </literallayout>
9373 </para>
9374 </glossdef>
9375 </glossentry>
9376
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009377<!--
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009378 <glossentry id='var-MULTIMACH_HOST_SYS'><glossterm>MULTIMACH_HOST_SYS</glossterm>
9379 <info>
9380 MULTIMACH_HOST_SYS[doc] = "Separates files for different machines such that you can build for multiple host machines using the same output directories."
9381 </info>
9382 <glossdef>
9383 <para role="glossdeffirst">
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009384-->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009385<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009386<!--
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009387 Serves the same purpose as
9388 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
9389 but for the "HOST" system, in situations that involve a
9390 "HOST" and a "TARGET" system.
9391 See the
9392 <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link>
9393 variable for more information.
9394 </para>
9395
9396 <para>
9397 The default value of this variable is:
9398 <literallayout class='monospaced'>
9399 ${PACKAGE_ARCH}${HOST_VENDOR}-${HOST_OS}
9400 </literallayout>
9401 </para>
9402 </glossdef>
9403 </glossentry>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009404-->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009405
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009406 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
9407 <info>
9408 MULTIMACH_TARGET_SYS[doc] = "Separates files for different machines such that you can build for multiple target machines using the same output directories."
9409 </info>
9410 <glossdef>
9411 <para role="glossdeffirst">
9412<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009413 Uniquely identifies the type of the target system for
9414 which packages are being built.
9415 This variable allows output for different types of target
9416 systems to be put into different subdirectories of the same
9417 output directory.
9418 </para>
9419
9420 <para>
9421 The default value of this variable is:
9422 <literallayout class='monospaced'>
9423 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}
9424 </literallayout>
9425 Some classes (e.g.
9426 <link linkend='ref-classes-cross-canadian'><filename>cross-canadian</filename></link>)
9427 modify the <filename>MULTIMACH_TARGET_SYS</filename> value.
9428 </para>
9429
9430 <para>
9431 See the
9432 <link linkend='var-STAMP'><filename>STAMP</filename></link>
9433 variable for an example.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009434 See the
9435 <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link>
9436 variable for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009437 </para>
9438 </glossdef>
9439 </glossentry>
9440
9441 </glossdiv>
9442
9443 <glossdiv id='var-glossary-n'><title>N</title>
9444
9445 <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
9446 <info>
9447 NATIVELSBSTRING[doc] = "A string identifying the host distribution."
9448 </info>
9449 <glossdef>
9450 <para role="glossdeffirst">
9451<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9452 A string identifying the host distribution.
9453 Strings consist of the host distributor ID
9454 followed by the release, as reported by the
9455 <filename>lsb_release</filename> tool
9456 or as read from <filename>/etc/lsb-release</filename>.
9457 For example, when running a build on Ubuntu 12.10, the value
9458 is "Ubuntu-12.10".
9459 If this information is unable to be determined, the value
9460 resolves to "Unknown".
9461 </para>
9462
9463 <para>
9464 This variable is used by default to isolate native shared
9465 state packages for different distributions (e.g. to avoid
9466 problems with <filename>glibc</filename> version
9467 incompatibilities).
9468 Additionally, the variable is checked against
9469 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
9470 if that variable is set.
9471 </para>
9472 </glossdef>
9473 </glossentry>
9474
9475 <glossentry id='var-NM'><glossterm>NM</glossterm>
9476 <info>
9477 NM[doc] = "Minimal command and arguments to run 'nm'."
9478 </info>
9479 <glossdef>
9480 <para role="glossdeffirst">
9481<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9482 The minimal command and arguments to run
9483 <filename>nm</filename>.
9484 </para>
9485 </glossdef>
9486 </glossentry>
9487
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08009488 <glossentry id='var-NO_GENERIC_LICENSE'><glossterm>NO_GENERIC_LICENSE</glossterm>
9489 <info>
9490 NO_GENERIC_LICENSE[doc] = "Used to allow copying a license that does not exist in common licenses."
9491 </info>
9492 <glossdef>
9493 <para role="glossdeffirst">
9494<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9495 Avoids QA errors when you use a non-common, non-CLOSED
9496 license in a recipe.
9497 Packages exist, such as the linux-firmware package, with
9498 many licenses that are not in any way common.
9499 Also, new licenses are added occasionally to avoid
9500 introducing a lot of common license files, which are only
9501 applicable to a specific package.
9502 <filename>NO_GENERIC_LICENSE</filename> is used to allow
9503 copying a license that does not exist in common licenses.
9504 </para>
9505
9506 <para>
9507 The following example shows how to add
9508 <filename>NO_GENERIC_LICENSE</filename> to a recipe:
9509 <literallayout class='monospaced'>
9510 NO_GENERIC_LICENSE[<replaceable>license_name</replaceable>] = "<replaceable>license_file_in_fetched_source</replaceable>"
9511 </literallayout>
9512 The following is an example that uses the
9513 <filename>LICENSE.Abilis.txt</filename> file as the license
9514 from the fetched source:
9515 <literallayout class='monospaced'>
9516 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
9517 </literallayout>
9518 </para>
9519 </glossdef>
9520 </glossentry>
9521
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009522 <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
9523 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04009524 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009525 </info>
9526 <glossdef>
9527 <para role="glossdeffirst">
9528<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9529 Prevents installation of all "recommended-only" packages.
9530 Recommended-only packages are packages installed only
9531 through the
9532 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
9533 variable).
9534 Setting the <filename>NO_RECOMMENDATIONS</filename> variable
9535 to "1" turns this feature on:
9536 <literallayout class='monospaced'>
9537 NO_RECOMMENDATIONS = "1"
9538 </literallayout>
9539 </para>
9540
9541 <para>
9542 You can set this variable globally in your
9543 <filename>local.conf</filename> file or you can attach it to
9544 a specific image recipe by using the recipe name override:
9545 <literallayout class='monospaced'>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009546 NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "1"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009547 </literallayout>
9548 </para>
9549
9550 <para>
9551 It is important to realize that if you choose to not install
9552 packages using this variable and some other packages are
9553 dependent on them (i.e. listed in a recipe's
9554 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
9555 variable), the OpenEmbedded build system ignores your
9556 request and will install the packages to avoid dependency
9557 errors.
9558 <note>
9559 Some recommended packages might be required for certain
9560 system functionality, such as kernel modules.
9561 It is up to you to add packages with the
9562 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
9563 variable.
9564 </note>
9565 </para>
9566
9567 <para>
9568 Support for this variable exists only when using the
9569 IPK and RPM packaging backend.
9570 Support does not exist for DEB.
9571 </para>
9572
9573 <para>
9574 See the
9575 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
9576 and the
9577 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
9578 variables for related information.
9579 </para>
9580 </glossdef>
9581 </glossentry>
9582
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009583 <glossentry id='var-NOAUTOPACKAGEDEBUG'><glossterm>NOAUTOPACKAGEDEBUG</glossterm>
9584 <info>
9585 NOAUTOPACKAGEDEBUG[doc] = "Disables auto package from splitting .debug files."
9586 </info>
9587 <glossdef>
9588 <para role="glossdeffirst">
9589<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9590 Disables auto package from splitting
9591 <filename>.debug</filename> files. If a recipe requires
9592 <filename>FILES_${PN}-dbg</filename> to be set manually,
9593 the <filename>NOAUTOPACKAGEDEBUG</filename> can be defined
9594 allowing you to define the content of the debug package.
9595 For example:
9596 <literallayout class='monospaced'>
9597 NOAUTOPACKAGEDEBUG = "1"
9598 FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
9599 FILES_${PN}-dbg = "/usr/src/debug/"
9600 FILES_${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"
9601 </literallayout>
9602 </para>
9603 </glossdef>
9604 </glossentry>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009605 </glossdiv>
9606
9607 <glossdiv id='var-glossary-o'><title>O</title>
9608
9609 <glossentry id='var-OBJCOPY'><glossterm>OBJCOPY</glossterm>
9610 <info>
9611 OBJCOPY[doc] = "Minimal command and arguments to run 'objcopy'."
9612 </info>
9613 <glossdef>
9614 <para role="glossdeffirst">
9615<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9616 The minimal command and arguments to run
9617 <filename>objcopy</filename>.
9618 </para>
9619 </glossdef>
9620 </glossentry>
9621
9622 <glossentry id='var-OBJDUMP'><glossterm>OBJDUMP</glossterm>
9623 <info>
9624 OBJDUMP[doc] = "Minimal command and arguments to run 'objdump'."
9625 </info>
9626 <glossdef>
9627 <para role="glossdeffirst">
9628<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9629 The minimal command and arguments to run
9630 <filename>objdump</filename>.
9631 </para>
9632 </glossdef>
9633 </glossentry>
9634
9635 <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
9636 <info>
9637 OE_BINCONFIG_EXTRA_MANGLE[doc] = "When a recipe inherits the binconfig.bbclass class, this variable specifies additional arguments passed to the "sed" command."
9638 </info>
9639 <glossdef>
9640 <para role="glossdeffirst">
9641<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9642 When inheriting the
9643 <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
9644 class, this variable
9645 specifies additional arguments passed to the "sed" command.
9646 The sed command alters any paths in configuration scripts
9647 that have been set up during compilation.
9648 Inheriting this class results in all paths in these scripts
9649 being changed to point into the
9650 <filename>sysroots/</filename> directory so that all builds
9651 that use the script will use the correct directories
9652 for the cross compiling layout.
9653 </para>
9654
9655 <para>
9656 See the <filename>meta/classes/binconfig.bbclass</filename>
9657 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009658 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009659 for details on how this class applies these additional
9660 sed command arguments.
9661 For general information on the
Brad Bishop316dfdd2018-06-25 12:45:53 -04009662 <filename>binconfig</filename> class, see the
9663 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009664 section.
9665 </para>
9666 </glossdef>
9667 </glossentry>
9668
9669 <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
9670 <info>
9671 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."
9672 </info>
9673 <glossdef>
9674 <para role="glossdeffirst">
9675<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9676 An internal variable used to tell the OpenEmbedded build
9677 system what Python modules to import for every Python
9678 function run by the system.
9679 </para>
9680
9681 <note>
9682 Do not set this variable.
9683 It is for internal use only.
9684 </note>
9685 </glossdef>
9686 </glossentry>
9687
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05009688 <glossentry id='var-OE_INIT_ENV_SCRIPT'><glossterm>OE_INIT_ENV_SCRIPT</glossterm>
9689 <info>
9690 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."
9691 </info>
9692 <glossdef>
9693 <para role="glossdeffirst">
9694<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9695 The name of the build environment setup script for the
9696 purposes of setting up the environment within the
9697 extensible SDK.
9698 The default value is "oe-init-build-env".
9699 </para>
9700
9701 <para>
9702 If you use a custom script to set up your build
9703 environment, set the
9704 <filename>OE_INIT_ENV_SCRIPT</filename> variable to its
9705 name.
9706 </para>
9707 </glossdef>
9708 </glossentry>
9709
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009710 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
9711 <info>
9712 OE_TERMINAL[doc] = "Controls how the OpenEmbedded build system spawns interactive terminals on the host development system."
9713 </info>
9714 <glossdef>
9715 <para role="glossdeffirst">
9716<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9717 Controls how the OpenEmbedded build system spawns
9718 interactive terminals on the host development system
9719 (e.g. using the BitBake command with the
9720 <filename>-c devshell</filename> command-line option).
9721 For more information, see the
9722 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009723 in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009724 </para>
9725
9726 <para>
9727 You can use the following values for the
9728 <filename>OE_TERMINAL</filename> variable:
9729 <literallayout class='monospaced'>
9730 auto
9731 gnome
9732 xfce
9733 rxvt
9734 screen
9735 konsole
9736 none
9737 </literallayout>
9738 </para>
9739 </glossdef>
9740 </glossentry>
9741
9742 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
9743 <info>
9744 OEROOT[doc] = "The directory from which the top-level build environment setup script is sourced."
9745 </info>
9746 <glossdef>
9747 <para role="glossdeffirst">
9748<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9749 The directory from which the top-level build environment
9750 setup script is sourced.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009751 The Yocto Project provides a top-level build environment
9752 setup script:
9753 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
9754 When you run this script, the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009755 <filename>OEROOT</filename> variable resolves to the
9756 directory that contains the script.
9757 </para>
9758
9759 <para>
9760 For additional information on how this variable is used,
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009761 see the initialization script.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009762 </para>
9763 </glossdef>
9764 </glossentry>
9765
9766 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
9767 <info>
9768 OLDEST_KERNEL[doc] = "Declares the oldest version of the Linux kernel that the produced binaries must support."
9769 </info>
9770 <glossdef>
9771 <para role="glossdeffirst">
9772<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9773 Declares the oldest version of the Linux kernel that the
9774 produced binaries must support.
9775 This variable is passed into the build of the Embedded
9776 GNU C Library (<filename>glibc</filename>).
9777 </para>
9778
9779 <para>
9780 The default for this variable comes from the
9781 <filename>meta/conf/bitbake.conf</filename> configuration
9782 file.
9783 You can override this default by setting the variable
9784 in a custom distribution configuration file.
9785 </para>
9786 </glossdef>
9787 </glossentry>
9788
9789 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
9790 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009791 OVERRIDES[doc] = "A colon-separated list of overrides that currently apply."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009792 </info>
9793 <glossdef>
9794 <para role="glossdeffirst">
9795<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009796 A colon-separated list of overrides that currently apply.
9797 Overrides are a BitBake mechanism that allows variables to
9798 be selectively overridden at the end of parsing.
9799 The set of overrides in <filename>OVERRIDES</filename>
9800 represents the "state" during building, which includes
9801 the current recipe being built, the machine for which
9802 it is being built, and so forth.
9803 </para>
9804
9805 <para>
9806 As an example, if the string "an-override" appears as an
9807 element in the colon-separated list in
9808 <filename>OVERRIDES</filename>, then the following
9809 assignment will override <filename>FOO</filename> with the
9810 value "overridden" at the end of parsing:
9811 <literallayout class='monospaced'>
9812 FOO_an-override = "overridden"
9813 </literallayout>
9814 See the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009815 "<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009816 section in the BitBake User Manual for more information on
9817 the overrides mechanism.
9818 </para>
9819
9820 <para>
9821 The default value of <filename>OVERRIDES</filename>
9822 includes the values of the
9823 <link linkend='var-CLASSOVERRIDE'><filename>CLASSOVERRIDE</filename></link>,
9824 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>,
9825 and
9826 <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
9827 variables.
9828 Another important override included by default is
9829 <filename>pn-${PN}</filename>.
9830 This override allows variables to be set for a single
9831 recipe within configuration (<filename>.conf</filename>)
9832 files.
9833 Here is an example:
9834 <literallayout class='monospaced'>
9835 FOO_pn-myrecipe = "myrecipe-specific value"
9836 </literallayout>
9837 <note><title>Tip</title>
9838 An easy way to see what overrides apply is to search for
9839 <filename>OVERRIDES</filename> in the output of the
9840 <filename>bitbake -e</filename> command.
9841 See the
Brad Bishop316dfdd2018-06-25 12:45:53 -04009842 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-debugging-viewing-variable-values'>Viewing Variable Values</ulink>"
9843 section in the Yocto Project Development Tasks
9844 Manual for more information.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009845 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009846 </para>
9847 </glossdef>
9848 </glossentry>
9849 </glossdiv>
9850
9851 <glossdiv id='var-glossary-p'><title>P</title>
9852
9853 <glossentry id='var-P'><glossterm>P</glossterm>
9854 <info>
9855 P[doc] = "The recipe name and version. P is comprised of ${PN}-${PV}."
9856 </info>
9857 <glossdef>
9858 <para role="glossdeffirst">
9859<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9860 The recipe name and version.
9861 <filename>P</filename> is comprised of the following:
9862 <literallayout class='monospaced'>
9863 ${PN}-${PV}
9864 </literallayout>
9865 </para>
9866 </glossdef>
9867 </glossentry>
9868
9869 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
9870 <info>
9871 PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages."
9872 </info>
9873 <glossdef>
9874 <para role="glossdeffirst">
9875<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9876 The architecture of the resulting package or packages.
9877 </para>
9878
9879 <para>
9880 By default, the value of this variable is set to
9881 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
9882 when building for the target,
Brad Bishop316dfdd2018-06-25 12:45:53 -04009883 <link linkend='var-BUILD_ARCH'><filename>BUILD_ARCH</filename></link>
9884 when building for the
9885 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009886 for the SDK.
Brad Bishop316dfdd2018-06-25 12:45:53 -04009887 <note>
9888 See
9889 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>
9890 for more information.
9891 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009892 However, if your recipe's output packages are built
Brad Bishop316dfdd2018-06-25 12:45:53 -04009893 specific to the target machine rather than generally for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009894 the architecture of the machine, you should set
9895 <filename>PACKAGE_ARCH</filename> to the value of
9896 <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>
9897 in the recipe as follows:
9898 <literallayout class='monospaced'>
9899 PACKAGE_ARCH = "${MACHINE_ARCH}"
9900 </literallayout>
9901 </para>
9902 </glossdef>
9903 </glossentry>
9904
9905 <glossentry id='var-PACKAGE_ARCHS'><glossterm>PACKAGE_ARCHS</glossterm>
9906 <info>
9907 PACKAGE_ARCHS[doc] = "A list of architectures compatible with the given target in order of priority."
9908 </info>
9909 <glossdef>
9910 <para role="glossdeffirst">
9911<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9912 Specifies a list of architectures compatible with
9913 the target machine.
9914 This variable is set automatically and should not
9915 normally be hand-edited.
9916 Entries are separated using spaces and listed in order
9917 of priority.
9918 The default value for
9919 <filename>PACKAGE_ARCHS</filename> is "all any noarch
9920 ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
9921 </para>
9922 </glossdef>
9923 </glossentry>
9924
9925 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
9926 <info>
9927 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."
9928 </info>
9929 <glossdef>
9930 <para role="glossdeffirst">
9931<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9932 Enables easily adding packages to
9933 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
9934 before <filename>${<link linkend='var-PN'>PN</link>}</filename>
9935 so that those added packages can pick up files that would normally be
9936 included in the default package.
9937 </para>
9938 </glossdef>
9939 </glossentry>
9940
9941 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
9942 <info>
9943 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."
9944 </info>
9945 <glossdef>
9946 <para role="glossdeffirst">
9947<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9948 This variable, which is set in the
9949 <filename>local.conf</filename> configuration file found in
9950 the <filename>conf</filename> folder of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009951 <link linkend='build-directory'>Build Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009952 specifies the package manager the OpenEmbedded build system
9953 uses when packaging data.
9954 </para>
9955
9956 <para>
9957 You can provide one or more of the following arguments for
9958 the variable:
9959 <literallayout class='monospaced'>
9960 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"
9961 </literallayout>
9962 <note><title>Warning</title>
9963 While it is a legal option, the
Brad Bishop316dfdd2018-06-25 12:45:53 -04009964 <filename>package_tar</filename> class has limited
9965 functionality due to no support for package
9966 dependencies by that backend.
9967 Therefore, it is recommended that you do not use it.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009968 </note>
9969 The build system uses only the first argument in the list
9970 as the package manager when creating your image or SDK.
9971 However, packages will be created using any additional
9972 packaging classes you specify.
9973 For example, if you use the following in your
9974 <filename>local.conf</filename> file:
9975 <literallayout class='monospaced'>
9976 PACKAGE_CLASSES ?= "package_ipk"
9977 </literallayout>
9978 The OpenEmbedded build system uses the IPK package manager
9979 to create your image or SDK.
9980 </para>
9981
9982 <para>
9983 For information on packaging and build performance effects
9984 as a result of the package manager in use, see the
9985 "<link linkend='ref-classes-package'><filename>package.bbclass</filename></link>"
9986 section.
9987 </para>
9988 </glossdef>
9989 </glossentry>
9990
9991 <glossentry id='var-PACKAGE_DEBUG_SPLIT_STYLE'><glossterm>PACKAGE_DEBUG_SPLIT_STYLE</glossterm>
9992 <info>
9993 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)."
9994 </info>
9995 <glossdef>
9996 <para role="glossdeffirst">
9997<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9998 Determines how to split up the binary and debug information
9999 when creating <filename>*-dbg</filename> packages to be
10000 used with the GNU Project Debugger (GDB).
10001 </para>
10002
10003 <para>
10004 With the
10005 <filename>PACKAGE_DEBUG_SPLIT_STYLE</filename> variable,
10006 you can control where debug information, which can include
10007 or exclude source files, is stored:
10008 <itemizedlist>
10009 <listitem><para>
10010 ".debug": Debug symbol files are placed next
10011 to the binary in a <filename>.debug</filename>
10012 directory on the target.
10013 For example, if a binary is installed into
10014 <filename>/bin</filename>, the corresponding debug
10015 symbol files are installed in
10016 <filename>/bin/.debug</filename>.
10017 Source files are placed in
10018 <filename>/usr/src/debug</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010019 </para></listitem>
10020 <listitem><para>
10021 "debug-file-directory": Debug symbol files are
10022 placed under <filename>/usr/lib/debug</filename>
10023 on the target, and separated by the path from where
10024 the binary is installed.
10025 For example, if a binary is installed in
10026 <filename>/bin</filename>, the corresponding debug
10027 symbols are installed in
10028 <filename>/usr/lib/debug/bin</filename>.
10029 Source files are placed in
10030 <filename>/usr/src/debug</filename>.
10031 </para></listitem>
10032 <listitem><para>
10033 "debug-without-src": The same behavior as
10034 ".debug" previously described with the exception
10035 that no source files are installed.
10036 </para></listitem>.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010037 <listitem><para>
10038 "debug-with-srcpkg": The same behavior as
10039 ".debug" previously described with the exception
10040 that all source files are placed in a separate
10041 <filename>*-src</filename> pkg.
Brad Bishop19323692019-04-05 15:28:33 -040010042 This is the default behavior.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010043 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010044 </itemizedlist>
10045 </para>
10046
10047 <para>
10048 You can find out more about debugging using GDB by reading
10049 the
10050 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010051 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010052 </para>
10053 </glossdef>
10054 </glossentry>
10055
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010056 <glossentry id='var-PACKAGE_EXCLUDE_COMPLEMENTARY'><glossterm>PACKAGE_EXCLUDE_COMPLEMENTARY</glossterm>
10057 <info>
10058 PACKAGE_EXCLUDE_COMPLEMENTARY[doc] = "Prevents specific packages from being installed when you are installing complementary packages."
10059 </info>
10060 <glossdef>
10061 <para role="glossdeffirst">
10062<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10063 Prevents specific packages from being installed when
10064 you are installing complementary packages.
10065 </para>
10066
10067 <para>
10068 You might find that you want to prevent installing certain
10069 packages when you are installing complementary packages.
10070 For example, if you are using
10071 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
10072 to install <filename>dev-pkgs</filename>, you might not want
10073 to install all packages from a particular multilib.
10074 If you find yourself in this situation, you can use the
10075 <filename>PACKAGE_EXCLUDE_COMPLEMENTARY</filename> variable
10076 to specify regular expressions to match the packages you
10077 want to exclude.
10078 </para>
10079 </glossdef>
10080 </glossentry>
10081
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010082 <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
10083 <info>
10084 PACKAGE_EXCLUDE[doc] = "Packages to exclude from the installation. If a listed package is required, an error is generated."
10085 </info>
10086 <glossdef>
10087 <para role="glossdeffirst">
10088<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10089 Lists packages that should not be installed into an image.
10090 For example:
10091 <literallayout class='monospaced'>
10092 PACKAGE_EXCLUDE = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."
10093 </literallayout>
10094 </para>
10095
10096 <para>
10097 You can set this variable globally in your
10098 <filename>local.conf</filename> file or you can attach it to
10099 a specific image recipe by using the recipe name override:
10100 <literallayout class='monospaced'>
10101 PACKAGE_EXCLUDE_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"
10102 </literallayout>
10103 </para>
10104
10105 <para>
10106 If you choose to not install
10107 a package using this variable and some other package is
10108 dependent on it (i.e. listed in a recipe's
10109 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
10110 variable), the OpenEmbedded build system generates a fatal
10111 installation error.
10112 Because the build system halts the process with a fatal
10113 error, you can use the variable with an iterative
10114 development process to remove specific components from a
10115 system.
10116 </para>
10117
10118 <para>
10119 Support for this variable exists only when using the
10120 IPK and RPM packaging backend.
10121 Support does not exist for DEB.
10122 </para>
10123
10124 <para>
10125 See the
10126 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
10127 and the
10128 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
10129 variables for related information.
10130 </para>
10131 </glossdef>
10132 </glossentry>
10133
10134 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
10135 <info>
10136 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."
10137 </info>
10138 <glossdef>
10139 <para role="glossdeffirst">
10140<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10141 Specifies the list of architectures compatible with the device CPU.
10142 This variable is useful when you build for several different devices that use
10143 miscellaneous processors such as XScale and ARM926-EJS.
10144 </para>
10145 </glossdef>
10146 </glossentry>
10147
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010148 <glossentry id='var-PACKAGE_FEED_ARCHS'><glossterm>PACKAGE_FEED_ARCHS</glossterm>
10149 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040010150 PACKAGE_FEED_ARCHS[doc] = "Optionally specifies user-defined package architectures when constructing package feed URIs."
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010151 </info>
10152 <glossdef>
10153 <para role="glossdeffirst">
10154<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040010155 Optionally specifies the package architectures used as
10156 part of the package feed URIs during the build.
10157 When used, the <filename>PACKAGE_FEED_ARCHS</filename>
10158 variable is appended to the final package feed URI, which
10159 is constructed using the
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010160 <link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
10161 and
10162 <link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>
10163 variables.
Brad Bishop316dfdd2018-06-25 12:45:53 -040010164 <note><title>Tip</title>
10165 You can use the <filename>PACKAGE_FEEDS_ARCHS</filename>
10166 variable to whitelist specific package architectures.
10167 If you do not need to whitelist specific architectures,
10168 which is a common case, you can omit this variable.
10169 Omitting the variable results in all available
10170 architectures for the current machine being included
10171 into remote package feeds.
10172 </note>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010173 </para>
10174
10175 <para>
10176 Consider the following example where the
10177 <filename>PACKAGE_FEED_URIS</filename>,
10178 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
10179 <filename>PACKAGE_FEED_ARCHS</filename> variables are
10180 defined in your <filename>local.conf</filename> file:
10181 <literallayout class='monospaced'>
10182 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
10183 https://example.com/packagerepos/updates"
10184 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
10185 PACKAGE_FEED_ARCHS = "all core2-64"
10186 </literallayout>
10187 Given these settings, the resulting package feeds are
10188 as follows:
10189 <literallayout class='monospaced'>
10190 https://example.com/packagerepos/release/rpm/all
10191 https://example.com/packagerepos/release/rpm/core2-64
10192 https://example.com/packagerepos/release/rpm-dev/all
10193 https://example.com/packagerepos/release/rpm-dev/core2-64
10194 https://example.com/packagerepos/updates/rpm/all
10195 https://example.com/packagerepos/updates/rpm/core2-64
10196 https://example.com/packagerepos/updates/rpm-dev/all
10197 https://example.com/packagerepos/updates/rpm-dev/core2-64
10198 </literallayout>
10199 </para>
10200 </glossdef>
10201 </glossentry>
10202
10203 <glossentry id='var-PACKAGE_FEED_BASE_PATHS'><glossterm>PACKAGE_FEED_BASE_PATHS</glossterm>
10204 <info>
10205 PACKAGE_FEED_BASE_PATHS[doc] = "Specifies base path used when constructing package feed URIs."
10206 </info>
10207 <glossdef>
10208 <para role="glossdeffirst">
10209<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10210 Specifies the base path used when constructing package feed
10211 URIs.
10212 The <filename>PACKAGE_FEED_BASE_PATHS</filename> variable
10213 makes up the middle portion of a package feed URI used
10214 by the OpenEmbedded build system.
10215 The base path lies between the
10216 <link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
10217 and
10218 <link linkend='var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></link>
10219 variables.
10220 </para>
10221
10222 <para>
10223 Consider the following example where the
10224 <filename>PACKAGE_FEED_URIS</filename>,
10225 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
10226 <filename>PACKAGE_FEED_ARCHS</filename> variables are
10227 defined in your <filename>local.conf</filename> file:
10228 <literallayout class='monospaced'>
10229 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
10230 https://example.com/packagerepos/updates"
10231 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
10232 PACKAGE_FEED_ARCHS = "all core2-64"
10233 </literallayout>
10234 Given these settings, the resulting package feeds are
10235 as follows:
10236 <literallayout class='monospaced'>
10237 https://example.com/packagerepos/release/rpm/all
10238 https://example.com/packagerepos/release/rpm/core2-64
10239 https://example.com/packagerepos/release/rpm-dev/all
10240 https://example.com/packagerepos/release/rpm-dev/core2-64
10241 https://example.com/packagerepos/updates/rpm/all
10242 https://example.com/packagerepos/updates/rpm/core2-64
10243 https://example.com/packagerepos/updates/rpm-dev/all
10244 https://example.com/packagerepos/updates/rpm-dev/core2-64
10245 </literallayout>
10246 </para>
10247 </glossdef>
10248 </glossentry>
10249
10250 <glossentry id='var-PACKAGE_FEED_URIS'><glossterm>PACKAGE_FEED_URIS</glossterm>
10251 <info>
10252 PACKAGE_FEED_URIS[doc] = "Specifies the front portion of the package feed URI used by the OpenEmbedded build system."
10253 </info>
10254 <glossdef>
10255 <para role="glossdeffirst">
10256<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10257 Specifies the front portion of the package feed URI
10258 used by the OpenEmbedded build system.
10259 Each final package feed URI is comprised of
10260 <filename>PACKAGE_FEED_URIS</filename>,
10261 <link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>,
10262 and
10263 <link linkend='var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></link>
10264 variables.
10265 </para>
10266
10267 <para>
10268 Consider the following example where the
10269 <filename>PACKAGE_FEED_URIS</filename>,
10270 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
10271 <filename>PACKAGE_FEED_ARCHS</filename> variables are
10272 defined in your <filename>local.conf</filename> file:
10273 <literallayout class='monospaced'>
10274 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
10275 https://example.com/packagerepos/updates"
10276 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
10277 PACKAGE_FEED_ARCHS = "all core2-64"
10278 </literallayout>
10279 Given these settings, the resulting package feeds are
10280 as follows:
10281 <literallayout class='monospaced'>
10282 https://example.com/packagerepos/release/rpm/all
10283 https://example.com/packagerepos/release/rpm/core2-64
10284 https://example.com/packagerepos/release/rpm-dev/all
10285 https://example.com/packagerepos/release/rpm-dev/core2-64
10286 https://example.com/packagerepos/updates/rpm/all
10287 https://example.com/packagerepos/updates/rpm/core2-64
10288 https://example.com/packagerepos/updates/rpm-dev/all
10289 https://example.com/packagerepos/updates/rpm-dev/core2-64
10290 </literallayout>
10291 </para>
10292 </glossdef>
10293 </glossentry>
10294
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010295 <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
10296 <info>
10297 PACKAGE_GROUP[doc] = "Defines one or more packages to include in an image when a specific item is included in IMAGE_FEATURES."
10298 </info>
10299 <glossdef>
10300 <para role="glossdeffirst">
10301<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10302 The <filename>PACKAGE_GROUP</filename> variable has been
10303 renamed to
10304 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>.
10305 See the variable description for
10306 <filename>FEATURE_PACKAGES</filename> for information.
10307 </para>
10308
10309 <para>
10310 If if you use the <filename>PACKAGE_GROUP</filename>
10311 variable, the OpenEmbedded build system issues a warning
10312 message.
10313 </para>
10314 </glossdef>
10315 </glossentry>
10316
10317 <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
10318 <info>
10319 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."
10320 </info>
10321 <glossdef>
10322 <para role="glossdeffirst">
10323<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10324 The final list of packages passed to the package manager
10325 for installation into the image.
10326 </para>
10327
10328 <para>
10329 Because the package manager controls actual installation
10330 of all packages, the list of packages passed using
10331 <filename>PACKAGE_INSTALL</filename> is not the final list
10332 of packages that are actually installed.
10333 This variable is internal to the image construction
10334 code.
10335 Consequently, in general, you should use the
10336 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
10337 variable to specify packages for installation.
10338 The exception to this is when working with
10339 the
10340 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
10341 image.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050010342 When working with an initial RAM filesystem (initramfs)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010343 image, use the <filename>PACKAGE_INSTALL</filename>
10344 variable.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050010345 For information on creating an initramfs, see the
10346 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010347 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010348 </para>
10349 </glossdef>
10350 </glossentry>
10351
10352 <glossentry id='var-PACKAGE_INSTALL_ATTEMPTONLY'><glossterm>PACKAGE_INSTALL_ATTEMPTONLY</glossterm>
10353 <info>
10354 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."
10355 </info>
10356 <glossdef>
10357 <para role="glossdeffirst">
10358<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10359 Specifies a list of packages the OpenEmbedded build
10360 system attempts to install when creating an image.
10361 If a listed package fails to install, the build system
10362 does not generate an error.
10363 This variable is generally not user-defined.
10364 </para>
10365 </glossdef>
10366 </glossentry>
10367
10368 <glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm>PACKAGE_PREPROCESS_FUNCS</glossterm>
10369 <info>
10370 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."
10371 </info>
10372 <glossdef>
10373 <para role="glossdeffirst">
10374<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10375 Specifies a list of functions run to pre-process the
10376 <link linkend='var-PKGD'><filename>PKGD</filename></link>
10377 directory prior to splitting the files out to individual
10378 packages.
10379 </para>
10380 </glossdef>
10381 </glossentry>
10382
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010383 <glossentry id='var-PACKAGE_WRITE_DEPS'><glossterm>PACKAGE_WRITE_DEPS</glossterm>
10384 <info>
10385 PACKAGE_WRITE_DEPS[doc] = "Specifies post-installation and pre-installation script dependencies on native/cross tools."
10386 </info>
10387 <glossdef>
10388 <para role="glossdeffirst">
10389<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10390 Specifies a list of dependencies for post-installation and
10391 pre-installation scripts on native/cross tools.
10392 If your post-installation or pre-installation script can
10393 execute at rootfs creation time rather than on the
10394 target but depends on a native tool in order to execute,
10395 you need to list the tools in
Brad Bishopd5ae7d92018-06-14 09:52:03 -070010396 <filename>PACKAGE_WRITE_DEPS</filename>.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010397 </para>
10398
10399 <para>
10400 For information on running post-installation scripts, see
10401 the
10402 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010403 section in the Yocto Project Development Tasks Manual.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010404 </para>
10405 </glossdef>
10406 </glossentry>
10407
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010408 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
10409 <info>
10410 PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis."
10411 </info>
10412 <glossdef>
10413 <para role="glossdeffirst">
10414<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10415 This variable provides a means of enabling or disabling
10416 features of a recipe on a per-recipe basis.
10417 <filename>PACKAGECONFIG</filename> blocks are defined
10418 in recipes when you specify features and then arguments
10419 that define feature behaviors.
Andrew Geissler82c905d2020-04-13 13:39:40 -050010420 Here is the basic block structure (broken over multiple
10421 lines for readability):
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010422 <literallayout class='monospaced'>
10423 PACKAGECONFIG ??= "f1 f2 f3 ..."
Andrew Geissler82c905d2020-04-13 13:39:40 -050010424 PACKAGECONFIG[f1] = "\
10425 --with-f1, \
10426 --without-f1, \
10427 build-deps-for-f1, \
10428 runtime-deps-for-f1, \
10429 runtime-recommends-for-f1, \
10430 packageconfig-conflicts-for-f1 \
10431 "
10432 PACKAGECONFIG[f2] = "\
10433 ... and so on and so on ...
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010434 </literallayout>
10435 </para>
10436
10437 <para>
10438 The <filename>PACKAGECONFIG</filename>
10439 variable itself specifies a space-separated list of the
10440 features to enable.
10441 Following the features, you can determine the behavior of
Andrew Geissler82c905d2020-04-13 13:39:40 -050010442 each feature by providing up to six order-dependent
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010443 arguments, which are separated by commas.
10444 You can omit any argument you like but must retain the
10445 separating commas.
10446 The order is important and specifies the following:
10447 <orderedlist>
10448 <listitem><para>Extra arguments
10449 that should be added to the configure script
10450 argument list
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010451 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
10452 or
10453 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010454 if the feature is enabled.</para></listitem>
10455 <listitem><para>Extra arguments
10456 that should be added to <filename>EXTRA_OECONF</filename>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010457 or <filename>PACKAGECONFIG_CONFARGS</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010458 if the feature is disabled.
10459 </para></listitem>
10460 <listitem><para>Additional build dependencies
10461 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
10462 that should be added if the feature is enabled.
10463 </para></listitem>
10464 <listitem><para>Additional runtime dependencies
10465 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
10466 that should be added if the feature is enabled.
10467 </para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010468 <listitem><para>Additional runtime recommendations
10469 (<link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)
10470 that should be added if the feature is enabled.
10471 </para></listitem>
Andrew Geissler82c905d2020-04-13 13:39:40 -050010472 <listitem><para>Any conflicting (that is, mutually
10473 exclusive) <filename>PACKAGECONFIG</filename>
10474 settings for this feature.
10475 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010476 </orderedlist>
10477 </para>
10478
10479 <para>
10480 Consider the following
10481 <filename>PACKAGECONFIG</filename> block taken from the
10482 <filename>librsvg</filename> recipe.
Andrew Geissler82c905d2020-04-13 13:39:40 -050010483 In this example the feature is <filename>gtk</filename>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010484 which has three arguments that determine the feature's
10485 behavior.
10486 <literallayout class='monospaced'>
Andrew Geissler82c905d2020-04-13 13:39:40 -050010487 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010488 </literallayout>
Andrew Geissler82c905d2020-04-13 13:39:40 -050010489 The <filename>--with-gtk3</filename> and
10490 <filename>gtk+3</filename> arguments apply only if
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010491 the feature is enabled.
Andrew Geissler82c905d2020-04-13 13:39:40 -050010492 In this case, <filename>--with-gtk3</filename> is
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010493 added to the configure script argument list and
Andrew Geissler82c905d2020-04-13 13:39:40 -050010494 <filename>gtk+3</filename> is added to
Brad Bishop316dfdd2018-06-25 12:45:53 -040010495 <filename>DEPENDS</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010496 On the other hand, if the feature is disabled say through
10497 a <filename>.bbappend</filename> file in another layer, then
Andrew Geissler82c905d2020-04-13 13:39:40 -050010498 the second argument <filename>--without-gtk3</filename> is
10499 added to the configure script instead.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010500 </para>
10501
10502 <para>
10503 The basic <filename>PACKAGECONFIG</filename> structure
10504 previously described holds true regardless of whether you
10505 are creating a block or changing a block.
10506 When creating a block, use the structure inside your
10507 recipe.
10508 </para>
10509
10510 <para>
10511 If you want to change an existing
10512 <filename>PACKAGECONFIG</filename> block, you can do so
10513 one of two ways:
10514 <itemizedlist>
10515 <listitem><para><emphasis>Append file:</emphasis>
10516 Create an append file named
10517 <replaceable>recipename</replaceable><filename>.bbappend</filename>
10518 in your layer and override the value of
10519 <filename>PACKAGECONFIG</filename>.
10520 You can either completely override the variable:
10521 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010522 PACKAGECONFIG = "f4 f5"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010523 </literallayout>
10524 Or, you can just append the variable:
10525 <literallayout class='monospaced'>
10526 PACKAGECONFIG_append = " f4"
10527 </literallayout></para></listitem>
10528 <listitem><para><emphasis>Configuration file:</emphasis>
10529 This method is identical to changing the block
10530 through an append file except you edit your
10531 <filename>local.conf</filename> or
10532 <filename><replaceable>mydistro</replaceable>.conf</filename> file.
10533 As with append files previously described,
10534 you can either completely override the variable:
10535 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010536 PACKAGECONFIG_pn-<replaceable>recipename</replaceable> = "f4 f5"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010537 </literallayout>
10538 Or, you can just amend the variable:
10539 <literallayout class='monospaced'>
10540 PACKAGECONFIG_append_pn-<replaceable>recipename</replaceable> = " f4"
10541 </literallayout></para></listitem>
10542 </itemizedlist>
10543 </para>
10544 </glossdef>
10545 </glossentry>
10546
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010547 <glossentry id='var-PACKAGECONFIG_CONFARGS'><glossterm>PACKAGECONFIG_CONFARGS</glossterm>
10548 <info>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010549 PACKAGECONFIG_CONFARGS[doc] = "A space-separated list of configuration options generated from the PACKAGECONFIG setting."
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010550 </info>
10551 <glossdef>
10552 <para role="glossdeffirst">
10553<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10554 A space-separated list of configuration options generated
10555 from the
10556 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
10557 setting.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010558 </para>
10559
10560 <para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010561 Classes such as
10562 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
10563 and
10564 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
10565 use <filename>PACKAGECONFIG_CONFARGS</filename> to pass
Brad Bishop316dfdd2018-06-25 12:45:53 -040010566 <filename>PACKAGECONFIG</filename> options to
10567 <filename>configure</filename> and
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010568 <filename>cmake</filename>, respectively.
10569 If you are using
10570 <filename>PACKAGECONFIG</filename> but not a class that
10571 handles the <filename>do_configure</filename> task, then
10572 you need to use
10573 <filename>PACKAGECONFIG_CONFARGS</filename> appropriately.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010574 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010575 </glossdef>
10576 </glossentry>
10577
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010578 <glossentry id='var-PACKAGEGROUP_DISABLE_COMPLEMENTARY'><glossterm>PACKAGEGROUP_DISABLE_COMPLEMENTARY</glossterm>
10579 <info>
10580 PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents automatic creation of the normal complementary packages such as -dev and -dbg in a packagegroup recipe."
10581 </info>
10582 <glossdef>
10583 <para role="glossdeffirst">
10584<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10585 For recipes inheriting the
10586 <link linkend='ref-classes-packagegroup'><filename>packagegroup</filename></link>
10587 class, setting
10588 <filename>PACKAGEGROUP_DISABLE_COMPLEMENTARY</filename> to
10589 "1" specifies that the normal complementary packages
10590 (i.e. <filename>-dev</filename>,
10591 <filename>-dbg</filename>, and so forth) should not be
10592 automatically created by the
10593 <filename>packagegroup</filename> recipe, which is the
10594 default behavior.
10595 </para>
10596 </glossdef>
10597 </glossentry>
10598
10599 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
10600 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040010601 PACKAGES[doc] = "The list of packages the recipe creates."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010602 </info>
10603 <glossdef>
10604 <para role="glossdeffirst">
10605<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040010606 The list of packages the recipe creates.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010607 The default value is the following:
10608 <literallayout class='monospaced'>
10609 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
10610 </literallayout>
10611 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010612
10613 <para>
10614 During packaging, the
10615 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
10616 task goes through <filename>PACKAGES</filename> and uses
10617 the
10618 <link linkend='var-FILES'><filename>FILES</filename></link>
10619 variable corresponding to each package to assign files to
10620 the package.
10621 If a file matches the <filename>FILES</filename> variable
10622 for more than one package in <filename>PACKAGES</filename>,
10623 it will be assigned to the earliest (leftmost) package.
10624 </para>
10625
10626 <para>
10627 Packages in the variable's list that are empty (i.e. where
10628 none of the patterns in
10629 <filename>FILES_</filename><replaceable>pkg</replaceable>
10630 match any files installed by the
10631 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
10632 task) are not generated, unless generation is forced through
10633 the
10634 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>
10635 variable.
10636 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010637 </glossdef>
10638 </glossentry>
10639
10640 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
10641 <info>
10642 PACKAGES_DYNAMIC[doc] = "A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes."
10643 </info>
10644 <glossdef>
10645 <para role="glossdeffirst">
10646<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10647 A promise that your recipe satisfies runtime dependencies
10648 for optional modules that are found in other recipes.
10649 <filename>PACKAGES_DYNAMIC</filename>
10650 does not actually satisfy the dependencies, it only states that
10651 they should be satisfied.
10652 For example, if a hard, runtime dependency
10653 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
10654 of another package is satisfied
10655 at build time through the <filename>PACKAGES_DYNAMIC</filename>
10656 variable, but a package with the module name is never actually
10657 produced, then the other package will be broken.
10658 Thus, if you attempt to include that package in an image,
10659 you will get a dependency failure from the packaging system
10660 during the
10661 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
10662 task.
10663 </para>
10664
10665 <para>
10666 Typically, if there is a chance that such a situation can
10667 occur and the package that is not created is valid
10668 without the dependency being satisfied, then you should use
10669 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
10670 (a soft runtime dependency) instead of
10671 <filename>RDEPENDS</filename>.
10672 </para>
10673
10674 <para>
10675 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
10676 variable when you are splitting packages, see the
10677 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010678 in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010679 </para>
10680 </glossdef>
10681 </glossentry>
10682
10683 <glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm>
10684 <info>
10685 PACKAGESPLITFUNCS[doc] = "Specifies a list of functions run to perform additional splitting of files into individual packages."
10686 </info>
10687 <glossdef>
10688 <para role="glossdeffirst">
10689<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10690 Specifies a list of functions run to perform additional
10691 splitting of files into individual packages.
10692 Recipes can either prepend to this variable or prepend
10693 to the <filename>populate_packages</filename> function
10694 in order to perform additional package splitting.
10695 In either case, the function should set
10696 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>,
10697 <link linkend='var-FILES'><filename>FILES</filename></link>,
10698 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
10699 and other packaging variables appropriately in order to
10700 perform the desired splitting.
10701 </para>
10702 </glossdef>
10703 </glossentry>
10704
10705 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
10706 <info>
10707 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."
10708 </info>
10709 <glossdef>
10710 <para role="glossdeffirst">
10711<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10712 Extra options passed to the <filename>make</filename>
10713 command during the
10714 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
10715 task in order to specify parallel compilation on the local
10716 build host.
10717 This variable is usually in the form "-j <replaceable>x</replaceable>",
10718 where <replaceable>x</replaceable> represents the maximum
10719 number of parallel threads <filename>make</filename> can
10720 run.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010721 <note><title>Caution</title>
10722 In order for <filename>PARALLEL_MAKE</filename> to be
10723 effective, <filename>make</filename> must be called
10724 with
10725 <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.
10726 An easy way to ensure this is to use the
10727 <filename>oe_runmake</filename> function.
10728 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010729 </para>
10730
10731 <para>
10732 By default, the OpenEmbedded build system automatically
10733 sets this variable to be equal to the number of cores the
10734 build system uses.
10735 <note>
10736 If the software being built experiences dependency
10737 issues during the <filename>do_compile</filename>
10738 task that result in race conditions, you can clear
10739 the <filename>PARALLEL_MAKE</filename> variable within
10740 the recipe as a workaround.
10741 For information on addressing race conditions, see the
10742 "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010743 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010744 </note>
10745 For single socket systems (i.e. one CPU), you should not
10746 have to override this variable to gain optimal parallelism
10747 during builds.
10748 However, if you have very large systems that employ
10749 multiple physical CPUs, you might want to make sure the
10750 <filename>PARALLEL_MAKE</filename> variable is not
10751 set higher than "-j 20".
10752 </para>
10753
10754 <para>
10755 For more information on speeding up builds, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040010756 "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"
10757 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010758 </para>
10759 </glossdef>
10760 </glossentry>
10761
10762 <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
10763 <info>
10764 PARALLEL_MAKEINST[doc] = "Extra options passed to the make install command during the do_install task in order to specify parallel installation."
10765 </info>
10766 <glossdef>
10767 <para role="glossdeffirst">
10768<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10769 Extra options passed to the
10770 <filename>make install</filename> command during the
10771 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
10772 task in order to specify parallel installation.
10773 This variable defaults to the value of
10774 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010775 <note><title>Notes and Cautions</title>
10776 <para>In order for <filename>PARALLEL_MAKEINST</filename>
10777 to be
10778 effective, <filename>make</filename> must be called
10779 with
10780 <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.
10781 An easy way to ensure this is to use the
10782 <filename>oe_runmake</filename> function.</para>
10783
10784 <para>If the software being built experiences
10785 dependency issues during the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010786 <filename>do_install</filename> task that result in
10787 race conditions, you can clear the
10788 <filename>PARALLEL_MAKEINST</filename> variable within
10789 the recipe as a workaround.
10790 For information on addressing race conditions, see the
10791 "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010792 section in the Yocto Project Development Tasks Manual.
10793 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010794 </note>
10795 </para>
10796 </glossdef>
10797 </glossentry>
10798
10799 <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
10800 <info>
10801 PATCHRESOLVE[doc] = "Enable or disable interactive patch resolution."
10802 </info>
10803 <glossdef>
10804 <para role="glossdeffirst">
10805<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10806 Determines the action to take when a patch fails.
10807 You can set this variable to one of two values: "noop" and
10808 "user".
10809 </para>
10810
10811 <para>
10812 The default value of "noop" causes the build to simply fail
10813 when the OpenEmbedded build system cannot successfully
10814 apply a patch.
10815 Setting the value to "user" causes the build system to
10816 launch a shell and places you in the right location so that
10817 you can manually resolve the conflicts.
10818 </para>
10819
10820 <para>
10821 Set this variable in your
10822 <filename>local.conf</filename> file.
10823 </para>
10824 </glossdef>
10825 </glossentry>
10826
10827 <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
10828 <info>
10829 PATCHTOOL[doc] = "Specifies the utility used to apply patches for a recipe during do_patch."
10830 </info>
10831 <glossdef>
10832 <para role="glossdeffirst">
10833<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10834 Specifies the utility used to apply patches for a recipe
10835 during the
10836 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
10837 task.
10838 You can specify one of three utilities: "patch", "quilt", or
10839 "git".
10840 The default utility used is "quilt" except for the
10841 quilt-native recipe itself.
10842 Because the quilt tool is not available at the
10843 time quilt-native is being patched, it uses "patch".
10844 </para>
10845
10846 <para>
10847 If you wish to use an alternative patching tool, set the
10848 variable in the recipe using one of the following:
10849 <literallayout class='monospaced'>
10850 PATCHTOOL = "patch"
10851 PATCHTOOL = "quilt"
10852 PATCHTOOL = "git"
10853 </literallayout>
10854 </para>
10855 </glossdef>
10856 </glossentry>
10857
10858 <glossentry id='var-PE'><glossterm>PE</glossterm>
10859 <info>
10860 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."
10861 </info>
10862 <glossdef>
10863 <para role="glossdeffirst">
10864<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10865 The epoch of the recipe.
10866 By default, this variable is unset.
10867 The variable is used to make upgrades possible when the
10868 versioning scheme changes in some backwards incompatible
10869 way.
10870 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010871
10872 <para>
10873 <filename>PE</filename> is the default value of the
10874 <link linkend='var-PKGE'><filename>PKGE</filename></link>
10875 variable.
10876 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010877 </glossdef>
10878 </glossentry>
10879
10880 <glossentry id='var-PF'><glossterm>PF</glossterm>
10881 <info>
10882 PF[doc] = "Specifies the recipe or package name and includes all version and revision numbers. This variable is comprised of ${PN}-${EXTENDPE}${PV}-${PR}."
10883 </info>
10884 <glossdef>
10885 <para role="glossdeffirst">
10886<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10887 Specifies the recipe or package name and includes all version and revision
10888 numbers (i.e. <filename>glibc-2.13-r20+svnr15508/</filename> and
10889 <filename>bash-4.2-r1/</filename>).
10890 This variable is comprised of the following:
10891 <literallayout class='monospaced'>
10892 ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
10893 </literallayout>
10894 </para>
10895 </glossdef>
10896 </glossentry>
10897
10898 <glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm>
10899 <info>
10900 PIXBUF_PACKAGES[doc] = "When a recipe inherits the pixbufcache class, this variable identifies packages that contain the pixbuf loaders used with gdk-pixbuf."
10901 </info>
10902 <glossdef>
10903 <para role="glossdeffirst">
10904<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10905 When inheriting the
10906 <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link>
10907 class, this variable identifies packages that contain
10908 the pixbuf loaders used with
10909 <filename>gdk-pixbuf</filename>.
10910 By default, the <filename>pixbufcache</filename> class
10911 assumes that the loaders are in the recipe's main package
10912 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
10913 Use this variable if the loaders you need are in a package
10914 other than that main package.
10915 </para>
10916 </glossdef>
10917 </glossentry>
10918
10919 <glossentry id='var-PKG'><glossterm>PKG</glossterm>
10920 <info>
10921 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."
10922 </info>
10923 <glossdef>
10924 <para role="glossdeffirst">
10925<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10926 The name of the resulting package created by the
10927 OpenEmbedded build system.
10928 <note>
10929 When using the <filename>PKG</filename> variable, you
10930 must use a package name override.
10931 </note>
10932 </para>
10933
10934 <para>
10935 For example, when the
10936 <link linkend='ref-classes-debian'><filename>debian</filename></link>
10937 class renames the output package, it does so by setting
10938 <filename>PKG_<replaceable>packagename</replaceable></filename>.
10939 </para>
10940 </glossdef>
10941 </glossentry>
10942
10943 <glossentry id='var-PKG_CONFIG_PATH'><glossterm>PKG_CONFIG_PATH</glossterm>
10944 <info>
10945 PKG_CONFIG_PATH[doc] = "Path to pkg-config files for the current build context."
10946 </info>
10947 <glossdef>
10948 <para role="glossdeffirst">
10949<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10950 The path to <filename>pkg-config</filename> files for the
10951 current build context.
10952 <filename>pkg-config</filename> reads this variable
10953 from the environment.
10954 </para>
10955 </glossdef>
10956 </glossentry>
10957
10958 <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
10959 <info>
10960 PKGD[doc] = "Points to the destination directory for files to be packaged before they are split into individual packages."
10961 </info>
10962 <glossdef>
10963 <para role="glossdeffirst">
10964<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10965 Points to the destination directory for files to be
10966 packaged before they are split into individual packages.
10967 This directory defaults to the following:
10968 <literallayout class='monospaced'>
10969 ${WORKDIR}/package
10970 </literallayout>
10971 </para>
10972
10973 <para>
10974 Do not change this default.
10975 </para>
10976 </glossdef>
10977 </glossentry>
10978
10979 <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
10980 <info>
10981 PKGDATA_DIR[doc] = "Points to a shared, global-state directory that holds data generated during the packaging process."
10982 </info>
10983 <glossdef>
10984 <para role="glossdeffirst">
10985<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10986 Points to a shared, global-state directory that holds data
10987 generated during the packaging process.
10988 During the packaging process, the
10989 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
10990 task packages data for each recipe and installs it into
10991 this temporary, shared area.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010992 This directory defaults to the following, which you should
10993 not change:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010994 <literallayout class='monospaced'>
10995 ${STAGING_DIR_HOST}/pkgdata
10996 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010997 For examples of how this data is used, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040010998 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
10999 section in the Yocto Project Overview and Concepts Manual
11000 and the
11001 "<ulink url='&YOCTO_DOCS_DEV_URL;#viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></ulink>"
11002 section in the Yocto Project Development Tasks Manual.
11003 For more information on the shared, global-state directory,
11004 see
11005 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011006 </para>
11007 </glossdef>
11008 </glossentry>
11009
11010 <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
11011 <info>
11012 PKGDEST[doc] = "Points to the parent directory for files to be packaged after they have been split into individual packages."
11013 </info>
11014 <glossdef>
11015 <para role="glossdeffirst">
11016<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11017 Points to the parent directory for files to be packaged
11018 after they have been split into individual packages.
11019 This directory defaults to the following:
11020 <literallayout class='monospaced'>
11021 ${WORKDIR}/packages-split
11022 </literallayout>
11023 </para>
11024
11025 <para>
11026 Under this directory, the build system creates
11027 directories for each package specified in
11028 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
11029 Do not change this default.
11030 </para>
11031 </glossdef>
11032 </glossentry>
11033
11034 <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
11035 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011036 PKGDESTWORK[doc] = "Points to a temporary work area where the do_package task saves package metadata."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011037 </info>
11038 <glossdef>
11039 <para role="glossdeffirst">
11040<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011041 Points to a temporary work area where the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011042 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011043 task saves package metadata.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011044 The <filename>PKGDESTWORK</filename> location defaults to
11045 the following:
11046 <literallayout class='monospaced'>
11047 ${WORKDIR}/pkgdata
11048 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011049 Do not change this default.
11050 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011051
11052 <para>
11053 The
11054 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
11055 task copies the package metadata from
11056 <filename>PKGDESTWORK</filename> to
11057 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
11058 to make it available globally.
11059 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011060 </glossdef>
11061 </glossentry>
11062
11063 <glossentry id='var-PKGE'><glossterm>PKGE</glossterm>
11064 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011065 PKGE[doc] = "The epoch of the package(s) built by the recipe."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011066 </info>
11067 <glossdef>
11068 <para role="glossdeffirst">
11069<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011070 The epoch of the package(s) built by the recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011071 By default, <filename>PKGE</filename> is set to
11072 <link linkend='var-PE'><filename>PE</filename></link>.
11073 </para>
11074 </glossdef>
11075 </glossentry>
11076
11077 <glossentry id='var-PKGR'><glossterm>PKGR</glossterm>
11078 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011079 PKGR[doc] = "The revision of the package(s) built by the recipe."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011080 </info>
11081 <glossdef>
11082 <para role="glossdeffirst">
11083<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011084 The revision of the package(s) built by the recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011085 By default, <filename>PKGR</filename> is set to
11086 <link linkend='var-PR'><filename>PR</filename></link>.
11087 </para>
11088 </glossdef>
11089 </glossentry>
11090
11091 <glossentry id='var-PKGV'><glossterm>PKGV</glossterm>
11092 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011093 PKGV[doc] = "The version of the package(s) built by the recipe."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011094 </info>
11095 <glossdef>
11096 <para role="glossdeffirst">
11097<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011098 The version of the package(s) built by the
11099 recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011100 By default, <filename>PKGV</filename> is set to
11101 <link linkend='var-PV'><filename>PV</filename></link>.
11102 </para>
11103 </glossdef>
11104 </glossentry>
11105
11106 <glossentry id='var-PN'><glossterm>PN</glossterm>
11107 <info>
Andrew Geissler82c905d2020-04-13 13:39:40 -050011108 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011109 </info>
11110 <glossdef>
11111 <para role="glossdeffirst">
11112<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11113 This variable can have two separate functions depending on the context: a recipe
11114 name or a resulting package name.
11115 </para>
11116
11117 <para>
11118 <filename>PN</filename> refers to a recipe name in the context of a file used
11119 by the OpenEmbedded build system as input to create a package.
11120 The name is normally extracted from the recipe file name.
11121 For example, if the recipe is named
11122 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
11123 will be "expat".
11124 </para>
11125
11126 <para>
11127 The variable refers to a package name in the context of a file created or produced by the
11128 OpenEmbedded build system.
11129 </para>
11130
11131 <para>
11132 If applicable, the <filename>PN</filename> variable also contains any special
11133 suffix or prefix.
11134 For example, using <filename>bash</filename> to build packages for the native
11135 machine, <filename>PN</filename> is <filename>bash-native</filename>.
11136 Using <filename>bash</filename> to build packages for the target and for Multilib,
11137 <filename>PN</filename> would be <filename>bash</filename> and
11138 <filename>lib64-bash</filename>, respectively.
11139 </para>
11140 </glossdef>
11141 </glossentry>
11142
11143 <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>
11144 <info>
11145 PNBLACKLIST[doc] = "Lists recipes you do not want the OpenEmbedded build system to build."
11146 </info>
11147 <glossdef>
11148 <para role="glossdeffirst">
11149<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11150 Lists recipes you do not want the OpenEmbedded build system
11151 to build.
11152 This variable works in conjunction with the
11153 <link linkend='ref-classes-blacklist'><filename>blacklist</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011154 class, which is inherited globally.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011155 </para>
11156
11157 <para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011158 To prevent a recipe from being built, use the
11159 <filename>PNBLACKLIST</filename> variable in your
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011160 <filename>local.conf</filename> file.
11161 Here is an example that prevents
11162 <filename>myrecipe</filename> from being built:
11163 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011164 PNBLACKLIST[myrecipe] = "Not supported by our organization."
11165 </literallayout>
11166 </para>
11167 </glossdef>
11168 </glossentry>
11169
11170 <glossentry id='var-POPULATE_SDK_POST_HOST_COMMAND'><glossterm>POPULATE_SDK_POST_HOST_COMMAND</glossterm>
11171 <info>
11172 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."
11173 </info>
11174 <glossdef>
11175 <para role="glossdeffirst">
11176<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11177 Specifies a list of functions to call once the
11178 OpenEmbedded build system has created the host part of
11179 the SDK.
11180 You can specify functions separated by semicolons:
11181 <literallayout class='monospaced'>
11182 POPULATE_SDK_POST_HOST_COMMAND += "<replaceable>function</replaceable>; ... "
11183 </literallayout>
11184 </para>
11185
11186 <para>
11187 If you need to pass the SDK path to a command
11188 within a function, you can use
11189 <filename>${SDK_DIR}</filename>, which points to
11190 the parent directory used by the OpenEmbedded build
11191 system when creating SDK output.
11192 See the
11193 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
11194 variable for more information.
11195 </para>
11196 </glossdef>
11197 </glossentry>
11198
11199 <glossentry id='var-POPULATE_SDK_POST_TARGET_COMMAND'><glossterm>POPULATE_SDK_POST_TARGET_COMMAND</glossterm>
11200 <info>
11201 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."
11202 </info>
11203 <glossdef>
11204 <para role="glossdeffirst">
11205<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11206 Specifies a list of functions to call once the
11207 OpenEmbedded build system has created the target part of
11208 the SDK.
11209 You can specify functions separated by semicolons:
11210 <literallayout class='monospaced'>
11211 POPULATE_SDK_POST_TARGET_COMMAND += "<replaceable>function</replaceable>; ... "
11212 </literallayout>
11213 </para>
11214
11215 <para>
11216 If you need to pass the SDK path to a command
11217 within a function, you can use
11218 <filename>${SDK_DIR}</filename>, which points to
11219 the parent directory used by the OpenEmbedded build
11220 system when creating SDK output.
11221 See the
11222 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
11223 variable for more information.
11224 </para>
11225 </glossdef>
11226 </glossentry>
11227
11228 <glossentry id='var-PR'><glossterm>PR</glossterm>
11229 <info>
11230 PR[doc] = "The revision of the recipe. The default value for this variable is 'r0'."
11231 </info>
11232 <glossdef>
11233 <para role="glossdeffirst">
11234<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011235 The revision of the recipe. The default value for this
11236 variable is "r0".
11237 Subsequent revisions of the recipe conventionally have the
11238 values "r1", "r2", and so forth.
11239 When
11240 <link linkend='var-PV'><filename>PV</filename></link>
11241 increases, <filename>PR</filename> is conventionally reset
11242 to "r0".
11243 <note>
11244 The OpenEmbedded build system does not need the aid of
11245 <filename>PR</filename> to know when to rebuild a
11246 recipe.
11247 The build system uses the task
Brad Bishop316dfdd2018-06-25 12:45:53 -040011248 <ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>input checksums</ulink>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011249 along with the
11250 <link linkend='structure-build-tmp-stamps'>stamp</link>
11251 and
Brad Bishop316dfdd2018-06-25 12:45:53 -040011252 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state cache</ulink>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011253 mechanisms.
11254 </note>
11255 The <filename>PR</filename> variable primarily becomes
11256 significant when a package manager dynamically installs
11257 packages on an already built image.
11258 In this case, <filename>PR</filename>, which is the default
11259 value of
11260 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
11261 helps the package manager distinguish which package is the
11262 most recent one in cases where many packages have the same
11263 <filename>PV</filename> (i.e. <filename>PKGV</filename>).
11264 A component having many packages with the same
11265 <filename>PV</filename> usually means that the packages all
11266 install the same upstream version, but with later
11267 (<filename>PR</filename>) version packages including
11268 packaging fixes.
11269 <note>
11270 <filename>PR</filename> does not need to be increased
11271 for changes that do not change the package contents or
11272 metadata.
11273 </note>
11274 Because manually managing <filename>PR</filename> can be
11275 cumbersome and error-prone, an automated solution exists.
11276 See the
11277 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011278 section in the Yocto Project Development Tasks Manual
11279 for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011280 </para>
11281 </glossdef>
11282 </glossentry>
11283
11284 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
11285 <info>
11286 PREFERRED_PROVIDER[doc] = "If multiple recipes provide an item, this variable determines which recipe should be given preference."
11287 </info>
11288 <glossdef>
11289 <para role="glossdeffirst">
11290<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040011291 If multiple recipes provide the same item, this variable
11292 determines which recipe is preferred and thus provides
11293 the item (i.e. the preferred provider).
11294 You should always suffix this variable with the name of the
11295 provided item.
11296 And, you should define the variable using the preferred
11297 recipe's name
11298 (<link linkend='var-PN'><filename>PN</filename></link>).
11299 Here is a common example:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011300 <literallayout class='monospaced'>
11301 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
Brad Bishop316dfdd2018-06-25 12:45:53 -040011302 </literallayout>
11303 In the previous example, multiple recipes are providing
11304 "virtual/kernel".
11305 The <filename>PREFERRED_PROVIDER</filename> variable is
11306 set with the name (<filename>PN</filename>) of the recipe
11307 you prefer to provide "virtual/kernel".
11308 </para>
11309
11310 <para>
11311 Following are more examples:
11312 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011313 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
11314 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
11315 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011316 For more information, see the
11317 "<ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>Using Virtual Providers</ulink>"
11318 section in the Yocto Project Development Tasks Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011319 <note>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011320 If you use a <filename>virtual/*</filename> item
11321 with <filename>PREFERRED_PROVIDER</filename>, then any
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011322 recipe that
11323 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011324 that item but is not selected (defined) by
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011325 <filename>PREFERRED_PROVIDER</filename> is prevented
11326 from building, which is usually desirable since this
11327 mechanism is designed to select between mutually
11328 exclusive alternative providers.
11329 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011330 </para>
11331 </glossdef>
11332 </glossentry>
11333
11334 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
11335 <info>
11336 PREFERRED_VERSION[doc] = "If there are multiple versions of recipes available, this variable determines which recipe should be given preference."
11337 </info>
11338 <glossdef>
11339 <para role="glossdeffirst">
11340<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011341 If multiple versions of recipes exist, this
11342 variable determines which version is given preference.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011343 You must always suffix the variable with the
11344 <link linkend='var-PN'><filename>PN</filename></link>
11345 you want to select, and you should set the
11346 <link linkend='var-PV'><filename>PV</filename></link>
11347 accordingly for precedence.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011348 </para>
11349
11350 <para>
11351 The <filename>PREFERRED_VERSION</filename> variable
11352 supports limited wildcard use through the
11353 "<filename>%</filename>" character.
11354 You can use the character to match any number of
11355 characters, which can be useful when specifying versions
11356 that contain long revision numbers that potentially change.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011357 Here are two examples:
11358 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011359 PREFERRED_VERSION_python = "3.4.0"
Brad Bishopc342db32019-05-15 21:57:59 -040011360 PREFERRED_VERSION_linux-yocto = "5.0%"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011361 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011362 <note><title>Important</title>
11363 The use of the "<filename>%</filename>" character
11364 is limited in that it only works at the end of the
11365 string.
11366 You cannot use the wildcard character in any other
11367 location of the string.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011368 </note>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011369 </para>
11370
11371 <para>
11372 The specified version is matched against
11373 <link linkend='var-PV'><filename>PV</filename></link>,
11374 which does not necessarily match the version part of
11375 the recipe's filename.
11376 For example, consider two recipes
11377 <filename>foo_1.2.bb</filename> and
11378 <filename>foo_git.bb</filename> where
11379 <filename>foo_git.bb</filename> contains the following
11380 assignment:
11381 <literallayout class='monospaced'>
11382 PV = "1.1+git${SRCPV}"
11383 </literallayout>
11384 In this case, the correct way to select
11385 <filename>foo_git.bb</filename> is by using an
11386 assignment such as the following:
11387 <literallayout class='monospaced'>
11388 PREFERRED_VERSION_foo = "1.1+git%"
11389 </literallayout>
11390 Compare that previous example against the following
11391 incorrect example, which does not work:
11392 <literallayout class='monospaced'>
11393 PREFERRED_VERSION_foo = "git"
11394 </literallayout>
11395 </para>
11396
11397 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011398 Sometimes the <filename>PREFERRED_VERSION</filename>
11399 variable can be set by configuration files in a way that
11400 is hard to change.
11401 You can use
11402 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
11403 to set a machine-specific override.
11404 Here is an example:
11405 <literallayout class='monospaced'>
Brad Bishopc342db32019-05-15 21:57:59 -040011406 PREFERRED_VERSION_linux-yocto_qemux86 = "5.0%"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011407 </literallayout>
11408 Although not recommended, worst case, you can also use the
11409 "forcevariable" override, which is the strongest override
11410 possible.
11411 Here is an example:
11412 <literallayout class='monospaced'>
Brad Bishopc342db32019-05-15 21:57:59 -040011413 PREFERRED_VERSION_linux-yocto_forcevariable = "5.0%"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011414 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011415 <note>
11416 The <filename>_forcevariable</filename> override is
11417 not handled specially.
11418 This override only works because the default value of
Brad Bishop316dfdd2018-06-25 12:45:53 -040011419 <filename>OVERRIDES</filename> includes
11420 "forcevariable".
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011421 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011422 </para>
11423 </glossdef>
11424 </glossentry>
11425
11426 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
11427 <info>
11428 PREMIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."
11429 </info>
11430 <glossdef>
11431 <para role="glossdeffirst">
11432<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11433 Specifies additional paths from which the OpenEmbedded
11434 build system gets source code.
11435 When the build system searches for source code, it first
11436 tries the local download directory.
11437 If that location fails, the build system tries locations
11438 defined by <filename>PREMIRRORS</filename>, the upstream
11439 source, and then locations specified by
11440 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
11441 in that order.
11442 </para>
11443
11444 <para>
11445 Assuming your distribution
11446 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
11447 is "poky", the default value for
11448 <filename>PREMIRRORS</filename> is defined in the
11449 <filename>conf/distro/poky.conf</filename> file in the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011450 <filename>meta-poky</filename> Git repository.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011451 </para>
11452
11453 <para>
11454 Typically, you could add a specific server for the
11455 build system to attempt before any others by adding
11456 something like the following to the
11457 <filename>local.conf</filename> configuration file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011458 <link linkend='build-directory'>Build Directory</link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011459 <literallayout class='monospaced'>
11460 PREMIRRORS_prepend = "\
11461 git://.*/.* http://www.yoctoproject.org/sources/ \n \
11462 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
11463 http://.*/.* http://www.yoctoproject.org/sources/ \n \
11464 https://.*/.* http://www.yoctoproject.org/sources/ \n"
11465 </literallayout>
11466 These changes cause the build system to intercept
11467 Git, FTP, HTTP, and HTTPS requests and direct them to
11468 the <filename>http://</filename> sources mirror.
11469 You can use <filename>file://</filename> URLs to point
11470 to local directories or network shares as well.
11471 </para>
11472 </glossdef>
11473 </glossentry>
11474
11475 <glossentry id='var-PRIORITY'><glossterm>PRIORITY</glossterm>
11476 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011477 PRIORITY[doc] = "Indicates the importance of a package. The default value is 'optional'. Other standard values are 'required', 'standard', and 'extra'."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011478 </info>
11479 <glossdef>
11480 <para role="glossdeffirst">
11481<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11482 Indicates the importance of a package.
11483 </para>
11484
11485 <para>
11486 <filename>PRIORITY</filename> is considered to be part of
11487 the distribution policy because the importance of any given
11488 recipe depends on the purpose for which the distribution
11489 is being produced.
11490 Thus, <filename>PRIORITY</filename> is not normally set
11491 within recipes.
11492 </para>
11493
11494 <para>
11495 You can set <filename>PRIORITY</filename> to "required",
11496 "standard", "extra", and "optional", which is the default.
11497 </para>
11498 </glossdef>
11499 </glossentry>
11500
11501 <glossentry id='var-PRIVATE_LIBS'><glossterm>PRIVATE_LIBS</glossterm>
11502 <info>
11503 PRIVATE_LIBS[doc] = "Specifies libraries installed within a recipe that should be ignored by the OpenEmbedded build system's shared library resolver."
11504 </info>
11505 <glossdef>
11506 <para role="glossdeffirst">
11507<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11508 Specifies libraries installed within a recipe that
11509 should be ignored by the OpenEmbedded build system's
11510 shared library resolver.
11511 This variable is typically used when software being
11512 built by a recipe has its own private versions of a
11513 library normally provided by another recipe.
11514 In this case, you would not want the package containing
11515 the private libraries to be set as a dependency on other
11516 unrelated packages that should instead depend on the
11517 package providing the standard version of the library.
11518 </para>
11519
11520 <para>
11521 Libraries specified in this variable should be specified
11522 by their file name.
11523 For example, from the Firefox recipe in meta-browser:
11524 <literallayout class='monospaced'>
11525 PRIVATE_LIBS = "libmozjs.so \
11526 libxpcom.so \
11527 libnspr4.so \
11528 libxul.so \
11529 libmozalloc.so \
11530 libplc4.so \
11531 libplds4.so"
11532 </literallayout>
11533 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011534
11535 <para>
11536 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040011537 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
11538 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011539 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011540 </glossdef>
11541 </glossentry>
11542
11543 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
11544 <info>
11545 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."
11546 </info>
11547 <glossdef>
11548 <para role="glossdeffirst">
11549<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11550 A list of aliases by which a particular recipe can be
11551 known.
11552 By default, a recipe's own
11553 <filename><link linkend='var-PN'>PN</link></filename>
11554 is implicitly already in its <filename>PROVIDES</filename>
Andrew Geissler82c905d2020-04-13 13:39:40 -050011555 list and therefore does not need to mention that it provides itself.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011556 If a recipe uses <filename>PROVIDES</filename>, the
11557 additional aliases are synonyms for the recipe and can
Andrew Geissler82c905d2020-04-13 13:39:40 -050011558 be useful for satisfying dependencies of other recipes during
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011559 the build as specified by
11560 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
11561 </para>
11562
11563 <para>
11564 Consider the following example
Andrew Geissler82c905d2020-04-13 13:39:40 -050011565 <filename>PROVIDES</filename> statement from the recipe
11566 file <filename>eudev_3.2.9.bb</filename>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011567 <literallayout class='monospaced'>
Andrew Geissler82c905d2020-04-13 13:39:40 -050011568 PROVIDES = "udev"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011569 </literallayout>
11570 The <filename>PROVIDES</filename> statement results in
Andrew Geissler82c905d2020-04-13 13:39:40 -050011571 the "eudev" recipe also being available as simply "udev".
11572
11573 <note>
11574 Given that a recipe's own recipe name is already
11575 implicitly in its own <filename>PROVIDES</filename> list,
11576 it is unnecessary to add aliases with the "+=" operator;
11577 using a simple assignment will be sufficient. In other
11578 words, while you could write:
11579 <literallayout class='monospaced'>
11580 PROVIDES += "udev"
11581 </literallayout>
11582 in the above, the "+=" is overkill and unnecessary.
11583 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011584 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011585
11586 <para>
11587 In addition to providing recipes under alternate names,
11588 the <filename>PROVIDES</filename> mechanism is also used
11589 to implement virtual targets.
11590 A virtual target is a name that corresponds to some
11591 particular functionality (e.g. a Linux kernel).
11592 Recipes that provide the functionality in question list the
11593 virtual target in <filename>PROVIDES</filename>.
11594 Recipes that depend on the functionality in question can
Brad Bishop316dfdd2018-06-25 12:45:53 -040011595 include the virtual target in <filename>DEPENDS</filename>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011596 to leave the choice of provider open.
11597 </para>
11598
11599 <para>
11600 Conventionally, virtual targets have names on the form
11601 "virtual/function" (e.g. "virtual/kernel").
11602 The slash is simply part of the name and has no
11603 syntactical significance.
11604 </para>
11605
11606 <para>
11607 The
11608 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
11609 variable is used to select which particular recipe
11610 provides a virtual target.
11611 <note>
11612 <para>A corresponding mechanism for virtual runtime
11613 dependencies (packages) exists.
11614 However, the mechanism does not depend on any special
11615 functionality beyond ordinary variable assignments.
11616 For example,
11617 <filename>VIRTUAL-RUNTIME_dev_manager</filename>
11618 refers to the package of the component that manages
11619 the <filename>/dev</filename> directory.</para>
11620
11621 <para>Setting the "preferred provider" for runtime
11622 dependencies is as simple as using the following
11623 assignment in a configuration file:</para>
11624 <literallayout class='monospaced'>
11625 VIRTUAL-RUNTIME_dev_manager = "udev"
11626 </literallayout>
11627 </note>
11628 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011629 </glossdef>
11630 </glossentry>
11631
11632 <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
11633 <info>
11634 PRSERV_HOST[doc] = "The network based PR service host and port."
11635 </info>
11636 <glossdef>
11637 <para role="glossdeffirst">
11638<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11639 The network based
11640 <link linkend='var-PR'><filename>PR</filename></link>
11641 service host and port.
11642 </para>
11643
11644 <para>
11645 The <filename>conf/local.conf.sample.extended</filename>
11646 configuration file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011647 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011648 shows how the <filename>PRSERV_HOST</filename> variable is
11649 set:
11650 <literallayout class='monospaced'>
11651 PRSERV_HOST = "localhost:0"
11652 </literallayout>
11653 You must set the variable if you want to automatically
11654 start a local
11655 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.
11656 You can set <filename>PRSERV_HOST</filename> to other
11657 values to use a remote PR service.
11658 </para>
11659 </glossdef>
11660 </glossentry>
11661
11662 <glossentry id='var-PTEST_ENABLED'><glossterm>PTEST_ENABLED</glossterm>
11663 <info>
11664 PRSERV_HOST[doc] = "Specifies whether or not Package Test (ptest) functionality is enabled when building a recipe."
11665 </info>
11666 <glossdef>
11667 <para role="glossdeffirst">
11668<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11669 Specifies whether or not
11670 <ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Package Test</ulink>
11671 (ptest) functionality is enabled when building a recipe.
11672 You should not set this variable directly.
11673 Enabling and disabling building Package Tests
11674 at build time should be done by adding "ptest" to (or
11675 removing it from)
11676 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
11677 </para>
11678 </glossdef>
11679 </glossentry>
11680
11681 <glossentry id='var-PV'><glossterm>PV</glossterm>
11682 <info>
11683 PV[doc] = "The version of the recipe. The version is normally extracted from the recipe filename."
11684 </info>
11685 <glossdef>
11686 <para role="glossdeffirst">
11687<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11688 The version of the recipe.
11689 The version is normally extracted from the recipe filename.
11690 For example, if the recipe is named
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011691 <filename>expat_2.0.1.bb</filename>, then the default value
11692 of <filename>PV</filename> will be "2.0.1".
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011693 <filename>PV</filename> is generally not overridden within
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011694 a recipe unless it is building an unstable (i.e.
11695 development) version from a source code repository
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011696 (e.g. Git or Subversion).
11697 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011698
11699 <para>
11700 <filename>PV</filename> is the default value of the
11701 <link linkend='var-PKGV'><filename>PKGV</filename></link>
11702 variable.
11703 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011704 </glossdef>
11705 </glossentry>
11706
11707 <glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>
11708 <info>
11709 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."
11710 </info>
11711 <glossdef>
11712 <para role="glossdeffirst">
11713<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11714 When used by recipes that inherit the
11715 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
11716 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
11717 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
11718 or
11719 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
11720 classes, denotes the Application Binary Interface (ABI)
11721 currently in use for Python.
11722 By default, the ABI is "m".
11723 You do not have to set this variable as the OpenEmbedded
11724 build system sets it for you.
11725 </para>
11726
11727 <para>
11728 The OpenEmbedded build system uses the ABI to construct
11729 directory names used when installing the Python headers
11730 and libraries in sysroot
11731 (e.g. <filename>.../python3.3m/...</filename>).
11732 </para>
11733
11734 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011735 Recipes that inherit the <filename>distutils</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011736 class during cross-builds also use this variable to
11737 locate the headers and libraries of the appropriate Python
11738 that the extension is targeting.
11739 </para>
11740 </glossdef>
11741 </glossentry>
11742
11743 <glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>
11744 <info>
11745 PYTHON_PN[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, specifies the major Python version being built."
11746 </info>
11747 <glossdef>
11748 <para role="glossdeffirst">
11749<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11750 When used by recipes that inherit the
11751 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
11752 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
11753 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
11754 or
11755 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
11756 classes, specifies the major Python version being built.
Brad Bishop96ff1982019-08-19 13:50:42 -040011757 For Python 3.x, <filename>PYTHON_PN</filename> would be
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011758 "python3".
11759 You do not have to set this variable as the
11760 OpenEmbedded build system automatically sets it for you.
11761 </para>
11762
11763 <para>
11764 The variable allows recipes to use common infrastructure
11765 such as the following:
11766 <literallayout class='monospaced'>
11767 DEPENDS += "${PYTHON_PN}-native"
11768 </literallayout>
11769 In the previous example, the version of the dependency
11770 is <filename>PYTHON_PN</filename>.
11771 </para>
11772 </glossdef>
11773 </glossentry>
11774
11775 </glossdiv>
11776
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011777 <glossdiv id='var-glossary-r'><title>R</title>
11778
11779 <glossentry id='var-RANLIB'><glossterm>RANLIB</glossterm>
11780 <info>
11781 RANLIB[doc] = "Minimal command and arguments to run 'ranlib'."
11782 </info>
11783 <glossdef>
11784 <para role="glossdeffirst">
11785<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11786 The minimal command and arguments to run
11787 <filename>ranlib</filename>.
11788 </para>
11789 </glossdef>
11790 </glossentry>
11791
11792 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
11793 <info>
11794 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."
11795 </info>
11796 <glossdef>
11797 <para role="glossdeffirst">
11798<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11799 The list of packages that conflict with packages.
11800 Note that packages will not be installed if conflicting
11801 packages are not first removed.
11802 </para>
11803
11804 <para>
11805 Like all package-controlling variables, you must always use
11806 them in conjunction with a package name override.
11807 Here is an example:
11808 <literallayout class='monospaced'>
11809 RCONFLICTS_${PN} = "<replaceable>another_conflicting_package_name</replaceable>"
11810 </literallayout>
11811 </para>
11812
11813 <para>
11814 BitBake, which the OpenEmbedded build system uses, supports
11815 specifying versioned dependencies.
11816 Although the syntax varies depending on the packaging
11817 format, BitBake hides these differences from you.
11818 Here is the general syntax to specify versions with
11819 the <filename>RCONFLICTS</filename> variable:
11820 <literallayout class='monospaced'>
11821 RCONFLICTS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
11822 </literallayout>
11823 For <filename>operator</filename>, you can specify the
11824 following:
11825 <literallayout class='monospaced'>
11826 =
11827 &lt;
11828 &gt;
11829 &lt;=
11830 &gt;=
11831 </literallayout>
11832 For example, the following sets up a dependency on version
11833 1.2 or greater of the package <filename>foo</filename>:
11834 <literallayout class='monospaced'>
11835 RCONFLICTS_${PN} = "foo (>= 1.2)"
11836 </literallayout>
11837 </para>
11838 </glossdef>
11839 </glossentry>
11840
11841 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
11842 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011843 RDEPENDS[doc] = "Lists runtime dependencies of a package."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011844 </info>
11845 <glossdef>
11846 <para role="glossdeffirst">
11847<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011848 Lists runtime dependencies of a package.
11849 These dependencies are other packages that must be
11850 installed in order for the package to function correctly.
11851 As an example, the following assignment declares that the
11852 package <filename>foo</filename> needs the packages
11853 <filename>bar</filename> and <filename>baz</filename> to
11854 be installed:
11855 <literallayout class='monospaced'>
11856 RDEPENDS_foo = "bar baz"
11857 </literallayout>
11858 The most common types of package runtime dependencies are
11859 automatically detected and added.
11860 Therefore, most recipes do not need to set
11861 <filename>RDEPENDS</filename>.
11862 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040011863 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
11864 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011865 </para>
11866
11867 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011868 The practical effect of the above
11869 <filename>RDEPENDS</filename> assignment is that
11870 <filename>bar</filename> and <filename>baz</filename>
11871 will be declared as dependencies inside the package
11872 <filename>foo</filename> when it is written out by one of
11873 the
11874 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>
11875 tasks.
11876 Exactly how this is done depends on which package format
11877 is used, which is determined by
11878 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>.
11879 When the corresponding package manager installs the
11880 package, it will know to also install the packages on
11881 which it depends.
11882 </para>
11883
11884 <para>
11885 To ensure that the packages <filename>bar</filename> and
11886 <filename>baz</filename> get built, the previous
11887 <filename>RDEPENDS</filename> assignment also causes a task
11888 dependency to be added.
11889 This dependency is from the recipe's
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011890 <link linkend='ref-tasks-build'><filename>do_build</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011891 (not to be confused with
11892 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>)
11893 task to the <filename>do_package_write_*</filename>
11894 task of the recipes that build <filename>bar</filename> and
11895 <filename>baz</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011896 </para>
11897
11898 <para>
11899 The names of the packages you list within
11900 <filename>RDEPENDS</filename> must be the names of other
11901 packages - they cannot be recipe names.
11902 Although package names and recipe names usually match,
11903 the important point here is that you are
11904 providing package names within the
11905 <filename>RDEPENDS</filename> variable.
11906 For an example of the default list of packages created from
11907 a recipe, see the
11908 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
11909 variable.
11910 </para>
11911
11912 <para>
11913 Because the <filename>RDEPENDS</filename> variable applies
11914 to packages being built, you should always use the variable
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011915 in a form with an attached package name (remember that a
11916 single recipe can build multiple packages).
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011917 For example, suppose you are building a development package
11918 that depends on the <filename>perl</filename> package.
11919 In this case, you would use the following
11920 <filename>RDEPENDS</filename> statement:
11921 <literallayout class='monospaced'>
11922 RDEPENDS_${PN}-dev += "perl"
11923 </literallayout>
11924 In the example, the development package depends on
11925 the <filename>perl</filename> package.
11926 Thus, the <filename>RDEPENDS</filename> variable has the
11927 <filename>${PN}-dev</filename> package name as part of the
11928 variable.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011929 <note>
11930 <title>Caution</title>
11931 <filename>RDEPENDS_${PN}-dev</filename> includes
11932 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>
11933 by default.
11934 This default is set in the BitBake configuration file
11935 (<filename>meta/conf/bitbake.conf</filename>).
11936 Be careful not to accidentally remove
11937 <filename>${PN}</filename> when modifying
11938 <filename>RDEPENDS_${PN}-dev</filename>.
11939 Use the "+=" operator rather than the "=" operator.
11940 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011941 </para>
11942
11943 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011944 The package names you use with
11945 <filename>RDEPENDS</filename> must appear as they would in
11946 the <filename>PACKAGES</filename> variable.
11947 The
11948 <link linkend='var-PKG'><filename>PKG</filename></link>
11949 variable allows a different name to be used for
11950 the final package (e.g. the
11951 <link linkend='ref-classes-debian'><filename>debian</filename></link>
11952 class uses this to rename packages), but this final package
11953 name cannot be used with <filename>RDEPENDS</filename>,
11954 which makes sense as <filename>RDEPENDS</filename> is meant
11955 to be independent of the package format used.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011956 </para>
11957
11958 <para>
11959 BitBake, which the OpenEmbedded build system uses, supports
11960 specifying versioned dependencies.
11961 Although the syntax varies depending on the packaging
11962 format, BitBake hides these differences from you.
11963 Here is the general syntax to specify versions with
11964 the <filename>RDEPENDS</filename> variable:
11965 <literallayout class='monospaced'>
11966 RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
11967 </literallayout>
Brad Bishop37a0e4d2017-12-04 01:01:44 -050011968 For <replaceable>operator</replaceable>, you can specify the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011969 following:
11970 <literallayout class='monospaced'>
11971 =
11972 &lt;
11973 &gt;
11974 &lt;=
11975 &gt;=
11976 </literallayout>
Brad Bishop37a0e4d2017-12-04 01:01:44 -050011977 For <replaceable>version</replaceable>, provide the version
11978 number.
11979 <note><title>Tip</title>
11980 You can use
11981 <link linkend='var-EXTENDPKGV'><filename>EXTENDPKGV</filename></link>
11982 to provide a full package version specification.
11983 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011984 For example, the following sets up a dependency on version
11985 1.2 or greater of the package <filename>foo</filename>:
11986 <literallayout class='monospaced'>
11987 RDEPENDS_${PN} = "foo (>= 1.2)"
11988 </literallayout>
11989 </para>
11990
11991 <para>
11992 For information on build-time dependencies, see the
11993 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
11994 variable.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011995 You can also see the
11996 "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
11997 "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
11998 sections in the BitBake User Manual for additional
11999 information on tasks and dependencies.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012000 </para>
12001 </glossdef>
12002 </glossentry>
12003
12004 <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm>
12005 <info>
12006 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."
12007 </info>
12008 <glossdef>
12009 <para role="glossdeffirst">
12010<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12011 When inheriting the
12012 <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link>
12013 class, this
12014 variable identifies distribution features that must
12015 exist in the current configuration in order for the
12016 OpenEmbedded build system to build the recipe.
12017 In other words, if the
12018 <filename>REQUIRED_DISTRO_FEATURES</filename> variable
12019 lists a feature that does not appear in
12020 <filename>DISTRO_FEATURES</filename> within the
12021 current configuration, an error occurs and the
12022 build stops.
12023 </para>
12024 </glossdef>
12025 </glossentry>
12026
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012027 <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
12028 <info>
12029 RM_WORK_EXCLUDE[doc] = "With rm_work enabled, this variable specifies a list of packages whose work directories should not be removed."
12030 </info>
12031 <glossdef>
12032 <para role="glossdeffirst">
12033<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12034 With <filename>rm_work</filename> enabled, this
12035 variable specifies a list of recipes whose work directories
12036 should not be removed.
12037 See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
12038 section for more details.
12039 </para>
12040 </glossdef>
12041 </glossentry>
12042
12043 <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm>
12044 <info>
12045 ROOT_HOME[doc] = "Defines the root home directory."
12046 </info>
12047 <glossdef>
12048 <para role="glossdeffirst">
12049<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12050 Defines the root home directory.
12051 By default, this directory is set as follows in the
12052 BitBake configuration file:
12053 <literallayout class='monospaced'>
12054 ROOT_HOME ??= "/home/root"
12055 </literallayout>
12056 <note>
12057 This default value is likely used because some
12058 embedded solutions prefer to have a read-only root
12059 filesystem and prefer to keep writeable data in one
12060 place.
12061 </note>
12062 </para>
12063
12064 <para>
12065 You can override the default by setting the variable
12066 in any layer or in the <filename>local.conf</filename> file.
12067 Because the default is set using a "weak" assignment
12068 (i.e. "??="), you can use either of the following forms
12069 to define your override:
12070 <literallayout class='monospaced'>
12071 ROOT_HOME = "/root"
12072 ROOT_HOME ?= "/root"
12073 </literallayout>
12074 These override examples use <filename>/root</filename>,
12075 which is probably the most commonly used override.
12076 </para>
12077 </glossdef>
12078 </glossentry>
12079
12080 <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>
12081 <info>
12082 ROOTFS[doc] = "Indicates a filesystem image to include as the root filesystem."
12083 </info>
12084 <glossdef>
12085 <para role="glossdeffirst">
12086<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12087 Indicates a filesystem image to include as the root
12088 filesystem.
12089 </para>
12090
12091 <para>
12092 The <filename>ROOTFS</filename> variable is an optional
12093 variable used with the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012094 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012095 class.
12096 </para>
12097 </glossdef>
12098 </glossentry>
12099
12100 <glossentry id='var-ROOTFS_POSTINSTALL_COMMAND'><glossterm>ROOTFS_POSTINSTALL_COMMAND</glossterm>
12101 <info>
12102 ROOTFS_POSTINSTALL_COMMAND[doc] = "Specifies a list of functions to call after installing packages."
12103 </info>
12104 <glossdef>
12105 <para role="glossdeffirst">
12106<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12107 Specifies a list of functions to call after the
12108 OpenEmbedded build system has installed packages.
12109 You can specify functions separated by semicolons:
12110 <literallayout class='monospaced'>
12111 ROOTFS_POSTINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
12112 </literallayout>
12113 </para>
12114
12115 <para>
12116 If you need to pass the root filesystem path to a command
12117 within a function, you can use
12118 <filename>${IMAGE_ROOTFS}</filename>, which points to
12119 the directory that becomes the root filesystem image.
12120 See the
12121 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12122 variable for more information.
12123 </para>
12124 </glossdef>
12125 </glossentry>
12126
12127 <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
12128 <info>
12129 ROOTFS_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the root filesystem."
12130 </info>
12131 <glossdef>
12132 <para role="glossdeffirst">
12133<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12134 Specifies a list of functions to call once the
12135 OpenEmbedded build system has created the root filesystem.
12136 You can specify functions separated by semicolons:
12137 <literallayout class='monospaced'>
12138 ROOTFS_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
12139 </literallayout>
12140 </para>
12141
12142 <para>
12143 If you need to pass the root filesystem path to a command
12144 within a function, you can use
12145 <filename>${IMAGE_ROOTFS}</filename>, which points to
12146 the directory that becomes the root filesystem image.
12147 See the
12148 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12149 variable for more information.
12150 </para>
12151 </glossdef>
12152 </glossentry>
12153
12154 <glossentry id='var-ROOTFS_POSTUNINSTALL_COMMAND'><glossterm>ROOTFS_POSTUNINSTALL_COMMAND</glossterm>
12155 <info>
12156 ROOTFS_POSTUNINSTALL_COMMAND[doc] = "Specifies a list of functions to call after removal of unneeded packages."
12157 </info>
12158 <glossdef>
12159 <para role="glossdeffirst">
12160<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12161 Specifies a list of functions to call after the
12162 OpenEmbedded build system has removed unnecessary
12163 packages.
12164 When runtime package management is disabled in the
12165 image, several packages are removed including
12166 <filename>base-passwd</filename>,
12167 <filename>shadow</filename>, and
12168 <filename>update-alternatives</filename>.
12169 You can specify functions separated by semicolons:
12170 <literallayout class='monospaced'>
12171 ROOTFS_POSTUNINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
12172 </literallayout>
12173 </para>
12174
12175 <para>
12176 If you need to pass the root filesystem path to a command
12177 within a function, you can use
12178 <filename>${IMAGE_ROOTFS}</filename>, which points to
12179 the directory that becomes the root filesystem image.
12180 See the
12181 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12182 variable for more information.
12183 </para>
12184 </glossdef>
12185 </glossentry>
12186
12187 <glossentry id='var-ROOTFS_PREPROCESS_COMMAND'><glossterm>ROOTFS_PREPROCESS_COMMAND</glossterm>
12188 <info>
12189 ROOTFS_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the root filesystem."
12190 </info>
12191 <glossdef>
12192 <para role="glossdeffirst">
12193<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12194 Specifies a list of functions to call before the
12195 OpenEmbedded build system has created the root filesystem.
12196 You can specify functions separated by semicolons:
12197 <literallayout class='monospaced'>
12198 ROOTFS_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
12199 </literallayout>
12200 </para>
12201
12202 <para>
12203 If you need to pass the root filesystem path to a command
12204 within a function, you can use
12205 <filename>${IMAGE_ROOTFS}</filename>, which points to
12206 the directory that becomes the root filesystem image.
12207 See the
12208 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12209 variable for more information.
12210 </para>
12211 </glossdef>
12212 </glossentry>
12213
12214 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
12215 <info>
12216 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."
12217 </info>
12218 <glossdef>
12219 <para role="glossdeffirst">
12220<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12221 A list of package name aliases that a package also provides.
12222 These aliases are useful for satisfying runtime dependencies
12223 of other packages both during the build and on the target
12224 (as specified by
12225 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
12226 <note>
12227 A package's own name is implicitly already in its
12228 <filename>RPROVIDES</filename> list.
12229 </note>
12230 </para>
12231
12232 <para>
12233 As with all package-controlling variables, you must always
12234 use the variable in conjunction with a package name override.
12235 Here is an example:
12236 <literallayout class='monospaced'>
12237 RPROVIDES_${PN} = "widget-abi-2"
12238 </literallayout>
12239 </para>
12240 </glossdef>
12241 </glossentry>
12242
12243 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
12244 <info>
12245 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."
12246 </info>
12247 <glossdef>
12248 <para role="glossdeffirst">
12249<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12250 A list of packages that extends the usability of a package
12251 being built.
12252 The package being built does not depend on this list of
12253 packages in order to successfully build, but rather
12254 uses them for extended usability.
12255 To specify runtime dependencies for packages, see the
12256 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
12257 variable.
12258 </para>
12259
12260 <para>
12261 The package manager will automatically install the
12262 <filename>RRECOMMENDS</filename> list of packages when
12263 installing the built package.
12264 However, you can prevent listed packages from being
12265 installed by using the
12266 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
12267 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
12268 and
12269 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
12270 variables.
12271 </para>
12272
12273 <para>
12274 Packages specified in
12275 <filename>RRECOMMENDS</filename> need not actually be
12276 produced.
12277 However, a recipe must exist that provides each package,
12278 either through the
12279 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
12280 or
12281 <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link>
12282 variables or the
12283 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>
12284 variable, or an error will occur during the build.
12285 If such a recipe does exist and the package is not produced,
12286 the build continues without error.
12287 </para>
12288
12289 <para>
12290 Because the <filename>RRECOMMENDS</filename> variable
12291 applies to packages being built, you should always attach
12292 an override to the variable to specify the particular
12293 package whose usability is being extended.
12294 For example, suppose you are building a development package
12295 that is extended to support wireless functionality.
12296 In this case, you would use the following:
12297 <literallayout class='monospaced'>
12298 RRECOMMENDS_${PN}-dev += "<replaceable>wireless_package_name</replaceable>"
12299 </literallayout>
12300 In the example, the package name
12301 (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
12302 must appear as it would in the
Brad Bishop316dfdd2018-06-25 12:45:53 -040012303 <filename>PACKAGES</filename> namespace before any renaming
12304 of the output package by classes such as
12305 <filename>debian.bbclass</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012306 </para>
12307
12308 <para>
12309 BitBake, which the OpenEmbedded build system uses, supports
12310 specifying versioned recommends.
12311 Although the syntax varies depending on the packaging
12312 format, BitBake hides these differences from you.
12313 Here is the general syntax to specify versions with
12314 the <filename>RRECOMMENDS</filename> variable:
12315 <literallayout class='monospaced'>
12316 RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
12317 </literallayout>
12318 For <filename>operator</filename>, you can specify the
12319 following:
12320 <literallayout class='monospaced'>
12321 =
12322 &lt;
12323 &gt;
12324 &lt;=
12325 &gt;=
12326 </literallayout>
12327 For example, the following sets up a recommend on version
12328 1.2 or greater of the package <filename>foo</filename>:
12329 <literallayout class='monospaced'>
12330 RRECOMMENDS_${PN} = "foo (>= 1.2)"
12331 </literallayout>
12332 </para>
12333 </glossdef>
12334 </glossentry>
12335
12336 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
12337 <info>
12338 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."
12339 </info>
12340 <glossdef>
12341 <para role="glossdeffirst">
12342<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12343 A list of packages replaced by a package.
12344 The package manager uses this variable to determine which
12345 package should be installed to replace other package(s)
12346 during an upgrade.
12347 In order to also have the other package(s) removed at the
12348 same time, you must add the name of the other
12349 package to the
12350 <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
12351 </para>
12352
12353 <para>
12354 As with all package-controlling variables, you must use
12355 this variable in conjunction with a package name
12356 override.
12357 Here is an example:
12358 <literallayout class='monospaced'>
12359 RREPLACES_${PN} = "<replaceable>other_package_being_replaced</replaceable>"
12360 </literallayout>
12361 </para>
12362
12363 <para>
12364 BitBake, which the OpenEmbedded build system uses, supports
12365 specifying versioned replacements.
12366 Although the syntax varies depending on the packaging
12367 format, BitBake hides these differences from you.
12368 Here is the general syntax to specify versions with
12369 the <filename>RREPLACES</filename> variable:
12370 <literallayout class='monospaced'>
12371 RREPLACES_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
12372 </literallayout>
12373 For <filename>operator</filename>, you can specify the
12374 following:
12375 <literallayout class='monospaced'>
12376 =
12377 &lt;
12378 &gt;
12379 &lt;=
12380 &gt;=
12381 </literallayout>
12382 For example, the following sets up a replacement using
12383 version 1.2 or greater of the package
12384 <filename>foo</filename>:
12385 <literallayout class='monospaced'>
12386 RREPLACES_${PN} = "foo (>= 1.2)"
12387 </literallayout>
12388 </para>
12389 </glossdef>
12390 </glossentry>
12391
12392 <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
12393 <info>
12394 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."
12395 </info>
12396 <glossdef>
12397 <para role="glossdeffirst">
12398<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12399 A list of additional packages that you can suggest for
12400 installation by the package manager at the time a package
12401 is installed.
12402 Not all package managers support this functionality.
12403 </para>
12404
12405 <para>
12406 As with all package-controlling variables, you must always
12407 use this variable in conjunction with a package name
12408 override.
12409 Here is an example:
12410 <literallayout class='monospaced'>
12411 RSUGGESTS_${PN} = "<replaceable>useful_package</replaceable> <replaceable>another_package</replaceable>"
12412 </literallayout>
12413 </para>
12414 </glossdef>
12415 </glossentry>
12416
12417 </glossdiv>
12418
12419 <glossdiv id='var-glossary-s'><title>S</title>
12420
12421 <glossentry id='var-S'><glossterm>S</glossterm>
12422 <info>
12423 S[doc] = "The location in the Build Directory where unpacked package source code resides."
12424 </info>
12425 <glossdef>
12426 <para role="glossdeffirst">
12427<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12428 The location in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050012429 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012430 where unpacked recipe source code resides.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012431 By default, this directory is
12432 <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>,
12433 where <filename>${BPN}</filename> is the base recipe name
12434 and <filename>${PV}</filename> is the recipe version.
12435 If the source tarball extracts the code to a directory
12436 named anything other than <filename>${BPN}-${PV}</filename>,
Brad Bishopd7bf8c12018-02-25 22:55:05 -050012437 or if the source code is fetched from an SCM such as
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012438 Git or Subversion, then you must set <filename>S</filename>
12439 in the recipe so that the OpenEmbedded build system
12440 knows where to find the unpacked source.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012441 </para>
12442
12443 <para>
12444 As an example, assume a
Brad Bishopd7bf8c12018-02-25 22:55:05 -050012445 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012446 top-level folder named <filename>poky</filename> and a
12447 default Build Directory at <filename>poky/build</filename>.
12448 In this case, the work directory the build system uses
12449 to keep the unpacked recipe for <filename>db</filename>
12450 is the following:
12451 <literallayout class='monospaced'>
12452 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
12453 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012454 The unpacked source code resides in the
12455 <filename>db-5.1.19</filename> folder.
12456 </para>
12457
12458 <para>
12459 This next example assumes a Git repository.
12460 By default, Git repositories are cloned to
12461 <filename>${WORKDIR}/git</filename> during
12462 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>.
12463 Since this path is different from the default value of
12464 <filename>S</filename>, you must set it specifically
12465 so the source can be located:
12466 <literallayout class='monospaced'>
12467 SRC_URI = "git://path/to/repo.git"
12468 S = "${WORKDIR}/git"
12469 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012470 </para>
12471 </glossdef>
12472 </glossentry>
12473
12474 <glossentry id='var-SANITY_REQUIRED_UTILITIES'><glossterm>SANITY_REQUIRED_UTILITIES</glossterm>
12475 <info>
12476 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."
12477 </info>
12478 <glossdef>
12479 <para role="glossdeffirst">
12480<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12481 Specifies a list of command-line utilities that should be
12482 checked for during the initial sanity checking process when
12483 running BitBake.
12484 If any of the utilities are not installed on the build host,
12485 then BitBake immediately exits with an error.
12486 </para>
12487 </glossdef>
12488 </glossentry>
12489
12490 <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
12491 <info>
12492 SANITY_TESTED_DISTROS[doc] = "A list of the host distribution identifiers that the build system has been tested against."
12493 </info>
12494 <glossdef>
12495 <para role="glossdeffirst">
12496<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12497 A list of the host distribution identifiers that the
12498 build system has been tested against.
12499 Identifiers consist of the host distributor ID
12500 followed by the release,
12501 as reported by the <filename>lsb_release</filename> tool
12502 or as read from <filename>/etc/lsb-release</filename>.
12503 Separate the list items with explicit newline
12504 characters (<filename>\n</filename>).
12505 If <filename>SANITY_TESTED_DISTROS</filename> is not empty
12506 and the current value of
12507 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
12508 does not appear in the list, then the build system reports
12509 a warning that indicates the current host distribution has
12510 not been tested as a build host.
12511 </para>
12512 </glossdef>
12513 </glossentry>
12514
12515 <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
12516 <info>
12517 SDK_ARCH[doc] = "The target architecture for the SDK."
12518 </info>
12519 <glossdef>
12520 <para role="glossdeffirst">
12521<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12522 The target architecture for the SDK.
12523 Typically, you do not directly set this variable.
12524 Instead, use
12525 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
12526 </para>
12527 </glossdef>
12528 </glossentry>
12529
12530 <glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>
12531 <info>
12532 SDK_DEPLOY[doc] = "The directory set up and used by the populate_sdk_base to which the SDK is deployed."
12533 </info>
12534 <glossdef>
12535 <para role="glossdeffirst">
12536<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12537 The directory set up and used by the
12538 <link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012539 class to which the SDK is deployed.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012540 The <filename>populate_sdk_base</filename> class defines
12541 <filename>SDK_DEPLOY</filename> as follows:
12542 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012543 SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012544 </literallayout>
12545 </para>
12546 </glossdef>
12547 </glossentry>
12548
12549 <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm>
12550 <info>
12551 SDK_DIR[doc] = "The parent directory used by the OpenEmbedded build system when creating SDK output."
12552 </info>
12553 <glossdef>
12554 <para role="glossdeffirst">
12555<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12556 The parent directory used by the OpenEmbedded build system
12557 when creating SDK output.
12558 The
12559 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12560 class defines the variable as follows:
12561 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012562 SDK_DIR = "${WORKDIR}/sdk"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012563 </literallayout>
12564 <note>
12565 The <filename>SDK_DIR</filename> directory is a
12566 temporary directory as it is part of
12567 <filename>WORKDIR</filename>.
12568 The final output directory is
12569 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
12570 </note>
12571 </para>
12572 </glossdef>
12573 </glossentry>
12574
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012575 <glossentry id='var-SDK_EXT_TYPE'><glossterm>SDK_EXT_TYPE</glossterm>
12576 <info>
12577 SDK_EXT_TYPE[doc] = "Controls whether or not shared state artifacts are copied into the extensible SDK."
12578 </info>
12579 <glossdef>
12580 <para role="glossdeffirst">
12581<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12582 Controls whether or not shared state artifacts are copied
12583 into the extensible SDK.
12584 The default value of "full" copies all of the required
12585 shared state artifacts into the extensible SDK.
12586 The value "minimal" leaves these artifacts out of the
12587 SDK.
12588 <note>
12589 If you set the variable to "minimal", you need to
12590 ensure
12591 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
12592 is set in the SDK's configuration to enable the
12593 artifacts to be fetched as needed.
12594 </note>
12595 </para>
12596 </glossdef>
12597 </glossentry>
12598
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012599 <glossentry id='var-SDK_HOST_MANIFEST'><glossterm>SDK_HOST_MANIFEST</glossterm>
12600 <info>
12601 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."
12602 </info>
12603 <glossdef>
12604 <para role="glossdeffirst">
12605<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12606 The manifest file for the host part of the SDK.
12607 This file lists all the installed packages that make up
Brad Bishop316dfdd2018-06-25 12:45:53 -040012608 the host part of the SDK.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012609 The file contains package information on a line-per-package
12610 basis as follows:
12611 <literallayout class='monospaced'>
12612 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
12613 </literallayout>
12614 </para>
12615
12616 <para>
12617 The
12618 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12619 class defines the manifest file as follows:
12620 <literallayout class='monospaced'>
12621 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"
12622 </literallayout>
12623 The location is derived using the
12624 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>
12625 and
12626 <link linkend='var-TOOLCHAIN_OUTPUTNAME'><filename>TOOLCHAIN_OUTPUTNAME</filename></link>
12627 variables.
12628 </para>
12629 </glossdef>
12630 </glossentry>
12631
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012632 <glossentry id='var-SDK_INCLUDE_PKGDATA'><glossterm>SDK_INCLUDE_PKGDATA</glossterm>
12633 <info>
12634 SDK_INCLUDE_PKGDATA[doc] = "When set to "1", specifies to include the packagedata for all recipes in the "world" target in the extensible SDK."
12635 </info>
12636 <glossdef>
12637 <para role="glossdeffirst">
12638<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12639 When set to "1", specifies to include the packagedata for
12640 all recipes in the "world" target in the extensible SDK.
12641 Including this data allows the
12642 <filename>devtool search</filename> command to find these
12643 recipes in search results, as well as allows the
12644 <filename>devtool add</filename> command to map
12645 dependencies more effectively.
12646 <note>
12647 Enabling the <filename>SDK_INCLUDE_PKGDATA</filename>
12648 variable significantly increases build time because
12649 all of world needs to be built.
12650 Enabling the variable also slightly increases the size
12651 of the extensible SDK.
12652 </note>
12653 </para>
12654 </glossdef>
12655 </glossentry>
12656
Patrick Williamsc0f7c042017-02-23 20:41:17 -060012657 <glossentry id='var-SDK_INCLUDE_TOOLCHAIN'><glossterm>SDK_INCLUDE_TOOLCHAIN</glossterm>
12658 <info>
12659 SDK_INCLUDE_TOOLCHAIN[doc] = "When set to "1", specifies to include the toolchain in the extensible SDK."
12660 </info>
12661 <glossdef>
12662 <para role="glossdeffirst">
12663<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12664 When set to "1", specifies to include the toolchain in the
12665 extensible SDK.
12666 Including the toolchain is useful particularly when
12667 <link linkend='var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></link>
12668 is set to "minimal" to keep the SDK reasonably small
12669 but you still want to provide a usable toolchain.
12670 For example, suppose you want to use the toolchain from an
Brad Bishopc342db32019-05-15 21:57:59 -040012671 IDE or from other tools and you do not
Patrick Williamsc0f7c042017-02-23 20:41:17 -060012672 want to perform additional steps to install the toolchain.
12673 </para>
12674
12675 <para>
12676 The <filename>SDK_INCLUDE_TOOLCHAIN</filename> variable
12677 defaults to "0" if <filename>SDK_EXT_TYPE</filename>
12678 is set to "minimal", and defaults to "1" if
12679 <filename>SDK_EXT_TYPE</filename> is set to "full".
12680 </para>
12681 </glossdef>
12682 </glossentry>
12683
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012684 <glossentry id='var-SDK_INHERIT_BLACKLIST'><glossterm>SDK_INHERIT_BLACKLIST</glossterm>
12685 <info>
12686 SDK_INHERIT_BLACKLIST[doc] = "A list of classes to remove from the INHERIT value globally within the extensible SDK configuration."
12687 </info>
12688 <glossdef>
12689 <para role="glossdeffirst">
12690<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12691 A list of classes to remove from the
12692 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
12693 value globally within the extensible SDK configuration.
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012694 The
12695 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12696 class sets the default value:
12697 <literallayout class='monospaced'>
12698 SDK_INHERIT_BLACKLIST ?= "buildhistory icecc"
12699 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012700 </para>
12701
12702 <para>
12703 Some classes are not generally applicable within
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012704 the extensible SDK context.
12705 You can use this variable to disable those classes.
12706 </para>
12707
12708 <para>
12709 For additional information on how to customize the
12710 extensible SDK's configuration, see the
12711 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12712 section in the Yocto Project Application Development and
12713 the Extensible Software Development Kit (eSDK) manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012714 </para>
12715 </glossdef>
12716 </glossentry>
12717
12718 <glossentry id='var-SDK_LOCAL_CONF_BLACKLIST'><glossterm>SDK_LOCAL_CONF_BLACKLIST</glossterm>
12719 <info>
12720 SDK_LOCAL_CONF_BLACKLIST[doc] = "A list of variables not allowed through from the build system configuration into the extensible SDK configuration."
12721 </info>
12722 <glossdef>
12723 <para role="glossdeffirst">
12724<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012725 A list of variables not allowed through from the
12726 OpenEmbedded build system configuration into the extensible
12727 SDK configuration.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012728 Usually, these are variables that are specific to the
12729 machine on which the build system is running and thus
12730 would be potentially problematic within the extensible SDK.
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012731 </para>
12732
12733 <para>By default,
12734 <filename>SDK_LOCAL_CONF_BLACKLIST</filename> is set in the
12735 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12736 class and excludes the following variables:
12737 <literallayout class='monospaced'>
12738 <link linkend='var-CONF_VERSION'>CONF_VERSION</link>
12739 <link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link>
12740 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'>BB_NUMBER_PARSE_THREADS</ulink>
12741 <link linkend='var-PARALLEL_MAKE'>PARALLEL_MAKE</link>
12742 <link linkend='var-PRSERV_HOST'>PRSERV_HOST</link>
12743 <link linkend='var-SSTATE_MIRRORS'>SSTATE_MIRRORS</link>
12744 <link linkend='var-DL_DIR'>DL_DIR</link>
12745 <link linkend='var-SSTATE_DIR'>SSTATE_DIR</link>
12746 <link linkend='var-TMPDIR'>TMPDIR</link>
12747 <link linkend='var-BB_SERVER_TIMEOUT'>BB_SERVER_TIMEOUT</link>
12748 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012749 </para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012750
12751 <para>
12752 For additional information on how to customize the
12753 extensible SDK's configuration, see the
12754 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12755 section in the Yocto Project Application Development and
12756 the Extensible Software Development Kit (eSDK) manual.
12757 </para>
12758
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012759 </glossdef>
12760 </glossentry>
12761
12762 <glossentry id='var-SDK_LOCAL_CONF_WHITELIST'><glossterm>SDK_LOCAL_CONF_WHITELIST</glossterm>
12763 <info>
12764 SDK_LOCAL_CONF_WHITELIST[doc] = "A list of variables allowed through from the build system configuration into the extensible SDK configuration."
12765 </info>
12766 <glossdef>
12767 <para role="glossdeffirst">
12768<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012769 A list of variables allowed through from the OpenEmbedded
12770 build system configuration into the extensible SDK
12771 configuration.
12772 By default, the list of variables is empty and is set in
12773 the
12774 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12775 class.
12776 </para>
12777
12778 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012779 This list overrides the variables specified using the
12780 <link linkend='var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></link>
12781 variable as well as any variables identified by automatic
12782 blacklisting due to the "/" character being found at the
12783 start of the value, which is usually indicative of being a
12784 path and thus might not be valid on the system where the
12785 SDK is installed.
12786 </para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012787
12788 <para>
12789 For additional information on how to customize the
12790 extensible SDK's configuration, see the
12791 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12792 section in the Yocto Project Application Development and
12793 the Extensible Software Development Kit (eSDK) manual.
12794 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012795 </glossdef>
12796 </glossentry>
12797
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012798 <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
12799 <info>
12800 SDK_NAME[doc] = "The base name for SDK output files."
12801 </info>
12802 <glossdef>
12803 <para role="glossdeffirst">
12804<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12805 The base name for SDK output files.
12806 The name is derived from the
12807 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
12808 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
12809 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
12810 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
12811 and
12812 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
12813 variables:
12814 <literallayout class='monospaced'>
12815 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
12816 </literallayout>
12817 </para>
12818 </glossdef>
12819 </glossentry>
12820
12821 <glossentry id='var-SDK_OS'><glossterm>SDK_OS</glossterm>
12822 <info>
12823 SDK_OS[doc] = "The operating system for which the SDK will be built."
12824 </info>
12825 <glossdef>
12826 <para role="glossdeffirst">
12827<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12828 Specifies the operating system for which the SDK
12829 will be built.
12830 The default value is the value of
12831 <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>.
12832 </para>
12833 </glossdef>
12834 </glossentry>
12835
12836 <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>
12837 <info>
12838 SDK_OUTPUT[doc] = "The location used by the OpenEmbedded build system when creating SDK output."
12839 </info>
12840 <glossdef>
12841 <para role="glossdeffirst">
12842<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12843 The location used by the OpenEmbedded build system when
12844 creating SDK output.
12845 The
12846 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12847 class defines the variable as follows:
12848 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012849 SDK_DIR = "${WORKDIR}/sdk"
12850 SDK_OUTPUT = "${SDK_DIR}/image"
12851 SDK_DEPLOY = "${DEPLOY_DIR}/sdk"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012852 </literallayout>
12853 <note>
12854 The <filename>SDK_OUTPUT</filename> directory is a
12855 temporary directory as it is part of
Brad Bishop316dfdd2018-06-25 12:45:53 -040012856 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
12857 by way of
12858 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012859 The final output directory is
12860 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
12861 </note>
12862 </para>
12863 </glossdef>
12864 </glossentry>
12865
12866 <glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm>
12867 <info>
12868 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."
12869 </info>
12870 <glossdef>
12871 <para role="glossdeffirst">
12872<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12873 Specifies a list of architectures compatible with
12874 the SDK machine.
12875 This variable is set automatically and should not
12876 normally be hand-edited.
12877 Entries are separated using spaces and listed in order
12878 of priority.
12879 The default value for
12880 <filename>SDK_PACKAGE_ARCHS</filename> is "all any noarch
12881 ${SDK_ARCH}-${SDKPKGSUFFIX}".
12882 </para>
12883 </glossdef>
12884 </glossentry>
12885
12886 <glossentry id='var-SDK_POSTPROCESS_COMMAND'><glossterm>SDK_POSTPROCESS_COMMAND</glossterm>
12887 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012888 SDK_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system creates the SDK."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012889 </info>
12890 <glossdef>
12891 <para role="glossdeffirst">
12892<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12893 Specifies a list of functions to call once the
Brad Bishop316dfdd2018-06-25 12:45:53 -040012894 OpenEmbedded build system creates the SDK.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012895 You can specify functions separated by semicolons:
12896 <literallayout class='monospaced'>
12897 SDK_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
12898 </literallayout>
12899 </para>
12900
12901 <para>
12902 If you need to pass an SDK path to a command within a
12903 function, you can use
12904 <filename>${SDK_DIR}</filename>, which points to
12905 the parent directory used by the OpenEmbedded build system
12906 when creating SDK output.
12907 See the
12908 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
12909 variable for more information.
12910 </para>
12911 </glossdef>
12912 </glossentry>
12913
12914 <glossentry id='var-SDK_PREFIX'><glossterm>SDK_PREFIX</glossterm>
12915 <info>
12916 SDK_PREFIX[doc] = "The toolchain binary prefix used for nativesdk recipes."
12917 </info>
12918 <glossdef>
12919 <para role="glossdeffirst">
12920<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012921 The toolchain binary prefix used for
12922 <filename>nativesdk</filename> recipes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012923 The OpenEmbedded build system uses the
12924 <filename>SDK_PREFIX</filename> value to set the
12925 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
12926 when building <filename>nativesdk</filename> recipes.
12927 The default value is "${SDK_SYS}-".
12928 </para>
12929 </glossdef>
12930 </glossentry>
12931
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012932 <glossentry id='var-SDK_RECRDEP_TASKS'><glossterm>SDK_RECRDEP_TASKS</glossterm>
12933 <info>
12934 SDK_RECRDEP_TASKS[doc] = "A list of shared state tasks added to the extensible SDK."
12935 </info>
12936 <glossdef>
12937 <para role="glossdeffirst">
12938<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12939 A list of shared state tasks added to the extensible SDK.
12940 By default, the following tasks are added:
12941 <literallayout class='monospaced'>
12942 do_populate_lic
12943 do_package_qa
12944 do_populate_sysroot
12945 do_deploy
12946 </literallayout>
12947 Despite the default value of "" for the
12948 <filename>SDK_RECRDEP_TASKS</filename> variable, the
12949 above four tasks are always added to the SDK.
12950 To specify tasks beyond these four, you need to use
12951 the <filename>SDK_RECRDEP_TASKS</filename> variable (e.g.
12952 you are defining additional tasks that are needed in
12953 order to build
12954 <link linkend='var-SDK_TARGETS'><filename>SDK_TARGETS</filename></link>).
12955 </para>
12956 </glossdef>
12957 </glossentry>
12958
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012959 <glossentry id='var-SDK_SYS'><glossterm>SDK_SYS</glossterm>
12960 <info>
12961 SDK_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the SDK will be built."
12962 </info>
12963 <glossdef>
12964 <para role="glossdeffirst">
12965<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12966 Specifies the system, including the architecture and the
12967 operating system, for which the SDK will be built.
12968 </para>
12969
12970 <para>
12971 The OpenEmbedded build system automatically sets this
12972 variable based on
12973 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
12974 <link linkend='var-SDK_VENDOR'><filename>SDK_VENDOR</filename></link>,
12975 and
12976 <link linkend='var-SDK_OS'><filename>SDK_OS</filename></link>.
12977 You do not need to set the <filename>SDK_SYS</filename>
12978 variable yourself.
12979 </para>
12980 </glossdef>
12981 </glossentry>
12982
12983 <glossentry id='var-SDK_TARGET_MANIFEST'><glossterm>SDK_TARGET_MANIFEST</glossterm>
12984 <info>
12985 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."
12986 </info>
12987 <glossdef>
12988 <para role="glossdeffirst">
12989<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12990 The manifest file for the target part of the SDK.
12991 This file lists all the installed packages that make up
12992 the target part of the SDK.
12993 The file contains package information on a line-per-package
12994 basis as follows:
12995 <literallayout class='monospaced'>
12996 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
12997 </literallayout>
12998 </para>
12999
13000 <para>
13001 The
13002 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
13003 class defines the manifest file as follows:
13004 <literallayout class='monospaced'>
13005 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"
13006 </literallayout>
13007 The location is derived using the
13008 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>
13009 and
13010 <link linkend='var-TOOLCHAIN_OUTPUTNAME'><filename>TOOLCHAIN_OUTPUTNAME</filename></link>
13011 variables.
13012 </para>
13013 </glossdef>
13014 </glossentry>
13015
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013016 <glossentry id='var-SDK_TARGETS'><glossterm>SDK_TARGETS</glossterm>
13017 <info>
13018 SDK_TARGETS[doc] = "A list of targets to install from shared state as part of the standard or extensible SDK installation."
13019 </info>
13020 <glossdef>
13021 <para role="glossdeffirst">
13022<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13023 A list of targets to install from shared state as part of
13024 the standard or extensible SDK installation.
13025 The default value is "${PN}" (i.e. the image from which
13026 the SDK is built).
13027 </para>
13028
13029 <para>
13030 The <filename>SDK_TARGETS</filename> variable is an
13031 internal variable and typically would not be changed.
13032 </para>
13033 </glossdef>
13034 </glossentry>
13035
13036 <glossentry id='var-SDK_TITLE'><glossterm>SDK_TITLE</glossterm>
13037 <info>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080013038 SDK_TITLE[doc] = "The title to be printed when running the SDK installer."
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013039 </info>
13040 <glossdef>
13041 <para role="glossdeffirst">
13042<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080013043 The title to be printed when running the SDK installer.
13044 By default, this title is based on the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013045 <link linkend='var-DISTRO_NAME'><filename>DISTRO_NAME</filename></link>
13046 or
13047 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080013048 variable and is set in the
13049 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
13050 class as follows:
13051 <literallayout class='monospaced'>
13052 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
13053 </literallayout>
13054 For the default distribution "poky",
13055 <filename>SDK_TITLE</filename> is set to
13056 "Poky (Yocto Project Reference Distro)".
13057 </para>
13058
13059 <para>
13060 For information on how to change this default title,
13061 see the
13062 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-changing-the-sdk-installer-title'>Changing the Extensible SDK Installer Title</ulink>"
13063 section in the Yocto Project Application Development and
13064 the Extensible Software Development Kit (eSDK) manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013065 </para>
13066 </glossdef>
13067 </glossentry>
13068
13069 <glossentry id='var-SDK_UPDATE_URL'><glossterm>SDK_UPDATE_URL</glossterm>
13070 <info>
13071 SDK_UPDATE_URL[doc] = "An optional URL for an update server for the extensible SDK."
13072 </info>
13073 <glossdef>
13074 <para role="glossdeffirst">
13075<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13076 An optional URL for an update server for the extensible
13077 SDK.
13078 If set, the value is used as the default update server when
13079 running <filename>devtool sdk-update</filename> within the
13080 extensible SDK.
13081 </para>
13082 </glossdef>
13083 </glossentry>
13084
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013085 <glossentry id='var-SDK_VENDOR'><glossterm>SDK_VENDOR</glossterm>
13086 <info>
13087 SDK_VENDOR[doc] = "Specifies the name of the SDK vendor."
13088 </info>
13089 <glossdef>
13090 <para role="glossdeffirst">
13091<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13092 Specifies the name of the SDK vendor.
13093 </para>
13094 </glossdef>
13095 </glossentry>
13096
13097 <glossentry id='var-SDK_VERSION'><glossterm>SDK_VERSION</glossterm>
13098 <info>
13099 SDK_VERSION[doc] = "Specifies the version for the SDK."
13100 </info>
13101 <glossdef>
13102 <para role="glossdeffirst">
13103<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13104 Specifies the version of the SDK.
13105 The distribution configuration file (e.g.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013106 <filename>/meta-poky/conf/distro/poky.conf</filename>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013107 defines the <filename>SDK_VERSION</filename> as follows:
13108 <literallayout class='monospaced'>
Brad Bishop19323692019-04-05 15:28:33 -040013109 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013110 </literallayout>
13111 </para>
13112
13113 <para>
13114 For additional information, see the
13115 <link linkend='var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></link>
13116 and
13117 <link linkend='var-DATE'><filename>DATE</filename></link>
13118 variables.
13119 </para>
13120 </glossdef>
13121 </glossentry>
13122
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080013123 <glossentry id='var-SDKEXTPATH'><glossterm>SDKEXTPATH</glossterm>
13124 <info>
13125 SDKEXTPATH[doc] = "The default installation directory for the extensible SDK."
13126 </info>
13127 <glossdef>
13128 <para role="glossdeffirst">
13129<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13130 The default installation directory for the Extensible SDK.
13131 By default, this directory is based on the
13132 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
13133 variable and is set in the
13134 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
13135 class as follows:
13136 <literallayout class='monospaced'>
13137 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
13138 </literallayout>
13139 For the default distribution "poky", the
13140 <filename>SDKEXTPATH</filename> is set to "poky_sdk".
13141 </para>
13142
13143 <para>
13144 For information on how to change this default directory,
13145 see the
13146 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-changing-the-default-sdk-installation-directory'>Changing the Default SDK Installation Directory</ulink>"
13147 section in the Yocto Project Application Development and
13148 the Extensible Software Development Kit (eSDK) manual.
13149 </para>
13150 </glossdef>
13151 </glossentry>
13152
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013153 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
13154 <info>
13155 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'."
13156 </info>
13157 <glossdef>
13158 <para role="glossdeffirst">
13159<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13160 Equivalent to
13161 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
13162 However, this variable applies to the SDK generated from an
13163 image using the following command:
13164 <literallayout class='monospaced'>
13165 $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
13166 </literallayout>
13167 </para>
13168 </glossdef>
13169 </glossentry>
13170
13171 <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
13172 <info>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013173 SDKMACHINE[doc] = "Specifies the architecture (i.e. i686 or x86_64) for which to build SDK items."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013174 </info>
13175 <glossdef>
13176 <para role="glossdeffirst">
13177<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013178 The machine for which the SDK is built.
13179 In other words, the SDK is built such that it
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013180 runs on the target you specify with the
13181 <filename>SDKMACHINE</filename> value.
13182 The value points to a corresponding
13183 <filename>.conf</filename> file under
13184 <filename>conf/machine-sdk/</filename>.
13185 </para>
13186
13187 <para>
13188 You can use "i686" and "x86_64" as possible values
13189 for this variable. The variable defaults to "i686"
13190 and is set in the local.conf file in the Build Directory.
13191 <literallayout class='monospaced'>
13192 SDKMACHINE ?= "i686"
13193 </literallayout>
13194 <note>
13195 You cannot set the <filename>SDKMACHINE</filename>
13196 variable in your distribution configuration file.
13197 If you do, the configuration will not take affect.
13198 </note>
13199 </para>
13200 </glossdef>
13201 </glossentry>
13202
13203 <glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>
13204 <info>
13205 SDKPATH[doc] = "Defines the path offered to the user for installation of the SDK that is generated by the OpenEmbedded build system."
13206 </info>
13207 <glossdef>
13208 <para role="glossdeffirst">
13209<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13210 Defines the path offered to the user for installation
13211 of the SDK that is generated by the OpenEmbedded build
13212 system.
13213 The path appears as the default location for installing
13214 the SDK when you run the SDK's installation script.
13215 You can override the offered path when you run the
13216 script.
13217 </para>
13218 </glossdef>
13219 </glossentry>
13220
13221 <glossentry id='var-SDKTARGETSYSROOT'><glossterm>SDKTARGETSYSROOT</glossterm>
13222 <info>
13223 SDKTARGETSYSROOT[doc] = "Full path to the sysroot used for cross-compilation within an SDK as it will be when installed into the default SDKPATH."
13224 </info>
13225 <glossdef>
13226 <para role="glossdeffirst">
13227<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13228 The full path to the sysroot used for cross-compilation
13229 within an SDK as it will be when installed into the
13230 default
13231 <link linkend='var-SDKPATH'><filename>SDKPATH</filename></link>.
13232 </para>
13233 </glossdef>
13234 </glossentry>
13235
13236 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
13237 <info>
13238 SECTION[doc] = "The section in which packages should be categorized. Package management utilities can make use of this variable."
13239 </info>
13240 <glossdef>
13241 <para role="glossdeffirst">
13242<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13243 The section in which packages should be categorized.
13244 Package management utilities can make use of this variable.
13245 </para>
13246 </glossdef>
13247 </glossentry>
13248
13249 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
13250 <info>
13251 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."
13252 </info>
13253 <glossdef>
13254 <para role="glossdeffirst">
13255<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13256 Specifies the optimization flags passed to the C compiler
13257 when building for the target.
13258 The flags are passed through the default value of the
13259 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
13260 variable.
13261 </para>
13262
13263 <para>
13264 The <filename>SELECTED_OPTIMIZATION</filename> variable
13265 takes the value of
13266 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
13267 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
13268 If that is the case, the value of
13269 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
13270 </para>
13271 </glossdef>
13272 </glossentry>
13273
13274 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
13275 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013276 SERIAL_CONSOLE[doc] = "Defines the serial consoles (TTYs) to enable using getty."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013277 </info>
13278 <glossdef>
13279 <para role="glossdeffirst">
13280<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040013281 Defines a serial console (TTY) to enable using
13282 <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013283 Provide a value that specifies the baud rate followed by
13284 the TTY device name separated by a space.
13285 You cannot specify more than one TTY device:
13286 <literallayout class='monospaced'>
13287 SERIAL_CONSOLE = "115200 ttyS0"
13288 </literallayout>
13289 <note>
13290 The <filename>SERIAL_CONSOLE</filename> variable
13291 is deprecated.
13292 Please use the
13293 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
13294 variable.
13295 </note>
13296 </para>
13297 </glossdef>
13298 </glossentry>
13299
13300 <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
13301 <info>
13302 SERIAL_CONSOLES[doc] = "Defines the serial consoles (TTYs) to enable using getty."
13303 </info>
13304 <glossdef>
13305 <para role="glossdeffirst">
13306<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040013307 Defines a serial console (TTY) to enable using
13308 <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013309 Provide a value that specifies the baud rate followed by
13310 the TTY device name separated by a semicolon.
13311 Use spaces to separate multiple devices:
13312 <literallayout class='monospaced'>
13313 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
13314 </literallayout>
13315 </para>
13316 </glossdef>
13317 </glossentry>
13318
13319 <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
13320 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060013321 SERIAL_CONSOLES_CHECK[doc] = "Selected SERIAL_CONSOLES to check against /proc/console before enabling using getty. Supported only by SysVinit."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013322 </info>
13323 <glossdef>
13324 <para role="glossdeffirst">
13325<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060013326 Specifies serial consoles, which must be listed in
13327 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>,
13328 to check against <filename>/proc/console</filename>
13329 before enabling them using getty.
13330 This variable allows aliasing in the format:
13331 &lt;device&gt;:&lt;alias&gt;.
13332 If a device was listed as "sclp_line0"
13333 in <filename>/dev/</filename> and "ttyS0" was listed
13334 in <filename>/proc/console</filename>, you would do the
13335 following:
13336 <literallayout class='monospaced'>
13337 SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0"
13338 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013339 This variable is currently only supported with SysVinit
13340 (i.e. not with systemd).
13341 </para>
13342 </glossdef>
13343 </glossentry>
13344
13345 <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
13346 <info>
13347 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."
13348 </info>
13349 <glossdef>
13350 <para role="glossdeffirst">
13351<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13352 A list of recipe dependencies that should not be used to
13353 determine signatures of tasks from one recipe when they
13354 depend on tasks from another recipe.
13355 For example:
13356 <literallayout class='monospaced'>
13357 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
13358 </literallayout>
13359 </para>
13360
13361 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013362 In the previous example, <filename>intone</filename>
13363 depends on <filename>mplayer2</filename>.
13364 </para>
13365
13366 <para>
13367 You can use the special token <filename>"*"</filename> on
13368 the left-hand side of the dependency to match all
13369 recipes except the one on the right-hand side.
13370 Here is an example:
13371 <literallayout class='monospaced'>
13372 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
13373 </literallayout>
13374 </para>
13375
13376 <para>
13377 In the previous example, all recipes except
13378 <filename>quilt-native</filename> ignore task
13379 signatures from the <filename>quilt-native</filename>
13380 recipe when determining their task signatures.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013381 </para>
13382
13383 <para>
13384 Use of this variable is one mechanism to remove dependencies
13385 that affect task signatures and thus force rebuilds when a
13386 recipe changes.
13387 <note><title>Caution</title>
13388 If you add an inappropriate dependency for a recipe
13389 relationship, the software might break during
13390 runtime if the interface of the second recipe was
13391 changed after the first recipe had been built.
13392 </note>
13393 </para>
13394 </glossdef>
13395 </glossentry>
13396
13397 <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
13398 <info>
13399 SIGGEN_EXCLUDERECIPES_ABISAFE[doc] = "A list of recipes that are completely stable and will never change."
13400 </info>
13401 <glossdef>
13402 <para role="glossdeffirst">
13403<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13404 A list of recipes that are completely stable and will
13405 never change.
13406 The ABI for the recipes in the list are presented by
13407 output from the tasks run to build the recipe.
13408 Use of this variable is one way to remove dependencies from
13409 one recipe on another that affect task signatures and
13410 thus force rebuilds when the recipe changes.
13411 <note><title>Caution</title>
13412 If you add an inappropriate variable to this list,
13413 the software might break at runtime if the
13414 interface of the recipe was changed after the other
13415 had been built.
13416 </note>
13417 </para>
13418 </glossdef>
13419 </glossentry>
13420
13421 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
13422 <info>
13423 SITEINFO_BITS[doc] = "Specifies the number of bits for the target system CPU."
13424 </info>
13425 <glossdef>
13426 <para role="glossdeffirst">
13427<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13428 Specifies the number of bits for the target system CPU.
13429 The value should be either "32" or "64".
13430 </para>
13431 </glossdef>
13432 </glossentry>
13433
13434 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
13435 <info>
13436 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'."
13437 </info>
13438 <glossdef>
13439 <para role="glossdeffirst">
13440<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13441 Specifies the endian byte order of the target system.
13442 The value should be either "le" for little-endian or "be" for big-endian.
13443 </para>
13444 </glossdef>
13445 </glossentry>
13446
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013447 <glossentry id='var-SKIP_FILEDEPS'><glossterm>SKIP_FILEDEPS</glossterm>
13448 <info>
Andrew Geissler82c905d2020-04-13 13:39:40 -050013449 SKIP_FILEDEPS[doc] = "Enables you to remove all files from the 'Provides' section of an RPM package."
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013450 </info>
13451 <glossdef>
13452 <para role="glossdeffirst">
13453<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13454 Enables removal of all files from the "Provides" section of
13455 an RPM package.
13456 Removal of these files is required for packages containing
13457 prebuilt binaries and libraries such as
13458 <filename>libstdc++</filename> and
13459 <filename>glibc</filename>.
13460 </para>
13461
13462 <para>
13463 To enable file removal, set the variable to "1" in your
13464 <filename>conf/local.conf</filename> configuration file
13465 in your:
Brad Bishopd7bf8c12018-02-25 22:55:05 -050013466 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013467 <literallayout class='monospaced'>
13468 SKIP_FILEDEPS = "1"
13469 </literallayout>
13470 </para>
13471 </glossdef>
13472 </glossentry>
13473
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013474 <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
13475 <info>
13476 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."
13477 </info>
13478 <glossdef>
13479 <para role="glossdeffirst">
13480<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13481 Groups together machines based upon the same family
13482 of SOC (System On Chip).
13483 You typically set this variable in a common
13484 <filename>.inc</filename> file that you include in the
13485 configuration files of all the machines.
13486 <note>
13487 You must include
13488 <filename>conf/machine/include/soc-family.inc</filename>
13489 for this variable to appear in
13490 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
13491 </note>
13492 </para>
13493 </glossdef>
13494 </glossentry>
13495
13496 <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
13497 <info>
13498 SOLIBS[doc] = "Defines the suffix for shared libraries used on the target platform."
13499 </info>
13500 <glossdef>
13501 <para role="glossdeffirst">
13502<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13503 Defines the suffix for shared libraries used on the
13504 target platform.
13505 By default, this suffix is ".so.*" for all Linux-based
13506 systems and is defined in the
13507 <filename>meta/conf/bitbake.conf</filename> configuration
13508 file.
13509 </para>
13510
13511 <para>
13512 You will see this variable referenced in the default values
13513 of <filename>FILES_${PN}</filename>.
13514 </para>
13515 </glossdef>
13516 </glossentry>
13517
13518 <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
13519 <info>
13520 SOLIBSDEV[doc] = "Defines the suffix for the development symbolic link (symlink) for shared libraries on the target platform."
13521 </info>
13522 <glossdef>
13523 <para role="glossdeffirst">
13524<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13525 Defines the suffix for the development symbolic link
13526 (symlink) for shared libraries on the target platform.
13527 By default, this suffix is ".so" for Linux-based
13528 systems and is defined in the
13529 <filename>meta/conf/bitbake.conf</filename> configuration
13530 file.
13531 </para>
13532
13533 <para>
13534 You will see this variable referenced in the default values
13535 of <filename>FILES_${PN}-dev</filename>.
13536 </para>
13537 </glossdef>
13538 </glossentry>
13539
13540 <glossentry id='var-SOURCE_MIRROR_FETCH'><glossterm>SOURCE_MIRROR_FETCH</glossterm>
13541 <info>
13542 SOURCE_MIRROR_FETCH[doc] = "Set as part of a source mirror generation script to skip COMPATIBLE_MACHINE and COMPATIBLE_HOST checks."
13543 </info>
13544 <glossdef>
13545 <para role="glossdeffirst">
13546<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13547 When you are fetching files to create a mirror of sources
13548 (i.e. creating a source mirror), setting
13549 <filename>SOURCE_MIRROR_FETCH</filename> to "1" in your
13550 <filename>local.conf</filename> configuration file ensures
13551 the source for all recipes are fetched regardless of
13552 whether or not a recipe is compatible with the
13553 configuration.
13554 A recipe is considered incompatible with the currently
13555 configured machine when either or both the
13556 <link linkend='var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></link>
13557 variable and
13558 <link linkend='var-COMPATIBLE_HOST'><filename>COMPATIBLE_HOST</filename></link>
13559 variables specify compatibility with a machine other
13560 than that of the current machine or host.
13561 <note><title>Warning</title>
13562 Do not set the
13563 <filename>SOURCE_MIRROR_FETCH</filename> variable
13564 unless you are creating a source mirror.
13565 In other words, do not set the variable during a
13566 normal build.
13567 </note>
13568 </para>
13569 </glossdef>
13570 </glossentry>
13571
13572 <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm>
13573 <info>
13574 SOURCE_MIRROR_URL[doc] = "URL to source mirror that will be used before fetching from original SRC_URI."
13575 </info>
13576 <glossdef>
13577 <para role="glossdeffirst">
13578<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13579 Defines your own
13580 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
13581 from which to first fetch source before attempting to fetch
13582 from the upstream specified in
13583 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
13584 </para>
13585
13586 <para>
13587 To use this variable, you must globally inherit the
13588 <link linkend='ref-classes-own-mirrors'><filename>own-mirrors</filename></link>
13589 class and then provide the URL to your mirrors.
13590 Here is the general syntax:
13591 <literallayout class='monospaced'>
13592 INHERIT += "own-mirrors"
13593 SOURCE_MIRROR_URL = "http://<replaceable>example</replaceable>.com/<replaceable>my_source_mirror</replaceable>"
13594 </literallayout>
13595 <note>
13596 You can specify only a single URL in
13597 <filename>SOURCE_MIRROR_URL</filename>.
13598 </note>
13599 </para>
13600 </glossdef>
13601 </glossentry>
13602
13603 <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>
13604 <info>
13605 SPDXLICENSEMAP[doc] = "Maps commonly used license names to their SPDX counterparts found in meta/files/common-licenses/."
13606 </info>
13607 <glossdef>
13608 <para role="glossdeffirst">
13609<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13610 Maps commonly used license names to their SPDX counterparts
13611 found in <filename>meta/files/common-licenses/</filename>.
13612 For the default <filename>SPDXLICENSEMAP</filename>
13613 mappings, see the
13614 <filename>meta/conf/licenses.conf</filename> file.
13615 </para>
13616
13617 <para>
13618 For additional information, see the
13619 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
13620 variable.
13621 </para>
13622 </glossdef>
13623 </glossentry>
13624
13625 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
13626 <info>
13627 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."
13628 </info>
13629 <glossdef>
13630 <para role="glossdeffirst">
13631<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13632 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
13633 OpenEmbedded build system to create variants of recipes or packages.
13634 The list specifies the prefixes to strip off during certain circumstances
13635 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
13636 </para>
13637 </glossdef>
13638 </glossentry>
13639
Brad Bishop316dfdd2018-06-25 12:45:53 -040013640 <glossentry id='var-SPL_BINARY'><glossterm>SPL_BINARY</glossterm>
13641 <info>
13642 SPL_BINARY[doc] = "The file type of the Secondary Program Loader (SPL)."
13643 </info>
13644 <glossdef>
13645 <para role="glossdeffirst">
13646<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13647 The file type for the Secondary Program Loader (SPL).
13648 Some devices use an SPL from which to boot (e.g. the
13649 BeagleBone development board).
13650 For such cases, you can declare the file type of the
13651 SPL binary in the <filename>u-boot.inc</filename> include
13652 file, which is used in the U-Boot recipe.
13653 </para>
13654
13655 <para>
13656 The SPL file type is set to "null" by default in the
13657 <filename>u-boot.inc</filename> file as follows:
13658 <literallayout class='monospaced'>
13659 # Some versions of u-boot build an SPL (Second Program Loader) image that
13660 # should be packaged along with the u-boot binary as well as placed in the
13661 # deploy directory. For those versions they can set the following variables
13662 # to allow packaging the SPL.
13663 SPL_BINARY ?= ""
13664 SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"
13665 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
13666 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"
13667 </literallayout>
13668 The <filename>SPL_BINARY</filename> variable helps form
13669 various <filename>SPL_*</filename> variables used by
13670 the OpenEmbedded build system.
13671 </para>
13672
13673 <para>
13674 See the BeagleBone machine configuration example in the
13675 "<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>"
13676 section in the Yocto Project Board Support Package
13677 Developer's Guide for additional information.
13678 </para>
13679 </glossdef>
13680 </glossentry>
13681
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013682 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
13683 <info>
13684 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."
13685 </info>
13686 <glossdef>
13687 <para role="glossdeffirst">
13688<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13689 The list of source files - local or remote.
13690 This variable tells the OpenEmbedded build system which bits
13691 to pull in for the build and how to pull them in.
13692 For example, if the recipe or append file only needs to
13693 fetch a tarball from the Internet, the recipe or
13694 append file uses a single <filename>SRC_URI</filename>
13695 entry.
13696 On the other hand, if the recipe or append file needs to
13697 fetch a tarball, apply two patches, and include a custom
13698 file, the recipe or append file would include four
13699 instances of the variable.
13700 </para>
13701
13702 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013703 The following list explains the available URI protocols.
13704 URI protocols are highly dependent on particular BitBake
13705 Fetcher submodules.
13706 Depending on the fetcher BitBake uses, various URL
13707 parameters are employed.
13708 For specifics on the supported Fetchers, see the
13709 "<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"
13710 section in the BitBake User Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013711 <itemizedlist>
13712 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
13713 Fetches files, which are usually files shipped with
13714 the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050013715 <link linkend='metadata'>Metadata</link>,
Brad Bishop316dfdd2018-06-25 12:45:53 -040013716 from the local machine (e.g.
13717 <ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>patch</ulink>
13718 files).
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013719 The path is relative to the
13720 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
13721 variable.
13722 Thus, the build system searches, in order, from the
13723 following directories, which are assumed to be a
13724 subdirectories of the directory in which the
13725 recipe file (<filename>.bb</filename>) or
13726 append file (<filename>.bbappend</filename>)
13727 resides:
13728 <itemizedlist>
13729 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
13730 The base recipe name without any special
13731 suffix or version numbers.
13732 </para></listitem>
13733 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
13734 <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
13735 The base recipe name and version but without
13736 any special package name suffix.
13737 </para></listitem>
13738 <listitem><para><emphasis>files -</emphasis>
13739 Files within a directory, which is named
13740 <filename>files</filename> and is also
13741 alongside the recipe or append file.
13742 </para></listitem>
13743 </itemizedlist>
13744 <note>
13745 If you want the build system to pick up files
13746 specified through a
13747 <filename>SRC_URI</filename>
13748 statement from your append file, you need to be
13749 sure to extend the
13750 <filename>FILESPATH</filename>
13751 variable by also using the
13752 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
13753 variable from within your append file.
13754 </note>
13755 </para></listitem>
13756 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
13757 Bazaar revision control repository.</para></listitem>
13758 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
13759 Git revision control repository.</para></listitem>
13760 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
13761 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
13762 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
13763 a repo (Git) repository.</para></listitem>
13764 <listitem><para><emphasis><filename>ccrc://</filename> -</emphasis>
13765 Fetches files from a ClearCase repository.
13766 </para></listitem>
13767 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
13768 the Internet using <filename>http</filename>.</para></listitem>
13769 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
13770 from the Internet using <filename>https</filename>.</para></listitem>
13771 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
13772 from the Internet using <filename>ftp</filename>.</para></listitem>
13773 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
13774 a CVS revision control repository.</para></listitem>
13775 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
13776 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
13777 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
13778 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
13779 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
13780 a secure shell.</para></listitem>
13781 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
13782 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
Brad Bishopc342db32019-05-15 21:57:59 -040013783 <listitem><para><emphasis><filename>npm://</filename> -</emphasis> Fetches JavaScript
13784 modules from a registry.
13785 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013786 </itemizedlist>
13787 </para>
13788
13789 <para>
13790 Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
13791 Here are standard options:
13792 <itemizedlist>
13793 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
13794 the patch or not.
13795 The default action is to apply the patch.</para></listitem>
13796 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
13797 striplevel to use when applying the patch.
13798 The default level is 1.</para></listitem>
13799 <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
13800 the directory in which the patch should be applied.
13801 The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
13802 </para></listitem>
13803 </itemizedlist>
13804 </para>
13805
13806 <para>
13807 Here are options specific to recipes building code from a revision control system:
13808 <itemizedlist>
13809 <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
13810 Apply the patch only if
13811 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
13812 is equal to or greater than <filename>mindate</filename>.
13813 </para></listitem>
13814 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
13815 Apply the patch only if <filename>SRCDATE</filename>
Andrew Geissler5fa08482019-03-20 15:58:14 -050013816 is not later than <filename>maxdate</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013817 </para></listitem>
13818 <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
13819 Apply the patch only if <filename>SRCREV</filename>
13820 is equal to or greater than <filename>minrev</filename>.
13821 </para></listitem>
13822 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
13823 Apply the patch only if <filename>SRCREV</filename>
13824 is not later than <filename>maxrev</filename>.
13825 </para></listitem>
13826 <listitem><para><emphasis><filename>rev</filename> -</emphasis>
13827 Apply the patch only if <filename>SRCREV</filename>
13828 is equal to <filename>rev</filename>.
13829 </para></listitem>
13830 <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
13831 Apply the patch only if <filename>SRCREV</filename>
13832 is not equal to <filename>rev</filename>.
13833 </para></listitem>
13834 </itemizedlist>
13835 </para>
13836
13837 <para>
13838 Here are some additional options worth mentioning:
13839 <itemizedlist>
13840 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
13841 whether or not to unpack the file if it is an archive.
13842 The default action is to unpack the file.</para></listitem>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013843 <listitem><para><emphasis><filename>destsuffix</filename> -</emphasis> Places the file
13844 (or extracts its contents) into the specified
13845 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
13846 when the Git fetcher is used.
13847 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013848 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
13849 (or extracts its contents) into the specified
Brad Bishop316dfdd2018-06-25 12:45:53 -040013850 subdirectory of <filename>WORKDIR</filename>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013851 when the local (<filename>file://</filename>)
13852 fetcher is used.
13853 </para></listitem>
13854 <listitem><para><emphasis><filename>localdir</filename> -</emphasis> Places the file
13855 (or extracts its contents) into the specified
Brad Bishop316dfdd2018-06-25 12:45:53 -040013856 subdirectory of <filename>WORKDIR</filename> when
13857 the CVS fetcher is used.
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013858 </para></listitem>
13859 <listitem><para><emphasis><filename>subpath</filename> -</emphasis>
13860 Limits the checkout to a specific subpath of the
13861 tree when using the Git fetcher is used.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013862 </para></listitem>
13863 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
13864 name to be used for association with <filename>SRC_URI</filename> checksums
13865 when you have more than one file specified in <filename>SRC_URI</filename>.
13866 </para></listitem>
13867 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
13868 the filename used when storing the downloaded file.</para></listitem>
13869 </itemizedlist>
13870 </para>
13871 </glossdef>
13872 </glossentry>
13873
13874 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
13875 <info>
13876 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."
13877 </info>
13878 <glossdef>
13879 <para role="glossdeffirst">
13880<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13881 By default, the OpenEmbedded build system automatically detects whether
13882 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
13883 contains files that are machine-specific.
13884 If so, the build system automatically changes
13885 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
13886 Setting this variable to "0" disables this behavior.
13887 </para>
13888 </glossdef>
13889 </glossentry>
13890
13891 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
13892 <info>
13893 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)."
13894 </info>
13895 <glossdef>
13896 <para role="glossdeffirst">
13897<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13898 The date of the source code used to build the package.
13899 This variable applies only if the source was fetched from a Source Code Manager (SCM).
13900 </para>
13901 </glossdef>
13902 </glossentry>
13903
13904 <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
13905 <info>
13906 SRCPV[doc] = "Returns the version string of the current package. This string is used to help define the value of PV."
13907 </info>
13908 <glossdef>
13909 <para role="glossdeffirst">
13910<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13911 Returns the version string of the current package.
13912 This string is used to help define the value of
13913 <link linkend='var-PV'><filename>PV</filename></link>.
13914 </para>
13915
13916 <para>
13917 The <filename>SRCPV</filename> variable is defined in the
13918 <filename>meta/conf/bitbake.conf</filename> configuration
13919 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050013920 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013921 as follows:
13922 <literallayout class='monospaced'>
13923 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
13924 </literallayout>
13925 </para>
13926
13927 <para>
13928 Recipes that need to define <filename>PV</filename> do so
13929 with the help of the <filename>SRCPV</filename>.
13930 For example, the <filename>ofono</filename> recipe
13931 (<filename>ofono_git.bb</filename>) located in
13932 <filename>meta/recipes-connectivity</filename> in the
13933 Source Directory defines <filename>PV</filename> as
13934 follows:
13935 <literallayout class='monospaced'>
13936 PV = "0.12-git${SRCPV}"
13937 </literallayout>
13938 </para>
13939 </glossdef>
13940 </glossentry>
13941
13942 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
13943 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013944 SRCREV[doc] = "The revision of the source code used to build the package. This variable applies to Subversion, Git, Mercurial, and Bazaar only."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013945 </info>
13946 <glossdef>
13947 <para role="glossdeffirst">
13948<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13949 The revision of the source code used to build the package.
Brad Bishop316dfdd2018-06-25 12:45:53 -040013950 This variable applies to Subversion, Git, Mercurial, and
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013951 Bazaar only.
13952 Note that if you want to build a fixed revision and you
13953 want to avoid performing a query on the remote repository
13954 every time BitBake parses your recipe, you should specify
13955 a <filename>SRCREV</filename> that is a
13956 full revision identifier and not just a tag.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050013957 <note>
13958 For information on limitations when inheriting the
13959 latest revision of software using
13960 <filename>SRCREV</filename>, see the
13961 <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link>
13962 variable description and the
13963 "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050013964 section, which is in the Yocto Project Development
13965 Tasks Manual.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050013966 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013967 </para>
13968
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013969 </glossdef>
13970 </glossentry>
13971
13972 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
13973 <info>
13974 SSTATE_DIR[doc] = "The directory for the shared state cache."
13975 </info>
13976 <glossdef>
13977 <para role="glossdeffirst">
13978<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13979 The directory for the shared state cache.
13980 </para>
13981 </glossdef>
13982 </glossentry>
13983
13984 <glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm>
13985 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013986 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"."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013987 </info>
13988 <glossdef>
13989 <para role="glossdeffirst">
13990<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13991 If set to "1", allows fetches from
13992 mirrors that are specified in
13993 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013994 to work even when fetching from the network is
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013995 disabled by setting <filename>BB_NO_NETWORK</filename>
13996 to "1".
13997 Using the
13998 <filename>SSTATE_MIRROR_ALLOW_NETWORK</filename>
13999 variable is useful if you have set
14000 <filename>SSTATE_MIRRORS</filename> to point to an
14001 internal server for your shared state cache, but
14002 you want to disable any other fetching from the network.
14003 </para>
14004 </glossdef>
14005 </glossentry>
14006
14007 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
14008 <info>
14009 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."
14010 </info>
14011 <glossdef>
14012 <para role="glossdeffirst">
14013<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14014 Configures the OpenEmbedded build system to search other
14015 mirror locations for prebuilt cache data objects before
14016 building out the data.
14017 This variable works like fetcher
14018 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
14019 and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
14020 and points to the cache locations to check for the shared
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080014021 state (sstate) objects.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014022 </para>
14023
14024 <para>
14025 You can specify a filesystem directory or a remote URL such
14026 as HTTP or FTP.
14027 The locations you specify need to contain the shared state
14028 cache (sstate-cache) results from previous builds.
14029 The sstate-cache you point to can also be from builds on
14030 other machines.
14031 </para>
14032
14033 <para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080014034 When pointing to sstate build artifacts on another machine
14035 that uses a different GCC version for native builds,
14036 you must configure <filename>SSTATE_MIRROR</filename>
14037 with a regular expression that maps local search paths
14038 to server paths.
14039 The paths need to take into account
14040 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
14041 set by the
14042 <link linkend='ref-classes-uninative'><filename>uninative</filename></link>
14043 class.
14044 For example, the following maps the local search path
14045 <filename>universal-4.9</filename> to the server-provided
14046 path <replaceable>server_url_sstate_path</replaceable>:
14047 <literallayout class='monospaced'>
14048 SSTATE_MIRRORS ?= file://universal-4.9/(.*) http://<replaceable>server_url_sstate_path</replaceable>/universal-4.8/\1 \n
14049 </literallayout>
14050 </para>
14051
14052 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014053 If a mirror uses the same structure as
14054 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
14055 you need to add
14056 "PATH" at the end as shown in the examples below.
14057 The build system substitutes the correct path within the
14058 directory structure.
14059 <literallayout class='monospaced'>
14060 SSTATE_MIRRORS ?= "\
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014061 file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH;downloadfilename=PATH \n \
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014062 file://.* file:///<replaceable>some-local-dir</replaceable>/sstate/PATH"
14063 </literallayout>
14064 </para>
14065 </glossdef>
14066 </glossentry>
14067
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014068 <glossentry id='var-SSTATE_SCAN_FILES'><glossterm>SSTATE_SCAN_FILES</glossterm>
14069 <info>
14070 SSTATE_SCAN_FILES[doc] = "Controls the list of files the OpenEmbedded build system scans for hardcoded installation paths."
14071 </info>
14072 <glossdef>
14073 <para role="glossdeffirst">
14074<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14075 Controls the list of files the OpenEmbedded build system
14076 scans for hardcoded installation paths. The variable uses a
14077 space-separated list of filenames (not paths) with standard
14078 wildcard characters allowed.
14079 </para>
14080
14081 <para>
14082 During a build, the OpenEmbedded build system creates a
14083 shared state (sstate) object during the first stage of
14084 preparing the sysroots. That object is scanned for
14085 hardcoded paths for original installation locations.
14086 The list of files that are scanned for paths is controlled
14087 by the <filename>SSTATE_SCAN_FILES</filename> variable.
14088 Typically, recipes add files they want to be scanned to the
14089 value of <filename>SSTATE_SCAN_FILES</filename> rather than
14090 the variable being comprehensively set. The
14091 <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
14092 class specifies the default list of files.
14093 </para>
14094
14095 <para>
14096 For details on the process, see the
14097 <link linkend='ref-classes-staging'><filename>staging</filename></link>
14098 class.
14099 </para>
14100 </glossdef>
14101 </glossentry>
14102
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014103 <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm>
14104 <info>
14105 STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host."
14106 </info>
14107 <glossdef>
14108 <para role="glossdeffirst">
14109<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14110 Specifies the path to the <filename>/lib</filename>
14111 subdirectory of the sysroot directory for the
14112 build host.
14113 </para>
14114 </glossdef>
14115 </glossentry>
14116
14117 <glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm>
14118 <info>
14119 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)."
14120 </info>
14121 <glossdef>
14122 <para role="glossdeffirst">
14123<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14124 Specifies the path to the <filename>/lib</filename>
14125 subdirectory of the sysroot directory for the target
14126 for which the current recipe is being built
14127 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14128 </para>
14129 </glossdef>
14130 </glossentry>
14131
14132 <glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm>
14133 <info>
14134 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)."
14135 </info>
14136 <glossdef>
14137 <para role="glossdeffirst">
14138<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14139 Specifies the path to the
14140 <filename>/usr/bin</filename> subdirectory of the
14141 sysroot directory for the target for which the current
14142 recipe is being built
14143 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14144 </para>
14145 </glossdef>
14146 </glossentry>
14147
14148 <glossentry id='var-STAGING_BINDIR_CROSS'><glossterm>STAGING_BINDIR_CROSS</glossterm>
14149 <info>
14150 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."
14151 </info>
14152 <glossdef>
14153 <para role="glossdeffirst">
14154<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14155 Specifies the path to the directory containing binary
14156 configuration scripts.
14157 These scripts provide configuration information for
14158 other software that wants to make use of libraries or
14159 include files provided by the software associated with
14160 the script.
14161 <note>
14162 This style of build configuration has been largely
14163 replaced by <filename>pkg-config</filename>.
14164 Consequently, if <filename>pkg-config</filename>
14165 is supported by the library to which you are linking,
14166 it is recommended you use
14167 <filename>pkg-config</filename> instead of a
14168 provided configuration script.
14169 </note>
14170 </para>
14171 </glossdef>
14172 </glossentry>
14173
14174 <glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm>
14175 <info>
14176 STAGING_BINDIR_NATIVE[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the build host."
14177 </info>
14178 <glossdef>
14179 <para role="glossdeffirst">
14180<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14181 Specifies the path to the
14182 <filename>/usr/bin</filename> subdirectory of the
14183 sysroot directory for the build host.
14184 </para>
14185 </glossdef>
14186 </glossentry>
14187
14188 <glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm>
14189 <info>
14190 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)."
14191 </info>
14192 <glossdef>
14193 <para role="glossdeffirst">
14194<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14195 Specifies the path to the <filename>/usr/share</filename>
14196 subdirectory of the sysroot directory for the target
14197 for which the current recipe is being built
14198 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14199 </para>
14200 </glossdef>
14201 </glossentry>
14202
14203 <glossentry id='var-STAGING_DATADIR_NATIVE'><glossterm>STAGING_DATADIR_NATIVE</glossterm>
14204 <info>
14205 STAGING_DATADIR_NATIVE[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the build host."
14206 </info>
14207 <glossdef>
14208 <para role="glossdeffirst">
14209<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14210 Specifies the path to the <filename>/usr/share</filename>
14211 subdirectory of the sysroot directory for the build host.
14212 </para>
14213 </glossdef>
14214 </glossentry>
14215
14216 <glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm>
14217 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014218 STAGING_DIR[doc] = "Helps construct the recipe-sysroots directory, which is used during packaging."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014219 </info>
14220 <glossdef>
14221 <para role="glossdeffirst">
14222<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040014223 Helps construct the <filename>recipe-sysroots</filename>
14224 directory, which is used during packaging.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014225 </para>
14226
14227 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014228 For information on how staging for recipe-specific
14229 sysroots occurs, see the
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014230 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014231 task, the
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014232 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-sharing-files-between-recipes'>Sharing Files Between Recipes</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -040014233 section in the Yocto Project Development Tasks Manual, the
14234 "<ulink url='&YOCTO_DOCS_OM_URL;#configuration-compilation-and-staging-dev-environment'>Configuration, Compilation, and Staging</ulink>"
14235 section in the Yocto Project Overview and Concepts Manual,
14236 and the
14237 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
14238 variable.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014239 <note>
14240 Recipes should never write files directly under
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014241 the <filename>STAGING_DIR</filename> directory because
14242 the OpenEmbedded build system
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014243 manages the directory automatically.
14244 Instead, files should be installed to
14245 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
14246 within your recipe's
14247 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
14248 task and then the OpenEmbedded build system will
14249 stage a subset of those files into the sysroot.
14250 </note>
14251 </para>
14252 </glossdef>
14253 </glossentry>
14254
14255 <glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm>
14256 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014257 STAGING_DIR_HOST[doc] = "Specifies the path to the sysroot directory for the system that the component is built to run on."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014258 </info>
14259 <glossdef>
14260 <para role="glossdeffirst">
14261<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014262 Specifies the path to the sysroot directory for the system
Brad Bishop316dfdd2018-06-25 12:45:53 -040014263 on which the component is built to run (the system that
14264 hosts the component).
14265 For most recipes, this sysroot is the one in which that
14266 recipe's
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014267 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014268 task copies files.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014269 Exceptions include <filename>-native</filename> recipes,
14270 where the <filename>do_populate_sysroot</filename> task
14271 instead uses
14272 <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>.
14273 Depending on the type of recipe and the build target,
14274 <filename>STAGING_DIR_HOST</filename> can have the
14275 following values:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014276 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014277 <listitem><para>
14278 For recipes building for the target machine, the
14279 value is
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014280 "${<link linkend='var-STAGING_DIR'>STAGING_DIR</link>}/${<link linkend='var-MACHINE'>MACHINE</link>}".
14281 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014282 <listitem><para>
14283 For native recipes building for the build host, the
14284 value is empty given the assumption that when
14285 building for the build host, the build host's own
14286 directories should be used.
14287 <note>
14288 <para><filename>-native</filename> recipes are
14289 not installed into host paths like such as
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014290 <filename>/usr</filename>.
14291 Rather, these recipes are installed into
14292 <filename>STAGING_DIR_NATIVE</filename>.
14293 When compiling <filename>-native</filename>
14294 recipes, standard build environment variables
14295 such as
14296 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
14297 and
14298 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
14299 are set up so that both host paths and
14300 <filename>STAGING_DIR_NATIVE</filename> are
14301 searched for libraries and headers using, for
14302 example, GCC's <filename>-isystem</filename>
14303 option.</para>
14304
Brad Bishop316dfdd2018-06-25 12:45:53 -040014305 <para>Thus, the emphasis is that the
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014306 <filename>STAGING_DIR*</filename> variables
14307 should be viewed as input variables by tasks
14308 such as
14309 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>,
14310 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
14311 and
14312 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
14313 Having the real system root correspond to
14314 <filename>STAGING_DIR_HOST</filename> makes
14315 conceptual sense for
14316 <filename>-native</filename> recipes, as
14317 they make use of host headers and libraries.
14318 </para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014319 </note>
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014320 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014321 </itemizedlist>
14322 </para>
14323 </glossdef>
14324 </glossentry>
14325
14326 <glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm>
14327 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014328 STAGING_DIR_NATIVE[doc] = "Specifies the path to the sysroot directory used when building components that run on the build host itself."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014329 </info>
14330 <glossdef>
14331 <para role="glossdeffirst">
14332<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014333 Specifies the path to the sysroot directory used when
14334 building components that run on the build host itself.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014335 </para>
14336 </glossdef>
14337 </glossentry>
14338
14339 <glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm>
14340 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014341 STAGING_DIR_TARGET[doc] = "Specifies the path to the sysroot used for the system for which the component generates code."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014342 </info>
14343 <glossdef>
14344 <para role="glossdeffirst">
14345<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014346 Specifies the path to the sysroot used for the system for
14347 which the component generates code.
14348 For components that do not generate code, which is the
14349 majority, <filename>STAGING_DIR_TARGET</filename> is set
14350 to match
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014351 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
14352 </para>
14353
14354 <para>
14355 Some recipes build binaries that can run on the target
14356 system but those binaries in turn generate code for
14357 another different system (e.g. cross-canadian recipes).
14358 Using terminology from GNU, the primary system is referred
14359 to as the "HOST" and the secondary, or different, system is
14360 referred to as the "TARGET".
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014361 Thus, the binaries run on the "HOST" system
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014362 and generate binaries for the "TARGET" system.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014363 The <filename>STAGING_DIR_HOST</filename> variable points
14364 to the sysroot used for the "HOST" system, while
14365 <filename>STAGING_DIR_TARGET</filename>
14366 points to the sysroot used for the "TARGET" system.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014367 </para>
14368 </glossdef>
14369 </glossentry>
14370
14371 <glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm>STAGING_ETCDIR_NATIVE</glossterm>
14372 <info>
14373 STAGING_ETCDIR_NATIVE[doc] = "Specifies the path to the /etc subdirectory of the sysroot directory for the build host."
14374 </info>
14375 <glossdef>
14376 <para role="glossdeffirst">
14377<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14378 Specifies the path to the <filename>/etc</filename>
14379 subdirectory of the sysroot directory for the
14380 build host.
14381 </para>
14382 </glossdef>
14383 </glossentry>
14384
14385 <glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm>
14386 <info>
14387 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)."
14388 </info>
14389 <glossdef>
14390 <para role="glossdeffirst">
14391<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14392 Specifies the path to the <filename>/usr</filename>
14393 subdirectory of the sysroot directory for the target
14394 for which the current recipe is being built
14395 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14396 </para>
14397 </glossdef>
14398 </glossentry>
14399
14400 <glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm>
14401 <info>
14402 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)."
14403 </info>
14404 <glossdef>
14405 <para role="glossdeffirst">
14406<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14407 Specifies the path to the
14408 <filename>/usr/include</filename> subdirectory of the
14409 sysroot directory for the target for which the current
14410 recipe being built
14411 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14412 </para>
14413 </glossdef>
14414 </glossentry>
14415
14416 <glossentry id='var-STAGING_INCDIR_NATIVE'><glossterm>STAGING_INCDIR_NATIVE</glossterm>
14417 <info>
14418 STAGING_INCDIR_NATIVE[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the build host."
14419 </info>
14420 <glossdef>
14421 <para role="glossdeffirst">
14422<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14423 Specifies the path to the <filename>/usr/include</filename>
14424 subdirectory of the sysroot directory for the build host.
14425 </para>
14426 </glossdef>
14427 </glossentry>
14428
Patrick Williamsf1e5d692016-03-30 15:21:19 -050014429 <glossentry id='var-STAGING_KERNEL_BUILDDIR'><glossterm>STAGING_KERNEL_BUILDDIR</glossterm>
14430 <info>
14431 STAGING_KERNEL_BUILDDIR[doc] = "Points to the directory containing the kernel build artifacts."
14432 </info>
14433 <glossdef>
14434 <para role="glossdeffirst">
14435<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14436 Points to the directory containing the kernel build
14437 artifacts.
14438 Recipes building software that needs to access kernel
14439 build artifacts
14440 (e.g. <filename>systemtap-uprobes</filename>) can look in
14441 the directory specified with the
14442 <filename>STAGING_KERNEL_BUILDDIR</filename> variable to
14443 find these artifacts after the kernel has been built.
14444 </para>
14445 </glossdef>
14446 </glossentry>
14447
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014448 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
14449 <info>
14450 STAGING_KERNEL_DIR[doc] = "The directory with kernel headers that are required to build out-of-tree modules."
14451 </info>
14452 <glossdef>
14453 <para role="glossdeffirst">
14454<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14455 The directory with kernel headers that are required to build out-of-tree
14456 modules.
14457 </para>
14458 </glossdef>
14459 </glossentry>
14460
14461 <glossentry id='var-STAGING_LIBDIR'><glossterm>STAGING_LIBDIR</glossterm>
14462 <info>
14463 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)."
14464 </info>
14465 <glossdef>
14466 <para role="glossdeffirst">
14467<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14468 Specifies the path to the <filename>/usr/lib</filename>
14469 subdirectory of the sysroot directory for the target for
14470 which the current recipe is being built
14471 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14472 </para>
14473 </glossdef>
14474 </glossentry>
14475
14476 <glossentry id='var-STAGING_LIBDIR_NATIVE'><glossterm>STAGING_LIBDIR_NATIVE</glossterm>
14477 <info>
14478 STAGING_LIBDIR_NATIVE[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the build host."
14479 </info>
14480 <glossdef>
14481 <para role="glossdeffirst">
14482<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14483 Specifies the path to the <filename>/usr/lib</filename>
14484 subdirectory of the sysroot directory for the build host.
14485 </para>
14486 </glossdef>
14487 </glossentry>
14488
14489 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
14490 <info>
14491 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."
14492 </info>
14493 <glossdef>
14494 <para role="glossdeffirst">
14495<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14496 Specifies the base path used to create recipe stamp files.
14497 The path to an actual stamp file is constructed by evaluating this
14498 string and then appending additional information.
14499 Currently, the default assignment for <filename>STAMP</filename>
14500 as set in the <filename>meta/conf/bitbake.conf</filename> file
14501 is:
14502 <literallayout class='monospaced'>
14503 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
14504 </literallayout>
14505 </para>
14506
14507 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014508 For information on how BitBake uses stamp files to determine
14509 if a task should be rerun, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040014510 "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
14511 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014512 </para>
14513
14514 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014515 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
14516 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
14517 <link linkend='var-PN'><filename>PN</filename></link>,
14518 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
14519 <link linkend='var-PV'><filename>PV</filename></link>, and
14520 <link linkend='var-PR'><filename>PR</filename></link> for related variable
14521 information.
14522 </para>
14523 </glossdef>
14524 </glossentry>
14525
14526 <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
14527 <info>
14528 STAMPS_DIR[doc] = "Specifies the base directory in which the OpenEmbedded build system places stamps."
14529 </info>
14530 <glossdef>
14531 <para role="glossdeffirst">
14532<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14533 Specifies the base directory in which the OpenEmbedded
14534 build system places stamps.
14535 The default directory is
14536 <filename>${TMPDIR}/stamps</filename>.
14537 </para>
14538 </glossdef>
14539 </glossentry>
14540
14541 <glossentry id='var-STRIP'><glossterm>STRIP</glossterm>
14542 <info>
14543 STRIP[doc] = "Minimal command and arguments to run 'strip' (strip symbols)."
14544 </info>
14545 <glossdef>
14546 <para role="glossdeffirst">
14547<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14548 The minimal command and arguments to run
14549 <filename>strip</filename>, which is used to strip
14550 symbols.
14551 </para>
14552 </glossdef>
14553 </glossentry>
14554
14555 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
14556 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014557 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014558 </info>
14559 <glossdef>
14560 <para role="glossdeffirst">
14561<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14562 The short (72 characters or less) summary of the binary package for packaging
Brad Bishop316dfdd2018-06-25 12:45:53 -040014563 systems such as <filename>opkg</filename>, <filename>rpm</filename>, or
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014564 <filename>dpkg</filename>.
14565 By default, <filename>SUMMARY</filename> is used to define
14566 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
14567 variable if <filename>DESCRIPTION</filename> is not set
14568 in the recipe.
14569 </para>
14570 </glossdef>
14571 </glossentry>
14572
14573 <glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm>
14574 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014575 SVNDIR[doc] = "The directory where Subversion checkouts are stored."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014576 </info>
14577 <glossdef>
14578 <para role="glossdeffirst">
14579<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14580 The directory in which files checked out of a Subversion
14581 system are stored.
14582 </para>
14583 </glossdef>
14584 </glossentry>
14585
14586 <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm>
14587 <info>
14588 SYSLINUX_DEFAULT_CONSOLE[doc] = "Specifies the kernel boot default console."
14589 </info>
14590 <glossdef>
14591 <para role="glossdeffirst">
14592<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14593 Specifies the kernel boot default console.
14594 If you want to use a console other than the default,
14595 set this variable in your recipe as follows where "X" is
14596 the console number you want to use:
14597 <literallayout class='monospaced'>
14598 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
14599 </literallayout>
14600 </para>
14601
14602 <para>
14603 The
14604 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14605 class initially sets this variable to null but then checks
14606 for a value later.
14607 </para>
14608 </glossdef>
14609 </glossentry>
14610
14611 <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm>
14612 <info>
14613 SYSLINUX_OPTS[doc] = "Lists additional options to add to the syslinux file."
14614 </info>
14615 <glossdef>
14616 <para role="glossdeffirst">
14617<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14618 Lists additional options to add to the syslinux file.
14619 You need to set this variable in your recipe.
14620 If you want to list multiple options, separate the options
14621 with a semicolon character (<filename>;</filename>).
14622 </para>
14623
14624 <para>
14625 The
14626 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14627 class uses this variable to create a set of options.
14628 </para>
14629 </glossdef>
14630 </glossentry>
14631
14632 <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm>
14633 <info>
14634 SYSLINUX_SERIAL[doc] = "Specifies the alternate serial port or turns it off."
14635 </info>
14636 <glossdef>
14637 <para role="glossdeffirst">
14638<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14639 Specifies the alternate serial port or turns it off.
14640 To turn off serial, set this variable to an empty string
14641 in your recipe.
14642 The variable's default value is set in the
14643 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014644 class as follows:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014645 <literallayout class='monospaced'>
14646 SYSLINUX_SERIAL ?= "0 115200"
14647 </literallayout>
14648 </para>
14649
14650 <para>
14651 The class checks for and uses the variable as needed.
14652 </para>
14653 </glossdef>
14654 </glossentry>
14655
14656 <glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm>
14657 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014658 SYSLINUX_SPLASH[doc] = "An .LSS file used as the background for the VGA boot menu when you use the boot menu."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014659 </info>
14660 <glossdef>
14661 <para role="glossdeffirst">
14662<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14663 An <filename>.LSS</filename> file used as the background
Brad Bishop316dfdd2018-06-25 12:45:53 -040014664 for the VGA boot menu when you use the boot menu.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014665 You need to set this variable in your recipe.
14666 </para>
14667
14668 <para>
14669 The
14670 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14671 class checks for this variable and if found, the
14672 OpenEmbedded build system installs the splash screen.
14673 </para>
14674 </glossdef>
14675 </glossentry>
14676
14677 <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>
14678 <info>
14679 SYSLINUX_SERIAL_TTY[doc] = "Specifies the alternate console=tty... kernel boot argument."
14680 </info>
14681 <glossdef>
14682 <para role="glossdeffirst">
14683<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14684 Specifies the alternate console=tty... kernel boot argument.
14685 The variable's default value is set in the
14686 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014687 class as follows:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014688 <literallayout class='monospaced'>
14689 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
14690 </literallayout>
14691 </para>
14692
14693 <para>
14694 The class checks for and uses the variable as needed.
14695 </para>
14696 </glossdef>
14697 </glossentry>
14698
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014699 <glossentry id='var-SYSROOT_DESTDIR'><glossterm>SYSROOT_DESTDIR</glossterm>
14700 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014701 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."
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014702 </info>
14703 <glossdef>
14704 <para role="glossdeffirst">
14705<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14706 Points to the temporary directory under the work directory
14707 (default
Brad Bishopd7bf8c12018-02-25 22:55:05 -050014708 "<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/sysroot-destdir</filename>")
Brad Bishop316dfdd2018-06-25 12:45:53 -040014709 where the files populated into the sysroot are assembled
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014710 during the
14711 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14712 task.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014713 </para>
14714 </glossdef>
14715 </glossentry>
14716
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014717 <glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm>
14718 <info>
14719 SYSROOT_DIRS[doc] = "Directories that are staged into the sysroot by the do_populate_sysroot task."
14720 </info>
14721 <glossdef>
14722 <para role="glossdeffirst">
14723<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14724 Directories that are staged into the sysroot by the
14725 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14726 task.
14727 By default, the following directories are staged:
14728 <literallayout class='monospaced'>
14729 SYSROOT_DIRS = " \
14730 ${includedir} \
14731 ${libdir} \
14732 ${base_libdir} \
14733 ${nonarch_base_libdir} \
14734 ${datadir} \
14735 "
14736 </literallayout>
14737 </para>
14738 </glossdef>
14739 </glossentry>
14740
14741 <glossentry id='var-SYSROOT_DIRS_BLACKLIST'><glossterm>SYSROOT_DIRS_BLACKLIST</glossterm>
14742 <info>
14743 SYSROOT_DIRS_BLACKLIST[doc] = "Directories that are not staged into the sysroot by the do_populate_sysroot task."
14744 </info>
14745 <glossdef>
14746 <para role="glossdeffirst">
14747<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14748 Directories that are not staged into the sysroot by the
14749 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14750 task.
14751 You can use this variable to exclude certain subdirectories
14752 of directories listed in
14753 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
14754 from staging.
14755 By default, the following directories are not staged:
14756 <literallayout class='monospaced'>
14757 SYSROOT_DIRS_BLACKLIST = " \
14758 ${mandir} \
14759 ${docdir} \
14760 ${infodir} \
14761 ${datadir}/locale \
14762 ${datadir}/applications \
14763 ${datadir}/fonts \
14764 ${datadir}/pixmaps \
14765 "
14766 </literallayout>
14767 </para>
14768 </glossdef>
14769 </glossentry>
14770
14771 <glossentry id='var-SYSROOT_DIRS_NATIVE'><glossterm>SYSROOT_DIRS_NATIVE</glossterm>
14772 <info>
14773 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."
14774 </info>
14775 <glossdef>
14776 <para role="glossdeffirst">
14777<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14778 Extra directories staged into the sysroot by the
14779 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14780 task for <filename>-native</filename> recipes, in addition
14781 to those specified in
14782 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>.
14783 By default, the following extra directories are staged:
14784 <literallayout class='monospaced'>
14785 SYSROOT_DIRS_NATIVE = " \
14786 ${bindir} \
14787 ${sbindir} \
14788 ${base_bindir} \
14789 ${base_sbindir} \
14790 ${libexecdir} \
14791 ${sysconfdir} \
14792 ${localstatedir} \
14793 "
14794 </literallayout>
14795 <note>
14796 Programs built by <filename>-native</filename> recipes
14797 run directly from the sysroot
14798 (<link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>),
14799 which is why additional directories containing program
14800 executables and supporting files need to be staged.
14801 </note>
14802 </para>
14803 </glossdef>
14804 </glossentry>
14805
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014806 <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
14807 <info>
14808 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."
14809 </info>
14810 <glossdef>
14811 <para role="glossdeffirst">
14812<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14813 A list of functions to execute after files are staged into
14814 the sysroot.
14815 These functions are usually used to apply additional
14816 processing on the staged files, or to stage additional
14817 files.
14818 </para>
14819 </glossdef>
14820 </glossentry>
14821
14822 <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>
14823 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014824 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014825 </info>
14826 <glossdef>
14827 <para role="glossdeffirst">
14828<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14829 When inheriting the
14830 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014831 class, this variable specifies whether the specified service
14832 in
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014833 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014834 should start automatically or not.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014835 By default, the service is enabled to automatically start
14836 at boot time.
14837 The default setting is in the
14838 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14839 class as follows:
14840 <literallayout class='monospaced'>
14841 SYSTEMD_AUTO_ENABLE ??= "enable"
14842 </literallayout>
14843 </para>
14844
14845 <para>
14846 You can disable the service by setting the variable to
14847 "disable".
14848 </para>
14849 </glossdef>
14850 </glossentry>
14851
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014852 <glossentry id='var-SYSTEMD_BOOT_CFG'><glossterm>SYSTEMD_BOOT_CFG</glossterm>
14853 <info>
14854 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."
14855 </info>
14856 <glossdef>
14857 <para role="glossdeffirst">
14858<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14859 When
14860 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14861 is set to "systemd-boot", the
14862 <filename>SYSTEMD_BOOT_CFG</filename> variable specifies the
14863 configuration file that should be used.
14864 By default, the
14865 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14866 class sets the <filename>SYSTEMD_BOOT_CFG</filename> as
14867 follows:
14868 <literallayout class='monospaced'>
14869 SYSTEMD_BOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf"
14870 </literallayout>
14871 </para>
14872
14873 <para>
14874 For information on Systemd-boot, see the
14875 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14876 </para>
14877 </glossdef>
14878 </glossentry>
14879
14880 <glossentry id='var-SYSTEMD_BOOT_ENTRIES'><glossterm>SYSTEMD_BOOT_ENTRIES</glossterm>
14881 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014882 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."
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014883 </info>
14884 <glossdef>
14885 <para role="glossdeffirst">
14886<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14887 When
14888 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14889 is set to "systemd-boot", the
14890 <filename>SYSTEMD_BOOT_ENTRIES</filename> variable specifies
14891 a list of entry files
Brad Bishop316dfdd2018-06-25 12:45:53 -040014892 (<filename>*.conf</filename>) to install that contain
14893 one boot entry per file.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014894 By default, the
14895 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14896 class sets the <filename>SYSTEMD_BOOT_ENTRIES</filename> as
14897 follows:
14898 <literallayout class='monospaced'>
14899 SYSTEMD_BOOT_ENTRIES ?= ""
14900 </literallayout>
14901 </para>
14902
14903 <para>
14904 For information on Systemd-boot, see the
14905 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14906 </para>
14907 </glossdef>
14908 </glossentry>
14909
14910 <glossentry id='var-SYSTEMD_BOOT_TIMEOUT'><glossterm>SYSTEMD_BOOT_TIMEOUT</glossterm>
14911 <info>
14912 SYSTEMD_BOOT_TIMEOUT[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_TIMEOUT variable specifies the boot menu timeout in seconds."
14913 </info>
14914 <glossdef>
14915 <para role="glossdeffirst">
14916<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14917 When
14918 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14919 is set to "systemd-boot", the
14920 <filename>SYSTEMD_BOOT_TIMEOUT</filename> variable specifies
14921 the boot menu timeout in seconds.
14922 By default, the
14923 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14924 class sets the <filename>SYSTEMD_BOOT_TIMEOUT</filename> as
14925 follows:
14926 <literallayout class='monospaced'>
14927 SYSTEMD_BOOT_TIMEOUT ?= "10"
14928 </literallayout>
14929 </para>
14930
14931 <para>
14932 For information on Systemd-boot, see the
14933 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14934 </para>
14935 </glossdef>
14936 </glossentry>
14937
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014938 <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>
14939 <info>
14940 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."
14941 </info>
14942 <glossdef>
14943 <para role="glossdeffirst">
14944<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14945 When inheriting the
14946 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14947 class, this variable locates the systemd unit files when
14948 they are not found in the main recipe's package.
14949 By default, the
14950 <filename>SYSTEMD_PACKAGES</filename> variable is set
14951 such that the systemd unit files are assumed to reside in
14952 the recipes main package:
14953 <literallayout class='monospaced'>
14954 SYSTEMD_PACKAGES ?= "${PN}"
14955 </literallayout>
14956 </para>
14957
14958 <para>
14959 If these unit files are not in this recipe's main
14960 package, you need to use
14961 <filename>SYSTEMD_PACKAGES</filename> to list the package
14962 or packages in which the build system can find the systemd
14963 unit files.
14964 </para>
14965 </glossdef>
14966 </glossentry>
14967
14968 <glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm>
14969 <info>
14970 SYSTEMD_SERVICE[doc] = "For recipes that inherit the systemd class, this variable specifies the systemd service name for a package."
14971 </info>
14972 <glossdef>
14973 <para role="glossdeffirst">
14974<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14975 When inheriting the
14976 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14977 class, this variable specifies the systemd service name for
14978 a package.
14979 </para>
14980
14981 <para>
14982 When you specify this file in your recipe, use a package
14983 name override to indicate the package to which the value
14984 applies.
14985 Here is an example from the connman recipe:
14986 <literallayout class='monospaced'>
14987 SYSTEMD_SERVICE_${PN} = "connman.service"
14988 </literallayout>
14989 </para>
14990 </glossdef>
14991 </glossentry>
14992
14993 <glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>SYSVINIT_ENABLED_GETTYS</glossterm>
14994 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014995 SYSVINIT_ENABLED_GETTYS[doc] = "Specifies which virtual terminals should run a getty, the default is '1'."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014996 </info>
14997 <glossdef>
14998 <para role="glossdeffirst">
14999<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15000 When using
15001 <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
15002 specifies a space-separated list of the virtual terminals
Brad Bishop316dfdd2018-06-25 12:45:53 -040015003 that should run a
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015004 <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
15005 (allowing login), assuming
15006 <link linkend='var-USE_VT'><filename>USE_VT</filename></link>
15007 is not set to "0".
15008 </para>
15009
15010 <para>
15011 The default value for
15012 <filename>SYSVINIT_ENABLED_GETTYS</filename> is "1"
15013 (i.e. only run a getty on the first virtual terminal).
15014 </para>
15015 </glossdef>
15016 </glossentry>
15017
15018 </glossdiv>
15019
15020 <glossdiv id='var-glossary-t'><title>T</title>
15021
15022 <glossentry id='var-T'><glossterm>T</glossterm>
15023 <info>
15024 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."
15025 </info>
15026 <glossdef>
15027 <para role="glossdeffirst">
15028<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15029 This variable points to a directory were BitBake places
15030 temporary files, which consist mostly of task logs and
15031 scripts, when building a particular recipe.
15032 The variable is typically set as follows:
15033 <literallayout class='monospaced'>
15034 T = "${WORKDIR}/temp"
15035 </literallayout>
15036 </para>
15037
15038 <para>
15039 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
15040 is the directory into which BitBake unpacks and builds the
15041 recipe.
15042 The default <filename>bitbake.conf</filename> file sets this variable.</para>
15043 <para>The <filename>T</filename> variable is not to be confused with
15044 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
15045 which points to the root of the directory tree where BitBake
15046 places the output of an entire build.
15047 </para>
15048 </glossdef>
15049 </glossentry>
15050
15051 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
15052 <info>
15053 TARGET_ARCH[doc] = "The architecture of the device being built. The OpenEmbedded build system supports the following architectures: arm, mips, ppc, x86, x86-64."
15054 </info>
15055 <glossdef>
15056 <para role="glossdeffirst">
15057<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15058 The target machine's architecture.
15059 The OpenEmbedded build system supports many
15060 architectures.
15061 Here is an example list of architectures supported.
15062 This list is by no means complete as the architecture
15063 is configurable:
15064 <literallayout class='monospaced'>
15065 arm
15066 i586
15067 x86_64
15068 powerpc
15069 powerpc64
15070 mips
15071 mipsel
15072 </literallayout>
15073 </para>
15074
15075 <para>
15076 For additional information on machine architectures, see
15077 the
15078 <link linkend='var-TUNE_ARCH'><filename>TUNE_ARCH</filename></link>
15079 variable.
15080 </para>
15081 </glossdef>
15082 </glossentry>
15083
15084 <glossentry id='var-TARGET_AS_ARCH'><glossterm>TARGET_AS_ARCH</glossterm>
15085 <info>
15086 TARGET_AS_ARCH[doc] = "Specifies architecture-specific assembler flags for the target system."
15087 </info>
15088 <glossdef>
15089 <para role="glossdeffirst">
15090<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15091 Specifies architecture-specific assembler flags for the
15092 target system.
15093 <filename>TARGET_AS_ARCH</filename> is initialized from
15094 <link linkend='var-TUNE_ASARGS'><filename>TUNE_ASARGS</filename></link>
15095 by default in the BitBake configuration file
15096 (<filename>meta/conf/bitbake.conf</filename>):
15097 <literallayout class='monospaced'>
15098 TARGET_AS_ARCH = "${TUNE_ASARGS}"
15099 </literallayout>
15100 </para>
15101 </glossdef>
15102 </glossentry>
15103
15104 <glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm>
15105 <info>
15106 TARGET_CC_ARCH[doc] = "Specifies architecture-specific C compiler flags for the target system."
15107 </info>
15108 <glossdef>
15109 <para role="glossdeffirst">
15110<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15111 Specifies architecture-specific C compiler flags for the
15112 target system.
15113 <filename>TARGET_CC_ARCH</filename> is initialized from
15114 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
15115 by default.
15116 <note>
15117 It is a common workaround to append
15118 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
15119 to <filename>TARGET_CC_ARCH</filename>
15120 in recipes that build software for the target that
15121 would not otherwise respect the exported
15122 <filename>LDFLAGS</filename> variable.
15123 </note>
15124 </para>
15125 </glossdef>
15126 </glossentry>
15127
15128 <glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm>
15129 <info>
15130 TARGET_CC_KERNEL_ARCH[doc] = "This is a specific kernel compiler flag for a CPU or Application Binary Interface (ABI) tune."
15131 </info>
15132 <glossdef>
15133 <para role="glossdeffirst">
15134<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15135 This is a specific kernel compiler flag for a CPU or
15136 Application Binary Interface (ABI) tune.
15137 The flag is used rarely and only for cases where a
15138 userspace
15139 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
15140 is not compatible with the kernel compilation.
15141 The <filename>TARGET_CC_KERNEL_ARCH</filename> variable
15142 allows the kernel (and associated modules) to use a
15143 different configuration.
15144 See the
15145 <filename>meta/conf/machine/include/arm/feature-arm-thumb.inc</filename>
15146 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015147 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015148 for an example.
15149 </para>
15150 </glossdef>
15151 </glossentry>
15152
15153 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
15154 <info>
15155 TARGET_CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as CFLAGS."
15156 </info>
15157 <glossdef>
15158 <para role="glossdeffirst">
15159<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15160 Specifies the flags to pass to the C compiler when building
15161 for the target.
15162 When building in the target context,
15163 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
15164 is set to the value of this variable by default.
15165 </para>
15166
15167 <para>
15168 Additionally, the SDK's environment setup script sets
Brad Bishop316dfdd2018-06-25 12:45:53 -040015169 the <filename>CFLAGS</filename> variable in the environment
15170 to the <filename>TARGET_CFLAGS</filename> value so that
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015171 executables built using the SDK also have the flags
15172 applied.
15173 </para>
15174 </glossdef>
15175 </glossentry>
15176
15177 <glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm>
15178 <info>
15179 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."
15180 </info>
15181 <glossdef>
15182 <para role="glossdeffirst">
15183<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15184 Specifies the flags to pass to the C pre-processor
15185 (i.e. to both the C and the C++ compilers) when building
15186 for the target.
15187 When building in the target context,
15188 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
15189 is set to the value of this variable by default.
15190 </para>
15191
15192 <para>
15193 Additionally, the SDK's environment setup script sets
Brad Bishop316dfdd2018-06-25 12:45:53 -040015194 the <filename>CPPFLAGS</filename> variable in the
15195 environment to the <filename>TARGET_CPPFLAGS</filename>
15196 value so that executables built using the SDK also have
15197 the flags applied.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015198 </para>
15199 </glossdef>
15200 </glossentry>
15201
15202 <glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm>
15203 <info>
15204 TARGET_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the target."
15205 </info>
15206 <glossdef>
15207 <para role="glossdeffirst">
15208<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15209 Specifies the flags to pass to the C++ compiler when
15210 building for the target.
15211 When building in the target context,
15212 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
15213 is set to the value of this variable by default.
15214 </para>
15215
15216 <para>
15217 Additionally, the SDK's environment setup script sets
Brad Bishop316dfdd2018-06-25 12:45:53 -040015218 the <filename>CXXFLAGS</filename> variable in the
15219 environment to the <filename>TARGET_CXXFLAGS</filename>
15220 value so that executables built using the SDK also have
15221 the flags applied.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015222 </para>
15223 </glossdef>
15224 </glossentry>
15225
15226 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
15227 <info>
15228 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."
15229 </info>
15230 <glossdef>
15231 <para role="glossdeffirst">
15232<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15233 Specifies the method for handling FPU code.
15234 For FPU-less targets, which include most ARM CPUs, the variable must be
15235 set to "soft".
15236 If not, the kernel emulation gets used, which results in a performance penalty.
15237 </para>
15238 </glossdef>
15239 </glossentry>
15240
15241 <glossentry id='var-TARGET_LD_ARCH'><glossterm>TARGET_LD_ARCH</glossterm>
15242 <info>
15243 TARGET_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the target system."
15244 </info>
15245 <glossdef>
15246 <para role="glossdeffirst">
15247<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15248 Specifies architecture-specific linker flags for the
15249 target system.
15250 <filename>TARGET_LD_ARCH</filename> is initialized from
15251 <link linkend='var-TUNE_LDARGS'><filename>TUNE_LDARGS</filename></link>
15252 by default in the BitBake configuration file
15253 (<filename>meta/conf/bitbake.conf</filename>):
15254 <literallayout class='monospaced'>
15255 TARGET_LD_ARCH = "${TUNE_LDARGS}"
15256 </literallayout>
15257 </para>
15258 </glossdef>
15259 </glossentry>
15260
15261 <glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm>
15262 <info>
15263 TARGET_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the target."
15264 </info>
15265 <glossdef>
15266 <para role="glossdeffirst">
15267<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15268 Specifies the flags to pass to the linker when building
15269 for the target.
15270 When building in the target context,
15271 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
15272 is set to the value of this variable by default.
15273 </para>
15274
15275 <para>
15276 Additionally, the SDK's environment setup script sets
15277 the
15278 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
15279 variable in the environment to the
15280 <filename>TARGET_LDFLAGS</filename> value so that
15281 executables built using the SDK also have the flags
15282 applied.
15283 </para>
15284 </glossdef>
15285 </glossentry>
15286
15287 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
15288 <info>
15289 TARGET_OS[doc] = "Specifies the target's operating system."
15290 </info>
15291 <glossdef>
15292 <para role="glossdeffirst">
15293<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15294 Specifies the target's operating system.
Brad Bishop316dfdd2018-06-25 12:45:53 -040015295 The variable can be set to "linux" for glibc-based systems
15296 (GNU C Library) and to "linux-musl" for musl libc.
15297 For ARM/EABI targets, "linux-gnueabi" and "linux-musleabi"
15298 possible values exist.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015299 </para>
15300 </glossdef>
15301 </glossentry>
15302
15303 <glossentry id='var-TARGET_PREFIX'><glossterm>TARGET_PREFIX</glossterm>
15304 <info>
15305 TARGET_PREFIX[doc] = "The prefix used for the toolchain binary target tools."
15306 </info>
15307 <glossdef>
15308 <para role="glossdeffirst">
15309<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15310 Specifies the prefix used for the toolchain binary target
15311 tools.
15312 </para>
15313
15314 <para>
15315 Depending on the type of recipe and the build target,
15316 <filename>TARGET_PREFIX</filename> is set as follows:
15317 <itemizedlist>
15318 <listitem><para>
15319 For recipes building for the target machine,
15320 the value is
15321 "${<link linkend='var-TARGET_SYS'>TARGET_SYS</link>}-".
15322 </para></listitem>
15323 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015324 For native recipes, the build system sets the
15325 variable to the value of
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015326 <filename>BUILD_PREFIX</filename>.
15327 </para></listitem>
15328 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015329 For native SDK recipes
15330 (<filename>nativesdk</filename>), the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015331 build system sets the variable to the value of
15332 <filename>SDK_PREFIX</filename>.
15333 </para></listitem>
15334 </itemizedlist>
15335 </para>
15336 </glossdef>
15337 </glossentry>
15338
15339 <glossentry id='var-TARGET_SYS'><glossterm>TARGET_SYS</glossterm>
15340 <info>
15341 TARGET_SYS[doc] = "The target system is comprised of TARGET_ARCH,TARGET_VENDOR and TARGET_OS."
15342 </info>
15343 <glossdef>
15344 <para role="glossdeffirst">
15345<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15346 Specifies the system, including the architecture and the
15347 operating system, for which the build is occurring in
15348 the context of the current recipe.
15349 </para>
15350
15351 <para>
15352 The OpenEmbedded build system automatically sets this
15353 variable based on
15354 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
15355 <link linkend='var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></link>,
15356 and
15357 <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>
15358 variables.
15359 <note>
15360 You do not need to set the
15361 <filename>TARGET_SYS</filename> variable yourself.
15362 </note>
15363 </para>
15364
15365 <para>
15366 Consider these two examples:
15367 <itemizedlist>
15368 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015369 Given a native recipe on a 32-bit, x86 machine
15370 running Linux, the value is "i686-linux".
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015371 </para></listitem>
15372 <listitem><para>
15373 Given a recipe being built for a little-endian,
15374 MIPS target running Linux, the value might be
15375 "mipsel-linux".
15376 </para></listitem>
15377 </itemizedlist>
15378 </para>
15379 </glossdef>
15380 </glossentry>
15381
15382 <glossentry id='var-TARGET_VENDOR'><glossterm>TARGET_VENDOR</glossterm>
15383 <info>
15384 TARGET_VENDOR[doc] = "The name of the target vendor."
15385 </info>
15386 <glossdef>
15387 <para role="glossdeffirst">
15388<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15389 Specifies the name of the target vendor.
15390 </para>
15391 </glossdef>
15392 </glossentry>
15393
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015394 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
15395 <info>
Andrew Geissler82c905d2020-04-13 13:39:40 -050015396 TCLIBC[doc] = "Specifies GNU standard C library (libc) variant to use during the build process. You can select 'glibc', 'musl' or 'newlib'."
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015397 </info>
15398 <glossdef>
15399 <para role="glossdeffirst">
15400<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15401 Specifies the GNU standard C library
15402 (<filename>libc</filename>) variant to use during the
15403 build process.
15404 This variable replaces <filename>POKYLIBC</filename>,
15405 which is no longer supported.
15406 </para>
15407
15408 <para>
15409 You can select "glibc", "musl", "newlib", or "baremetal"
15410 </para>
15411 </glossdef>
15412 </glossentry>
15413
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015414 <glossentry id='var-TCLIBCAPPEND'><glossterm>TCLIBCAPPEND</glossterm>
15415 <info>
15416 TCLIBCAPPEND[doc] = "Specifies a suffix appended to TMPDIR that identifies the libc variant for the build."
15417 </info>
15418 <glossdef>
15419 <para role="glossdeffirst">
15420<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15421 Specifies a suffix to be appended onto the
15422 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
15423 value.
15424 The suffix identifies the <filename>libc</filename> variant
15425 for building.
15426 When you are building for multiple variants with the same
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015427 <link linkend='build-directory'>Build Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015428 this mechanism ensures that output for different
15429 <filename>libc</filename> variants is kept separate to
15430 avoid potential conflicts.
15431 </para>
15432
15433 <para>
15434 In the <filename>defaultsetup.conf</filename> file, the
15435 default value of <filename>TCLIBCAPPEND</filename> is
15436 "-${TCLIBC}".
15437 However, distros such as poky, which normally only support
15438 one <filename>libc</filename> variant, set
15439 <filename>TCLIBCAPPEND</filename> to "" in their distro
15440 configuration file resulting in no suffix being applied.
15441 </para>
15442 </glossdef>
15443 </glossentry>
15444
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015445 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
15446 <info>
15447 TCMODE[doc] = "Enables an external toolchain (where provided by an additional layer) if set to a value other than 'default'."
15448 </info>
15449 <glossdef>
15450 <para role="glossdeffirst">
15451<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15452 Specifies the toolchain selector.
15453 <filename>TCMODE</filename> controls the characteristics
15454 of the generated packages and images by telling the
15455 OpenEmbedded build system which toolchain profile to use.
15456 By default, the OpenEmbedded build system builds its own
15457 internal toolchain.
15458 The variable's default value is "default", which uses
15459 that internal toolchain.
15460 <note>
15461 If <filename>TCMODE</filename> is set to a value
15462 other than "default", then it is your responsibility
15463 to ensure that the toolchain is compatible with the
15464 default toolchain.
15465 Using older or newer versions of these components
15466 might cause build problems.
Brad Bishop316dfdd2018-06-25 12:45:53 -040015467 See the Release Notes for the Yocto Project release
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015468 for the specific components with which the toolchain
15469 must be compatible.
Brad Bishop316dfdd2018-06-25 12:45:53 -040015470 To access the Release Notes, go to the
15471 <ulink url='&YOCTO_HOME_URL;/software-overview/downloads/'>Downloads</ulink>
15472 page on the Yocto Project website and click on the
15473 "RELEASE INFORMATION" link for the appropriate
15474 release.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015475 </note>
15476 </para>
15477
15478 <para>
15479 The <filename>TCMODE</filename> variable is similar to
15480 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
15481 which controls the variant of the GNU standard C library
15482 (<filename>libc</filename>) used during the build process:
Brad Bishop37a0e4d2017-12-04 01:01:44 -050015483 <filename>glibc</filename> or <filename>musl</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015484 </para>
15485
15486 <para>
15487 With additional layers, it is possible to use a pre-compiled
15488 external toolchain.
15489 One example is the Sourcery G++ Toolchain.
15490 The support for this toolchain resides in the separate
15491 <trademark class='registered'>Mentor Graphics</trademark>
15492 <filename>meta-sourcery</filename> layer at
15493 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
15494 </para>
15495
15496 <para>
15497 The layer's <filename>README</filename> file contains
15498 information on how to use the Sourcery G++ Toolchain as
15499 an external toolchain.
15500 In summary, you must be sure to add the layer to your
15501 <filename>bblayers.conf</filename> file in front of the
15502 <filename>meta</filename> layer and then set the
15503 <filename>EXTERNAL_TOOLCHAIN</filename>
15504 variable in your <filename>local.conf</filename> file
15505 to the location in which you installed the toolchain.
15506 </para>
15507
15508 <para>
15509 The fundamentals used for this example apply to any
15510 external toolchain.
15511 You can use <filename>meta-sourcery</filename> as a
15512 template for adding support for other external toolchains.
15513 </para>
15514 </glossdef>
15515 </glossentry>
15516
15517 <glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>
15518 <info>
15519 TEST_EXPORT_DIR[doc] = "The location the OpenEmbedded build system uses to export tests when the TEST_EXPORT_ONLY variable is set to "1"."
15520 </info>
15521 <glossdef>
15522 <para role="glossdeffirst">
15523<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15524 The location the OpenEmbedded build system uses to export
15525 tests when the
15526 <link linkend='var-TEST_EXPORT_ONLY'><filename>TEST_EXPORT_ONLY</filename></link>
15527 variable is set to "1".
15528 </para>
15529
15530 <para>
15531 The <filename>TEST_EXPORT_DIR</filename> variable defaults
15532 to <filename>"${TMPDIR}/testimage/${PN}"</filename>.
15533 </para>
15534 </glossdef>
15535 </glossentry>
15536
15537 <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>
15538 <info>
15539 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."
15540 </info>
15541 <glossdef>
15542 <para role="glossdeffirst">
15543<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15544 Specifies to export the tests only.
15545 Set this variable to "1" if you do not want to run the
15546 tests but you want them to be exported in a manner that
15547 you to run them outside of the build system.
15548 </para>
15549 </glossdef>
15550 </glossentry>
15551
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015552 <glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm>
15553 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040015554 TEST_LOG_DIR[doc] = "Holds the SSH log and the boot log for QEMU machines. The TEST_LOG_DIR variable defaults to "${WORKDIR}/testimage"."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015555 </info>
15556 <glossdef>
15557 <para role="glossdeffirst">
15558<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15559 Holds the SSH log and the boot log for QEMU machines.
15560 The <filename>TEST_LOG_DIR</filename> variable defaults
15561 to <filename>"${WORKDIR}/testimage"</filename>.
15562 <note>
15563 Actual test results reside in the task log
15564 (<filename>log.do_testimage</filename>), which is in
15565 the <filename>${WORKDIR}/temp/</filename> directory.
15566 </note>
15567 </para>
15568 </glossdef>
15569 </glossentry>
15570
15571 <glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm>TEST_POWERCONTROL_CMD</glossterm>
15572 <info>
15573 TEST_POWERCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to control the power of the target machine under test"
15574 </info>
15575 <glossdef>
15576 <para role="glossdeffirst">
15577<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15578 For automated hardware testing, specifies the command to
15579 use to control the power of the target machine under test.
15580 Typically, this command would point to a script that
15581 performs the appropriate action (e.g. interacting
15582 with a web-enabled power strip).
15583 The specified command should expect to receive as the last
15584 argument "off", "on" or "cycle" specifying to power off,
15585 on, or cycle (power off and then power on) the device,
15586 respectively.
15587 </para>
15588 </glossdef>
15589 </glossentry>
15590
15591 <glossentry id='var-TEST_POWERCONTROL_EXTRA_ARGS'><glossterm>TEST_POWERCONTROL_EXTRA_ARGS</glossterm>
15592 <info>
15593 TEST_POWERCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_POWERCONTROL_CMD"
15594 </info>
15595 <glossdef>
15596 <para role="glossdeffirst">
15597<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15598 For automated hardware testing, specifies additional
15599 arguments to pass through to the command specified in
15600 <link linkend='var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></link>.
15601 Setting <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
15602 is optional.
15603 You can use it if you wish, for example, to separate the
15604 machine-specific and non-machine-specific parts of the
15605 arguments.
15606 </para>
15607 </glossdef>
15608 </glossentry>
15609
15610 <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
15611 <info>
15612 TEST_QEMUBOOT_TIMEOUT[doc] = "The time in seconds allowed for an image to boot before automated runtime tests begin to run against an image."
15613 </info>
15614 <glossdef>
15615 <para role="glossdeffirst">
15616<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15617 The time in seconds allowed for an image to boot before
15618 automated runtime tests begin to run against an
15619 image.
15620 The default timeout period to allow the boot process to
15621 reach the login prompt is 500 seconds.
15622 You can specify a different value in the
15623 <filename>local.conf</filename> file.
15624 </para>
15625
15626 <para>
15627 For more information on testing images, see the
15628 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015629 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015630 </para>
15631 </glossdef>
15632 </glossentry>
15633
15634 <glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm>TEST_SERIALCONTROL_CMD</glossterm>
15635 <info>
15636 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."
15637 </info>
15638 <glossdef>
15639 <para role="glossdeffirst">
15640<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15641 For automated hardware testing, specifies the command
15642 to use to connect to the serial console of the target
15643 machine under test.
15644 This command simply needs to connect to the serial console
15645 and forward that connection to standard input and output
15646 as any normal terminal program does.
15647 </para>
15648
15649 <para>
15650 For example, to use the Picocom terminal program on
15651 serial device <filename>/dev/ttyUSB0</filename> at
15652 115200bps, you would set the variable as follows:
15653 <literallayout class='monospaced'>
15654 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
15655 </literallayout>
15656 </para>
15657 </glossdef>
15658 </glossentry>
15659
15660 <glossentry id='var-TEST_SERIALCONTROL_EXTRA_ARGS'><glossterm>TEST_SERIALCONTROL_EXTRA_ARGS</glossterm>
15661 <info>
15662 TEST_SERIALCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_SERIALCONTROL_CMD."
15663 </info>
15664 <glossdef>
15665 <para role="glossdeffirst">
15666<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15667 For automated hardware testing, specifies additional
15668 arguments to pass through to the command specified in
15669 <link linkend='var-TEST_SERIALCONTROL_CMD'><filename>TEST_SERIALCONTROL_CMD</filename></link>.
15670 Setting <filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename>
15671 is optional.
15672 You can use it if you wish, for example, to separate the
15673 machine-specific and non-machine-specific parts of the
15674 command.
15675 </para>
15676 </glossdef>
15677 </glossentry>
15678
15679 <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>
15680 <info>
15681 TEST_SERVER_IP[doc] = "The IP address of the build machine (host machine). This IP address is usually automatically detected."
15682 </info>
15683 <glossdef>
15684 <para role="glossdeffirst">
15685<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15686 The IP address of the build machine (host machine).
15687 This IP address is usually automatically detected.
15688 However, if detection fails, this variable needs to be set
15689 to the IP address of the build machine (i.e. where
15690 the build is taking place).
15691 <note>
15692 The <filename>TEST_SERVER_IP</filename> variable
15693 is only used for a small number of tests such as
Brad Bishop6e60e8b2018-02-01 10:27:11 -050015694 the "dnf" test suite, which needs to download
15695 packages from
15696 <filename>WORKDIR/oe-rootfs-repo</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015697 </note>
15698 </para>
15699 </glossdef>
15700 </glossentry>
15701
15702 <glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>
15703 <info>
15704 TEST_TARGET[doc] = "For automated runtime testing, specifies the method of deploying the image and running tests on the target machine."
15705 </info>
15706 <glossdef>
15707 <para role="glossdeffirst">
15708<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15709 Specifies the target controller to use when running tests
15710 against a test image.
Andrew Geissler82c905d2020-04-13 13:39:40 -050015711 The default controller to use is "qemu":
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015712 <literallayout class='monospaced'>
Andrew Geissler82c905d2020-04-13 13:39:40 -050015713 TEST_TARGET = "qemu"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015714 </literallayout>
15715 </para>
15716
15717 <para>
15718 A target controller is a class that defines how an
15719 image gets deployed on a target and how a target is started.
15720 A layer can extend the controllers by adding a module
15721 in the layer's <filename>/lib/oeqa/controllers</filename>
15722 directory and by inheriting the
15723 <filename>BaseTarget</filename> class, which is an abstract
15724 class that cannot be used as a value of
15725 <filename>TEST_TARGET</filename>.
15726 </para>
15727
15728 <para>
15729 You can provide the following arguments with
15730 <filename>TEST_TARGET</filename>:
15731 <itemizedlist>
Andrew Geissler82c905d2020-04-13 13:39:40 -050015732 <listitem><para><emphasis>"qemu":</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015733 Boots a QEMU image and runs the tests.
15734 See the
15735 "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015736 section in the Yocto Project Development Tasks
15737 Manual for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015738 </para></listitem>
Andrew Geissler82c905d2020-04-13 13:39:40 -050015739 <listitem><para><emphasis>"simpleremote":</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015740 Runs the tests on target hardware that is already
15741 up and running.
15742 The hardware can be on the network or it can be
15743 a device running an image on QEMU.
15744 You must also set
15745 <link linkend='var-TEST_TARGET_IP'><filename>TEST_TARGET_IP</filename></link>
Andrew Geissler82c905d2020-04-13 13:39:40 -050015746 when you use "simpleremote".
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015747 <note>
15748 This argument is defined in
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015749 <filename>meta/lib/oeqa/controllers/simpleremote.py</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015750 </note>
15751 </para></listitem>
15752 </itemizedlist>
15753 </para>
15754
15755 <para>
15756 For information on running tests on hardware, see the
15757 "<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015758 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015759 </para>
15760 </glossdef>
15761 </glossentry>
15762
15763 <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>
15764 <info>
15765 TEST_TARGET_IP[doc] = "The IP address of your hardware under test."
15766 </info>
15767 <glossdef>
15768 <para role="glossdeffirst">
15769<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15770 The IP address of your hardware under test.
15771 The <filename>TEST_TARGET_IP</filename> variable has no
15772 effect when
15773 <link linkend='var-TEST_TARGET'><filename>TEST_TARGET</filename></link>
15774 is set to "qemu".
15775 </para>
15776
15777 <para>
15778 When you specify the IP address, you can also include a
15779 port.
15780 Here is an example:
15781 <literallayout class='monospaced'>
15782 TEST_TARGET_IP = "192.168.1.4:2201"
15783 </literallayout>
15784 Specifying a port is useful when SSH is started on a
15785 non-standard port or in cases when your hardware under test
15786 is behind a firewall or network that is not directly
15787 accessible from your host and you need to do port address
15788 translation.
15789 </para>
15790 </glossdef>
15791 </glossentry>
15792
15793 <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
15794 <info>
15795 TEST_SUITES[doc] = "An ordered list of tests (modules) to run against an image when performing automated runtime testing."
15796 </info>
15797 <glossdef>
15798 <para role="glossdeffirst">
15799<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15800 An ordered list of tests (modules) to run against
15801 an image when performing automated runtime testing.
15802 </para>
15803
15804 <para>
15805 The OpenEmbedded build system provides a core set of tests
15806 that can be used against images.
15807 <note>
15808 Currently, there is only support for running these tests
15809 under QEMU.
15810 </note>
15811 Tests include <filename>ping</filename>,
15812 <filename>ssh</filename>, <filename>df</filename> among
15813 others.
15814 You can add your own tests to the list of tests by
15815 appending <filename>TEST_SUITES</filename> as follows:
15816 <literallayout class='monospaced'>
15817 TEST_SUITES_append = " <replaceable>mytest</replaceable>"
15818 </literallayout>
15819 Alternatively, you can provide the "auto" option to
15820 have all applicable tests run against the image.
15821 <literallayout class='monospaced'>
15822 TEST_SUITES_append = " auto"
15823 </literallayout>
15824 Using this option causes the build system to automatically
15825 run tests that are applicable to the image.
15826 Tests that are not applicable are skipped.
15827 </para>
15828
15829 <para>
15830 The order in which tests are run is important.
15831 Tests that depend on another test must appear later in the
15832 list than the test on which they depend.
15833 For example, if you append the list of tests with two
15834 tests (<filename>test_A</filename> and
15835 <filename>test_B</filename>) where
15836 <filename>test_B</filename> is dependent on
15837 <filename>test_A</filename>, then you must order the tests
15838 as follows:
15839 <literallayout class='monospaced'>
15840 TEST_SUITES = " test_A test_B"
15841 </literallayout>
15842 </para>
15843
15844 <para>
15845 For more information on testing images, see the
15846 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015847 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015848 </para>
15849 </glossdef>
15850 </glossentry>
15851
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015852 <glossentry id='var-TESTIMAGE_AUTO'><glossterm>TESTIMAGE_AUTO</glossterm>
15853 <info>
15854 TESTIMAGE_AUTO[doc] = "Enables automatic testing of an image once it is built."
15855 </info>
15856 <glossdef>
15857 <para role="glossdeffirst">
15858<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15859 Automatically runs the series of automated tests for
15860 images when an image is successfully built.
15861 Setting <filename>TESTIMAGE_AUTO</filename> to "1"
15862 causes any image that successfully builds to automatically
15863 boot under QEMU.
15864 Using the variable also adds in dependencies so that any
15865 SDK for which testing is requested is automatically built
15866 first.
15867 </para>
15868
15869 <para>
15870 These tests are written in Python making use of the
15871 <filename>unittest</filename> module, and the majority of
15872 them run commands on the target system over
15873 <filename>ssh</filename>.
15874 You can set this variable to "1" in your
15875 <filename>local.conf</filename> file in the
15876 <link linkend='build-directory'>Build Directory</link>
15877 to have the OpenEmbedded build system automatically run
15878 these tests after an image successfully builds:
15879 <literallayout class='monospaced'>
15880 TESTIMAGE_AUTO = "1"
15881 </literallayout>
15882 For more information on enabling, running, and writing
15883 these tests, see the
15884 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
15885 section in the Yocto Project Development Tasks Manual and
15886 the
15887 "<link linkend='ref-classes-testimage*'><filename>testimage*.bbclass</filename></link>"
15888 section.
15889 </para>
15890 </glossdef>
15891 </glossentry>
15892
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015893 <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
15894 <info>
15895 THISDIR[doc] = "The directory in which the file BitBake is currently parsing is located."
15896 </info>
15897 <glossdef>
15898 <para role="glossdeffirst">
15899<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15900 The directory in which the file BitBake is currently
15901 parsing is located.
15902 Do not manually set this variable.
15903 </para>
15904 </glossdef>
15905 </glossentry>
15906
15907 <glossentry id='var-TIME'><glossterm>TIME</glossterm>
15908 <info>
15909 TIME[doc] = "The time the build was started using HMS format."
15910 </info>
15911 <glossdef>
15912 <para role="glossdeffirst">
15913<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15914 The time the build was started.
15915 Times appear using the hour, minute, and second (HMS)
15916 format (e.g. "140159" for one minute and fifty-nine
15917 seconds past 1400 hours).
15918 </para>
15919 </glossdef>
15920 </glossentry>
15921
15922 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
15923 <info>
15924 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."
15925 </info>
15926 <glossdef>
15927 <para role="glossdeffirst">
15928<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15929 This variable is the base directory the OpenEmbedded
15930 build system uses for all build output and intermediate
15931 files (other than the shared state cache).
15932 By default, the <filename>TMPDIR</filename> variable points
15933 to <filename>tmp</filename> within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015934 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015935 </para>
15936
15937 <para>
15938 If you want to establish this directory in a location other
15939 than the default, you can uncomment and edit the following
15940 statement in the
15941 <filename>conf/local.conf</filename> file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015942 <link linkend='source-directory'>Source Directory</link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015943 <literallayout class='monospaced'>
15944 #TMPDIR = "${TOPDIR}/tmp"
15945 </literallayout>
15946 An example use for this scenario is to set
15947 <filename>TMPDIR</filename> to a local disk, which does
15948 not use NFS, while having the Build Directory use NFS.
15949 </para>
15950
15951 <para>
15952 The filesystem used by <filename>TMPDIR</filename> must
15953 have standard filesystem semantics (i.e. mixed-case files
15954 are unique, POSIX file locking, and persistent inodes).
15955 Due to various issues with NFS and bugs in some
15956 implementations, NFS does not meet this minimum
15957 requirement.
15958 Consequently, <filename>TMPDIR</filename> cannot be on
15959 NFS.
15960 </para>
15961 </glossdef>
15962 </glossentry>
15963
15964 <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
15965 <info>
15966 TOOLCHAIN_HOST_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when building an SDK, which contains a cross-development environment."
15967 </info>
15968 <glossdef>
15969 <para role="glossdeffirst">
15970<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15971 This variable lists packages the OpenEmbedded build system
15972 uses when building an SDK, which contains a
15973 cross-development environment.
15974 The packages specified by this variable are part of the
15975 toolchain set that runs on the
15976 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
15977 and each package should usually have the prefix
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015978 <filename>nativesdk-</filename>.
15979 For example, consider the following command when
15980 building an SDK:
15981 <literallayout class='monospaced'>
15982 $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
15983 </literallayout>
15984 In this case, a default list of packages is set in this
15985 variable, but you can add additional packages to the list.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050015986 See the
15987 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual Packages to the Standard SDK</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015988 section in the Yocto Project Application Development and
15989 the Extensible Software Development Kit (eSDK) manual
15990 for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015991 </para>
15992
15993 <para>
15994 For background information on cross-development toolchains
15995 in the Yocto Project development environment, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040015996 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
15997 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015998 For information on setting up a cross-development
15999 environment, see the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016000 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
16001 manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016002 </para>
16003 </glossdef>
16004 </glossentry>
16005
16006 <glossentry id='var-TOOLCHAIN_OUTPUTNAME'><glossterm>TOOLCHAIN_OUTPUTNAME</glossterm>
16007 <info>
16008 TOOLCHAIN_OUTPUTNAME[doc] = "Defines the name used for the toolchain output."
16009 </info>
16010 <glossdef>
16011 <para role="glossdeffirst">
16012<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16013 This variable defines the name used for the toolchain
16014 output.
16015 The
16016 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
16017 class sets the
16018 <filename>TOOLCHAIN_OUTPUTNAME</filename> variable as
16019 follows:
16020 <literallayout class='monospaced'>
16021 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"
16022 </literallayout>
16023 See the
16024 <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
16025 and
16026 <link linkend='var-SDK_VERSION'><filename>SDK_VERSION</filename></link>
16027 variables for additional information.
16028 </para>
16029 </glossdef>
16030 </glossentry>
16031
16032 <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
16033 <info>
16034 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."
16035 </info>
16036 <glossdef>
16037 <para role="glossdeffirst">
16038<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16039 This variable lists packages the OpenEmbedded build system
16040 uses when it creates the target part of an SDK
16041 (i.e. the part built for the target hardware), which
16042 includes libraries and headers.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050016043 Use this variable to add individual packages to the
16044 part of the SDK that runs on the target.
16045 See the
16046 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual Packages to the Standard SDK</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016047 section in the Yocto Project Application Development and
16048 the Extensible Software Development Kit (eSDK) manual for
16049 more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016050 </para>
16051
16052 <para>
16053 For background information on cross-development toolchains
16054 in the Yocto Project development environment, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040016055 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
16056 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016057 For information on setting up a cross-development
16058 environment, see the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016059 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
16060 manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016061 </para>
16062 </glossdef>
16063 </glossentry>
16064
16065 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
16066 <info>
16067 TOPDIR[doc] = "The Build Directory. BitBake automatically sets this variable. The OpenEmbedded build system uses the Build Directory when building images."
16068 </info>
16069 <glossdef>
16070 <para role="glossdeffirst">
16071<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16072 The top-level
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016073 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016074 BitBake automatically sets this variable when you
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016075 initialize your build environment using
16076 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016077 </para>
16078 </glossdef>
16079 </glossentry>
16080
16081 <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
16082 <info>
16083 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."
16084 </info>
16085 <glossdef>
16086 <para role="glossdeffirst">
16087<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16088 A sanitized version of
16089 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
16090 This variable is used where the architecture is needed in
16091 a value where underscores are not allowed, for example
16092 within package filenames.
16093 In this case, dash characters replace any underscore
Brad Bishop316dfdd2018-06-25 12:45:53 -040016094 characters used in <filename>TARGET_ARCH</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016095 </para>
16096
16097 <para>
16098 Do not edit this variable.
16099 </para>
16100 </glossdef>
16101 </glossentry>
16102
16103 <glossentry id='var-TUNE_ARCH'><glossterm>TUNE_ARCH</glossterm>
16104 <info>
16105 TUNE_ARCH[doc] = "The GNU canonical architecture for a specific architecture (i.e. arm, armeb, mips, mips64, and so forth)."
16106 </info>
16107 <glossdef>
16108 <para role="glossdeffirst">
16109<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16110 The GNU canonical architecture for a specific architecture
16111 (i.e. <filename>arm</filename>,
16112 <filename>armeb</filename>,
16113 <filename>mips</filename>,
16114 <filename>mips64</filename>, and so forth).
16115 BitBake uses this value to setup configuration.
16116 </para>
16117
16118 <para>
16119 <filename>TUNE_ARCH</filename> definitions are specific to
16120 a given architecture.
16121 The definitions can be a single static definition, or
16122 can be dynamically adjusted.
16123 You can see details for a given CPU family by looking at
16124 the architecture's <filename>README</filename> file.
16125 For example, the
16126 <filename>meta/conf/machine/include/mips/README</filename>
16127 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016128 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016129 provides information for <filename>TUNE_ARCH</filename>
16130 specific to the <filename>mips</filename> architecture.
16131 </para>
16132
16133 <para>
16134 <filename>TUNE_ARCH</filename> is tied closely to
16135 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
16136 which defines the target machine's architecture.
16137 The BitBake configuration file
16138 (<filename>meta/conf/bitbake.conf</filename>) sets
16139 <filename>TARGET_ARCH</filename> as follows:
16140 <literallayout class='monospaced'>
16141 TARGET_ARCH = "${TUNE_ARCH}"
16142 </literallayout>
16143 </para>
16144
16145 <para>
16146 The following list, which is by no means complete since
16147 architectures are configurable, shows supported machine
16148 architectures:
16149 <literallayout class='monospaced'>
16150 arm
16151 i586
16152 x86_64
16153 powerpc
16154 powerpc64
16155 mips
16156 mipsel
16157 </literallayout>
16158 </para>
16159 </glossdef>
16160 </glossentry>
16161
16162 <glossentry id='var-TUNE_ASARGS'><glossterm>TUNE_ASARGS</glossterm>
16163 <info>
16164 TUNE_ASARGS[doc] = "Specifies architecture-specific assembler flags for the target system."
16165 </info>
16166 <glossdef>
16167 <para role="glossdeffirst">
16168<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16169 Specifies architecture-specific assembler flags for
16170 the target system.
16171 The set of flags is based on the selected tune features.
16172 <filename>TUNE_ASARGS</filename> is set using
16173 the tune include files, which are typically under
16174 <filename>meta/conf/machine/include/</filename> and are
16175 influenced through
16176 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
16177 For example, the
16178 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
16179 file defines the flags for the x86 architecture as follows:
16180 <literallayout class='monospaced'>
16181 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
16182 </literallayout>
16183 <note>
16184 Board Support Packages (BSPs) select the tune.
16185 The selected tune, in turn, affects the tune variables
16186 themselves (i.e. the tune can supply its own
16187 set of flags).
16188 </note>
16189 </para>
16190 </glossdef>
16191 </glossentry>
16192
16193 <glossentry id='var-TUNE_CCARGS'><glossterm>TUNE_CCARGS</glossterm>
16194 <info>
16195 TUNE_CCARGS[doc] = "Specifies architecture-specific C compiler flags for the target system."
16196 </info>
16197 <glossdef>
16198 <para role="glossdeffirst">
16199<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16200 Specifies architecture-specific C compiler flags for
16201 the target system.
16202 The set of flags is based on the selected tune features.
16203 <filename>TUNE_CCARGS</filename> is set using
16204 the tune include files, which are typically under
16205 <filename>meta/conf/machine/include/</filename> and are
16206 influenced through
16207 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
16208 <note>
16209 Board Support Packages (BSPs) select the tune.
16210 The selected tune, in turn, affects the tune variables
16211 themselves (i.e. the tune can supply its own
16212 set of flags).
16213 </note>
16214 </para>
16215 </glossdef>
16216 </glossentry>
16217
16218 <glossentry id='var-TUNE_LDARGS'><glossterm>TUNE_LDARGS</glossterm>
16219 <info>
16220 TUNE_LDARGS[doc] = "Specifies architecture-specific linker flags for the target system."
16221 </info>
16222 <glossdef>
16223 <para role="glossdeffirst">
16224<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16225 Specifies architecture-specific linker flags for
16226 the target system.
16227 The set of flags is based on the selected tune features.
16228 <filename>TUNE_LDARGS</filename> is set using
16229 the tune include files, which are typically under
16230 <filename>meta/conf/machine/include/</filename> and are
16231 influenced through
16232 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
16233 For example, the
16234 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
16235 file defines the flags for the x86 architecture as follows:
16236 <literallayout class='monospaced'>
16237 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
16238 </literallayout>
16239 <note>
16240 Board Support Packages (BSPs) select the tune.
16241 The selected tune, in turn, affects the tune variables
16242 themselves (i.e. the tune can supply its own
16243 set of flags).
16244 </note>
16245 </para>
16246 </glossdef>
16247 </glossentry>
16248
16249 <glossentry id='var-TUNE_FEATURES'><glossterm>TUNE_FEATURES</glossterm>
16250 <info>
16251 TUNE_FEATURES[doc] = "Features used to "tune" a compiler for optimal use given a specific processor."
16252 </info>
16253 <glossdef>
16254 <para role="glossdeffirst">
16255<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16256 Features used to "tune" a compiler for optimal use
16257 given a specific processor.
16258 The features are defined within the tune files and allow
16259 arguments (i.e. <filename>TUNE_*ARGS</filename>) to be
16260 dynamically generated based on the features.
16261 </para>
16262
16263 <para>
16264 The OpenEmbedded build system verifies the features
16265 to be sure they are not conflicting and that they are
16266 supported.
16267 </para>
16268
16269 <para>
16270 The BitBake configuration file
16271 (<filename>meta/conf/bitbake.conf</filename>) defines
16272 <filename>TUNE_FEATURES</filename> as follows:
16273 <literallayout class='monospaced'>
16274 TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}"
16275 </literallayout>
16276 See the
16277 <link linkend='var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></link>
16278 variable for more information.
16279 </para>
16280 </glossdef>
16281 </glossentry>
16282
16283 <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
16284 <info>
16285 TUNE_PKGARCH[doc] = "The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages."
16286 </info>
16287 <glossdef>
16288 <para role="glossdeffirst">
16289<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16290 The package architecture understood by the packaging
16291 system to define the architecture, ABI, and tuning of
16292 output packages.
16293 The specific tune is defined using the "_tune" override
16294 as follows:
16295 <literallayout class='monospaced'>
16296 TUNE_PKGARCH_tune-<replaceable>tune</replaceable> = "<replaceable>tune</replaceable>"
16297 </literallayout>
16298 </para>
16299
16300 <para>
16301 These tune-specific package architectures are defined in
16302 the machine include files.
16303 Here is an example of the "core2-32" tuning as used
16304 in the
16305 <filename>meta/conf/machine/include/tune-core2.inc</filename>
16306 file:
16307 <literallayout class='monospaced'>
16308 TUNE_PKGARCH_tune-core2-32 = "core2-32"
16309 </literallayout>
16310 </para>
16311 </glossdef>
16312 </glossentry>
16313
16314 <glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm>
16315 <info>
16316 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."
16317 </info>
16318 <glossdef>
16319 <para role="glossdeffirst">
16320<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16321 An underlying Application Binary Interface (ABI) used by
16322 a particular tuning in a given toolchain layer.
16323 Providers that use prebuilt libraries can use the
16324 <filename>TUNEABI</filename>,
16325 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
16326 and
16327 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
16328 variables to check compatibility of tunings against their
16329 selection of libraries.
16330 </para>
16331
16332 <para>
16333 If <filename>TUNEABI</filename> is undefined, then every
16334 tuning is allowed.
16335 See the
16336 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
16337 class to see how the variable is used.
16338 </para>
16339 </glossdef>
16340 </glossentry>
16341
16342 <glossentry id='var-TUNEABI_OVERRIDE'><glossterm>TUNEABI_OVERRIDE</glossterm>
16343 <info>
16344 TUNEABI_OVERRIDE[doc] = "If set, ignores TUNEABI_WHITELIST."
16345 </info>
16346 <glossdef>
16347 <para role="glossdeffirst">
16348<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16349 If set, the OpenEmbedded system ignores the
16350 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
16351 variable.
16352 Providers that use prebuilt libraries can use the
16353 <filename>TUNEABI_OVERRIDE</filename>,
16354 <filename>TUNEABI_WHITELIST</filename>,
16355 and
16356 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
16357 variables to check compatibility of a tuning against their
16358 selection of libraries.
16359 </para>
16360
16361 <para>
16362 See the
16363 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
16364 class to see how the variable is used.
16365 </para>
16366 </glossdef>
16367 </glossentry>
16368
16369 <glossentry id='var-TUNEABI_WHITELIST'><glossterm>TUNEABI_WHITELIST</glossterm>
16370 <info>
16371 TUNEABI_WHITELIST[doc] = "A whitelist of permissible TUNEABI values. If the variable is not set, all values are allowed."
16372 </info>
16373 <glossdef>
16374 <para role="glossdeffirst">
16375<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16376 A whitelist of permissible
16377 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
16378 values.
16379 If <filename>TUNEABI_WHITELIST</filename> is not set,
16380 all tunes are allowed.
16381 Providers that use prebuilt libraries can use the
16382 <filename>TUNEABI_WHITELIST</filename>,
16383 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
16384 and <filename>TUNEABI</filename> variables to check
16385 compatibility of a tuning against their selection of
16386 libraries.
16387 </para>
16388
16389 <para>
16390 See the
16391 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
16392 class to see how the variable is used.
16393 </para>
16394 </glossdef>
16395 </glossentry>
16396
16397 <glossentry id='var-TUNECONFLICTS'><glossterm>TUNECONFLICTS[<replaceable>feature</replaceable>]</glossterm>
16398 <info>
16399 TUNECONFLICTS[doc] = "Specifies CPU or Application Binary Interface (ABI) tuning features that conflict with specified feature."
16400 </info>
16401 <glossdef>
16402 <para role="glossdeffirst">
16403<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16404 Specifies CPU or Application Binary Interface (ABI)
16405 tuning features that conflict with <replaceable>feature</replaceable>.
16406 </para>
16407
16408 <para>
16409 Known tuning conflicts are specified in the machine include
16410 files in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016411 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016412 Here is an example from the
16413 <filename>meta/conf/machine/include/mips/arch-mips.inc</filename>
16414 include file that lists the "o32" and "n64" features as
16415 conflicting with the "n32" feature:
16416 <literallayout class='monospaced'>
16417 TUNECONFLICTS[n32] = "o32 n64"
16418 </literallayout>
16419 </para>
16420 </glossdef>
16421 </glossentry>
16422
16423 <glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[<replaceable>feature</replaceable>]</glossterm>
16424 <info>
16425 TUNEVALID[doc] = "Descriptions, stored as flags, of valid tuning features."
16426 </info>
16427 <glossdef>
16428 <para role="glossdeffirst">
16429<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16430 Specifies a valid CPU or Application Binary Interface (ABI)
16431 tuning feature.
16432 The specified feature is stored as a flag.
16433 Valid features are specified in the machine include files
16434 (e.g. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>).
16435 Here is an example from that file:
16436 <literallayout class='monospaced'>
16437 TUNEVALID[bigendian] = "Enable big-endian mode."
16438 </literallayout>
16439 </para>
16440
16441 <para>
16442 See the machine include files in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016443 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016444 for these features.
16445 </para>
16446 </glossdef>
16447 </glossentry>
16448
16449 </glossdiv>
16450
16451 <glossdiv id='var-glossary-u'><title>U</title>
16452
16453 <glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm>
16454 <info>
16455 UBOOT_CONFIG[doc] = "Configures the UBOOT_MACHINE and can also define IMAGE_FSTYPES for individual cases."
16456 </info>
16457 <glossdef>
16458 <para role="glossdeffirst">
16459<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16460 Configures the
16461 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
16462 and can also define
16463 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
16464 for individual cases.
16465 </para>
16466
16467 <para>
16468 Following is an example from the
16469 <filename>meta-fsl-arm</filename> layer.
16470 <literallayout class='monospaced'>
16471 UBOOT_CONFIG ??= "sd"
16472 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
16473 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
16474 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
16475 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
16476 </literallayout>
16477 In this example, "sd" is selected as the configuration
16478 of the possible four for the
16479 <filename>UBOOT_MACHINE</filename>.
16480 The "sd" configuration defines "mx6qsabreauto_config"
16481 as the value for <filename>UBOOT_MACHINE</filename>, while
16482 the "sdcard" specifies the
16483 <filename>IMAGE_FSTYPES</filename> to use for the U-boot
16484 image.
16485 </para>
16486
16487 <para>
16488 For more information on how the
16489 <filename>UBOOT_CONFIG</filename> is handled, see the
16490 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass'><filename>uboot-config</filename></ulink>
16491 class.
16492 </para>
16493 </glossdef>
16494 </glossentry>
16495
16496 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
16497 <info>
16498 UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image."
16499 </info>
16500 <glossdef>
16501 <para role="glossdeffirst">
16502<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16503 Specifies the entry point for the U-Boot image.
16504 During U-Boot image creation, the
16505 <filename>UBOOT_ENTRYPOINT</filename> variable is passed
16506 as a command-line parameter to the
16507 <filename>uboot-mkimage</filename> utility.
16508 </para>
16509 </glossdef>
16510 </glossentry>
16511
16512 <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
16513 <info>
16514 UBOOT_LOADADDRESS[doc] = "Specifies the load address for the U-Boot image."
16515 </info>
16516 <glossdef>
16517 <para role="glossdeffirst">
16518<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16519 Specifies the load address for the U-Boot image.
16520 During U-Boot image creation, the
16521 <filename>UBOOT_LOADADDRESS</filename> variable is passed
16522 as a command-line parameter to the
16523 <filename>uboot-mkimage</filename> utility.
16524 </para>
16525 </glossdef>
16526 </glossentry>
16527
16528 <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>
16529 <info>
16530 UBOOT_LOCALVERSION[doc] = "Appends a string to the name of the local version of the U-Boot image."
16531 </info>
16532 <glossdef>
16533 <para role="glossdeffirst">
16534<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16535 Appends a string to the name of the local version of the
16536 U-Boot image.
16537 For example, assuming the version of the U-Boot image
Andrew Geissler82c905d2020-04-13 13:39:40 -050016538 built was "2013.10", the full version string reported by
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016539 U-Boot would be "2013.10-yocto" given the following
16540 statement:
16541 <literallayout class='monospaced'>
16542 UBOOT_LOCALVERSION = "-yocto"
16543 </literallayout>
16544 </para>
16545 </glossdef>
16546 </glossentry>
16547
16548 <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
16549 <info>
16550 UBOOT_MACHINE[doc] = "Specifies the value passed on the make command line when building a U-Boot image."
16551 </info>
16552 <glossdef>
16553 <para role="glossdeffirst">
16554<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16555 Specifies the value passed on the
16556 <filename>make</filename> command line when building
16557 a U-Boot image.
16558 The value indicates the target platform configuration.
16559 You typically set this variable from the machine
16560 configuration file (i.e.
16561 <filename>conf/machine/<replaceable>machine_name</replaceable>.conf</filename>).
16562 </para>
16563
16564 <para>
16565 Please see the "Selection of Processor Architecture and
16566 Board Type" section in the U-Boot README for valid values
16567 for this variable.
16568 </para>
16569 </glossdef>
16570 </glossentry>
16571
16572 <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm>
16573 <info>
16574 UBOOT_MAKE_TARGET[doc] = "Specifies the target called in the Makefile."
16575 </info>
16576 <glossdef>
16577 <para role="glossdeffirst">
16578<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16579 Specifies the target called in the
16580 <filename>Makefile</filename>.
16581 The default target is "all".
16582 </para>
16583 </glossdef>
16584 </glossentry>
16585
16586 <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>
16587 <info>
16588 UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension."
16589 </info>
16590 <glossdef>
16591 <para role="glossdeffirst">
16592<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16593 Points to the generated U-Boot extension.
16594 For example, <filename>u-boot.sb</filename> has a
16595 <filename>.sb</filename> extension.
16596 </para>
16597
16598 <para>
16599 The default U-Boot extension is
16600 <filename>.bin</filename>
16601 </para>
16602 </glossdef>
16603 </glossentry>
16604
16605 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
16606 <info>
16607 UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot."
16608 </info>
16609 <glossdef>
16610 <para role="glossdeffirst">
16611<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16612 Specifies the target used for building U-Boot.
16613 The target is passed directly as part of the "make" command
16614 (e.g. SPL and AIS).
16615 If you do not specifically set this variable, the
16616 OpenEmbedded build process passes and uses "all" for the
16617 target during the U-Boot building process.
16618 </para>
16619 </glossdef>
16620 </glossentry>
16621
16622 <glossentry id='var-UNKNOWN_CONFIGURE_WHITELIST'><glossterm>UNKNOWN_CONFIGURE_WHITELIST</glossterm>
16623 <info>
16624 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."
16625 </info>
16626 <glossdef>
16627 <para role="glossdeffirst">
16628<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16629 Specifies a list of options that, if reported by the
16630 configure script as being invalid, should not generate a
16631 warning during the
16632 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
16633 task.
16634 Normally, invalid configure options are simply not passed
16635 to the configure script (e.g. should be removed from
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016636 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
16637 or
16638 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>).
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016639 However, common options, for example, exist that are passed
16640 to all configure scripts at a class level that might not
16641 be valid for some configure scripts.
16642 It follows that no benefit exists in seeing a warning about
16643 these options.
16644 For these cases, the options are added to
16645 <filename>UNKNOWN_CONFIGURE_WHITELIST</filename>.
16646 </para>
16647
16648 <para>
16649 The configure arguments check that uses
16650 <filename>UNKNOWN_CONFIGURE_WHITELIST</filename> is part
16651 of the
16652 <link linkend='ref-classes-insane'><filename>insane</filename></link>
16653 class and is only enabled if the recipe inherits the
16654 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
16655 class.
16656 </para>
16657 </glossdef>
16658 </glossentry>
16659
16660 <glossentry id='var-UPDATERCPN'><glossterm>UPDATERCPN</glossterm>
16661 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040016662 UPDATERCPN[doc] = "Specifies the package that contains the initscript that is enabled."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016663 </info>
16664 <glossdef>
16665 <para role="glossdeffirst">
16666<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16667 For recipes inheriting the
16668 <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
16669 class, <filename>UPDATERCPN</filename> specifies
Brad Bishop316dfdd2018-06-25 12:45:53 -040016670 the package that contains the initscript that is
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016671 enabled.
16672 </para>
16673
16674 <para>
16675 The default value is "${PN}".
16676 Given that almost all recipes that install initscripts
16677 package them in the main package for the recipe, you
16678 rarely need to set this variable in individual recipes.
16679 </para>
16680 </glossdef>
16681 </glossentry>
16682
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016683 <glossentry id='var-UPSTREAM_CHECK_GITTAGREGEX'><glossterm>UPSTREAM_CHECK_GITTAGREGEX</glossterm>
16684 <info>
16685 UPSTREAM_CHECK_GITTAGREGEX[doc] = "Filters relevant Git tags when fetching source from an upstream Git repository."
16686 </info>
16687 <glossdef>
16688 <para role="glossdeffirst">
16689<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop15ae2502019-06-18 21:44:24 -040016690 You can perform a per-recipe check for what the latest
16691 upstream source code version is by calling
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016692 <filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.
16693 If the recipe source code is provided from Git
16694 repositories, the OpenEmbedded build system determines the
16695 latest upstream version by picking the latest tag from the
16696 list of all repository tags.
Brad Bishop15ae2502019-06-18 21:44:24 -040016697 </para>
16698
16699 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016700 You can use the
16701 <filename>UPSTREAM_CHECK_GITTAGREGEX</filename>
16702 variable to provide a regular expression to filter only the
16703 relevant tags should the default filter not work
16704 correctly.
16705 <literallayout class='monospaced'>
16706 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"
16707 </literallayout>
16708 </para>
16709 </glossdef>
16710 </glossentry>
16711
16712 <glossentry id='var-UPSTREAM_CHECK_REGEX'><glossterm>UPSTREAM_CHECK_REGEX</glossterm>
16713 <info>
16714 UPSTREAM_CHECK_REGEX[doc] = "The regular expression the package checking system uses to parse the page pointed to by UPSTREAM_CHECK_URI."
16715 </info>
16716 <glossdef>
16717 <para role="glossdeffirst">
16718<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop15ae2502019-06-18 21:44:24 -040016719 Use the <filename>UPSTREAM_CHECK_REGEX</filename> variable
16720 to specify a different regular expression instead of the
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016721 default one when the package checking system is parsing
16722 the page found using
16723 <link linkend='var-UPSTREAM_CHECK_URI'><filename>UPSTREAM_CHECK_URI</filename></link>.
16724 <literallayout class='monospaced'>
16725 UPSTREAM_CHECK_REGEX = "package_regex"
16726 </literallayout>
16727 </para>
16728 </glossdef>
16729 </glossentry>
16730
16731 <glossentry id='var-UPSTREAM_CHECK_URI'><glossterm>UPSTREAM_CHECK_URI</glossterm>
16732 <info>
16733 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."
16734 </info>
16735 <glossdef>
16736 <para role="glossdeffirst">
16737<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop15ae2502019-06-18 21:44:24 -040016738 You can perform a per-recipe check for what the latest
16739 upstream source code version is by calling
16740 <filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016741 If the source code is provided from tarballs, the latest
16742 version is determined by fetching the directory listing
16743 where the tarball is and attempting to find a later tarball.
16744 When this approach does not work, you can use
16745 <filename>UPSTREAM_CHECK_URI</filename> to
16746 provide a different URI that contains the link to the
16747 latest tarball.
16748 <literallayout class='monospaced'>
16749 UPSTREAM_CHECK_URI = "recipe_url"
16750 </literallayout>
16751 </para>
16752 </glossdef>
16753 </glossentry>
16754
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016755 <glossentry id='var-USE_DEVFS'><glossterm>USE_DEVFS</glossterm>
16756 <info>
16757 USE_DEVFS[doc] = "Determines if devtmpfs is used for /dev population."
16758 </info>
16759 <glossdef>
16760 <para role="glossdeffirst">
16761<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16762 Determines if <filename>devtmpfs</filename> is used for
16763 <filename>/dev</filename> population.
16764 The default value used for <filename>USE_DEVFS</filename>
16765 is "1" when no value is specifically set.
16766 Typically, you would set <filename>USE_DEVFS</filename>
16767 to "0" for a statically populated <filename>/dev</filename>
16768 directory.
16769 </para>
16770
16771 <para>
16772 See the
16773 "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-dev-manager'>Selecting a Device Manager</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016774 section in the Yocto Project Development Tasks Manual for
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016775 information on how to use this variable.
16776 </para>
16777 </glossdef>
16778 </glossentry>
16779
16780 <glossentry id='var-USE_VT'><glossterm>USE_VT</glossterm>
16781 <info>
16782 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."
16783 </info>
16784 <glossdef>
16785 <para role="glossdeffirst">
16786<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16787 When using
16788 <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
16789 determines whether or not to run a
16790 <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
16791 on any virtual terminals in order to enable logging in
16792 through those terminals.
16793 </para>
16794
16795 <para>
16796 The default value used for <filename>USE_VT</filename>
16797 is "1" when no default value is specifically set.
16798 Typically, you would set <filename>USE_VT</filename>
16799 to "0" in the machine configuration file for machines
16800 that do not have a graphical display attached and
16801 therefore do not need virtual terminal functionality.
16802 </para>
16803 </glossdef>
16804 </glossentry>
16805
16806 <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
16807 <info>
16808 USER_CLASSES[doc] = "List of additional classes to use when building images that enable extra features."
16809 </info>
16810 <glossdef>
16811 <para role="glossdeffirst">
16812<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16813 A list of classes to globally inherit.
16814 These classes are used by the OpenEmbedded build system
16815 to enable extra features (e.g.
16816 <filename>buildstats</filename>,
16817 <filename>image-mklibs</filename>, and so forth).
16818 </para>
16819
16820 <para>
16821 The default list is set in your
16822 <filename>local.conf</filename> file:
16823 <literallayout class='monospaced'>
16824 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
16825 </literallayout>
16826 For more information, see
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050016827 <filename>meta-poky/conf/local.conf.sample</filename> in
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016828 the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016829 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016830 </para>
16831 </glossdef>
16832 </glossentry>
16833
16834 <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>
16835 <info>
Andrew Geissler82c905d2020-04-13 13:39:40 -050016836 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016837 </info>
16838 <glossdef>
16839 <para role="glossdeffirst">
16840<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Andrew Geissler82c905d2020-04-13 13:39:40 -050016841
16842 If set to <filename>error</filename>, forces the
16843 OpenEmbedded build system to produce an error if the user
16844 identification (<filename>uid</filename>) and group
16845 identification (<filename>gid</filename>) values are not
16846 defined in any of the files listed
16847 in <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
16848 and <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>. If
16849 set to <filename>warn</filename>, a warning will be issued
16850 instead.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016851 </para>
16852
16853 <para>
16854 The default behavior for the build system is to dynamically
16855 apply <filename>uid</filename> and
16856 <filename>gid</filename> values.
16857 Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>
16858 variable is by default not set.
16859 If you plan on using statically assigned
16860 <filename>gid</filename> and <filename>uid</filename>
16861 values, you should set
16862 the <filename>USERADD_ERROR_DYNAMIC</filename> variable in
16863 your <filename>local.conf</filename> file as
16864 follows:
16865 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016866 USERADD_ERROR_DYNAMIC = "error"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016867 </literallayout>
16868 Overriding the default behavior implies you are going to
16869 also take steps to set static <filename>uid</filename> and
16870 <filename>gid</filename> values through use of the
16871 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
16872 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
16873 and
16874 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
16875 variables.
16876 </para>
Andrew Geissler82c905d2020-04-13 13:39:40 -050016877
16878 <note>
16879 There is a difference in behavior between
16880 setting <filename>USERADD_ERROR_DYNAMIC</filename>
16881 to <filename>error</filename> and setting it
16882 to <filename>warn</filename>. When it is set
16883 to <filename>warn</filename>, the build system will report a
16884 warning for every undefined <filename>uid</filename> and
16885 <filename>gid</filename> in any recipe. But when it is set
16886 to <filename>error</filename>, it will only report errors
16887 for recipes that are actually built. This saves you from
16888 having to add static IDs for recipes that you know will
16889 never be built.
16890 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016891 </glossdef>
16892 </glossentry>
16893
16894 <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>
16895 <info>
16896 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."
16897 </info>
16898 <glossdef>
16899 <para role="glossdeffirst">
16900<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16901 Specifies a password file to use for obtaining static
16902 group identification (<filename>gid</filename>) values
16903 when the OpenEmbedded build system adds a group to the
16904 system during package installation.
16905 </para>
16906
16907 <para>
16908 When applying static group identification
16909 (<filename>gid</filename>) values, the OpenEmbedded build
16910 system looks in
16911 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
16912 for a <filename>files/group</filename> file and then applies
16913 those <filename>uid</filename> values.
16914 Set the variable as follows in your
16915 <filename>local.conf</filename> file:
16916 <literallayout class='monospaced'>
16917 USERADD_GID_TABLES = "files/group"
16918 </literallayout>
16919 </para>
16920
16921 <note>
16922 Setting the
16923 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
16924 variable to "useradd-staticids" causes the build system
16925 to use static <filename>gid</filename> values.
16926 </note>
16927 </glossdef>
16928 </glossentry>
16929
16930 <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>
16931 <info>
16932 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."
16933 </info>
16934 <glossdef>
16935 <para role="glossdeffirst">
16936<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16937 When inheriting the
16938 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
16939 class, this variable
16940 specifies the individual packages within the recipe that
16941 require users and/or groups to be added.
16942 </para>
16943
16944 <para>
16945 You must set this variable if the recipe inherits the
16946 class.
16947 For example, the following enables adding a user for the
16948 main package in a recipe:
16949 <literallayout class='monospaced'>
16950 USERADD_PACKAGES = "${PN}"
16951 </literallayout>
16952 <note>
Andrew Geissler99467da2019-02-25 18:54:23 -060016953 It follows that if you are going to use the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016954 <filename>USERADD_PACKAGES</filename> variable,
16955 you need to set one or more of the
16956 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
16957 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
16958 or
16959 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
16960 variables.
16961 </note>
16962 </para>
16963
16964 </glossdef>
16965 </glossentry>
16966
16967 <glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>
16968 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040016969 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016970 </info>
16971 <glossdef>
16972 <para role="glossdeffirst">
16973<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16974 When inheriting the
16975 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
16976 class, this variable
Brad Bishop316dfdd2018-06-25 12:45:53 -040016977 specifies for a package what parameters should pass
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016978 to the <filename>useradd</filename> command
Brad Bishop316dfdd2018-06-25 12:45:53 -040016979 if you add a user to the system when the package
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016980 is installed.
16981 </para>
16982
16983 <para>
16984 Here is an example from the <filename>dbus</filename>
16985 recipe:
16986 <literallayout class='monospaced'>
16987 USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \
16988 --no-create-home --shell /bin/false \
16989 --user-group messagebus"
16990 </literallayout>
16991 For information on the standard Linux shell command
16992 <filename>useradd</filename>, see
16993 <ulink url='http://linux.die.net/man/8/useradd'></ulink>.
16994 </para>
16995 </glossdef>
16996 </glossentry>
16997
16998 <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>
16999 <info>
17000 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."
17001 </info>
17002 <glossdef>
17003 <para role="glossdeffirst">
17004<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17005 Specifies a password file to use for obtaining static
17006 user identification (<filename>uid</filename>) values
17007 when the OpenEmbedded build system adds a user to the
17008 system during package installation.
17009 </para>
17010
17011 <para>
17012 When applying static user identification
17013 (<filename>uid</filename>) values, the OpenEmbedded build
17014 system looks in
17015 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
17016 for a <filename>files/passwd</filename> file and then applies
17017 those <filename>uid</filename> values.
17018 Set the variable as follows in your
17019 <filename>local.conf</filename> file:
17020 <literallayout class='monospaced'>
17021 USERADD_UID_TABLES = "files/passwd"
17022 </literallayout>
17023 </para>
17024
17025 <note>
17026 Setting the
17027 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
17028 variable to "useradd-staticids" causes the build system
17029 to use static <filename>uid</filename> values.
17030 </note>
17031 </glossdef>
17032 </glossentry>
17033
17034 <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>
17035 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060017036 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."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017037 </info>
17038 <glossdef>
17039 <para role="glossdeffirst">
17040<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17041 When set to "useradd-staticids", causes the
17042 OpenEmbedded build system to base all user and group
17043 additions on a static
17044 <filename>passwd</filename> and
17045 <filename>group</filename> files found in
17046 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
17047 </para>
17048
17049 <para>
17050 To use static user identification (<filename>uid</filename>)
17051 and group identification (<filename>gid</filename>)
17052 values, set the variable
17053 as follows in your <filename>local.conf</filename> file:
17054 <literallayout class='monospaced'>
17055 USERADDEXTENSION = "useradd-staticids"
17056 </literallayout>
17057 <note>
17058 Setting this variable to use static
17059 <filename>uid</filename> and <filename>gid</filename>
17060 values causes the OpenEmbedded build system to employ
17061 the
Patrick Williamsf1e5d692016-03-30 15:21:19 -050017062 <link linkend='ref-classes-useradd'><filename>useradd-staticids</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017063 class.
17064 </note>
17065 </para>
17066
17067 <para>
17068 If you use static <filename>uid</filename> and
17069 <filename>gid</filename> information, you must also
17070 specify the <filename>files/passwd</filename> and
17071 <filename>files/group</filename> files by setting the
17072 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
17073 and
17074 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
17075 variables.
17076 Additionally, you should also set the
17077 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
17078 variable.
17079 </para>
17080 </glossdef>
17081 </glossentry>
17082
17083 </glossdiv>
17084
Brad Bishop6e60e8b2018-02-01 10:27:11 -050017085 <glossdiv id='var-glossary-v'><title>V</title>
17086
17087 <glossentry id='var-VOLATILE_LOG_DIR'><glossterm>VOLATILE_LOG_DIR</glossterm>
17088 <info>
17089 VOLATILE_LOG_DIR[doc] = "Specifies the persistence of the target's /var/log directory, which is used to house postinstall target log files."
17090 </info>
17091 <glossdef>
17092 <para role="glossdeffirst">
17093<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17094 Specifies the persistence of the target's
17095 <filename>/var/log</filename> directory, which is used to
17096 house postinstall target log files.
17097 </para>
17098
17099 <para>
17100 By default, <filename>VOLATILE_LOG_DIR</filename> is set
17101 to "yes", which means the file is not persistent.
17102 You can override this setting by setting the
17103 variable to "no" to make the log directory persistent.
17104 </para>
17105 </glossdef>
17106 </glossentry>
17107
17108 </glossdiv>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017109
17110 <glossdiv id='var-glossary-w'><title>W</title>
17111
17112 <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
17113 <info>
17114 WARN_QA[doc] = "Specifies the quality assurance checks whose failures are reported as warnings by the OpenEmbedded build system."
17115 </info>
17116 <glossdef>
17117 <para role="glossdeffirst">
17118<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17119 Specifies the quality assurance checks whose failures are
17120 reported as warnings by the OpenEmbedded build system.
17121 You set this variable in your distribution configuration
17122 file.
17123 For a list of the checks you can control with this variable,
17124 see the
17125 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
17126 section.
17127 </para>
17128 </glossdef>
17129 </glossentry>
17130
Brad Bishop6e60e8b2018-02-01 10:27:11 -050017131 <glossentry id='var-WKS_FILE_DEPENDS'><glossterm>WKS_FILE_DEPENDS</glossterm>
17132 <info>
17133 WKS_FILE_DEPENDS[doc] = "Lists a recipe's build-time dependencies specific to Wic."
17134 </info>
17135 <glossdef>
17136 <para role="glossdeffirst">
17137 When placed in the recipe that builds your image, this
17138 variable lists build-time dependencies.
17139 The <filename>WKS_FILE_DEPENDS</filename> variable is only
17140 applicable when Wic images are active (i.e. when
17141 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
17142 contains entries related to Wic).
17143 If your recipe does not create Wic images, the variable
17144 has no effect.
17145 </para>
17146
17147 <para>
17148 The <filename>WKS_FILE_DEPENDS</filename> variable is
17149 similar to the
17150 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
17151 variable.
17152 When you use the variable in your recipe that builds the
17153 Wic image, dependencies you list in the
17154 <filename>WIC_FILE_DEPENDS</filename> variable are added to
17155 the <filename>DEPENDS</filename> variable.
17156 </para>
17157
17158 <para>
17159 With the <filename>WKS_FILE_DEPENDS</filename> variable,
17160 you have the possibility to specify a list of additional
17161 dependencies (e.g. native tools, bootloaders, and so forth),
17162 that are required to build Wic images.
17163 Following is an example:
17164 <literallayout class='monospaced'>
17165 WKS_FILE_DEPENDS = "<replaceable>some-native-tool</replaceable>"
17166 </literallayout>
17167 In the previous example,
17168 <replaceable>some-native-tool</replaceable> would be
17169 replaced with an actual native tool on which the build
17170 would depend.
17171 </para>
17172 </glossdef>
17173 </glossentry>
17174
Brad Bishop37a0e4d2017-12-04 01:01:44 -050017175 <glossentry id='var-WKS_FILE'><glossterm>WKS_FILE</glossterm>
17176 <info>
17177 WKS_FILE[doc] = "Specifies the name of the wic kickstart file."
17178 </info>
17179 <glossdef>
17180 <para role="glossdeffirst">
17181 Specifies the location of the Wic
17182 kickstart file that is used by the OpenEmbedded build
17183 system to create a partitioned image
17184 (<replaceable>image</replaceable><filename>.wic</filename>).
Brad Bishopd7bf8c12018-02-25 22:55:05 -050017185 For information on how to create a partitioned image, see
17186 the
17187 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
17188 section in the Yocto Project Development Tasks Manual.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050017189 For details on the kickstart file format, see the
Andrew Geissler82c905d2020-04-13 13:39:40 -050017190 "<link linkend='ref-kickstart'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</link>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050017191 Chapter.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050017192 </para>
17193 </glossdef>
17194 </glossentry>
17195
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017196 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
17197 <info>
17198 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."
17199 </info>
17200 <glossdef>
17201 <para role="glossdeffirst">
17202<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17203 The pathname of the work directory in which the OpenEmbedded
17204 build system builds a recipe.
17205 This directory is located within the
17206 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
17207 directory structure and is specific to the recipe being
17208 built and the system for which it is being built.
17209 </para>
17210
17211 <para>
17212 The <filename>WORKDIR</filename> directory is defined as
17213 follows:
17214 <literallayout class='monospaced'>
17215 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
17216 </literallayout>
17217 The actual directory depends on several things:
17218 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -040017219 <listitem><filename>TMPDIR</filename>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017220 The top-level build output directory</listitem>
17221 <listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>:
17222 The target system identifier</listitem>
17223 <listitem><link linkend='var-PN'><filename>PN</filename></link>:
17224 The recipe name</listitem>
17225 <listitem><link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>:
17226 The epoch - (if
17227 <link linkend='var-PE'><filename>PE</filename></link>
17228 is not specified, which is usually the case for most
17229 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
17230 <listitem><link linkend='var-PV'><filename>PV</filename></link>:
17231 The recipe version</listitem>
17232 <listitem><link linkend='var-PR'><filename>PR</filename></link>:
17233 The recipe revision</listitem>
17234 </itemizedlist>
17235 </para>
17236
17237 <para>
17238 As an example, assume a Source Directory top-level folder
17239 name <filename>poky</filename>, a default Build Directory at
17240 <filename>poky/build</filename>, and a
17241 <filename>qemux86-poky-linux</filename> machine target
17242 system.
17243 Furthermore, suppose your recipe is named
17244 <filename>foo_1.3.0-r0.bb</filename>.
17245 In this case, the work directory the build system uses to
17246 build the package would be as follows:
17247 <literallayout class='monospaced'>
17248 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
17249 </literallayout>
17250 </para>
17251 </glossdef>
17252 </glossentry>
17253
17254 </glossdiv>
17255
17256 <glossdiv id='var-glossary-x'><title>X</title>
17257
17258 <glossentry id='var-XSERVER'><glossterm>XSERVER</glossterm>
17259 <info>
Andrew Geissler82c905d2020-04-13 13:39:40 -050017260 XSERVER[doc] = "Specifies the packages that should be installed to provide an X server and drivers for the current machine."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017261 </info>
17262 <glossdef>
17263 <para role="glossdeffirst">
17264<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17265 Specifies the packages that should be installed to
17266 provide an X server and drivers for the current machine,
17267 assuming your image directly includes
17268 <filename>packagegroup-core-x11-xserver</filename> or,
17269 perhaps indirectly, includes "x11-base" in
17270 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
17271 </para>
17272
17273 <para>
17274 The default value of <filename>XSERVER</filename>, if not
17275 specified in the machine configuration, is
17276 "xserver-xorg xf86-video-fbdev xf86-input-evdev".
17277 </para>
17278 </glossdef>
17279 </glossentry>
17280
17281 </glossdiv>
17282
17283<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
17284<!-- </glossdiv>-->
17285
17286<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
17287<!-- </glossdiv>-->
17288
17289</glossary>
17290</chapter>
17291<!--
17292vim: expandtab tw=80 ts=4
17293-->