blob: 12876e3d9af17d1a86bd07cebe5ff62cd201b028 [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" /> -->
338 The minimal command and arguments used to run the
339 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>
370 ASSUME_SHLIBS[doc] = Provides additional shlibs provider mapping information, which adds to or overwrites the information provided automatically by the system."
371 </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
498 <glossentry id='var-AVAILTUNES'><glossterm>AVAILTUNES</glossterm>
499 <info>
500 AVAILTUNES[doc] = "The list of defined CPU and Application Binary Interface (ABI) tunings (i.e. "tunes") available for use by the OpenEmbedded build system."
501 </info>
502 <glossdef>
503 <para role="glossdeffirst">
504<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
505 The list of defined CPU and Application Binary Interface
506 (ABI) tunings (i.e. "tunes") available for use by the
507 OpenEmbedded build system.
508 </para>
509
510 <para>
511 The list simply presents the tunes that are available.
512 Not all tunes may be compatible with a particular
513 machine configuration, or with each other in a
514 <ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Multilib</ulink>
515 configuration.
516 </para>
517
518 <para>
519 To add a tune to the list, be sure to append it with
520 spaces using the "+=" BitBake operator.
521 Do not simply replace the list by using the "=" operator.
522 See the
523 "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>"
524 section in the BitBake User Manual for more information.
525 </para>
526 </glossdef>
527 </glossentry>
528
529 </glossdiv>
530
531 <glossdiv id='var-glossary-b'><title>B</title>
532
533 <glossentry id='var-B'><glossterm>B</glossterm>
534 <info>
535 B[doc] = "The Build Directory. The OpenEmbedded build system places generated objects into the Build Directory during a recipe's build process."
536 </info>
537 <glossdef>
538 <para role="glossdeffirst">
539<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
540 The directory within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500541 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500542 in which the OpenEmbedded build system places generated
543 objects during a recipe's build process.
544 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
545 directory, which is defined as:
546 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600547 S = "${WORKDIR}/${BP}"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500548 </literallayout>
549 </para>
550
551 <para>
552 You can separate the (<filename>S</filename>) directory
553 and the directory pointed to by the <filename>B</filename>
554 variable.
555 Most Autotools-based recipes support separating these
556 directories.
557 The build system defaults to using separate directories for
558 <filename>gcc</filename> and some kernel recipes.
559 </para>
560 </glossdef>
561 </glossentry>
562
563 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
564 <info>
565 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."
566 </info>
567 <glossdef>
568 <para role="glossdeffirst">
569<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
570 Lists "recommended-only" packages to not install.
571 Recommended-only packages are packages installed only
572 through the
573 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
574 variable.
575 You can prevent any of these "recommended" packages from
576 being installed by listing them with the
577 <filename>BAD_RECOMMENDATIONS</filename> variable:
578 <literallayout class='monospaced'>
579 BAD_RECOMMENDATIONS = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."
580 </literallayout>
581 </para>
582
583 <para>
584 You can set this variable globally in your
585 <filename>local.conf</filename> file or you can attach it to
586 a specific image recipe by using the recipe name override:
587 <literallayout class='monospaced'>
588 BAD_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"
589 </literallayout>
590 </para>
591
592 <para>
593 It is important to realize that if you choose to not install
594 packages using this variable and some other packages are
595 dependent on them (i.e. listed in a recipe's
596 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
597 variable), the OpenEmbedded build system ignores your
598 request and will install the packages to avoid dependency
599 errors.
600 </para>
601
602 <para>
603 Support for this variable exists only when using the
604 IPK and RPM packaging backend.
605 Support does not exist for DEB.
606 </para>
607
608 <para>
609 See the
610 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
611 and the
612 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
613 variables for related information.
614 </para>
615 </glossdef>
616 </glossentry>
617
618 <glossentry id='var-BASE_LIB'><glossterm>BASE_LIB</glossterm>
619 <info>
620 BASE_LIB[doc] = "The library directory name for the CPU or Application Binary Interface (ABI) tune."
621 </info>
622 <glossdef>
623 <para role="glossdeffirst">
624<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
625 The library directory name for the CPU or Application
626 Binary Interface (ABI) tune.
627 The <filename>BASE_LIB</filename> applies only in the
628 Multilib context.
629 See the
630 "<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 -0500631 section in the Yocto Project Development Tasks Manual for
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500632 information on Multilib.
633 </para>
634
635 <para>
636 The <filename>BASE_LIB</filename> variable is defined in
637 the machine include files in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500638 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500639 If Multilib is not being used, the value defaults to "lib".
640 </para>
641 </glossdef>
642 </glossentry>
643
644 <glossentry id='var-BASE_WORKDIR'><glossterm>BASE_WORKDIR</glossterm>
645 <info>
646 BASE_WORKDIR[doc] = "Points to the base of the work directory for all recipes."
647 </info>
648 <glossdef>
649 <para role="glossdeffirst">
650<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
651 Points to the base of the work directory for all recipes.
652 The default value is "${TMPDIR}/work".
653 </para>
654 </glossdef>
655 </glossentry>
656
657 <glossentry id='var-BB_ALLOWED_NETWORKS'><glossterm>BB_ALLOWED_NETWORKS</glossterm>
658 <info>
659 BB_ALLOWED_NETWORKS[doc] = "A list of hosts that the fetcher is allowed to use to obtain the required source code."
660 </info>
661 <glossdef>
662 <para>
663 Specifies a space-delimited list of hosts that the fetcher
664 is allowed to use to obtain the required source code.
665 Following are considerations surrounding this variable:
666 <itemizedlist>
667 <listitem><para>
668 This host list is only used if
669 <filename>BB_NO_NETWORK</filename> is either not
670 set or set to "0".
671 </para></listitem>
672 <listitem><para>
673 Limited support for wildcard matching against the
674 beginning of host names exists.
675 For example, the following setting matches
676 <filename>git.gnu.org</filename>,
677 <filename>ftp.gnu.org</filename>, and
678 <filename>foo.git.gnu.org</filename>.
679 <literallayout class='monospaced'>
680 BB_ALLOWED_NETWORKS = "*.gnu.org"
681 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800682 <note><title>Important</title>
683 <para>The use of the "<filename>*</filename>"
684 character only works at the beginning of
685 a host name and it must be isolated from
686 the remainder of the host name.
687 You cannot use the wildcard character in any
688 other location of the name or combined with
689 the front part of the name.</para>
690
691 <para>For example,
692 <filename>*.foo.bar</filename> is supported,
693 while <filename>*aa.foo.bar</filename> is not.
694 </para>
695 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500696 </para></listitem>
697 <listitem><para>
698 Mirrors not in the host list are skipped and
699 logged in debug.
700 </para></listitem>
701 <listitem><para>
702 Attempts to access networks not in the host list
703 cause a failure.
704 </para></listitem>
705 </itemizedlist>
706 Using <filename>BB_ALLOWED_NETWORKS</filename> in
707 conjunction with
708 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
709 is very useful.
710 Adding the host you want to use to
711 <filename>PREMIRRORS</filename> results in the source code
712 being fetched from an allowed location and avoids raising
713 an error when a host that is not allowed is in a
714 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
715 statement.
716 This is because the fetcher does not attempt to use the
717 host listed in <filename>SRC_URI</filename> after a
718 successful fetch from the
719 <filename>PREMIRRORS</filename> occurs.
720 </para>
721 </glossdef>
722 </glossentry>
723
724 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
725 <info>
726 BB_DANGLINGAPPENDS_WARNONLY[doc] = "Defines how BitBake handles situations where an append file (.bbappend) has no corresponding recipe file (.bb)."
727 </info>
728 <glossdef>
729 <para role="glossdeffirst">
730<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
731 Defines how BitBake handles situations where an append
732 file (<filename>.bbappend</filename>) has no
733 corresponding recipe file (<filename>.bb</filename>).
734 This condition often occurs when layers get out of sync
735 (e.g. <filename>oe-core</filename> bumps a
736 recipe version and the old recipe no longer exists and the
737 other layer has not been updated to the new version
738 of the recipe yet).
739 </para>
740
741 <para>
742 The default fatal behavior is safest because it is
743 the sane reaction given something is out of sync.
744 It is important to realize when your changes are no longer
745 being applied.
746 </para>
747
748 <para>
749 You can change the default behavior by setting this
750 variable to "1", "yes", or "true"
751 in your <filename>local.conf</filename> file, which is
752 located in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500753 <link linkend='build-directory'>Build Directory</link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500754 Here is an example:
755 <literallayout class='monospaced'>
756 BB_DANGLINGAPPENDS_WARNONLY = "1"
757 </literallayout>
758 </para>
759 </glossdef>
760 </glossentry>
761
762 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
763 <info>
764 BB_DISKMON_DIRS[doc] = "Monitors disk space and available inodes during the build and allows you to control the build based on these parameters."
765 </info>
766 <glossdef>
767 <para role="glossdeffirst">
768<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
769 Monitors disk space and available inodes during the build
770 and allows you to control the build based on these
771 parameters.
772 </para>
773
774 <para>
775 Disk space monitoring is disabled by default.
776 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
777 variable to your <filename>conf/local.conf</filename> file found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500778 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500779 Use the following form:
780 <literallayout class='monospaced'>
781 BB_DISKMON_DIRS = "<replaceable>action</replaceable>,<replaceable>dir</replaceable>,<replaceable>threshold</replaceable> [...]"
782
783 where:
784
785 <replaceable>action</replaceable> is:
786 ABORT: Immediately abort the build when
787 a threshold is broken.
788 STOPTASKS: Stop the build after the currently
789 executing tasks have finished when
790 a threshold is broken.
791 WARN: Issue a warning but continue the
792 build when a threshold is broken.
793 Subsequent warnings are issued as
Brad Bishop316dfdd2018-06-25 12:45:53 -0400794 defined by the BB_DISKMON_WARNINTERVAL
795 variable, which must be defined in
796 the conf/local.conf file.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500797
798 <replaceable>dir</replaceable> is:
799 Any directory you choose. You can specify one or
800 more directories to monitor by separating the
801 groupings with a space. If two directories are
802 on the same device, only the first directory
803 is monitored.
804
805 <replaceable>threshold</replaceable> is:
806 Either the minimum available disk space,
807 the minimum number of free inodes, or
808 both. You must specify at least one. To
809 omit one or the other, simply omit the value.
810 Specify the threshold using G, M, K for Gbytes,
811 Mbytes, and Kbytes, respectively. If you do
812 not specify G, M, or K, Kbytes is assumed by
813 default. Do not use GB, MB, or KB.
814 </literallayout>
815 </para>
816
817 <para>
818 Here are some examples:
819 <literallayout class='monospaced'>
820 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
821 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
822 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
823 </literallayout>
824 The first example works only if you also provide
825 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
826 in the <filename>conf/local.conf</filename>.
827 This example causes the build system to immediately
828 abort when either the disk space in <filename>${TMPDIR}</filename> drops
829 below 1 Gbyte or the available free inodes drops below
830 100 Kbytes.
831 Because two directories are provided with the variable, the
832 build system also issue a
833 warning when the disk space in the
834 <filename>${SSTATE_DIR}</filename> directory drops
835 below 1 Gbyte or the number of free inodes drops
836 below 100 Kbytes.
837 Subsequent warnings are issued during intervals as
838 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
839 variable.
840 </para>
841
842 <para>
843 The second example stops the build after all currently
844 executing tasks complete when the minimum disk space
845 in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
846 directory drops below 1 Gbyte.
847 No disk monitoring occurs for the free inodes in this case.
848 </para>
849
850 <para>
851 The final example immediately aborts the build when the
852 number of free inodes in the <filename>${TMPDIR}</filename> directory
853 drops below 100 Kbytes.
854 No disk space monitoring for the directory itself occurs
855 in this case.
856 </para>
857 </glossdef>
858 </glossentry>
859
860 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
861 <info>
862 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."
863 </info>
864 <glossdef>
865 <para role="glossdeffirst">
866<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
867 Defines the disk space and free inode warning intervals.
868 To set these intervals, define the variable in your
869 <filename>conf/local.conf</filename> file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500870 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500871 </para>
872
873 <para>
874 If you are going to use the
875 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
876 also use the
877 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
878 and define its action as "WARN".
879 During the build, subsequent warnings are issued each time
880 disk space or number of free inodes further reduces by
881 the respective interval.
882 </para>
883
884 <para>
885 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
886 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
887 the "WARN" action, the disk monitoring interval defaults to
888 the following:
889 <literallayout class='monospaced'>
890 BB_DISKMON_WARNINTERVAL = "50M,5K"
891 </literallayout>
892 </para>
893
894 <para>
895 When specifying the variable in your configuration file,
896 use the following form:
897 <literallayout class='monospaced'>
898 BB_DISKMON_WARNINTERVAL = "<replaceable>disk_space_interval</replaceable>,<replaceable>disk_inode_interval</replaceable>"
899
900 where:
901
902 <replaceable>disk_space_interval</replaceable> is:
903 An interval of memory expressed in either
904 G, M, or K for Gbytes, Mbytes, or Kbytes,
905 respectively. You cannot use GB, MB, or KB.
906
907 <replaceable>disk_inode_interval</replaceable> is:
908 An interval of free inodes expressed in either
909 G, M, or K for Gbytes, Mbytes, or Kbytes,
910 respectively. You cannot use GB, MB, or KB.
911 </literallayout>
912 </para>
913
914 <para>
915 Here is an example:
916 <literallayout class='monospaced'>
917 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
918 BB_DISKMON_WARNINTERVAL = "50M,5K"
919 </literallayout>
920 These variables cause the OpenEmbedded build system to
921 issue subsequent warnings each time the available
922 disk space further reduces by 50 Mbytes or the number
923 of free inodes further reduces by 5 Kbytes in the
924 <filename>${SSTATE_DIR}</filename> directory.
925 Subsequent warnings based on the interval occur each time
926 a respective interval is reached beyond the initial warning
927 (i.e. 1 Gbytes and 100 Kbytes).
928 </para>
929 </glossdef>
930 </glossentry>
931
932 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
933 <info>
Brad Bishopd89cb5f2019-04-10 09:02:41 -0400934 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 -0500935 </info>
936 <glossdef>
937 <para role="glossdeffirst">
938<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd89cb5f2019-04-10 09:02:41 -0400939 Causes tarballs of the source control repositories
940 (e.g. Git repositories), including metadata, to be placed
941 in the
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500942 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
943 directory.
944 </para>
945
946 <para>
947 For performance reasons, creating and placing tarballs of
Brad Bishopd89cb5f2019-04-10 09:02:41 -0400948 these repositories is not the default action by the
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500949 OpenEmbedded build system.
950 <literallayout class='monospaced'>
951 BB_GENERATE_MIRROR_TARBALLS = "1"
952 </literallayout>
953 Set this variable in your <filename>local.conf</filename>
954 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500955 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500956 </para>
Brad Bishopd89cb5f2019-04-10 09:02:41 -0400957
958 <para>
959 Once you have the tarballs containing your source files,
960 you can clean up your <filename>DL_DIR</filename>
961 directory by deleting any Git or other source control
962 work directories.
963 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500964 </glossdef>
965 </glossentry>
966
967 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
968 <info>
969 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."
970 </info>
971 <glossdef>
972 <para role="glossdeffirst">
973<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
974 The maximum number of tasks BitBake should run in parallel
975 at any one time.
976 The OpenEmbedded build system automatically configures
977 this variable to be equal to the number of cores on the
978 build system.
979 For example, a system with a dual core processor that
980 also uses hyper-threading causes the
981 <filename>BB_NUMBER_THREADS</filename> variable to default
982 to "4".
983 </para>
984
985 <para>
986 For single socket systems (i.e. one CPU), you should not
987 have to override this variable to gain optimal parallelism
988 during builds.
989 However, if you have very large systems that employ
990 multiple physical CPUs, you might want to make sure the
991 <filename>BB_NUMBER_THREADS</filename> variable is not
992 set higher than "20".
993 </para>
994
995 <para>
996 For more information on speeding up builds, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400997 "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"
998 section in the Yocto Project Development Tasks Manual.
999 </para>
1000 </glossdef>
1001 </glossentry>
1002
1003 <glossentry id='var-BB_SERVER_TIMEOUT'><glossterm>BB_SERVER_TIMEOUT</glossterm>
1004 <info>
1005 BB_SERVER_TIMEOUT [doc] = "Specifies the time (in seconds) after which to unload the BitBake server due to inactivity."
1006 </info>
1007 <glossdef>
1008 <para role="glossdeffirst">
1009<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1010 Specifies the time (in seconds) after which to unload the
1011 BitBake server due to inactivity.
1012 Set <filename>BB_SERVER_TIMEOUT</filename> to determine how
1013 long the BitBake server stays resident between invocations.
1014 </para>
1015
1016 <para>
1017 For example, the following statement in your
1018 <filename>local.conf</filename> file instructs the server
1019 to be unloaded after 20 seconds of inactivity:
1020 <literallayout class='monospaced'>
1021 BB_SERVER_TIMEOUT = "20"
1022 </literallayout>
1023 If you want the server to never be unloaded, set
1024 <filename>BB_SERVER_TIMEOUT</filename> to "-1".
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001025 </para>
1026 </glossdef>
1027 </glossentry>
1028
1029 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
1030 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001031 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 -05001032 </info>
1033 <glossdef>
1034 <para role="glossdeffirst">
1035<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1036 Allows you to extend a recipe so that it builds variants of the software.
1037 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
1038 which is a copy of Quilt built to run on the build system;
1039 "crosses" such as <filename>gcc-cross</filename>,
1040 which is a compiler built to run on the build machine but produces binaries
1041 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
1042 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
1043 and "mulitlibs" in the form "<filename>multilib:</filename><replaceable>multilib_name</replaceable>".
1044 </para>
1045
1046 <para>
1047 To build a different variant of the recipe with a minimal amount of code, it usually
1048 is as simple as adding the following to your recipe:
1049 <literallayout class='monospaced'>
1050 BBCLASSEXTEND =+ "native nativesdk"
1051 BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>"
1052 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001053 <note>
1054 <para>
1055 Internally, the <filename>BBCLASSEXTEND</filename>
1056 mechanism generates recipe variants by rewriting
1057 variable values and applying overrides such as
1058 <filename>_class-native</filename>.
1059 For example, to generate a native version of a recipe,
1060 a
1061 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1062 on "foo" is rewritten to a <filename>DEPENDS</filename>
1063 on "foo-native".
1064 </para>
1065
1066 <para>
1067 Even when using <filename>BBCLASSEXTEND</filename>, the
1068 recipe is only parsed once.
1069 Parsing once adds some limitations.
1070 For example, it is not possible to
1071 include a different file depending on the variant,
1072 since <filename>include</filename> statements are
1073 processed when the recipe is parsed.
1074 </para>
1075 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001076 </para>
1077 </glossdef>
1078 </glossentry>
1079
1080 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
1081 <info>
1082 BBFILE_COLLECTIONS[doc] = "Lists the names of configured layers. These names are used to find the other BBFILE_* variables."
1083 </info>
1084 <glossdef>
1085 <para role="glossdeffirst">
1086<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1087 Lists the names of configured layers.
1088 These names are used to find the other <filename>BBFILE_*</filename>
1089 variables.
1090 Typically, each layer will append its name to this variable in its
1091 <filename>conf/layer.conf</filename> file.
1092 </para>
1093 </glossdef>
1094 </glossentry>
1095
1096 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
1097 <info>
1098 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."
1099 </info>
1100 <glossdef>
1101 <para role="glossdeffirst">
1102<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1103 Variable that expands to match files from
1104 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
1105 in a particular layer.
1106 This variable is used in the <filename>conf/layer.conf</filename> file and must
1107 be suffixed with the name of the specific layer (e.g.
1108 <filename>BBFILE_PATTERN_emenlow</filename>).
1109 </para>
1110 </glossdef>
1111 </glossentry>
1112
1113 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
1114 <info>
1115 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."
1116 </info>
1117 <glossdef>
1118 <para role="glossdeffirst">
1119<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1120 Assigns the priority for recipe files in each layer.
1121 </para>
1122
1123 <para>
1124 This variable is useful in situations where the same recipe appears in
1125 more than one layer.
1126 Setting this variable allows you to prioritize a
1127 layer against other layers that contain the same recipe - effectively
1128 letting you control the precedence for the multiple layers.
1129 The precedence established through this variable stands regardless of a
1130 recipe's version
1131 (<link linkend='var-PV'><filename>PV</filename></link> variable).
1132 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
1133 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
1134 lower precedence.
1135 </para>
1136
1137 <para>
1138 A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
1139 precedence.
1140 For example, the value 6 has a higher precedence than the value 5.
1141 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
1142 dependencies (see the
1143 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
1144 more information.
1145 The default priority, if unspecified
1146 for a layer with no dependencies, is the lowest defined priority + 1
1147 (or 1 if no priorities are defined).
1148 </para>
1149 <tip>
1150 You can use the command <filename>bitbake-layers show-layers</filename> to list
1151 all configured layers along with their priorities.
1152 </tip>
1153 </glossdef>
1154 </glossentry>
1155
1156 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
1157 <info>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001158 BBFILES[doc] = "A space-separated list of recipe files BitBake uses to build software."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001159 </info>
1160 <glossdef>
1161 <para role="glossdeffirst">
1162<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001163 A space-separated list of recipe files BitBake uses to
1164 build software.
1165 </para>
1166
1167 <para>
1168 When specifying recipe files, you can pattern match using
1169 Python's
1170 <ulink url='https://docs.python.org/3/library/glob.html'><filename>glob</filename></ulink>
1171 syntax.
1172 For details on the syntax, see the documentation by
1173 following the previous link.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001174 </para>
1175 </glossdef>
1176 </glossentry>
1177
Brad Bishop316dfdd2018-06-25 12:45:53 -04001178 <glossentry id='var-BBFILES_DYNAMIC'><glossterm>BBFILES_DYNAMIC</glossterm>
1179 <info>
1180 BBFILES_DYNAMIC[doc] = "Activates content when identified layers are present."
1181 </info>
1182 <glossdef>
1183 <para role="glossdeffirst">
1184<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1185 Activates content when identified layers are present.
1186 You identify the layers by the collections that the layers
1187 define.
1188 </para>
1189
1190 <para>
1191 Use the <filename>BBFILES_DYNAMIC</filename> variable to
1192 avoid <filename>.bbappend</filename> files whose
1193 corresponding <filename>.bb</filename> file is in a layer
1194 that attempts to modify other layers through
1195 <filename>.bbappend</filename> but does not want to
1196 introduce a hard dependency on those other layers.
1197 </para>
1198
1199 <para>
1200 Use the following form for
1201 <filename>BBFILES_DYNAMIC</filename>:
1202 <literallayout class='monospaced'>
1203 <replaceable>collection_name</replaceable>:<replaceable>filename_pattern</replaceable>
1204 </literallayout>
1205 The following example identifies two collection names and
1206 two filename patterns:
1207 <literallayout class='monospaced'>
1208 BBFILES_DYNAMIC += " \
1209 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
1210 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
1211 "
1212 </literallayout>
1213 This next example shows an error message that occurs
1214 because invalid entries are found, which cause parsing to
1215 abort:
1216 <literallayout class='monospaced'>
1217 ERROR: BBFILES_DYNAMIC entries must be of the form &lt;collection name&gt;:&lt;filename pattern&gt;, not:
1218 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
1219 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
1220 </literallayout>
1221 </para>
1222 </glossdef>
1223 </glossentry>
1224
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001225 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
1226 <info>
1227 BBINCLUDELOGS[doc] = "Variable that controls how BitBake displays logs on build failure."
1228 </info>
1229 <glossdef>
1230 <para role="glossdeffirst">
1231<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1232 Variable that controls how BitBake displays logs on build failure.
1233 </para>
1234 </glossdef>
1235 </glossentry>
1236
1237 <glossentry id='var-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm>
1238 <info>
1239 BBINCLUDELOGS_LINES[doc] = "Amount of log lines printed on failure."
1240 </info>
1241 <glossdef>
1242 <para role="glossdeffirst">
1243<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1244 If
1245 <link linkend='var-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link>
1246 is set, specifies the maximum number of lines from the
1247 task log file to print when reporting a failed task.
1248 If you do not set <filename>BBINCLUDELOGS_LINES</filename>,
1249 the entire log is printed.
1250 </para>
1251 </glossdef>
1252 </glossentry>
1253
1254 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
1255 <info>
1256 BBLAYERS[doc] = "Lists the layers to enable during the build. This variable is defined in the bblayers.conf configuration file."
1257 </info>
1258 <glossdef>
1259 <para role="glossdeffirst">
1260<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1261 Lists the layers to enable during the build.
1262 This variable is defined in the <filename>bblayers.conf</filename> configuration
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001263 file in the
1264 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001265 Here is an example:
1266 <literallayout class='monospaced'>
1267 BBLAYERS = " \
1268 /home/scottrif/poky/meta \
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001269 /home/scottrif/poky/meta-poky \
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001270 /home/scottrif/poky/meta-yocto-bsp \
1271 /home/scottrif/poky/meta-mykernel \
1272 "
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001273 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001274 </para>
1275
1276 <para>
1277 This example enables four layers, one of which is a custom, user-defined layer
1278 named <filename>meta-mykernel</filename>.
1279 </para>
1280 </glossdef>
1281 </glossentry>
1282
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001283 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
1284 <info>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001285 BBMASK[doc] = "Prevents BitBake from processing specific recipes or recipe append files."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001286 </info>
1287 <glossdef>
1288 <para role="glossdeffirst">
1289<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1290 Prevents BitBake from processing recipes and recipe
1291 append files.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001292 </para>
1293
1294 <para>
1295 You can use the <filename>BBMASK</filename> variable
1296 to "hide" these <filename>.bb</filename> and
1297 <filename>.bbappend</filename> files.
1298 BitBake ignores any recipe or recipe append files that
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001299 match any of the expressions.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001300 It is as if BitBake does not see them at all.
1301 Consequently, matching files are not parsed or otherwise
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001302 used by BitBake.
1303 </para>
1304
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001305 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001306 The values you provide are passed to Python's regular
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001307 expression compiler.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001308 Consequently, the syntax follows Python's Regular
1309 Expression (re) syntax.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001310 The expressions are compared against the full paths to
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001311 the files.
1312 For complete syntax information, see Python's
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001313 documentation at
1314 <ulink url='http://docs.python.org/3/library/re.html#re'></ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001315 </para>
1316
1317 <para>
1318 The following example uses a complete regular expression
1319 to tell BitBake to ignore all recipe and recipe append
1320 files in the <filename>meta-ti/recipes-misc/</filename>
1321 directory:
1322 <literallayout class='monospaced'>
1323 BBMASK = "meta-ti/recipes-misc/"
1324 </literallayout>
1325 If you want to mask out multiple directories or recipes,
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001326 you can specify multiple regular expression fragments.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001327 This next example masks out multiple directories and
1328 individual recipes:
1329 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001330 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
1331 BBMASK += "/meta-oe/recipes-support/"
1332 BBMASK += "/meta-foo/.*/openldap"
1333 BBMASK += "opencv.*\.bbappend"
1334 BBMASK += "lzma"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001335 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001336 <note>
1337 When specifying a directory name, use the trailing
1338 slash character to ensure you match just that directory
1339 name.
1340 </note>
1341 </para>
1342 </glossdef>
1343 </glossentry>
1344
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001345 <glossentry id='var-BBMULTICONFIG'><glossterm>BBMULTICONFIG</glossterm>
1346 <info>
1347 BBMULTICONFIG[doc] = "Specifies each separate configuration when you are building targets with multiple configurations."
1348 </info>
1349 <glossdef>
1350 <para role="glossdeffirst">
1351<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1352 Specifies each separate configuration when you are
1353 building targets with multiple configurations.
1354 Use this variable in your
1355 <filename>conf/local.conf</filename> configuration file.
1356 Specify a <replaceable>multiconfigname</replaceable> for
1357 each configuration file you are using.
1358 For example, the following line specifies three
1359 configuration files:
1360 <literallayout class='monospaced'>
1361 BBMULTIFONFIG = "configA configB configC"
1362 </literallayout>
1363 Each configuration file you use must reside in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001364 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001365 <filename>conf/multiconfig</filename> directory
1366 (e.g.
1367 <replaceable>build_directory</replaceable><filename>/conf/multiconfig/configA.conf</filename>).
1368 </para>
1369
1370 <para>
1371 For information on how to use
1372 <filename>BBMULTICONFIG</filename> in an environment that
1373 supports building targets with multiple configurations,
1374 see the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001375 "<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 -05001376 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001377 </para>
1378 </glossdef>
1379 </glossentry>
1380
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001381 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
1382 <info>
1383 BBPATH[doc] = "Used by BitBake to locate .bbclass and configuration files. This variable is analogous to the PATH variable."
1384 </info>
1385 <glossdef>
1386 <para role="glossdeffirst">
1387<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1388 Used by BitBake to locate
1389 <filename>.bbclass</filename> and configuration files.
1390 This variable is analogous to the
1391 <filename>PATH</filename> variable.
1392 <note>
1393 If you run BitBake from a directory outside of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001394 <link linkend='build-directory'>Build Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001395 you must be sure to set
1396 <filename>BBPATH</filename> to point to the
1397 Build Directory.
1398 Set the variable as you would any environment variable
1399 and then run BitBake:
1400 <literallayout class='monospaced'>
1401 $ BBPATH = "<replaceable>build_directory</replaceable>"
1402 $ export BBPATH
1403 $ bitbake <replaceable>target</replaceable>
1404 </literallayout>
1405 </note>
1406 </para>
1407 </glossdef>
1408 </glossentry>
1409
1410 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
1411 <info>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001412 BBSERVER[doc] = "Points to the BitBake remote server."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001413 </info>
1414 <glossdef>
1415 <para role="glossdeffirst">
1416<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001417 If defined in the BitBake environment,
1418 <filename>BBSERVER</filename> points to the BitBake
1419 remote server.
1420 </para>
1421
1422 <para>
1423 Use the following format to export the variable to the
1424 BitBake environment:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001425 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001426 export BBSERVER=localhost:$port"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001427 </literallayout>
1428 </para>
1429
1430 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001431 By default, <filename>BBSERVER</filename> also appears in
1432 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink>.
1433 Consequently, <filename>BBSERVER</filename> is excluded
1434 from checksum and dependency data.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001435 </para>
1436 </glossdef>
1437 </glossentry>
1438
1439 <glossentry id='var-BINCONFIG'><glossterm>BINCONFIG</glossterm>
1440 <info>
1441 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."
1442 </info>
1443 <glossdef>
1444 <para role="glossdeffirst">
1445<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1446 When inheriting the
1447 <link linkend='ref-classes-binconfig-disabled'><filename>binconfig-disabled</filename></link>
1448 class, this variable specifies binary configuration
1449 scripts to disable in favor of using
1450 <filename>pkg-config</filename> to query the information.
1451 The <filename>binconfig-disabled</filename> class will
1452 modify the specified scripts to return an error so that
1453 calls to them can be easily found and replaced.
1454 </para>
1455
1456 <para>
1457 To add multiple scripts, separate them by spaces.
1458 Here is an example from the <filename>libpng</filename>
1459 recipe:
1460 <literallayout class='monospaced'>
1461 BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"
1462 </literallayout>
1463 </para>
1464 </glossdef>
1465 </glossentry>
1466
1467 <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
1468 <info>
1469 BINCONFIG_GLOB[doc] = "When inheriting binconfig.bbclass from a recipe, this variable specifies a wildcard for configuration scripts that need editing."
1470 </info>
1471 <glossdef>
1472 <para role="glossdeffirst">
1473<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1474 When inheriting the
1475 <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
1476 class, this variable specifies a wildcard for
1477 configuration scripts that need editing.
1478 The scripts are edited to correct any paths that have been
1479 set up during compilation so that they are correct for
1480 use when installed into the sysroot and called by the
1481 build processes of other recipes.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001482 <note>
1483 The <filename>BINCONFIG_GLOB</filename> variable
1484 uses
1485 <ulink url='http://tldp.org/LDP/abs/html/globbingref.html'>shell globbing</ulink>,
1486 which is recognition and expansion of wildcards during
1487 pattern matching.
1488 Shell globbing is very similar to
1489 <ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>
1490 and
1491 <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>.
1492 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001493 </para>
1494
1495 <para>
1496 For more information on how this variable works, see
1497 <filename>meta/classes/binconfig.bbclass</filename> in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001498 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001499 You can also find general information on the class in the
1500 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
1501 section.
1502 </para>
1503 </glossdef>
1504 </glossentry>
1505
1506 <glossentry id='var-BP'><glossterm>BP</glossterm>
1507 <info>
1508 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}"
1509 </info>
1510 <glossdef>
1511 <para role="glossdeffirst">
1512<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1513 The base recipe name and version but without any special
1514 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
1515 and so forth).
1516 <filename>BP</filename> is comprised of the following:
1517 <literallayout class="monospaced">
1518 ${BPN}-${PV}
1519 </literallayout>
1520 </para>
1521 </glossdef>
1522 </glossentry>
1523
1524 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
1525 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001526 BPN[doc] = "This variable is a version of the PN variable but removes common suffixes and prefixes."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001527 </info>
1528 <glossdef>
1529 <para role="glossdeffirst">
1530<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001531 This variable is a version of the
1532 <link linkend='var-PN'><filename>PN</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001533 variable with common prefixes and suffixes
1534 removed, such as <filename>nativesdk-</filename>,
1535 <filename>-cross</filename>,
1536 <filename>-native</filename>, and multilib's
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001537 <filename>lib64-</filename> and
1538 <filename>lib32-</filename>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001539 The exact lists of prefixes and suffixes removed are
1540 specified by the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001541 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001542 and
1543 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link>
1544 variables, respectively.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001545 </para>
1546 </glossdef>
1547 </glossentry>
1548
1549 <glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm>
1550 <info>
1551 BUGTRACKER[doc] = "Specifies a URL for an upstream bug tracking website for a recipe."
1552 </info>
1553 <glossdef>
1554 <para role="glossdeffirst">
1555<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1556 Specifies a URL for an upstream bug tracking website for
1557 a recipe.
1558 The OpenEmbedded build system does not use this variable.
1559 Rather, the variable is a useful pointer in case a bug
1560 in the software being built needs to be manually reported.
1561 </para>
1562 </glossdef>
1563 </glossentry>
1564
1565 <glossentry id='var-BUILD_ARCH'><glossterm>BUILD_ARCH</glossterm>
1566 <info>
1567 BUILD_ARCH[doc] = "The name of the building architecture (e.g. i686)."
1568 </info>
1569 <glossdef>
1570 <para role="glossdeffirst">
1571<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1572 Specifies the architecture of the build host
1573 (e.g. <filename>i686</filename>).
1574 The OpenEmbedded build system sets the value of
1575 <filename>BUILD_ARCH</filename> from the machine name
1576 reported by the <filename>uname</filename> command.
1577 </para>
1578 </glossdef>
1579 </glossentry>
1580
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001581 <glossentry id='var-BUILD_AS_ARCH'><glossterm>BUILD_AS_ARCH</glossterm>
1582 <info>
1583 BUILD_AS_ARCH[doc] = "Specifies the architecture-specific assembler flags for the build host."
1584 </info>
1585 <glossdef>
1586 <para role="glossdeffirst">
1587<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1588 Specifies the architecture-specific assembler flags for
1589 the build host. By default, the value of
1590 <filename>BUILD_AS_ARCH</filename> is empty.
1591 </para>
1592 </glossdef>
1593 </glossentry>
1594
1595 <glossentry id='var-BUILD_CC_ARCH'><glossterm>BUILD_CC_ARCH</glossterm>
1596 <info>
1597 BUILD_CC_ARCH[doc] = "Specifies the architecture-specific C compiler flags for the build host."
1598 </info>
1599 <glossdef>
1600 <para role="glossdeffirst">
1601<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1602 Specifies the architecture-specific C compiler flags for
1603 the build host. By default, the value of
1604 <filename>BUILD_CC_ARCH</filename> is empty.
1605 </para>
1606 </glossdef>
1607 </glossentry>
1608
1609 <glossentry id='var-BUILD_CCLD'><glossterm>BUILD_CCLD</glossterm>
1610 <info>
1611 BUILD_CCLD[doc] = "Specifies the linker command to be used for the build host when the C compiler is being used as the linker."
1612 </info>
1613 <glossdef>
1614 <para role="glossdeffirst">
1615<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1616 Specifies the linker command to be used for the build host
1617 when the C compiler is being used as the linker. By default,
1618 <filename>BUILD_CCLD</filename> points to GCC and passes as
1619 arguments the value of
1620 <link linkend='var-BUILD_CC_ARCH'><filename>BUILD_CC_ARCH</filename></link>,
1621 assuming <filename>BUILD_CC_ARCH</filename> is set.
1622 </para>
1623 </glossdef>
1624 </glossentry>
1625
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001626 <glossentry id='var-BUILD_CFLAGS'><glossterm>BUILD_CFLAGS</glossterm>
1627 <info>
1628 BUILD_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the build host."
1629 </info>
1630 <glossdef>
1631 <para role="glossdeffirst">
1632<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1633 Specifies the flags to pass to the C compiler when building
1634 for the build host.
1635 When building in the <filename>-native</filename> context,
1636 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
1637 is set to the value of this variable by default.
1638 </para>
1639 </glossdef>
1640 </glossentry>
1641
1642 <glossentry id='var-BUILD_CPPFLAGS'><glossterm>BUILD_CPPFLAGS</glossterm>
1643 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001644 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 -05001645 </info>
1646 <glossdef>
1647 <para role="glossdeffirst">
1648<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -04001649 Specifies the flags to pass to the C preprocessor
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001650 (i.e. to both the C and the C++ compilers) when building
1651 for the build host.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001652 When building in the <filename>-native</filename> context,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001653 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
1654 is set to the value of this variable by default.
1655 </para>
1656 </glossdef>
1657 </glossentry>
1658
1659 <glossentry id='var-BUILD_CXXFLAGS'><glossterm>BUILD_CXXFLAGS</glossterm>
1660 <info>
1661 BUILD_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the build host."
1662 </info>
1663 <glossdef>
1664 <para role="glossdeffirst">
1665<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1666 Specifies the flags to pass to the C++ compiler when
1667 building for the build host.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001668 When building in the <filename>-native</filename> context,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001669 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
1670 is set to the value of this variable by default.
1671 </para>
1672 </glossdef>
1673 </glossentry>
1674
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001675 <glossentry id='var-BUILD_FC'><glossterm>BUILD_FC</glossterm>
1676 <info>
1677 BUILD_FC[doc] = "Specifies the Fortran compiler command for the build host."
1678 </info>
1679 <glossdef>
1680 <para role="glossdeffirst">
1681<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1682 Specifies the Fortran compiler command for the build host.
1683 By default, <filename>BUILD_FC</filename> points to
1684 Gfortran and passes as arguments the value of
1685 <link linkend='var-BUILD_CC_ARCH'><filename>BUILD_CC_ARCH</filename></link>,
1686 assuming <filename>BUILD_CC_ARCH</filename> is set.
1687 </para>
1688 </glossdef>
1689 </glossentry>
1690
1691 <glossentry id='var-BUILD_LD'><glossterm>BUILD_LD</glossterm>
1692 <info>
1693 BUILD_LD[doc] = "Specifies the linker command for the build host."
1694 </info>
1695 <glossdef>
1696 <para role="glossdeffirst">
1697<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1698 Specifies the linker command for the build host. By default,
1699 <filename>BUILD_LD</filename> points to the GNU linker (ld)
1700 and passes as arguments the value of
1701 <link linkend='var-BUILD_LD_ARCH'><filename>BUILD_LD_ARCH</filename></link>,
1702 assuming <filename>BUILD_LD_ARCH</filename> is set.
1703 </para>
1704 </glossdef>
1705 </glossentry>
1706
1707 <glossentry id='var-BUILD_LD_ARCH'><glossterm>BUILD_LD_ARCH</glossterm>
1708 <info>
1709 BUILD_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the build."
1710 </info>
1711 <glossdef>
1712 <para role="glossdeffirst">
1713<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1714 Specifies architecture-specific linker flags for the build
1715 host. By default, the value of
1716 <filename>BUILD_LD_ARCH</filename> is empty.
1717 </para>
1718 </glossdef>
1719 </glossentry>
1720
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001721 <glossentry id='var-BUILD_LDFLAGS'><glossterm>BUILD_LDFLAGS</glossterm>
1722 <info>
1723 BUILD_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the build host."
1724 </info>
1725 <glossdef>
1726 <para role="glossdeffirst">
1727<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1728 Specifies the flags to pass to the linker when building
1729 for the build host.
1730 When building in the <filename>-native</filename> context,
1731 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
1732 is set to the value of this variable by default.
1733 </para>
1734 </glossdef>
1735 </glossentry>
1736
1737 <glossentry id='var-BUILD_OPTIMIZATION'><glossterm>BUILD_OPTIMIZATION</glossterm>
1738 <info>
1739 BUILD_OPTIMIZATION[doc] = "Specifies the optimization flags passed to the C compiler when building for the build host or the SDK."
1740 </info>
1741 <glossdef>
1742 <para role="glossdeffirst">
1743<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1744 Specifies the optimization flags passed to the C compiler
1745 when building for the build host or the SDK.
1746 The flags are passed through the
1747 <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
1748 and
1749 <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
1750 default values.
1751 </para>
1752
1753 <para>
1754 The default value of the
1755 <filename>BUILD_OPTIMIZATION</filename> variable is
1756 "-O2 -pipe".
1757 </para>
1758 </glossdef>
1759 </glossentry>
1760
1761 <glossentry id='var-BUILD_OS'><glossterm>BUILD_OS</glossterm>
1762 <info>
1763 BUILD_OS[doc] = "The operating system (in lower case) of the building architecture (e.g. Linux)."
1764 </info>
1765 <glossdef>
1766 <para role="glossdeffirst">
1767<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1768 Specifies the operating system in use on the build
1769 host (e.g. "linux").
1770 The OpenEmbedded build system sets the value of
1771 <filename>BUILD_OS</filename> from the OS reported by
1772 the <filename>uname</filename> command - the first word,
1773 converted to lower-case characters.
1774 </para>
1775 </glossdef>
1776 </glossentry>
1777
1778 <glossentry id='var-BUILD_PREFIX'><glossterm>BUILD_PREFIX</glossterm>
1779 <info>
1780 BUILD_PREFIX[doc] = "The toolchain binary prefix used for native recipes."
1781 </info>
1782 <glossdef>
1783 <para role="glossdeffirst">
1784<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1785 The toolchain binary prefix used for native recipes.
1786 The OpenEmbedded build system uses the
1787 <filename>BUILD_PREFIX</filename> value to set the
1788 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001789 when building for <filename>native</filename> recipes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001790 </para>
1791 </glossdef>
1792 </glossentry>
1793
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001794 <glossentry id='var-BUILD_STRIP'><glossterm>BUILD_STRIP</glossterm>
1795 <info>
1796 BUILD_STRIP[doc] = "Specifies the command to be used to strip debugging symbols from binaries produced for the build host."
1797 </info>
1798 <glossdef>
1799 <para role="glossdeffirst">
1800<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1801 Specifies the command to be used to strip debugging symbols
1802 from binaries produced for the build host. By default,
1803 <filename>BUILD_STRIP</filename> points to
1804 <filename>${</filename><link linkend='var-BUILD_PREFIX'><filename>BUILD_PREFIX</filename></link><filename>}strip</filename>.
1805 </para>
1806 </glossdef>
1807 </glossentry>
1808
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001809 <glossentry id='var-BUILD_SYS'><glossterm>BUILD_SYS</glossterm>
1810 <info>
1811 BUILD_SYS[doc] = "The toolchain binary prefix used for native recipes."
1812 </info>
1813 <glossdef>
1814 <para role="glossdeffirst">
1815<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1816 Specifies the system, including the architecture and
1817 the operating system, to use when building for the build
1818 host (i.e. when building <filename>native</filename>
1819 recipes).
1820 </para>
1821
1822 <para>
1823 The OpenEmbedded build system automatically sets this
1824 variable based on
1825 <link linkend='var-BUILD_ARCH'><filename>BUILD_ARCH</filename></link>,
1826 <link linkend='var-BUILD_VENDOR'><filename>BUILD_VENDOR</filename></link>,
1827 and
1828 <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>.
1829 You do not need to set the <filename>BUILD_SYS</filename>
1830 variable yourself.
1831 </para>
1832 </glossdef>
1833 </glossentry>
1834
1835 <glossentry id='var-BUILD_VENDOR'><glossterm>BUILD_VENDOR</glossterm>
1836 <info>
1837 BUILD_VENDOR[doc] = "The vendor name to use when building for the build host."
1838 </info>
1839 <glossdef>
1840 <para role="glossdeffirst">
1841<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1842 Specifies the vendor name to use when building for the
1843 build host.
1844 The default value is an empty string ("").
1845 </para>
1846 </glossdef>
1847 </glossentry>
1848
1849 <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
1850 <info>
1851 BUILDDIR[doc] = "Points to the location of the Build Directory."
1852 </info>
1853 <glossdef>
1854 <para role="glossdeffirst">
1855<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1856 Points to the location of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001857 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001858 You can define this directory indirectly through the
1859 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001860 script by passing in a Build Directory path when you run
1861 the script.
1862 If you run the script and do not provide a Build Directory
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001863 path, the <filename>BUILDDIR</filename> defaults to
1864 <filename>build</filename> in the current directory.
1865 </para>
1866 </glossdef>
1867 </glossentry>
1868
1869 <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>BUILDHISTORY_COMMIT</glossterm>
1870 <info>
1871 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."
1872 </info>
1873 <glossdef>
1874 <para role="glossdeffirst">
1875<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1876 When inheriting the
1877 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1878 class, this variable specifies whether or not to commit the
1879 build history output in a local Git repository.
1880 If set to "1", this local repository will be maintained
1881 automatically by the
1882 <filename>buildhistory</filename>
1883 class and a commit will be created on every
1884 build for changes to each top-level subdirectory of the
1885 build history output (images, packages, and sdk).
1886 If you want to track changes to build history over
1887 time, you should set this value to "1".
1888 </para>
1889
1890 <para>
1891 By default, the <filename>buildhistory</filename> class
1892 does not commit the build history output in a local
1893 Git repository:
1894 <literallayout class='monospaced'>
1895 BUILDHISTORY_COMMIT ?= "0"
1896 </literallayout>
1897 </para>
1898 </glossdef>
1899 </glossentry>
1900
1901 <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>BUILDHISTORY_COMMIT_AUTHOR</glossterm>
1902 <info>
1903 BUILDHISTORY_COMMIT_AUTHOR[doc] = "When inheriting the buildhistory class, this variable specifies the author to use for each Git commit."
1904 </info>
1905 <glossdef>
1906 <para role="glossdeffirst">
1907<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1908 When inheriting the
1909 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1910 class, this variable specifies the author to use for each
1911 Git commit.
1912 In order for the <filename>BUILDHISTORY_COMMIT_AUTHOR</filename>
1913 variable to work, the
1914 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
1915 variable must be set to "1".
1916 </para>
1917
1918 <para>
1919 Git requires that the value you provide for the
1920 <filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable
Brad Bishop316dfdd2018-06-25 12:45:53 -04001921 takes the form of "name <replaceable>email@host</replaceable>".
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001922 Providing an email address or host that is not valid does
1923 not produce an error.
1924 </para>
1925
1926 <para>
1927 By default, the <filename>buildhistory</filename> class
1928 sets the variable as follows:
1929 <literallayout class='monospaced'>
1930 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory &lt;buildhistory@${DISTRO}&gt;"
1931 </literallayout>
1932 </para>
1933 </glossdef>
1934 </glossentry>
1935
1936 <glossentry id='var-BUILDHISTORY_DIR'><glossterm>BUILDHISTORY_DIR</glossterm>
1937 <info>
1938 BUILDHISTORY_DIR[doc] = "When inheriting the buildhistory class, this variable specifies the directory in which build history information is kept."
1939 </info>
1940 <glossdef>
1941 <para role="glossdeffirst">
1942<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1943 When inheriting the
1944 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1945 class, this variable specifies the directory in which
1946 build history information is kept.
1947 For more information on how the variable works, see the
1948 <filename>buildhistory.class</filename>.
1949 </para>
1950
1951 <para>
1952 By default, the <filename>buildhistory</filename> class
1953 sets the directory as follows:
1954 <literallayout class='monospaced'>
1955 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
1956 </literallayout>
1957 </para>
1958 </glossdef>
1959 </glossentry>
1960
1961 <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>BUILDHISTORY_FEATURES</glossterm>
1962 <info>
1963 BUILDHISTORY_FEATURES[doc] = "When inheriting the buildhistory class, this variable specifies the build history features to be enabled."
1964 </info>
1965 <glossdef>
1966 <para role="glossdeffirst">
1967<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1968 When inheriting the
1969 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1970 class, this variable specifies the build history features
1971 to be enabled.
1972 For more information on how build history works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04001973 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
1974 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001975 </para>
1976
1977 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001978 You can specify these features in the form of a
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001979 space-separated list:
1980 <itemizedlist>
1981 <listitem><para><emphasis>image:</emphasis>
1982 Analysis of the contents of images, which
1983 includes the list of installed packages among other
1984 things.
1985 </para></listitem>
1986 <listitem><para><emphasis>package:</emphasis>
1987 Analysis of the contents of individual packages.
1988 </para></listitem>
1989 <listitem><para><emphasis>sdk:</emphasis>
1990 Analysis of the contents of the software
1991 development kit (SDK).
1992 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001993 <listitem><para><emphasis>task:</emphasis>
1994 Save output file signatures for
1995 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state</ulink>
1996 (sstate) tasks.
1997 This saves one file per task and lists the SHA-256
1998 checksums for each file staged (i.e. the output of
1999 the task).
2000 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002001 </itemizedlist>
2002 </para>
2003
2004 <para>
2005 By default, the <filename>buildhistory</filename> class
Brad Bishop316dfdd2018-06-25 12:45:53 -04002006 enables the following features:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002007 <literallayout class='monospaced'>
2008 BUILDHISTORY_FEATURES ?= "image package sdk"
2009 </literallayout>
2010 </para>
2011 </glossdef>
2012 </glossentry>
2013
2014 <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>BUILDHISTORY_IMAGE_FILES</glossterm>
2015 <info>
2016 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."
2017 </info>
2018 <glossdef>
2019 <para role="glossdeffirst">
2020<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2021 When inheriting the
2022 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
2023 class, this variable specifies a list of paths to files
2024 copied from the
2025 image contents into the build history directory under
2026 an "image-files" directory in the directory for
2027 the image, so that you can track the contents of each file.
2028 The default is to copy <filename>/etc/passwd</filename>
2029 and <filename>/etc/group</filename>, which allows you to
2030 monitor for changes in user and group entries.
2031 You can modify the list to include any file.
2032 Specifying an invalid path does not produce an error.
2033 Consequently, you can include files that might
2034 not always be present.
2035 </para>
2036
2037 <para>
2038 By default, the <filename>buildhistory</filename> class
2039 provides paths to the following files:
2040 <literallayout class='monospaced'>
2041 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
2042 </literallayout>
2043 </para>
2044 </glossdef>
2045 </glossentry>
2046
2047 <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>BUILDHISTORY_PUSH_REPO</glossterm>
2048 <info>
2049 BUILDHISTORY_PUSH_REPO[doc] = "When inheriting the buildhistory class, this variable optionally specifies a remote repository to which build history pushes Git changes."
2050 </info>
2051 <glossdef>
2052 <para role="glossdeffirst">
2053<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2054 When inheriting the
2055 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
2056 class, this variable optionally specifies a remote
2057 repository to which build history pushes Git changes.
2058 In order for <filename>BUILDHISTORY_PUSH_REPO</filename>
2059 to work,
2060 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
2061 must be set to "1".
2062 </para>
2063
2064 <para>
2065 The repository should correspond to a remote
2066 address that specifies a repository as understood by
2067 Git, or alternatively to a remote name that you have
2068 set up manually using <filename>git remote</filename>
2069 within the local repository.
2070 </para>
2071
2072 <para>
2073 By default, the <filename>buildhistory</filename> class
2074 sets the variable as follows:
2075 <literallayout class='monospaced'>
2076 BUILDHISTORY_PUSH_REPO ?= ""
2077 </literallayout>
2078 </para>
2079 </glossdef>
2080 </glossentry>
2081
2082 <glossentry id='var-BUILDSDK_CFLAGS'><glossterm>BUILDSDK_CFLAGS</glossterm>
2083 <info>
2084 BUILDSDK_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the SDK."
2085 </info>
2086 <glossdef>
2087 <para role="glossdeffirst">
2088<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2089 Specifies the flags to pass to the C compiler when building
2090 for the SDK.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002091 When building in the <filename>nativesdk-</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002092 context,
2093 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
2094 is set to the value of this variable by default.
2095 </para>
2096 </glossdef>
2097 </glossentry>
2098
2099 <glossentry id='var-BUILDSDK_CPPFLAGS'><glossterm>BUILDSDK_CPPFLAGS</glossterm>
2100 <info>
2101 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."
2102 </info>
2103 <glossdef>
2104 <para role="glossdeffirst">
2105<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2106 Specifies the flags to pass to the C pre-processor
2107 (i.e. to both the C and the C++ compilers) when building
2108 for the SDK.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002109 When building in the <filename>nativesdk-</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002110 context,
2111 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
2112 is set to the value of this variable by default.
2113 </para>
2114 </glossdef>
2115 </glossentry>
2116
2117 <glossentry id='var-BUILDSDK_CXXFLAGS'><glossterm>BUILDSDK_CXXFLAGS</glossterm>
2118 <info>
2119 BUILDSDK_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the SDK."
2120 </info>
2121 <glossdef>
2122 <para role="glossdeffirst">
2123<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2124 Specifies the flags to pass to the C++ compiler when
2125 building for the SDK.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002126 When building in the <filename>nativesdk-</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002127 context,
2128 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
2129 is set to the value of this variable by default.
2130 </para>
2131 </glossdef>
2132 </glossentry>
2133
2134 <glossentry id='var-BUILDSDK_LDFLAGS'><glossterm>BUILDSDK_LDFLAGS</glossterm>
2135 <info>
2136 BUILDSDK_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the SDK."
2137 </info>
2138 <glossdef>
2139 <para role="glossdeffirst">
2140<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2141 Specifies the flags to pass to the linker when building
2142 for the SDK.
2143 When building in the <filename>nativesdk-</filename>
2144 context,
2145 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
2146 is set to the value of this variable by default.
2147 </para>
2148 </glossdef>
2149 </glossentry>
2150
2151 <glossentry id='var-BUILDSTATS_BASE'><glossterm>BUILDSTATS_BASE</glossterm>
2152 <info>
2153 BUILDSTATS_BASE[doc] = "Points to the location of the directory that holds build statistics when you use and enable the buildstats class."
2154 </info>
2155 <glossdef>
2156 <para role="glossdeffirst">
2157<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2158 Points to the location of the directory that holds build
2159 statistics when you use and enable the
2160 <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link>
2161 class.
2162 The <filename>BUILDSTATS_BASE</filename> directory defaults
2163 to
2164 <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/buildstats/</filename>.
2165 </para>
2166 </glossdef>
2167 </glossentry>
2168
2169 <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
2170 <info>
2171 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."
2172 </info>
2173 <glossdef>
2174 <para role="glossdeffirst">
2175<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2176 For the BusyBox recipe, specifies whether to split the
2177 output executable file into two parts: one for features
2178 that require <filename>setuid root</filename>, and one for
2179 the remaining features (i.e. those that do not require
2180 <filename>setuid root</filename>).
2181 </para>
2182
2183 <para>
2184 The <filename>BUSYBOX_SPLIT_SUID</filename> variable
2185 defaults to "1", which results in a single output
2186 executable file.
2187 Set the variable to "0" to split the output file.
2188 </para>
2189 </glossdef>
2190 </glossentry>
2191
2192 </glossdiv>
2193
2194 <glossdiv id='var-glossary-c'><title>C</title>
2195
2196 <glossentry id='var-CACHE'><glossterm>CACHE</glossterm>
2197 <info>
2198 CACHE[doc] = "The directory BitBake uses to store a cache of the metadata."
2199 </info>
2200 <glossdef>
2201 <para role="glossdeffirst">
2202<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2203 Specifies the directory BitBake uses to store a cache
2204 of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002205 <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002206 so it does not need to be parsed every time BitBake is
2207 started.
2208 </para>
2209 </glossdef>
2210 </glossentry>
2211
2212 <glossentry id='var-CC'><glossterm>CC</glossterm>
2213 <info>
2214 CC[doc] = "Minimum command and arguments to run the C compiler."
2215 </info>
2216 <glossdef>
2217 <para role="glossdeffirst">
2218<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2219 The minimal command and arguments used to run the C
2220 compiler.
2221 </para>
2222 </glossdef>
2223 </glossentry>
2224
2225 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
2226 <info>
2227 CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as TARGET_CFLAGS."
2228 </info>
2229 <glossdef>
2230 <para role="glossdeffirst">
2231<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2232 Specifies the flags to pass to the C compiler.
2233 This variable is exported to an environment
2234 variable and thus made visible to the software being
2235 built during the compilation step.
2236 </para>
2237
2238 <para>
2239 Default initialization for <filename>CFLAGS</filename>
2240 varies depending on what is being built:
2241 <itemizedlist>
2242 <listitem><para>
2243 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
2244 when building for the target
2245 </para></listitem>
2246 <listitem><para>
2247 <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
2248 when building for the build host (i.e.
2249 <filename>-native</filename>)
2250 </para></listitem>
2251 <listitem><para>
2252 <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
2253 when building for an SDK (i.e.
2254 <filename>nativesdk-</filename>)
2255 </para></listitem>
2256 </itemizedlist>
2257 </para>
2258 </glossdef>
2259 </glossentry>
2260
2261 <glossentry id='var-CLASSOVERRIDE'><glossterm>CLASSOVERRIDE</glossterm>
2262 <info>
2263 CLASSOVERRIDE[doc] = "An internal variable specifying the special class override that should currently apply (e.g. "class-target", "class-native", and so forth)."
2264 </info>
2265 <glossdef>
2266 <para role="glossdeffirst">
2267<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2268 An internal variable specifying the special class override
2269 that should currently apply (e.g. "class-target",
2270 "class-native", and so forth).
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002271 The classes that use this variable (e.g.
2272 <link linkend='ref-classes-native'><filename>native</filename></link>,
2273 <link linkend='ref-classes-nativesdk'><filename>nativesdk</filename></link>,
2274 and so forth) set the variable to appropriate values.
2275 <note>
2276 <filename>CLASSOVERRIDE</filename> gets its default
2277 "class-target" value from the
2278 <filename>bitbake.conf</filename> file.
2279 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002280 </para>
2281
2282 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002283 As an example, the following override allows you to install
2284 extra files, but only when building for the target:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002285 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002286 do_install_append_class-target() {
2287 install my-extra-file ${D}${sysconfdir}
2288 }
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002289 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002290 Here is an example where <filename>FOO</filename>
2291 is set to "native" when building for the build host, and
2292 to "other" when not building for the build host:
2293 <literallayout class='monospaced'>
2294 FOO_class-native = "native"
2295 FOO = "other"
2296 </literallayout>
2297 The underlying mechanism behind
2298 <filename>CLASSOVERRIDE</filename> is simply that it is
2299 included in the default value of
2300 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002301 </para>
2302 </glossdef>
2303 </glossentry>
2304
2305 <glossentry id='var-CLEANBROKEN'><glossterm>CLEANBROKEN</glossterm>
2306 <info>
2307 CLEANBROKEN[doc] = "Prevents the build system from running 'make clean' during the do_configure task."
2308 </info>
2309 <glossdef>
2310 <para role="glossdeffirst">
2311<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2312 If set to "1" within a recipe,
2313 <filename>CLEANBROKEN</filename> specifies that
2314 the <filename>make clean</filename> command does
2315 not work for the software being built.
2316 Consequently, the OpenEmbedded build system will not try
2317 to run <filename>make clean</filename> during the
2318 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2319 task, which is the default behavior.
2320 </para>
2321 </glossdef>
2322 </glossentry>
2323
2324 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
2325 <info>
2326 COMBINED_FEATURES[doc] = "A set of features common between MACHINE_FEATURES and DISTRO_FEATURES."
2327 </info>
2328 <glossdef>
2329 <para role="glossdeffirst">
2330<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2331 Provides a list of hardware features that are enabled in
2332 both
2333 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
2334 and
2335 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
2336 This select list of features contains features that make
2337 sense to be controlled both at the machine and distribution
2338 configuration level.
2339 For example, the "bluetooth" feature requires hardware
2340 support but should also be optional at the distribution
2341 level, in case the hardware supports Bluetooth but you
2342 do not ever intend to use it.
2343 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002344 </glossdef>
2345 </glossentry>
2346
2347 <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
2348 <info>
2349 COMMON_LICENSE_DIR[doc] = "Points to meta/files/common-licenses in the Source Directory, which is where generic license files reside."
2350 </info>
2351 <glossdef>
2352 <para role="glossdeffirst">
2353<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2354 Points to <filename>meta/files/common-licenses</filename>
2355 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002356 <link linkend='source-directory'>Source Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002357 which is where generic license files reside.
2358 </para>
2359 </glossdef>
2360 </glossentry>
2361
2362 <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
2363 <info>
2364 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."
2365 </info>
2366 <glossdef>
2367 <para role="glossdeffirst">
2368<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2369 A regular expression that resolves to one or more hosts
2370 (when the recipe is native) or one or more targets (when
2371 the recipe is non-native) with which a recipe is compatible.
2372 The regular expression is matched against
2373 <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
2374 You can use the variable to stop recipes from being built
2375 for classes of systems with which the recipes are not
2376 compatible.
2377 Stopping these builds is particularly useful with kernels.
2378 The variable also helps to increase parsing speed
2379 since the build system skips parsing recipes not
2380 compatible with the current system.
2381 </para>
2382 </glossdef>
2383 </glossentry>
2384
2385 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
2386 <info>
2387 COMPATIBLE_MACHINE[doc] = "A regular expression that resolves to one or more target machines with which a recipe is compatible."
2388 </info>
2389 <glossdef>
2390 <para role="glossdeffirst">
2391<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2392 A regular expression that resolves to one or more
2393 target machines with which a recipe is compatible.
2394 The regular expression is matched against
2395 <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
2396 You can use the variable to stop recipes from being built
2397 for machines with which the recipes are not compatible.
2398 Stopping these builds is particularly useful with kernels.
2399 The variable also helps to increase parsing speed
2400 since the build system skips parsing recipes not
2401 compatible with the current machine.
2402 </para>
2403 </glossdef>
2404 </glossentry>
2405
2406 <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
2407 <info>
2408 COMPLEMENTARY_GLOB[doc] = "Defines wildcards to match when installing a list of complementary packages for all the packages installed in an image."
2409 </info>
2410 <glossdef>
2411 <para role="glossdeffirst">
2412<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2413 Defines wildcards to match when installing a list of
2414 complementary packages for all the packages explicitly
2415 (or implicitly) installed in an image.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08002416 <note>
2417 The <filename>COMPLEMENTARY_GLOB</filename> variable
2418 uses Unix filename pattern matching
2419 (<ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>),
2420 which is similar to the Unix style pathname pattern
2421 expansion
2422 (<ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>).
2423 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002424 The resulting list of complementary packages is associated
2425 with an item that can be added to
2426 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
2427 An example usage of this is the "dev-pkgs" item that when
2428 added to <filename>IMAGE_FEATURES</filename> will
2429 install -dev packages (containing headers and other
2430 development files) for every package in the image.
2431 </para>
2432
2433 <para>
2434 To add a new feature item pointing to a wildcard, use a
2435 variable flag to specify the feature item name and
2436 use the value to specify the wildcard.
2437 Here is an example:
2438 <literallayout class='monospaced'>
2439 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
2440 </literallayout>
2441 </para>
2442 </glossdef>
2443 </glossentry>
2444
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002445 <glossentry id='var-COMPONENTS_DIR'><glossterm>COMPONENTS_DIR</glossterm>
2446 <info>
2447 COMPONENTS_DIR[doc] = "Stores sysroot components for each recipe."
2448 </info>
2449 <glossdef>
2450 <para role="glossdeffirst">
2451<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2452 Stores sysroot components for each recipe.
2453 The OpenEmbedded build system uses
2454 <filename>COMPONENTS_DIR</filename> when constructing
2455 recipe-specific sysroots for other recipes.
2456 </para>
2457
2458 <para>
2459 The default is
2460 "<filename>${</filename><link linkend='var-STAGING_DIR'><filename>STAGING_DIR</filename></link><filename>}-components</filename>."
2461 (i.e. "<filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots-components</filename>").
2462 </para>
2463 </glossdef>
2464 </glossentry>
2465
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002466 <glossentry id='var-CONF_VERSION'><glossterm>CONF_VERSION</glossterm>
2467 <info>
2468 CONF_VERSION[doc] = "Tracks the version of local.conf. Increased each time build/conf/ changes incompatibly."
2469 </info>
2470 <glossdef>
2471 <para role="glossdeffirst">
2472<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2473 Tracks the version of the local configuration file
2474 (i.e. <filename>local.conf</filename>).
2475 The value for <filename>CONF_VERSION</filename>
2476 increments each time <filename>build/conf/</filename>
2477 compatibility changes.
2478 </para>
2479 </glossdef>
2480 </glossentry>
2481
2482 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
2483 <info>
2484 CONFFILES[doc] = "Identifies editable or configurable files that are part of a package."
2485 </info>
2486 <glossdef>
2487 <para role="glossdeffirst">
2488<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2489 Identifies editable or configurable files that are part of a package.
2490 If the Package Management System (PMS) is being used to update
2491 packages on the target system, it is possible that
2492 configuration files you have changed after the original installation
2493 and that you now want to remain unchanged are overwritten.
2494 In other words, editable files might exist in the package that you do not
2495 want reset as part of the package update process.
2496 You can use the <filename>CONFFILES</filename> variable to list the files in the
2497 package that you wish to prevent the PMS from overwriting during this update process.
2498 </para>
2499
2500 <para>
2501 To use the <filename>CONFFILES</filename> variable, provide a package name
2502 override that identifies the resulting package.
2503 Then, provide a space-separated list of files.
2504 Here is an example:
2505 <literallayout class='monospaced'>
2506 CONFFILES_${PN} += "${sysconfdir}/file1 \
2507 ${sysconfdir}/file2 ${sysconfdir}/file3"
2508 </literallayout>
2509 </para>
2510
2511 <para>
2512 A relationship exists between the <filename>CONFFILES</filename> and
2513 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
2514 The files listed within <filename>CONFFILES</filename> must be a subset of
2515 the files listed within <filename>FILES</filename>.
2516 Because the configuration files you provide with <filename>CONFFILES</filename>
2517 are simply being identified so that the PMS will not overwrite them,
2518 it makes sense that
2519 the files must already be included as part of the package through the
2520 <filename>FILES</filename> variable.
2521 </para>
2522
2523 <note>
2524 When specifying paths as part of the <filename>CONFFILES</filename> variable,
2525 it is good practice to use appropriate path variables.
2526 For example, <filename>${sysconfdir}</filename> rather than
2527 <filename>/etc</filename> or <filename>${bindir}</filename> rather
2528 than <filename>/usr/bin</filename>.
2529 You can find a list of these variables at the top of the
2530 <filename>meta/conf/bitbake.conf</filename> file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002531 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002532 </note>
2533 </glossdef>
2534 </glossentry>
2535
2536 <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>
2537 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05002538 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 -05002539 </info>
2540 <glossdef>
2541 <para role="glossdeffirst">
2542<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop37a0e4d2017-12-04 01:01:44 -05002543 Identifies the initial RAM filesystem (initramfs) source
2544 files.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002545 The OpenEmbedded build system receives and uses
2546 this kernel Kconfig variable as an environment variable.
2547 By default, the variable is set to null ("").
2548 </para>
2549
2550 <para>
2551 The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be
2552 either a single cpio archive with a
2553 <filename>.cpio</filename> suffix or a
2554 space-separated list of directories and files for building
2555 the initramfs image.
2556 A cpio archive should contain a filesystem archive
2557 to be used as an initramfs image.
2558 Directories should contain a filesystem layout to be
2559 included in the initramfs image.
2560 Files should contain entries according to the format
2561 described by the
2562 <filename>usr/gen_init_cpio</filename> program in the
2563 kernel tree.
2564 </para>
2565
2566 <para>
2567 If you specify multiple directories and files, the
2568 initramfs image will be the aggregate of all of them.
2569 </para>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05002570
2571 <para>
2572 For information on creating an initramfs, see the
2573 "<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 -05002574 section in the Yocto Project Development Tasks Manual.
Brad Bishop37a0e4d2017-12-04 01:01:44 -05002575 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002576 </glossdef>
2577 </glossentry>
2578
2579 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
2580 <info>
2581 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."
2582 </info>
2583 <glossdef>
2584 <para role="glossdeffirst">
2585<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2586 A list of files that contains <filename>autoconf</filename> test results relevant
2587 to the current build.
2588 This variable is used by the Autotools utilities when running
2589 <filename>configure</filename>.
2590 </para>
2591 </glossdef>
2592 </glossentry>
2593
2594 <glossentry id='var-CONFIGURE_FLAGS'><glossterm>CONFIGURE_FLAGS</glossterm>
2595 <info>
2596 CONFIGURE_FLAGS[doc] = "The minimal arguments for GNU configure."
2597 </info>
2598 <glossdef>
2599 <para role="glossdeffirst">
2600<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2601 The minimal arguments for GNU configure.
2602 </para>
2603 </glossdef>
2604 </glossentry>
2605
2606 <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>CONFLICT_DISTRO_FEATURES</glossterm>
2607 <info>
2608 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."
2609 </info>
2610 <glossdef>
2611 <para role="glossdeffirst">
2612<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2613 When inheriting the
2614 <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link>
2615 class, this
2616 variable identifies distribution features that would
2617 be in conflict should the recipe
2618 be built.
2619 In other words, if the
2620 <filename>CONFLICT_DISTRO_FEATURES</filename> variable
2621 lists a feature that also appears in
2622 <filename>DISTRO_FEATURES</filename> within the
2623 current configuration, an error occurs and the
2624 build stops.
2625 </para>
2626 </glossdef>
2627 </glossentry>
2628
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002629 <glossentry id='var-COPYLEFT_LICENSE_EXCLUDE'><glossterm>COPYLEFT_LICENSE_EXCLUDE</glossterm>
2630 <info>
2631 COPYLEFT_LICENSE_EXCLUDE[doc] = "Licenses to exclude in the source archived by the archiver class."
2632 </info>
2633 <glossdef>
2634 <para role="glossdeffirst">
2635<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2636 A space-separated list of licenses to exclude from the
2637 source archived by the
2638 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2639 class.
2640 In other words, if a license in a recipe's
2641 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2642 value is in the value of
2643 <filename>COPYLEFT_LICENSE_EXCLUDE</filename>, then its
2644 source is not archived by the class.
2645 <note>
2646 The <filename>COPYLEFT_LICENSE_EXCLUDE</filename>
2647 variable takes precedence over the
2648 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2649 variable.
2650 </note>
2651 The default value, which is "CLOSED Proprietary", for
2652 <filename>COPYLEFT_LICENSE_EXCLUDE</filename> is set
2653 by the
2654 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2655 class, which is inherited by the
2656 <filename>archiver</filename> class.
2657 </para>
2658 </glossdef>
2659 </glossentry>
2660
2661 <glossentry id='var-COPYLEFT_LICENSE_INCLUDE'><glossterm>COPYLEFT_LICENSE_INCLUDE</glossterm>
2662 <info>
2663 COPYLEFT_LICENSE_INCLUDE[doc] = "Licenses to include in the source archived by the archiver class."
2664 </info>
2665 <glossdef>
2666 <para role="glossdeffirst">
2667<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2668 A space-separated list of licenses to include in the
2669 source archived by the
2670 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2671 class.
2672 In other words, if a license in a recipe's
2673 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2674 value is in the value of
2675 <filename>COPYLEFT_LICENSE_INCLUDE</filename>, then its
2676 source is archived by the class.
2677 </para>
2678
2679 <para>
2680 The default value is set by the
2681 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2682 class, which is inherited by the
2683 <filename>archiver</filename> class.
2684 The default value includes "GPL*", "LGPL*", and "AGPL*".
2685 </para>
2686 </glossdef>
2687 </glossentry>
2688
2689 <glossentry id='var-COPYLEFT_PN_EXCLUDE'><glossterm>COPYLEFT_PN_EXCLUDE</glossterm>
2690 <info>
2691 COPYLEFT_PN_EXCLUDE[doc] = "Recipes to exclude in the source archived by the archiver class."
2692 </info>
2693 <glossdef>
2694 <para role="glossdeffirst">
2695<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2696 A list of recipes to exclude in the source archived
2697 by the
2698 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2699 class.
2700 The <filename>COPYLEFT_PN_EXCLUDE</filename> variable
2701 overrides the license inclusion and exclusion caused
2702 through the
2703 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2704 and
2705 <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link>
2706 variables, respectively.
2707 </para>
2708
2709 <para>
2710 The default value, which is "" indicating to not explicitly
2711 exclude any recipes by name, for
2712 <filename>COPYLEFT_PN_EXCLUDE</filename> is set
2713 by the
2714 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2715 class, which is inherited by the
2716 <filename>archiver</filename> class.
2717 </para>
2718 </glossdef>
2719 </glossentry>
2720
2721 <glossentry id='var-COPYLEFT_PN_INCLUDE'><glossterm>COPYLEFT_PN_INCLUDE</glossterm>
2722 <info>
2723 COPYLEFT_PN_INCLUDE[doc] = "Recipes to include in the source archived by the archiver class."
2724 </info>
2725 <glossdef>
2726 <para role="glossdeffirst">
2727<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2728 A list of recipes to include in the source archived
2729 by the
2730 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2731 class.
2732 The <filename>COPYLEFT_PN_INCLUDE</filename> variable
2733 overrides the license inclusion and exclusion caused
2734 through the
2735 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2736 and
2737 <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link>
2738 variables, respectively.
2739 </para>
2740
2741 <para>
2742 The default value, which is "" indicating to not explicitly
2743 include any recipes by name, for
2744 <filename>COPYLEFT_PN_INCLUDE</filename> is set
2745 by the
2746 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2747 class, which is inherited by the
2748 <filename>archiver</filename> class.
2749 </para>
2750 </glossdef>
2751 </glossentry>
2752
2753 <glossentry id='var-COPYLEFT_RECIPE_TYPES'><glossterm>COPYLEFT_RECIPE_TYPES</glossterm>
2754 <info>
2755 COPYLEFT_RECIPE_TYPES[doc] = "Recipe types to include in the source archived by the archiver class."
2756 </info>
2757 <glossdef>
2758 <para role="glossdeffirst">
2759<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2760 A space-separated list of recipe types to include
2761 in the source archived by the
2762 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2763 class.
2764 Recipe types are <filename>target</filename>,
2765 <filename>native</filename>,
2766 <filename>nativesdk</filename>,
2767 <filename>cross</filename>,
2768 <filename>crosssdk</filename>, and
2769 <filename>cross-canadian</filename>.
2770 </para>
2771
2772 <para>
2773 The default value, which is "target*", for
2774 <filename>COPYLEFT_RECIPE_TYPES</filename> is set
2775 by the
2776 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2777 class, which is inherited by the
2778 <filename>archiver</filename> class.
2779 </para>
2780 </glossdef>
2781 </glossentry>
2782
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002783 <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm>
2784 <info>
2785 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."
2786 </info>
2787 <glossdef>
2788 <para role="glossdeffirst">
2789<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2790 If set to "1" along with the
2791 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
2792 variable, the OpenEmbedded build system copies
2793 into the image the license files, which are located in
2794 <filename>/usr/share/common-licenses</filename>,
2795 for each package.
2796 The license files are placed
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002797 in directories within the image itself during build time.
2798 <note>
2799 The <filename>COPY_LIC_DIRS</filename> does not
2800 offer a path for adding licenses for newly installed
2801 packages to an image, which might be most suitable
2802 for read-only filesystems that cannot be upgraded.
2803 See the
2804 <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link>
2805 variable for additional information.
2806 You can also reference the
2807 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002808 section in the Yocto Project Development Tasks Manual
2809 for information on providing license text.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002810 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002811 </para>
2812 </glossdef>
2813 </glossentry>
2814
2815 <glossentry id='var-COPY_LIC_MANIFEST'><glossterm>COPY_LIC_MANIFEST</glossterm>
2816 <info>
2817 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."
2818 </info>
2819 <glossdef>
2820 <para role="glossdeffirst">
2821<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2822 If set to "1", the OpenEmbedded build system copies
2823 the license manifest for the image to
2824 <filename>/usr/share/common-licenses/license.manifest</filename>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002825 within the image itself during build time.
2826 <note>
2827 The <filename>COPY_LIC_MANIFEST</filename> does not
2828 offer a path for adding licenses for newly installed
2829 packages to an image, which might be most suitable
2830 for read-only filesystems that cannot be upgraded.
2831 See the
2832 <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link>
2833 variable for additional information.
2834 You can also reference the
2835 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002836 section in the Yocto Project Development Tasks Manual
2837 for information on providing license text.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002838 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002839 </para>
2840 </glossdef>
2841 </glossentry>
2842
2843 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
2844 <info>
2845 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."
2846 </info>
2847 <glossdef>
2848 <para role="glossdeffirst">
2849<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2850 Specifies the list of packages to be added to the image.
2851 You should only set this variable in the
2852 <filename>local.conf</filename> configuration file found
2853 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002854 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002855 </para>
2856
2857 <para>
2858 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
2859 </para>
2860 </glossdef>
2861 </glossentry>
2862
2863 <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
2864 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002865 COREBASE[doc] = "Specifies the parent directory of the OpenEmbedded-Core Metadata layer (i.e. meta)."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002866 </info>
2867 <glossdef>
2868 <para role="glossdeffirst">
2869<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -04002870 Specifies the parent directory of the OpenEmbedded-Core
2871 Metadata layer (i.e. <filename>meta</filename>).
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002872 </para>
2873
2874 <para>
2875 It is an important distinction that
2876 <filename>COREBASE</filename> points to the parent of this
2877 layer and not the layer itself.
2878 Consider an example where you have cloned the Poky Git
2879 repository and retained the <filename>poky</filename>
2880 name for your local copy of the repository.
2881 In this case, <filename>COREBASE</filename> points to
2882 the <filename>poky</filename> folder because it is the
2883 parent directory of the <filename>poky/meta</filename>
2884 layer.
2885 </para>
2886 </glossdef>
2887 </glossentry>
2888
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002889 <glossentry id='var-COREBASE_FILES'><glossterm>COREBASE_FILES</glossterm>
2890 <info>
2891 COREBASE_FILES[doc] = "Lists files from the COREBASE directory that should be copied other than the layers listed in the bblayers.conf file."
2892 </info>
2893 <glossdef>
2894 <para role="glossdeffirst">
2895<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2896 Lists files from the
2897 <link linkend='var-COREBASE'><filename>COREBASE</filename></link>
2898 directory that should be copied other than the layers
2899 listed in the <filename>bblayers.conf</filename> file.
2900 The <filename>COREBASE_FILES</filename> variable exists
2901 for the purpose of copying metadata from the
2902 OpenEmbedded build system into the extensible
2903 SDK.
2904 </para>
2905
2906 <para>
2907 Explicitly listing files in <filename>COREBASE</filename>
2908 is needed because it typically contains build
2909 directories and other files that should not normally
2910 be copied into the extensible SDK.
2911 Consequently, the value of
2912 <filename>COREBASE_FILES</filename> is used in order to
2913 only copy the files that are actually needed.
2914 </para>
2915 </glossdef>
2916 </glossentry>
2917
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002918 <glossentry id='var-CPP'><glossterm>CPP</glossterm>
2919 <info>
2920 CPP[doc] = "Minimum command and arguments to run the C preprocessor."
2921 </info>
2922 <glossdef>
2923 <para role="glossdeffirst">
2924<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2925 The minimal command and arguments used to run the C
2926 preprocessor.
2927 </para>
2928 </glossdef>
2929 </glossentry>
2930
2931 <glossentry id='var-CPPFLAGS'><glossterm>CPPFLAGS</glossterm>
2932 <info>
2933 CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers)."
2934 </info>
2935 <glossdef>
2936 <para role="glossdeffirst">
2937<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2938 Specifies the flags to pass to the C pre-processor
2939 (i.e. to both the C and the C++ compilers).
2940 This variable is exported to an environment
2941 variable and thus made visible to the software being
2942 built during the compilation step.
2943 </para>
2944
2945 <para>
2946 Default initialization for <filename>CPPFLAGS</filename>
2947 varies depending on what is being built:
2948 <itemizedlist>
2949 <listitem><para>
2950 <link linkend='var-TARGET_CPPFLAGS'><filename>TARGET_CPPFLAGS</filename></link>
2951 when building for the target
2952 </para></listitem>
2953 <listitem><para>
2954 <link linkend='var-BUILD_CPPFLAGS'><filename>BUILD_CPPFLAGS</filename></link>
2955 when building for the build host (i.e.
2956 <filename>-native</filename>)
2957 </para></listitem>
2958 <listitem><para>
2959 <link linkend='var-BUILDSDK_CPPFLAGS'><filename>BUILDSDK_CPPFLAGS</filename></link>
2960 when building for an SDK (i.e.
2961 <filename>nativesdk-</filename>)
2962 </para></listitem>
2963 </itemizedlist>
2964 </para>
2965 </glossdef>
2966 </glossentry>
2967
2968 <glossentry id='var-CROSS_COMPILE'><glossterm>CROSS_COMPILE</glossterm>
2969 <info>
2970 CROSS_COMPILE[doc] = "The toolchain binary prefix for the target tools."
2971 </info>
2972 <glossdef>
2973 <para role="glossdeffirst">
2974<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2975 The toolchain binary prefix for the target tools.
2976 The <filename>CROSS_COMPILE</filename> variable is the
2977 same as the
2978 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
2979 variable.
2980 <note>
2981 The OpenEmbedded build system sets the
2982 <filename>CROSS_COMPILE</filename> variable only in
2983 certain contexts (e.g. when building for kernel
2984 and kernel module recipes).
2985 </note>
2986 </para>
2987 </glossdef>
2988 </glossentry>
2989
2990 <glossentry id='var-CVSDIR'><glossterm>CVSDIR</glossterm>
2991 <info>
2992 CVSDIR[doc] = "The directory where cvs checkouts will be stored in."
2993 </info>
2994 <glossdef>
2995 <para role="glossdeffirst">
2996<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2997 The directory in which files checked out under the
2998 CVS system are stored.
2999 </para>
3000 </glossdef>
3001 </glossentry>
3002
3003 <glossentry id='var-CXX'><glossterm>CXX</glossterm>
3004 <info>
3005 CXX[doc] = "Minimum command and arguments to run the C++ compiler."
3006 </info>
3007 <glossdef>
3008 <para role="glossdeffirst">
3009<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3010 The minimal command and arguments used to run the C++
3011 compiler.
3012 </para>
3013 </glossdef>
3014 </glossentry>
3015
3016 <glossentry id='var-CXXFLAGS'><glossterm>CXXFLAGS</glossterm>
3017 <info>
3018 CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler."
3019 </info>
3020 <glossdef>
3021 <para role="glossdeffirst">
3022<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3023 Specifies the flags to pass to the C++ compiler.
3024 This variable is exported to an environment
3025 variable and thus made visible to the software being
3026 built during the compilation step.
3027 </para>
3028
3029 <para>
3030 Default initialization for <filename>CXXFLAGS</filename>
3031 varies depending on what is being built:
3032 <itemizedlist>
3033 <listitem><para>
3034 <link linkend='var-TARGET_CXXFLAGS'><filename>TARGET_CXXFLAGS</filename></link>
3035 when building for the target
3036 </para></listitem>
3037 <listitem><para>
3038 <link linkend='var-BUILD_CXXFLAGS'><filename>BUILD_CXXFLAGS</filename></link>
3039 when building for the build host (i.e.
3040 <filename>-native</filename>)
3041 </para></listitem>
3042 <listitem><para>
3043 <link linkend='var-BUILDSDK_CXXFLAGS'><filename>BUILDSDK_CXXFLAGS</filename></link>
3044 when building for an SDK (i.e.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003045 <filename>nativesdk-</filename>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003046 </para></listitem>
3047 </itemizedlist>
3048 </para>
3049 </glossdef>
3050 </glossentry>
3051
3052 </glossdiv>
3053
3054 <glossdiv id='var-glossary-d'><title>D</title>
3055
3056 <glossentry id='var-D'><glossterm>D</glossterm>
3057 <info>
3058 D[doc] = "The destination directory."
3059 </info>
3060 <glossdef>
3061 <para role="glossdeffirst">
3062<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3063 The destination directory.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003064 The location in the
3065 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003066 where components are installed by the
3067 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
3068 task.
3069 This location defaults to:
3070 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003071 ${WORKDIR}/image
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003072 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003073 <note><title>Caution</title>
3074 Tasks that read from or write to this directory should
3075 run under
Brad Bishop316dfdd2018-06-25 12:45:53 -04003076 <ulink url='&YOCTO_DOCS_OM_URL;#fakeroot-and-pseudo'>fakeroot</ulink>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003077 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003078 </para>
3079 </glossdef>
3080 </glossentry>
3081
3082 <glossentry id='var-DATE'><glossterm>DATE</glossterm>
3083 <info>
3084 DATE[doc] = "The date the build was started using YMD format."
3085 </info>
3086 <glossdef>
3087 <para role="glossdeffirst">
3088<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3089 The date the build was started.
3090 Dates appear using the year, month, and day (YMD) format
3091 (e.g. "20150209" for February 9th, 2015).
3092 </para>
3093 </glossdef>
3094 </glossentry>
3095
3096 <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
3097 <info>
3098 DATETIME[doc] = "The date and time the build was started."
3099 </info>
3100 <glossdef>
3101 <para role="glossdeffirst">
3102<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3103 The date and time on which the current build started.
3104 The format is suitable for timestamps.
3105 </para>
3106 </glossdef>
3107 </glossentry>
3108
3109 <glossentry id='var-DEBIAN_NOAUTONAME'><glossterm>DEBIAN_NOAUTONAME</glossterm>
3110 <info>
3111 DEBIAN_NOAUTONAME[doc] = "Prevents a particular package from being renamed according to Debian package naming."
3112 </info>
3113 <glossdef>
3114 <para role="glossdeffirst">
3115<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3116 When the
3117 <link linkend='ref-classes-debian'><filename>debian</filename></link>
3118 class is inherited, which is the default behavior,
3119 <filename>DEBIAN_NOAUTONAME</filename> specifies a
3120 particular package should not be renamed according to
3121 Debian library package naming.
3122 You must use the package name as an override when you
3123 set this variable.
3124 Here is an example from the <filename>fontconfig</filename>
3125 recipe:
3126 <literallayout class='monospaced'>
3127 DEBIAN_NOAUTONAME_fontconfig-utils = "1"
3128 </literallayout>
3129 </para>
3130 </glossdef>
3131 </glossentry>
3132
3133 <glossentry id='var-DEBIANNAME'><glossterm>DEBIANNAME</glossterm>
3134 <info>
3135 DEBIANNAME[doc] = "Allows you to override the library name for an individual package for Debian library package renaming."
3136 </info>
3137 <glossdef>
3138 <para role="glossdeffirst">
3139<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3140 When the
3141 <link linkend='ref-classes-debian'><filename>debian</filename></link>
3142 class is inherited, which is the default behavior,
3143 <filename>DEBIANNAME</filename> allows you to override the
3144 library name for an individual package.
3145 Overriding the library name in these cases is rare.
3146 You must use the package name as an override when you
3147 set this variable.
3148 Here is an example from the <filename>dbus</filename>
3149 recipe:
3150 <literallayout class='monospaced'>
3151 DEBIANNAME_${PN} = "dbus-1"
3152 </literallayout>
3153 </para>
3154 </glossdef>
3155 </glossentry>
3156
3157 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
3158 <info>
3159 DEBUG_BUILD[doc] = "Specifies to build packages with debugging information. This influences the value of the SELECTED_OPTIMIZATION variable."
3160 </info>
3161 <glossdef>
3162 <para role="glossdeffirst">
3163<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3164 Specifies to build packages with debugging information.
3165 This influences the value of the
3166 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
3167 variable.
3168 </para>
3169 </glossdef>
3170 </glossentry>
3171
3172 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
3173 <info>
3174 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'."
3175 </info>
3176 <glossdef>
3177 <para role="glossdeffirst">
3178<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3179 The options to pass in
3180 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
3181 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
3182 a system for debugging.
3183 This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
3184 </para>
3185 </glossdef>
3186 </glossentry>
3187
3188 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
3189 <info>
3190 DEFAULT_PREFERENCE[doc] = "Specifies a weak bias for recipe selection priority."
3191 </info>
3192 <glossdef>
3193 <para role="glossdeffirst">
3194<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3195 Specifies a weak bias for recipe selection priority.
3196 </para>
3197
3198 <para>
3199 The most common usage of this is variable is to set
3200 it to "-1" within a recipe for a development version of a
3201 piece of software.
3202 Using the variable in this way causes the stable version
3203 of the recipe to build by default in the absence of
3204 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
3205 being used to build the development version.
3206 </para>
3207
3208 <note>
3209 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
3210 is weak and is overridden by
3211 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
3212 if that variable is different between two layers
3213 that contain different versions of the same recipe.
3214 </note>
3215 </glossdef>
3216 </glossentry>
3217
3218 <glossentry id='var-DEFAULTTUNE'><glossterm>DEFAULTTUNE</glossterm>
3219 <info>
3220 DEFAULTTUNE[doc] = "The default CPU and Application Binary Interface (ABI) tunings (i.e. the "tune") used by the OpenEmbedded build system."
3221 </info>
3222 <glossdef>
3223 <para role="glossdeffirst">
3224<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3225 The default CPU and Application Binary Interface (ABI)
3226 tunings (i.e. the "tune") used by the OpenEmbedded build
3227 system.
3228 The <filename>DEFAULTTUNE</filename> helps define
3229 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
3230 </para>
3231
3232 <para>
3233 The default tune is either implicitly or explicitly set
3234 by the machine
3235 (<link linkend='var-MACHINE'><filename>MACHINE</filename></link>).
3236 However, you can override the setting using available tunes
3237 as defined with
3238 <link linkend='var-AVAILTUNES'><filename>AVAILTUNES</filename></link>.
3239 </para>
3240 </glossdef>
3241 </glossentry>
3242
3243 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
3244 <info>
3245 DEPENDS[doc] = "Lists a recipe's build-time dependencies (i.e. other recipe files)."
3246 </info>
3247 <glossdef>
3248 <para role="glossdeffirst">
3249<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003250 Lists a recipe's build-time dependencies.
3251 These are dependencies on other recipes whose
3252 contents (e.g. headers and shared libraries) are needed
3253 by the recipe at build time.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003254 </para>
3255
3256 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003257 As an example, consider a recipe <filename>foo</filename>
3258 that contains the following assignment:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003259 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003260 DEPENDS = "bar"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003261 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003262 The practical effect of the previous assignment is that
3263 all files installed by bar will be available in the
3264 appropriate staging sysroot, given by the
3265 <link linkend='var-STAGING_DIR'><filename>STAGING_DIR*</filename></link>
3266 variables, by the time the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003267 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003268 task for <filename>foo</filename> runs.
3269 This mechanism is implemented by having
3270 <filename>do_configure</filename> depend on the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003271 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003272 task of each recipe listed in <filename>DEPENDS</filename>,
3273 through a
3274 <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>
3275 declaration in the
3276 <link linkend='ref-classes-base'><filename>base</filename></link>
3277 class.
3278 <note>
3279 It seldom is necessary to reference, for example,
3280 <filename>STAGING_DIR_HOST</filename> explicitly.
3281 The standard classes and build-related variables are
3282 configured to automatically use the appropriate staging
3283 sysroots.
3284 </note>
3285 As another example, <filename>DEPENDS</filename> can also
3286 be used to add utilities that run on the build machine
3287 during the build.
3288 For example, a recipe that makes use of a code generator
3289 built by the recipe <filename>codegen</filename> might have
3290 the following:
3291 <literallayout class='monospaced'>
3292 DEPENDS = "codegen-native"
3293 </literallayout>
3294 For more information, see the
3295 <link linkend='ref-classes-native'><filename>native</filename></link>
3296 class and the
3297 <link linkend='var-EXTRANATIVEPATH'><filename>EXTRANATIVEPATH</filename></link>
3298 variable.
3299 <note>
3300 <title>Notes</title>
3301 <itemizedlist>
3302 <listitem><para>
3303 <filename>DEPENDS</filename> is a list of
3304 recipe names.
3305 Or, to be more precise, it is a list of
3306 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
3307 names, which usually match recipe names.
3308 Putting a package name such as "foo-dev" in
3309 <filename>DEPENDS</filename> does not make
3310 sense.
3311 Use "foo" instead, as this will put files
3312 from all the packages that make up
3313 <filename>foo</filename>, which includes
3314 those from <filename>foo-dev</filename>, into
3315 the sysroot.
3316 </para></listitem>
3317 <listitem><para>
3318 One recipe having another recipe in
3319 <filename>DEPENDS</filename> does not by itself
3320 add any runtime dependencies between the
3321 packages produced by the two recipes.
3322 However, as explained in the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003323 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
3324 section in the Yocto Project Overview and
3325 Concepts Manual, runtime dependencies will
3326 often be added automatically, meaning
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003327 <filename>DEPENDS</filename> alone is
3328 sufficient for most recipes.
3329 </para></listitem>
3330 <listitem><para>
3331 Counterintuitively,
3332 <filename>DEPENDS</filename> is often necessary
3333 even for recipes that install precompiled
3334 components.
3335 For example, if <filename>libfoo</filename>
3336 is a precompiled library that links against
3337 <filename>libbar</filename>, then
3338 linking against <filename>libfoo</filename>
3339 requires both <filename>libfoo</filename>
3340 and <filename>libbar</filename> to be available
3341 in the sysroot.
3342 Without a <filename>DEPENDS</filename> from the
3343 recipe that installs <filename>libfoo</filename>
3344 to the recipe that installs
3345 <filename>libbar</filename>, other recipes might
3346 fail to link against
3347 <filename>libfoo</filename>.
3348 </para></listitem>
3349 </itemizedlist>
3350 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003351 </para>
3352
3353 <para>
3354 For information on runtime dependencies, see the
3355 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
3356 variable.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003357 You can also see the
3358 "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
3359 "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
3360 sections in the BitBake User Manual for additional
3361 information on tasks and dependencies.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003362 </para>
3363 </glossdef>
3364 </glossentry>
3365
3366 <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
3367 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003368 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 -05003369 </info>
3370 <glossdef>
3371 <para role="glossdeffirst">
3372<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3373 Points to the general area that the OpenEmbedded build
Brad Bishop316dfdd2018-06-25 12:45:53 -04003374 system uses to place images, packages, SDKs, and other output
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003375 files that are ready to be used outside of the build system.
3376 By default, this directory resides within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003377 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003378 as <filename>${TMPDIR}/deploy</filename>.
3379 </para>
3380
3381 <para>
3382 For more information on the structure of the Build
3383 Directory, see
3384 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
3385 section.
3386 For more detail on the contents of the
3387 <filename>deploy</filename> directory, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003388 "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>",
3389 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>",
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003390 and
Brad Bishop316dfdd2018-06-25 12:45:53 -04003391 "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
3392 sections all in the Yocto Project Overview and Concepts
3393 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003394 </para>
3395 </glossdef>
3396 </glossentry>
3397
3398 <glossentry id='var-DEPLOY_DIR_DEB'><glossterm>DEPLOY_DIR_DEB</glossterm>
3399 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003400 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 -05003401 </info>
3402 <glossdef>
3403 <para role="glossdeffirst">
3404<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3405 Points to the area that the OpenEmbedded build system uses
3406 to place Debian packages that are ready to be used outside
3407 of the build system.
3408 This variable applies only when
3409 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3410 contains "package_deb".
3411 </para>
3412
3413 <para>
3414 The BitBake configuration file initially defines the
3415 <filename>DEPLOY_DIR_DEB</filename> variable as a
3416 sub-folder of
3417 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3418 <literallayout class='monospaced'>
3419 DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
3420 </literallayout>
3421 </para>
3422
3423 <para>
3424 The
3425 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>
3426 class uses the
3427 <filename>DEPLOY_DIR_DEB</filename> variable to make sure
3428 the
3429 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>
3430 task writes Debian packages into the appropriate folder.
3431 For more information on how packaging works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003432 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3433 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003434 </para>
3435 </glossdef>
3436 </glossentry>
3437
3438 <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
3439 <info>
3440 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."
3441 </info>
3442 <glossdef>
3443 <para role="glossdeffirst">
3444<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3445 Points to the area that the OpenEmbedded build system uses
3446 to place images and other associated output files that are
3447 ready to be deployed onto the target machine.
3448 The directory is machine-specific as it contains the
3449 <filename>${MACHINE}</filename> name.
3450 By default, this directory resides within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003451 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003452 as <filename>${DEPLOY_DIR}/images/${MACHINE}/</filename>.
3453 </para>
3454
3455 <para>
3456 For more information on the structure of the Build
3457 Directory, see
3458 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
3459 section.
3460 For more detail on the contents of the
3461 <filename>deploy</filename> directory, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003462 "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
3463 and
3464 "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
3465 sections both in the Yocto Project Overview and Concepts
3466 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003467 </para>
3468 </glossdef>
3469 </glossentry>
3470
3471 <glossentry id='var-DEPLOY_DIR_IPK'><glossterm>DEPLOY_DIR_IPK</glossterm>
3472 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003473 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 -05003474 </info>
3475 <glossdef>
3476 <para role="glossdeffirst">
3477<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3478 Points to the area that the OpenEmbedded build system uses
3479 to place IPK packages that are ready to be used outside of
3480 the build system.
3481 This variable applies only when
3482 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3483 contains "package_ipk".
3484 </para>
3485
3486 <para>
3487 The BitBake configuration file initially defines this
3488 variable as a sub-folder of
3489 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3490 <literallayout class='monospaced'>
3491 DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
3492 </literallayout>
3493 </para>
3494
3495 <para>
3496 The
3497 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>
3498 class uses the
3499 <filename>DEPLOY_DIR_IPK</filename> variable to make sure
3500 the
3501 <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
3502 task writes IPK packages into the appropriate folder.
3503 For more information on how packaging works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003504 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3505 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003506 </para>
3507 </glossdef>
3508 </glossentry>
3509
3510 <glossentry id='var-DEPLOY_DIR_RPM'><glossterm>DEPLOY_DIR_RPM</glossterm>
3511 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003512 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 -05003513 </info>
3514 <glossdef>
3515 <para role="glossdeffirst">
3516<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3517 Points to the area that the OpenEmbedded build system uses
3518 to place RPM packages that are ready to be used outside
3519 of the build system.
3520 This variable applies only when
3521 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3522 contains "package_rpm".
3523 </para>
3524
3525 <para>
3526 The BitBake configuration file initially defines this
3527 variable as a sub-folder of
3528 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3529 <literallayout class='monospaced'>
3530 DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
3531 </literallayout>
3532 </para>
3533
3534 <para>
3535 The
3536 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>
3537 class uses the
3538 <filename>DEPLOY_DIR_RPM</filename> variable to make sure
3539 the
3540 <link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link>
3541 task writes RPM packages into the appropriate folder.
3542 For more information on how packaging works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003543 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3544 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003545 </para>
3546 </glossdef>
3547 </glossentry>
3548
3549 <glossentry id='var-DEPLOY_DIR_TAR'><glossterm>DEPLOY_DIR_TAR</glossterm>
3550 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003551 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 -05003552 </info>
3553 <glossdef>
3554 <para role="glossdeffirst">
3555<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3556 Points to the area that the OpenEmbedded build system uses
3557 to place tarballs that are ready to be used outside of
3558 the build system.
3559 This variable applies only when
3560 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3561 contains "package_tar".
3562 </para>
3563
3564 <para>
3565 The BitBake configuration file initially defines this
3566 variable as a sub-folder of
3567 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3568 <literallayout class='monospaced'>
3569 DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"
3570 </literallayout>
3571 </para>
3572
3573 <para>
3574 The
3575 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
3576 class uses the
3577 <filename>DEPLOY_DIR_TAR</filename> variable to make sure
3578 the
3579 <link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>
3580 task writes TAR packages into the appropriate folder.
3581 For more information on how packaging works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003582 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3583 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003584 </para>
3585 </glossdef>
3586 </glossentry>
3587
3588 <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm>
3589 <info>
3590 DEPLOYDIR[doc] = "For recipes that inherit the deploy class, the DEPLOYDIR points to a temporary work area for deployed files."
3591 </info>
3592 <glossdef>
3593 <para role="glossdeffirst">
3594<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3595 When inheriting the
3596 <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
3597 class, the <filename>DEPLOYDIR</filename> points to a
3598 temporary work area for deployed files that is set in the
3599 <filename>deploy</filename> class as follows:
3600 <literallayout class='monospaced'>
3601 DEPLOYDIR = "${WORKDIR}/deploy-${<link linkend='var-PN'><filename>PN</filename></link>}"
3602 </literallayout>
3603 </para>
3604
3605 <para>
3606 Recipes inheriting the <filename>deploy</filename> class
3607 should copy files to be deployed into
3608 <filename>DEPLOYDIR</filename>, and the class will take
3609 care of copying them into
3610 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
3611 afterwards.
3612 </para>
3613 </glossdef>
3614 </glossentry>
3615
3616 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
3617 <info>
3618 DESCRIPTION[doc] = "The package description used by package managers. If not set, DESCRIPTION takes the value of the SUMMARY variable."
3619 </info>
3620 <glossdef>
3621 <para role="glossdeffirst">
3622<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3623 The package description used by package managers.
3624 If not set, <filename>DESCRIPTION</filename> takes
3625 the value of the
3626 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
3627 variable.
3628 </para>
3629 </glossdef>
3630 </glossentry>
3631
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003632 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
3633 <info>
3634 DISTRO[doc] = "The short name of the distribution. If the variable is blank, meta/conf/distro/defaultsetup.conf will be used."
3635 </info>
3636 <glossdef>
3637 <para role="glossdeffirst">
3638<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3639 The short name of the distribution.
Brad Bishopd5ae7d92018-06-14 09:52:03 -07003640 For information on the long name of the distribution, see
3641 the
3642 <link linkend='var-DISTRO_NAME'><filename>DISTRO_NAME</filename></link>
3643 variable.
3644 </para>
3645
3646 <para>
3647 The <filename>DISTRO</filename> variable corresponds to a
3648 distribution configuration file whose root name is the
3649 same as the variable's argument and whose filename
3650 extension is <filename>.conf</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003651 For example, the distribution configuration file for the
3652 Poky distribution is named <filename>poky.conf</filename>
3653 and resides in the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003654 <filename>meta-poky/conf/distro</filename> directory of
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003655 the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003656 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003657 </para>
3658
3659 <para>
3660 Within that <filename>poky.conf</filename> file, the
3661 <filename>DISTRO</filename> variable is set as follows:
3662 <literallayout class='monospaced'>
3663 DISTRO = "poky"
3664 </literallayout>
3665 </para>
3666
3667 <para>
3668 Distribution configuration files are located in a
3669 <filename>conf/distro</filename> directory within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003670 <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003671 that contains the distribution configuration.
3672 The value for <filename>DISTRO</filename> must not contain
3673 spaces, and is typically all lower-case.
3674 <note>
Brad Bishopd5ae7d92018-06-14 09:52:03 -07003675 If the <filename>DISTRO</filename> variable is blank,
3676 a set of default configurations are used, which are
3677 specified within
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003678 <filename>meta/conf/distro/defaultsetup.conf</filename>
3679 also in the Source Directory.
3680 </note>
3681 </para>
3682 </glossdef>
3683 </glossentry>
3684
3685 <glossentry id='var-DISTRO_CODENAME'><glossterm>DISTRO_CODENAME</glossterm>
3686 <info>
3687 DISTRO_CODENAME[doc] = "Specifies a codename for the distribution being built."
3688 </info>
3689 <glossdef>
3690 <para role="glossdeffirst">
3691<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3692 Specifies a codename for the distribution being built.
3693 </para>
3694 </glossdef>
3695 </glossentry>
3696
3697 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
3698 <info>
3699 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."
3700 </info>
3701 <glossdef>
3702 <para role="glossdeffirst">
3703<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3704 Specifies a list of distro-specific packages to add to all images.
3705 This variable takes affect through
3706 <filename>packagegroup-base</filename> so the
3707 variable only really applies to the more full-featured
3708 images that include <filename>packagegroup-base</filename>.
3709 You can use this variable to keep distro policy out of
3710 generic images.
3711 As with all other distro variables, you set this variable
3712 in the distro <filename>.conf</filename> file.
3713 </para>
3714 </glossdef>
3715 </glossentry>
3716
3717 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
3718 <info>
3719 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."
3720 </info>
3721 <glossdef>
3722 <para role="glossdeffirst">
3723<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3724 Specifies a list of distro-specific packages to add to all images
3725 if the packages exist.
3726 The packages might not exist or be empty (e.g. kernel modules).
3727 The list of packages are automatically installed but you can
3728 remove them.
3729 </para>
3730 </glossdef>
3731 </glossentry>
3732
3733 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
3734 <info>
3735 DISTRO_FEATURES[doc] = "The features enabled for the distribution."
3736 </info>
3737 <glossdef>
3738 <para role="glossdeffirst">
3739<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3740 The software support you want in your distribution for
3741 various features.
3742 You define your distribution features in the distribution
3743 configuration file.
3744 </para>
3745
3746 <para>
3747 In most cases, the presence or absence of a feature in
3748 <filename>DISTRO_FEATURES</filename> is translated to the
3749 appropriate option supplied to the configure script
3750 during the
3751 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
3752 task for recipes that optionally support the feature.
3753 For example, specifying "x11" in
3754 <filename>DISTRO_FEATURES</filename>, causes
3755 every piece of software built for the target that can
3756 optionally support X11 to have its X11 support enabled.
3757 </para>
3758
3759 <para>
3760 Two more examples are Bluetooth and NFS support.
3761 For a more complete list of features that ships with the
3762 Yocto Project and that you can provide with this variable,
3763 see the
3764 "<link linkend='ref-features-distro'>Distro Features</link>"
3765 section.
3766 </para>
3767 </glossdef>
3768 </glossentry>
3769
3770 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
3771 <info>
3772 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."
3773 </info>
3774 <glossdef>
3775 <para role="glossdeffirst">
3776<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3777 Features to be added to
3778 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
3779 if not also present in
3780 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
3781 </para>
3782
3783 <para>
3784 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
3785 It is not intended to be user-configurable.
3786 It is best to just reference the variable to see which distro features are
3787 being backfilled for all distro configurations.
Brad Bishop316dfdd2018-06-25 12:45:53 -04003788 See the <link linkend='ref-features-backfill'>Feature Backfilling</link> section for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003789 more information.
3790 </para>
3791 </glossdef>
3792 </glossentry>
3793
3794 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
3795 <info>
3796 DISTRO_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from DISTRO_FEATURES_BACKFILL that should not be backfilled (i.e. added to DISTRO_FEATURES) during the build."
3797 </info>
3798 <glossdef>
3799 <para role="glossdeffirst">
3800<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3801 Features from
3802 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
3803 that should not be backfilled (i.e. added to
3804 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
3805 during the build.
3806 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
3807 more information.
3808 </para>
3809 </glossdef>
3810 </glossentry>
3811
3812 <glossentry id='var-DISTRO_FEATURES_DEFAULT'><glossterm>DISTRO_FEATURES_DEFAULT</glossterm>
3813 <info>
3814 DISTRO_FEATURES_DEFAULT[doc] = "Provides the default list of distro features with the exception of any libc-specific features."
3815 </info>
3816 <glossdef>
3817 <para role="glossdeffirst">
3818<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3819 A convenience variable that gives you the default
3820 list of distro features with the exception of any
3821 features specific to the C library
3822 (<filename>libc</filename>).
3823 </para>
3824
3825 <para>
3826 When creating a custom distribution, you might find it
3827 useful to be able to reuse the default
3828 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3829 options without the need to write out the full set.
3830 Here is an example that uses
3831 <filename>DISTRO_FEATURES_DEFAULT</filename> from a
3832 custom distro configuration file:
3833 <literallayout class='monospaced'>
Brad Bishop19323692019-04-05 15:28:33 -04003834 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003835 </literallayout>
3836 </para>
3837 </glossdef>
3838 </glossentry>
3839
Brad Bishop6e60e8b2018-02-01 10:27:11 -05003840 <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVE'><glossterm>DISTRO_FEATURES_FILTER_NATIVE</glossterm>
3841 <info>
3842 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."
3843 </info>
3844 <glossdef>
3845 <para role="glossdeffirst">
3846<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3847 Specifies a list of features that if present in
3848 the target
3849 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3850 value should be included in
3851 <filename>DISTRO_FEATURES</filename> when building native
3852 recipes.
3853 This variable is used in addition to the features
3854 filtered using the
3855 <link linkend='var-DISTRO_FEATURES_NATIVE'><filename>DISTRO_FEATURES_NATIVE</filename></link>
3856 variable.
3857 </para>
3858 </glossdef>
3859 </glossentry>
3860
3861 <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVESDK'><glossterm>DISTRO_FEATURES_FILTER_NATIVESDK</glossterm>
3862 <info>
3863 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."
3864 </info>
3865 <glossdef>
3866 <para role="glossdeffirst">
3867<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3868 Specifies a list of features that if present in the target
3869 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3870 value should be included in
3871 <filename>DISTRO_FEATURES</filename> when building
3872 nativesdk recipes.
3873 This variable is used in addition to the features
3874 filtered using the
3875 <link linkend='var-DISTRO_FEATURES_NATIVESDK'><filename>DISTRO_FEATURES_NATIVESDK</filename></link>
3876 variable.
3877 </para>
3878 </glossdef>
3879 </glossentry>
3880
Brad Bishop19323692019-04-05 15:28:33 -04003881<!--
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003882 <glossentry id='var-DISTRO_FEATURES_LIBC'><glossterm>DISTRO_FEATURES_LIBC</glossterm>
3883 <info>
3884 DISTRO_FEATURES_LIBC[doc] = "Specifies the list of distro features that are specific to the C library (libc)."
3885 </info>
3886 <glossdef>
3887 <para role="glossdeffirst">
Brad Bishop19323692019-04-05 15:28:33 -04003888 <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" />
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003889 A convenience variable that specifies the list of distro
3890 features that are specific to the C library
3891 (<filename>libc</filename>).
3892 Typically, these features are prefixed with "libc-" and
3893 control which features are enabled at during the build
3894 within the C library itself.
3895 </para>
3896 </glossdef>
3897 </glossentry>
Brad Bishop19323692019-04-05 15:28:33 -04003898-->
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003899
Brad Bishop6e60e8b2018-02-01 10:27:11 -05003900 <glossentry id='var-DISTRO_FEATURES_NATIVE'><glossterm>DISTRO_FEATURES_NATIVE</glossterm>
3901 <info>
3902 DISTRO_FEATURES_NATIVE[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building native recipes."
3903 </info>
3904 <glossdef>
3905 <para role="glossdeffirst">
3906<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3907 Specifies a list of features that should be included in
3908 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3909 when building native recipes.
3910 This variable is used in addition to the features
3911 filtered using the
3912 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVE'><filename>DISTRO_FEATURES_FILTER_NATIVE</filename></link>
3913 variable.
3914 </para>
3915 </glossdef>
3916 </glossentry>
3917
3918 <glossentry id='var-DISTRO_FEATURES_NATIVESDK'><glossterm>DISTRO_FEATURES_NATIVESDK</glossterm>
3919 <info>
3920 DISTRO_FEATURES_NATIVESDK[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building nativesdk recipes."
3921 </info>
3922 <glossdef>
3923 <para role="glossdeffirst">
3924<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3925 Specifies a list of features that should be included in
3926 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3927 when building nativesdk recipes.
3928 This variable is used in addition to the features
3929 filtered using the
3930 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVESDK'><filename>DISTRO_FEATURES_FILTER_NATIVESDK</filename></link>
3931 variable.
3932 </para>
3933 </glossdef>
3934 </glossentry>
3935
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003936 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
3937 <info>
3938 DISTRO_NAME[doc] = "The long name of the distribution."
3939 </info>
3940 <glossdef>
3941 <para role="glossdeffirst">
3942<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3943 The long name of the distribution.
Brad Bishopd5ae7d92018-06-14 09:52:03 -07003944 For information on the short name of the distribution, see
3945 the
3946 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
3947 variable.
3948 </para>
3949
3950 <para>
3951 The <filename>DISTRO_NAME</filename> variable corresponds
3952 to a distribution configuration file whose root name is the
3953 same as the variable's argument and whose filename
3954 extension is <filename>.conf</filename>.
3955 For example, the distribution configuration file for the
3956 Poky distribution is named <filename>poky.conf</filename>
3957 and resides in the
3958 <filename>meta-poky/conf/distro</filename> directory of
3959 the
3960 <link linkend='source-directory'>Source Directory</link>.
3961 </para>
3962
3963 <para>
3964 Within that <filename>poky.conf</filename> file, the
3965 <filename>DISTRO_NAME</filename> variable is set as
3966 follows:
3967 <literallayout class='monospaced'>
3968 DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
3969 </literallayout>
3970 </para>
3971
3972 <para>
3973 Distribution configuration files are located in a
3974 <filename>conf/distro</filename> directory within the
3975 <link linkend='metadata'>Metadata</link>
3976 that contains the distribution configuration.
3977 <note>
3978 If the <filename>DISTRO_NAME</filename> variable is
3979 blank, a set of default configurations are used, which
3980 are specified within
3981 <filename>meta/conf/distro/defaultsetup.conf</filename>
3982 also in the Source Directory.
3983 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003984 </para>
3985 </glossdef>
3986 </glossentry>
3987
3988 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
3989 <info>
3990 DISTRO_VERSION[doc] = "The version of the distribution."
3991 </info>
3992 <glossdef>
3993 <para role="glossdeffirst">
3994<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3995 The version of the distribution.
3996 </para>
3997 </glossdef>
3998 </glossentry>
3999
4000 <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
4001 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004002 DISTROOVERRIDES[doc] = "A colon-separated list of overrides specific to the current distribution."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004003 </info>
4004 <glossdef>
4005 <para role="glossdeffirst">
4006<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004007 A colon-separated list of overrides specific to the
4008 current distribution.
4009 By default, this list includes the value of
4010 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>.
4011 </para>
4012
4013 <para>
4014 You can extend <filename>DISTROOVERRIDES</filename>
4015 to add extra overrides that should apply to
4016 the distribution.
4017 </para>
4018
4019 <para>
4020 The underlying mechanism behind
4021 <filename>DISTROOVERRIDES</filename> is simply that it
4022 is included in the default value of
4023 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004024 </para>
4025 </glossdef>
4026 </glossentry>
4027
4028 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
4029 <info>
4030 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."
4031 </info>
4032 <glossdef>
4033 <para role="glossdeffirst">
4034<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4035 The central download directory used by the build process to
4036 store downloads.
4037 By default, <filename>DL_DIR</filename> gets files
4038 suitable for mirroring for everything except Git
4039 repositories.
4040 If you want tarballs of Git repositories, use the
4041 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
4042 variable.
4043 </para>
4044
4045 <para>
4046 You can set this directory by defining the
4047 <filename>DL_DIR</filename> variable in the
4048 <filename>conf/local.conf</filename> file.
4049 This directory is self-maintaining and you should not have
4050 to touch it.
4051 By default, the directory is <filename>downloads</filename>
4052 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004053 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004054 <literallayout class='monospaced'>
4055 #DL_DIR ?= "${TOPDIR}/downloads"
4056 </literallayout>
4057 To specify a different download directory, simply remove
4058 the comment from the line and provide your directory.
4059 </para>
4060
4061 <para>
4062 During a first build, the system downloads many different
4063 source code tarballs from various upstream projects.
4064 Downloading can take a while, particularly if your network
4065 connection is slow.
4066 Tarballs are all stored in the directory defined by
4067 <filename>DL_DIR</filename> and the build system looks there
4068 first to find source tarballs.
4069 <note>
4070 When wiping and rebuilding, you can preserve this
4071 directory to speed up this part of subsequent
4072 builds.
4073 </note>
4074 </para>
4075
4076 <para>
4077 You can safely share this directory between multiple builds
4078 on the same development machine.
4079 For additional information on how the build process gets
4080 source files when working behind a firewall or proxy server,
4081 see this specific question in the
4082 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
4083 chapter.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05004084 You can also refer to the
4085 "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
4086 Wiki page.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004087 </para>
4088 </glossdef>
4089 </glossentry>
4090
4091 <glossentry id='var-DOC_COMPRESS'><glossterm>DOC_COMPRESS</glossterm>
4092 <info>
4093 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."
4094 </info>
4095 <glossdef>
4096 <para role="glossdeffirst">
4097<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4098 When inheriting the
4099 <link linkend='ref-classes-compress_doc'><filename>compress_doc</filename></link>
4100 class, this variable sets the compression policy used when
4101 the OpenEmbedded build system compresses man pages and info
4102 pages.
4103 By default, the compression method used is gz (gzip).
4104 Other policies available are xz and bz2.
4105 </para>
4106
4107 <para>
4108 For information on policies and on how to use this
4109 variable, see the comments in the
4110 <filename>meta/classes/compress_doc.bbclass</filename> file.
4111 </para>
4112 </glossdef>
4113 </glossentry>
4114
4115 </glossdiv>
4116
4117 <glossdiv id='var-glossary-e'><title>E</title>
4118
4119 <glossentry id='var-EFI_PROVIDER'><glossterm>EFI_PROVIDER</glossterm>
4120 <info>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004121 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 -05004122 </info>
4123 <glossdef>
4124 <para role="glossdeffirst">
4125<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4126 When building bootable images (i.e. where
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004127 <filename>hddimg</filename>, <filename>iso</filename>,
4128 or <filename>wic.vmdk</filename> is in
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004129 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>),
4130 the <filename>EFI_PROVIDER</filename> variable specifies
4131 the EFI bootloader to use.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004132 The default is "grub-efi", but "systemd-boot" can be used
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004133 instead.
4134 </para>
4135
4136 <para>
4137 See the
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004138 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05004139 and
4140 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
4141 classes for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004142 </para>
4143 </glossdef>
4144 </glossentry>
4145
4146 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
4147 <info>
4148 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."
4149 </info>
4150 <glossdef>
4151 <para role="glossdeffirst">
4152<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4153 Variable that controls which locales for
4154 <filename>glibc</filename> are generated during the
4155 build (useful if the target device has 64Mbytes
4156 of RAM or less).
4157 </para>
4158 </glossdef>
4159 </glossentry>
4160
4161 <glossentry id='var-ERR_REPORT_DIR'><glossterm>ERR_REPORT_DIR</glossterm>
4162 <info>
4163 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."
4164 </info>
4165 <glossdef>
4166 <para role="glossdeffirst">
4167<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4168 When used with the
4169 <link linkend='ref-classes-report-error'><filename>report-error</filename></link>
4170 class, specifies the path used for storing the debug files
4171 created by the
4172 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
4173 which allows you to submit build errors you encounter to a
4174 central database.
4175 By default, the value of this variable is
4176 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
4177 </para>
4178
4179 <para>
4180 You can set <filename>ERR_REPORT_DIR</filename> to the path
4181 you want the error reporting tool to store the debug files
4182 as follows in your <filename>local.conf</filename> file:
4183 <literallayout class='monospaced'>
4184 ERR_REPORT_DIR = "<replaceable>path</replaceable>"
4185 </literallayout>
4186 </para>
4187 </glossdef>
4188 </glossentry>
4189
4190 <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
4191 <info>
4192 ERROR_QA[doc] = "Specifies the quality assurance checks whose failures are reported as errors by the OpenEmbedded build system."
4193 </info>
4194 <glossdef>
4195 <para role="glossdeffirst">
4196<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4197 Specifies the quality assurance checks whose failures are
4198 reported as errors by the OpenEmbedded build system.
4199 You set this variable in your distribution configuration
4200 file.
4201 For a list of the checks you can control with this variable,
4202 see the
4203 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
4204 section.
4205 </para>
4206 </glossdef>
4207 </glossentry>
4208
Patrick Williamsf1e5d692016-03-30 15:21:19 -05004209 <glossentry id='var-EXCLUDE_FROM_SHLIBS'><glossterm>EXCLUDE_FROM_SHLIBS</glossterm>
4210 <info>
4211 EXCLUDE_FROM_SHLIBS[doc] = "Causes the OpenEmbedded build system's shared libraries resolver to exclude an entire package when scanning for shared libraries."
4212 </info>
4213 <glossdef>
4214 <para role="glossdeffirst">
4215<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4216 Triggers the OpenEmbedded build system's shared libraries
4217 resolver to exclude an entire package when scanning for
4218 shared libraries.
4219 <note>
4220 The shared libraries resolver's functionality results
4221 in part from the internal function
4222 <filename>package_do_shlibs</filename>, which is part of
4223 the
4224 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
4225 task.
4226 You should be aware that the shared libraries resolver
4227 might implicitly define some dependencies between
4228 packages.
4229 </note>
4230 The <filename>EXCLUDE_FROM_SHLIBS</filename> variable is
4231 similar to the
4232 <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
4233 variable, which excludes a package's particular libraries
4234 only and not the whole package.
4235 </para>
4236
4237 <para>
4238 Use the
4239 <filename>EXCLUDE_FROM_SHLIBS</filename> variable by
4240 setting it to "1" for a particular package:
4241 <literallayout class='monospaced'>
4242 EXCLUDE_FROM_SHLIBS = "1"
4243 </literallayout>
4244 </para>
4245 </glossdef>
4246 </glossentry>
4247
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004248 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
4249 <info>
4250 EXCLUDE_FROM_WORLD[doc] = "Directs BitBake to exclude a recipe from world builds (i.e. bitbake world)."
4251 </info>
4252 <glossdef>
4253 <para role="glossdeffirst">
4254<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4255 Directs BitBake to exclude a recipe from world builds (i.e.
4256 <filename>bitbake world</filename>).
4257 During world builds, BitBake locates, parses and builds all
4258 recipes found in every layer exposed in the
4259 <filename>bblayers.conf</filename> configuration file.
4260 </para>
4261
4262 <para>
4263 To exclude a recipe from a world build using this variable,
4264 set the variable to "1" in the recipe.
4265 </para>
4266
4267 <note>
4268 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
4269 may still be built during a world build in order to satisfy
4270 dependencies of other recipes.
4271 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
4272 only ensures that the recipe is not explicitly added
4273 to the list of build targets in a world build.
4274 </note>
4275 </glossdef>
4276 </glossentry>
4277
4278 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
4279 <info>
4280 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."
4281 </info>
4282 <glossdef>
4283 <para role="glossdeffirst">
4284<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4285 Used with file and pathnames to create a prefix for a recipe's
4286 version based on the recipe's
4287 <link linkend='var-PE'><filename>PE</filename></link> value.
4288 If <filename>PE</filename> is set and greater than zero for a recipe,
4289 <filename>EXTENDPE</filename> becomes that value (e.g if
4290 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
4291 becomes "1_").
4292 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
4293 zero, <filename>EXTENDPE</filename> becomes "".</para>
4294 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
4295 variable for an example.
4296 </para>
4297 </glossdef>
4298 </glossentry>
4299
4300 <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
4301 <info>
4302 EXTENDPKGV[doc] = "The full package version specification as it appears on the final packages produced by a recipe."
4303 </info>
4304 <glossdef>
4305 <para role="glossdeffirst">
4306<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4307 The full package version specification as it appears on the
4308 final packages produced by a recipe.
4309 The variable's value is normally used to fix a runtime
4310 dependency to the exact same version of another package
4311 in the same recipe:
4312 <literallayout class='monospaced'>
4313 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
4314 </literallayout>
4315 </para>
4316
4317 <para>
4318 The dependency relationships are intended to force the
4319 package manager to upgrade these types of packages in
4320 lock-step.
4321 </para>
4322 </glossdef>
4323 </glossentry>
4324
4325 <glossentry id='var-EXTERNAL_KERNEL_TOOLS'><glossterm>EXTERNAL_KERNEL_TOOLS</glossterm>
4326 <info>
4327 EXTERNAL_KERNEL_TOOLS[doc] = "Indicates kernel tools are external to the source tree."
4328 </info>
4329 <glossdef>
4330 <para role="glossdeffirst">
4331<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4332 When set, the <filename>EXTERNAL_KERNEL_TOOLS</filename>
4333 variable indicates that these tools are not in the
4334 source tree.
4335 </para>
4336
4337 <para>
4338 When kernel tools are available in the tree, they are
4339 preferred over any externally installed tools.
4340 Setting the <filename>EXTERNAL_KERNEL_TOOLS</filename>
4341 variable tells the OpenEmbedded build system to prefer
4342 the installed external tools.
4343 See the
4344 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
4345 class in <filename>meta/classes</filename> to see how
4346 the variable is used.
4347 </para>
4348 </glossdef>
4349 </glossentry>
4350
4351 <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
4352 <info>
4353 EXTERNALSRC[doc] = "If externalsrc.bbclass is inherited, this variable points to the source tree, which is outside of the OpenEmbedded build system."
4354 </info>
4355 <glossdef>
4356 <para role="glossdeffirst">
4357<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4358 When inheriting the
4359 <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link>
4360 class, this variable points to the source tree, which is
4361 outside of the OpenEmbedded build system.
4362 When set, this variable sets the
4363 <link linkend='var-S'><filename>S</filename></link>
4364 variable, which is what the OpenEmbedded build system uses
4365 to locate unpacked recipe source code.
4366 </para>
4367
4368 <para>
4369 For more information on
4370 <filename>externalsrc.bbclass</filename>, see the
4371 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
4372 section.
4373 You can also find information on how to use this variable
4374 in the
4375 "<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 -05004376 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004377 </para>
4378 </glossdef>
4379 </glossentry>
4380
4381 <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
4382 <info>
4383 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."
4384 </info>
4385 <glossdef>
4386 <para role="glossdeffirst">
4387<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4388 When inheriting the
4389 <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link>
4390 class, this variable points to the directory in which the
4391 recipe's source code is built, which is outside of the
4392 OpenEmbedded build system.
4393 When set, this variable sets the
4394 <link linkend='var-B'><filename>B</filename></link>
4395 variable, which is what the OpenEmbedded build system uses
4396 to locate the Build Directory.
4397 </para>
4398
4399 <para>
4400 For more information on
4401 <filename>externalsrc.bbclass</filename>, see the
4402 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
4403 section.
4404 You can also find information on how to use this variable
4405 in the
4406 "<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 -05004407 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004408 </para>
4409 </glossdef>
4410 </glossentry>
4411
4412 <glossentry id='var-EXTRA_AUTORECONF'><glossterm>EXTRA_AUTORECONF</glossterm>
4413 <info>
4414 EXTRA_AUTORECONF[doc] = "Extra options passed to the autoreconf command, which is executed during do_configure."
4415 </info>
4416 <glossdef>
4417 <para role="glossdeffirst">
4418<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4419 For recipes inheriting the
4420 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
4421 class, you can use <filename>EXTRA_AUTORECONF</filename> to
4422 specify extra options to pass to the
4423 <filename>autoreconf</filename> command that is
4424 executed during the
4425 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
4426 task.
4427 </para>
4428
4429 <para>
4430 The default value is "--exclude=autopoint".
4431 </para>
4432 </glossdef>
4433 </glossentry>
4434
4435 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
4436 <info>
4437 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."
4438 </info>
4439 <glossdef>
4440 <para role="glossdeffirst">
4441<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4442 A list of additional features to include in an image.
4443 When listing more than one feature, separate them with
4444 a space.
4445 </para>
4446
4447 <para>
4448 Typically, you configure this variable in your
4449 <filename>local.conf</filename> file, which is found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004450 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004451 Although you can use this variable from within a recipe,
4452 best practices dictate that you do not.
4453 <note>
4454 To enable primary features from within the image
4455 recipe, use the
4456 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
4457 variable.
4458 </note>
4459 </para>
4460
4461 <para>
4462 Here are some examples of features you can add:
4463 <literallayout class='monospaced'>
4464"dbg-pkgs" - Adds -dbg packages for all installed packages
4465 including symbol information for debugging and
4466 profiling.
4467
4468"debug-tweaks" - Makes an image suitable for debugging.
4469 For example, allows root logins without
4470 passwords and enables post-installation
4471 logging. See the 'allow-empty-password'
4472 and 'post-install-logging' features in
4473 the "<link linkend='ref-features-image'>Image Features</link>" section for
4474 more information.
4475
4476"dev-pkgs" - Adds -dev packages for all installed packages.
4477 This is useful if you want to develop against
4478 the libraries in the image.
4479
4480"read-only-rootfs" - Creates an image whose root
4481 filesystem is read-only. See the
4482 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
4483 section in the Yocto Project
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004484 Development Tasks Manual for
4485 more information
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004486
4487"tools-debug" - Adds debugging tools such as gdb and
4488 strace.
4489
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004490"tools-sdk" - Adds development tools such as gcc, make,
4491 pkgconfig and so forth.
4492
4493"tools-testapps" - Adds useful testing tools such as
4494 ts_print, aplay, arecord and so
4495 forth.
4496
4497 </literallayout>
4498 </para>
4499
4500 <para>
4501 For a complete list of image features that ships with the
4502 Yocto Project, see the
4503 "<link linkend="ref-features-image">Image Features</link>"
4504 section.
4505 </para>
4506
4507 <para>
4508 For an example that shows how to customize your image by
4509 using this variable, see the
4510 "<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 -05004511 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004512 </para>
4513 </glossdef>
4514 </glossentry>
4515
4516 <glossentry id='var-EXTRA_IMAGECMD'><glossterm>EXTRA_IMAGECMD</glossterm>
4517 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04004518 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 -05004519 </info>
4520 <glossdef>
4521 <para role="glossdeffirst">
4522<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4523 Specifies additional options for the image
4524 creation command that has been specified in
4525 <link linkend='var-IMAGE_CMD'><filename>IMAGE_CMD</filename></link>.
Brad Bishop316dfdd2018-06-25 12:45:53 -04004526 When setting this variable, use an override for the
4527 associated image type.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004528 Here is an example:
4529 <literallayout class='monospaced'>
4530 EXTRA_IMAGECMD_ext3 ?= "-i 4096"
4531 </literallayout>
4532 </para>
4533 </glossdef>
4534 </glossentry>
4535
4536 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
4537 <info>
4538 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."
4539 </info>
4540 <glossdef>
4541 <para role="glossdeffirst">
4542<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4543 A list of recipes to build that do not provide packages
4544 for installing into the root filesystem.
4545 </para>
4546
4547 <para>
4548 Sometimes a recipe is required to build the final image but is not
4549 needed in the root filesystem.
4550 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
4551 list these recipes and thus specify the dependencies.
4552 A typical example is a required bootloader in a machine configuration.
4553 </para>
4554
4555 <note>
4556 To add packages to the root filesystem, see the various
4557 <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
4558 and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
4559 variables.
4560 </note>
4561 </glossdef>
4562 </glossentry>
4563
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004564 <glossentry id='var-EXTRANATIVEPATH'><glossterm>EXTRANATIVEPATH</glossterm>
4565 <info>
4566 EXTRANATIVEPATH[doc] = "A list of subdirectories of ${STAGING_BINDIR_NATIVE} added to the beginning of the environment variable PATH."
4567 </info>
4568 <glossdef>
4569 <para role="glossdeffirst">
4570<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4571 A list of subdirectories of
4572 <filename>${</filename><link linkend='var-STAGING_BINDIR_NATIVE'><filename>STAGING_BINDIR_NATIVE</filename></link><filename>}</filename>
4573 added to the beginning of the environment variable
4574 <filename>PATH</filename>.
4575 As an example, the following prepends
4576 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:"
4577 to <filename>PATH</filename>:
4578 <literallayout class='monospaced'>
4579 EXTRANATIVEPATH = "foo bar"
4580 </literallayout>
4581 </para>
4582 </glossdef>
4583 </glossentry>
4584
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004585 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
4586 <info>
4587 EXTRA_OECMAKE[doc] = "Additional cmake options."
4588 </info>
4589 <glossdef>
4590 <para role="glossdeffirst">
4591<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08004592 Additional
4593 <ulink url='https://cmake.org/overview/'>CMake</ulink>
4594 options.
4595 See the
4596 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
4597 class for additional information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004598 </para>
4599 </glossdef>
4600 </glossentry>
4601
4602 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
4603 <info>
4604 EXTRA_OECONF[doc] = "Additional configure script options."
4605 </info>
4606 <glossdef>
4607 <para role="glossdeffirst">
4608<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4609 Additional <filename>configure</filename> script options.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004610 See
4611 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>
4612 for additional information on passing configure script
4613 options.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004614 </para>
4615 </glossdef>
4616 </glossentry>
4617
4618 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
4619 <info>
4620 EXTRA_OEMAKE[doc] = "Additional GNU make options."
4621 </info>
4622 <glossdef>
4623 <para role="glossdeffirst">
4624<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4625 Additional GNU <filename>make</filename> options.
4626 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05004627
4628 <para>
4629 Because the <filename>EXTRA_OEMAKE</filename> defaults to
4630 "", you need to set the variable to specify any required
4631 GNU options.
4632 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004633
4634 <para>
4635 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
4636 and
4637 <link linkend='var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></link>
4638 also make use of
4639 <filename>EXTRA_OEMAKE</filename> to pass the required
4640 flags.
4641 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004642 </glossdef>
4643 </glossentry>
4644
4645 <glossentry id='var-EXTRA_OESCONS'><glossterm>EXTRA_OESCONS</glossterm>
4646 <info>
4647 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."
4648 </info>
4649 <glossdef>
4650 <para role="glossdeffirst">
4651<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4652 When inheriting the
4653 <link linkend='ref-classes-scons'><filename>scons</filename></link>
4654 class, this variable specifies additional configuration
4655 options you want to pass to the
4656 <filename>scons</filename> command line.
4657 </para>
4658 </glossdef>
4659 </glossentry>
4660
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004661 <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm>
4662 <info>
4663 EXTRA_USERS_PARAMS[doc] = "When a recipe inherits the extrausers class, this variable provides image level user and group operations."
4664 </info>
4665 <glossdef>
4666 <para role="glossdeffirst">
4667<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4668 When inheriting the
4669 <link linkend='ref-classes-extrausers'><filename>extrausers</filename></link>
4670 class, this variable provides image level user and group
4671 operations.
4672 This is a more global method of providing user and group
4673 configuration as compared to using the
4674 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
4675 class, which ties user and group configurations to a
4676 specific recipe.
4677 </para>
4678
4679 <para>
4680 The set list of commands you can configure using the
4681 <filename>EXTRA_USERS_PARAMS</filename> is shown in the
4682 <filename>extrausers</filename> class.
4683 These commands map to the normal Unix commands of the same
4684 names:
4685 <literallayout class='monospaced'>
4686 # EXTRA_USERS_PARAMS = "\
4687 # useradd -p '' tester; \
4688 # groupadd developers; \
4689 # userdel nobody; \
4690 # groupdel -g video; \
4691 # groupmod -g 1020 developers; \
4692 # usermod -s /bin/sh tester; \
4693 # "
4694 </literallayout>
4695 </para>
4696 </glossdef>
4697 </glossentry>
4698
4699 </glossdiv>
4700
4701 <glossdiv id='var-glossary-f'><title>F</title>
4702
4703 <glossentry id='var-FEATURE_PACKAGES'><glossterm>FEATURE_PACKAGES</glossterm>
4704 <info>
4705 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."
4706 </info>
4707 <glossdef>
4708 <para role="glossdeffirst">
4709<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4710 Defines one or more packages to include in an image when
4711 a specific item is included in
4712 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
4713 When setting the value, <filename>FEATURE_PACKAGES</filename>
4714 should have the name of the feature item as an override.
4715 Here is an example:
4716 <literallayout class='monospaced'>
4717 FEATURE_PACKAGES_widget = "<replaceable>package1</replaceable> <replaceable>package2</replaceable>"
4718 </literallayout>
4719 </para>
4720
4721 <para>
4722 In this example, if "widget" were added to
4723 <filename>IMAGE_FEATURES</filename>, <replaceable>package1</replaceable> and
4724 <replaceable>package2</replaceable> would be included in the image.
4725 <note>
4726 Packages installed by features defined through
4727 <filename>FEATURE_PACKAGES</filename> are often package
4728 groups.
4729 While similarly named, you should not confuse the
4730 <filename>FEATURE_PACKAGES</filename> variable with
4731 package groups, which are discussed elsewhere in the
4732 documentation.
4733 </note>
4734 </para>
4735 </glossdef>
4736 </glossentry>
4737
4738 <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm>
4739 <info>
4740 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."
4741 </info>
4742 <glossdef>
4743 <para role="glossdeffirst">
4744<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4745 Points to the base URL of the server and location within
4746 the document-root that provides the metadata and
4747 packages required by OPKG to support runtime package
4748 management of IPK packages.
4749 You set this variable in your
4750 <filename>local.conf</filename> file.
4751 </para>
4752
4753 <para>
4754 Consider the following example:
4755 <literallayout class='monospaced'>
4756 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
4757 </literallayout>
4758 This example assumes you are serving your packages over
4759 HTTP and your databases are located in a directory
4760 named <filename>BOARD-dir</filename>, which is underneath
4761 your HTTP server's document-root.
4762 In this case, the OpenEmbedded build system generates a set
4763 of configuration files for you in your target that work
4764 with the feed.
4765 </para>
4766 </glossdef>
4767 </glossentry>
4768
4769 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
4770 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004771 FILES[doc] = "The list of directories or files that are placed in a package."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004772 </info>
4773 <glossdef>
4774 <para role="glossdeffirst">
4775<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004776 The list of files and directories that are placed in a
4777 package.
4778 The
4779 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
4780 variable lists the packages generated by a recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004781 </para>
4782
4783 <para>
4784 To use the <filename>FILES</filename> variable, provide a
4785 package name override that identifies the resulting package.
4786 Then, provide a space-separated list of files or paths
4787 that identify the files you want included as part of the
4788 resulting package.
4789 Here is an example:
4790 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004791 FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004792 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08004793 <note><title>Notes</title>
4794 <itemizedlist>
4795 <listitem><para>
4796 When specifying files or paths, you can pattern
4797 match using Python's
4798 <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>
4799 syntax.
4800 For details on the syntax, see the
4801 documentation by following the previous link.
4802 </para></listitem>
4803 <listitem><para>
4804 When specifying paths as part of the
4805 <filename>FILES</filename> variable, it is
4806 good practice to use appropriate path
4807 variables.
4808 For example, use <filename>${sysconfdir}</filename>
4809 rather than <filename>/etc</filename>, or
4810 <filename>${bindir}</filename> rather than
4811 <filename>/usr/bin</filename>.
4812 You can find a list of these variables at the
4813 top of the
4814 <filename>meta/conf/bitbake.conf</filename>
4815 file in the
4816 <link linkend='source-directory'>Source Directory</link>.
4817 You will also find the default values of the
4818 various <filename>FILES_*</filename> variables
4819 in this file.
4820 </para></listitem>
4821 </itemizedlist>
4822 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004823 </para>
4824
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004825 <para>
4826 If some of the files you provide with the
4827 <filename>FILES</filename> variable are editable and you
4828 know they should not be overwritten during the package
4829 update process by the Package Management System (PMS), you
4830 can identify these files so that the PMS will not
4831 overwrite them.
4832 See the
4833 <link linkend='var-CONFFILES'><filename>CONFFILES</filename></link>
4834 variable for information on how to identify these files to
4835 the PMS.
4836 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004837 </glossdef>
4838 </glossentry>
4839
4840 <glossentry id='var-FILES_SOLIBSDEV'><glossterm>FILES_SOLIBSDEV</glossterm>
4841 <info>
4842 FILES_SOLIBSDEV[doc] = "Defines the full path name of the development symbolic link (symlink) for shared libraries on the target platform."
4843 </info>
4844 <glossdef>
4845 <para role="glossdeffirst">
4846<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4847 Defines the file specification to match
4848 <link linkend='var-SOLIBSDEV'><filename>SOLIBSDEV</filename></link>.
4849 In other words, <filename>FILES_SOLIBSDEV</filename>
4850 defines the full path name of the development symbolic link
4851 (symlink) for shared libraries on the target platform.
4852 </para>
4853
4854 <para>
4855 The following statement from the
4856 <filename>bitbake.conf</filename> shows how it is set:
4857 <literallayout class='monospaced'>
4858 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
4859 </literallayout>
4860 </para>
4861 </glossdef>
4862 </glossentry>
4863
4864 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
4865 <info>
4866 FILESEXTRAPATHS[doc] = "Extends the search path the OpenEmbedded build system uses when looking for files and patches as it processes recipes and append files."
4867 </info>
4868 <glossdef>
4869 <para role="glossdeffirst">
4870<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4871 Extends the search path the OpenEmbedded build system uses
4872 when looking for files and patches as it processes recipes
4873 and append files.
4874 The default directories BitBake uses when it processes
4875 recipes are initially defined by the
4876 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4877 variable.
4878 You can extend <filename>FILESPATH</filename> variable
4879 by using <filename>FILESEXTRAPATHS</filename>.
4880 </para>
4881
4882 <para>
4883 Best practices dictate that you accomplish this by using
4884 <filename>FILESEXTRAPATHS</filename> from within a
4885 <filename>.bbappend</filename> file and that you prepend
4886 paths as follows:
4887 <literallayout class='monospaced'>
4888 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
4889 </literallayout>
4890 In the above example, the build system first looks for files
4891 in a directory that has the same name as the corresponding
4892 append file.
4893 <note>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004894 <para>When extending
4895 <filename>FILESEXTRAPATHS</filename>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004896 be sure to use the immediate expansion
4897 (<filename>:=</filename>) operator.
4898 Immediate expansion makes sure that BitBake evaluates
4899 <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
4900 at the time the directive is encountered rather than at
4901 some later time when expansion might result in a
4902 directory that does not contain the files you need.
4903 </para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004904
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004905 <para>Also, include the trailing separating colon
4906 character if you are prepending.
4907 The trailing colon character is necessary because you
4908 are directing BitBake to extend the path by prepending
4909 directories to the search path.</para>
4910 </note>
4911 Here is another common use:
4912 <literallayout class='monospaced'>
4913 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
4914 </literallayout>
4915 In this example, the build system extends the
4916 <filename>FILESPATH</filename> variable to include a
4917 directory named <filename>files</filename> that is in the
4918 same directory as the corresponding append file.
4919 </para>
4920
4921 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004922 This next example specifically adds three paths:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004923 <literallayout class='monospaced'>
4924 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
4925 </literallayout>
4926 </para>
4927
4928 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004929 A final example shows how you can extend the search path
4930 and include a
4931 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>-specific
4932 override, which is useful in a BSP layer:
4933 <literallayout class='monospaced'>
4934 FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:"
4935 </literallayout>
4936 The previous statement appears in the
4937 <filename>linux-yocto-dev.bbappend</filename> file, which
4938 is found in the Yocto Project
Brad Bishop316dfdd2018-06-25 12:45:53 -04004939 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004940 in
4941 <filename>meta-intel/common/recipes-kernel/linux</filename>.
4942 Here, the machine override is a special
4943 <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
4944 definition for multiple <filename>meta-intel</filename>
4945 machines.
4946 <note>
4947 For a layer that supports a single BSP, the override
4948 could just be the value of <filename>MACHINE</filename>.
4949 </note>
4950 </para>
4951
4952 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004953 By prepending paths in <filename>.bbappend</filename>
4954 files, you allow multiple append files that reside in
4955 different layers but are used for the same recipe to
4956 correctly extend the path.
4957 </para>
4958 </glossdef>
4959 </glossentry>
4960
4961 <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
4962 <info>
4963 FILESOVERRIDES[doc] = "A subset of OVERRIDES used by the OpenEmbedded build system for creating FILESPATH."
4964 </info>
4965 <glossdef>
4966 <para role="glossdeffirst">
4967<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4968 A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
4969 used by the OpenEmbedded build system for creating
4970 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
Brad Bishop19323692019-04-05 15:28:33 -04004971 The <filename>FILESOVERRIDES</filename> variable uses
4972 overrides to automatically extend the
4973 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4974 variable.
4975 For an example of how that works, see the
4976 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4977 variable description.
4978 Additionally, you find more information on how overrides
4979 are handled in the
4980 "<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"
4981 section of the BitBake User Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004982 </para>
4983
4984 <para>
4985 By default, the <filename>FILESOVERRIDES</filename>
4986 variable is defined as:
4987 <literallayout class='monospaced'>
4988 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
4989 </literallayout>
4990
4991 <note>
4992 Do not hand-edit the <filename>FILESOVERRIDES</filename>
4993 variable.
4994 The values match up with expected overrides and are
4995 used in an expected manner by the build system.
4996 </note>
4997 </para>
4998 </glossdef>
4999 </glossentry>
5000
5001 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
5002 <info>
5003 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."
5004 </info>
5005 <glossdef>
5006 <para role="glossdeffirst">
5007<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop19323692019-04-05 15:28:33 -04005008 The default set of directories the OpenEmbedded build
5009 system uses when searching for patches and files.
5010 </para>
5011
5012 <para>
5013 During the build process, BitBake searches each directory
5014 in <filename>FILESPATH</filename> in the specified order
5015 when looking for files and patches specified by each
Brad Bishop316dfdd2018-06-25 12:45:53 -04005016 <filename>file://</filename> URI in a recipe's
5017 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
5018 statements.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005019 </para>
5020
5021 <para>
5022 The default value for the <filename>FILESPATH</filename>
5023 variable is defined in the <filename>base.bbclass</filename>
5024 class found in <filename>meta/classes</filename> in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005025 <link linkend='source-directory'>Source Directory</link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005026 <literallayout class='monospaced'>
5027 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
5028 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
5029 </literallayout>
Brad Bishop19323692019-04-05 15:28:33 -04005030 The <filename>FILESPATH</filename> variable is automatically
5031 extended using the overrides from the
5032 <link linkend='var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></link>
5033 variable.
5034 <note><title>Notes</title>
5035 <itemizedlist>
5036 <listitem><para>
5037 Do not hand-edit the
5038 <filename>FILESPATH</filename> variable.
5039 If you want the build system to look in
5040 directories other than the defaults, extend the
5041 <filename>FILESPATH</filename> variable by
5042 using the
5043 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
5044 variable.
5045 </para></listitem>
5046 <listitem><para>
5047 Be aware that the default
5048 <filename>FILESPATH</filename> directories do
5049 not map to directories in custom layers
5050 where append files
5051 (<filename>.bbappend</filename>) are used.
5052 If you want the build system to find patches
5053 or files that reside with your append files,
5054 you need to extend the
5055 <filename>FILESPATH</filename> variable by
5056 using the <filename>FILESEXTRAPATHS</filename>
5057 variable.
5058 </para></listitem>
5059 </itemizedlist>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005060 </note>
Brad Bishop19323692019-04-05 15:28:33 -04005061 </para>
5062
5063 <para>
5064 You can take advantage of this searching behavior in
5065 useful ways.
5066 For example, consider a case where the following
5067 directory structure exists for general and machine-specific
5068 configurations:
5069 <literallayout class='monospaced'>
5070 files/defconfig
5071 files/MACHINEA/defconfig
5072 files/MACHINEB/defconfig
5073 </literallayout>
5074 Also in the example, the <filename>SRC_URI</filename>
5075 statement contains "file://defconfig".
5076 Given this scenario, you can set
5077 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
5078 to "MACHINEA" and cause the build system to use files
5079 from <filename>files/MACHINEA</filename>.
5080 Set <filename>MACHINE</filename> to "MACHINEB" and the
5081 build system uses files from
5082 <filename>files/MACHINEB</filename>.
5083 Finally, for any machine other than "MACHINEA" and
5084 "MACHINEB", the build system uses files from
5085 <filename>files/defconfig</filename>.
Brad Bishop316dfdd2018-06-25 12:45:53 -04005086 </para>
5087
5088 <para>
5089 You can find out more about the patching process in the
5090 "<ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>Patching</ulink>"
5091 section in the Yocto Project Overview and Concepts Manual
5092 and the
5093 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code'>Patching Code</ulink>"
5094 section in the Yocto Project Development Tasks Manual.
5095 See the
5096 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
5097 task as well.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005098 </para>
5099 </glossdef>
5100 </glossentry>
5101
5102 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
5103 <info>
5104 FILESYSTEM_PERMS_TABLES[doc] = "Allows you to define your own file permissions settings table as part of your configuration for the packaging process."
5105 </info>
5106 <glossdef>
5107 <para role="glossdeffirst">
5108<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5109 Allows you to define your own file permissions settings table as part of
5110 your configuration for the packaging process.
5111 For example, suppose you need a consistent set of custom permissions for
5112 a set of groups and users across an entire work project.
5113 It is best to do this in the packages themselves but this is not always
5114 possible.
5115 </para>
5116
5117 <para>
5118 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
5119 is located in the <filename>meta/files</filename> folder in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005120 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005121 If you create your own file permissions setting table, you should place it in your
5122 layer or the distro's layer.
5123 </para>
5124
5125 <para>
5126 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
5127 <filename>conf/local.conf</filename> file, which is found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005128 <link linkend='build-directory'>Build Directory</link>, to
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005129 point to your custom <filename>fs-perms.txt</filename>.
5130 You can specify more than a single file permissions setting table.
5131 The paths you specify to these files must be defined within the
5132 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
5133 </para>
5134
5135 <para>
5136 For guidance on how to create your own file permissions settings table file,
5137 examine the existing <filename>fs-perms.txt</filename>.
5138 </para>
5139 </glossdef>
5140 </glossentry>
5141
5142 <glossentry id='var-FONT_EXTRA_RDEPENDS'><glossterm>FONT_EXTRA_RDEPENDS</glossterm>
5143 <info>
5144 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'."
5145 </info>
5146 <glossdef>
5147 <para role="glossdeffirst">
5148<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5149 When inheriting the
5150 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
5151 class, this variable specifies the runtime dependencies
5152 for font packages.
5153 By default, the <filename>FONT_EXTRA_RDEPENDS</filename>
5154 is set to "fontconfig-utils".
5155 </para>
5156 </glossdef>
5157 </glossentry>
5158
5159 <glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm>
5160 <info>
5161 FONT_PACKAGES[doc] = "When a recipe inherits the fontcache class, this variable identifies packages containing font files that need to be cached by Fontconfig."
5162 </info>
5163 <glossdef>
5164 <para role="glossdeffirst">
5165<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5166 When inheriting the
5167 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
5168 class, this variable identifies packages containing font
5169 files that need to be cached by Fontconfig.
5170 By default, the <filename>fontcache</filename> class assumes
5171 that fonts are in the recipe's main package
5172 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
5173 Use this variable if fonts you need are in a package
5174 other than that main package.
5175 </para>
5176 </glossdef>
5177 </glossentry>
5178
Patrick Williamsc0f7c042017-02-23 20:41:17 -06005179 <glossentry id='var-FORCE_RO_REMOVE'><glossterm>FORCE_RO_REMOVE</glossterm>
5180 <info>
5181 FORCE_RO_REMOVE[doc] = "Forces the removal of the packages listed in ROOTFS_RO_UNNEEDED during the generation of the root filesystem."
5182 </info>
5183 <glossdef>
5184 <para role="glossdeffirst">
5185<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5186 Forces the removal of the packages listed in
5187 <filename>ROOTFS_RO_UNNEEDED</filename> during the
5188 generation of the root filesystem.
5189 </para>
5190
5191 <para>
5192 Set the variable to "1" to force the removal of these
5193 packages.
5194 </para>
5195 </glossdef>
5196 </glossentry>
5197
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005198 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
5199 <info>
5200 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'."
5201 </info>
5202 <glossdef>
5203 <para role="glossdeffirst">
5204<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5205 The options to pass in
5206 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
5207 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
5208 when compiling an optimized system.
5209 This variable defaults to
5210 "-O2 -pipe ${DEBUG_FLAGS}".
5211 </para>
5212 </glossdef>
5213 </glossentry>
5214 </glossdiv>
5215
5216 <glossdiv id='var-glossary-g'><title>G</title>
5217
Brad Bishop316dfdd2018-06-25 12:45:53 -04005218 <glossentry id='var-GCCPIE'><glossterm>GCCPIE</glossterm>
5219 <info>
5220 GCCPIE[doc] = "Enables Position Independent Executables (PIE) within the GNU C Compiler (GCC)."
5221 </info>
5222 <glossdef>
5223 <para role="glossdeffirst">
5224<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5225 Enables Position Independent Executables (PIE) within the
5226 GNU C Compiler (GCC).
5227 Enabling PIE in the GCC makes Return Oriented Programming
5228 (ROP) attacks much more difficult to
5229 execute.
5230 </para>
5231
5232 <para>
5233 By default the <filename>security_flags.inc</filename>
5234 file enables PIE by setting the variable as follows:
5235 <literallayout class='monospaced'>
5236 GCCPIE ?= "--enable-default-pie"
5237 </literallayout>
5238 </para>
5239 </glossdef>
5240 </glossentry>
5241
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08005242 <glossentry id='var-GCCVERSION'><glossterm>GCCVERSION</glossterm>
5243 <info>
5244 GCCVERSION[doc] = "Specifies the default version of the GNU C Compiler (GCC) to use."
5245 </info>
5246 <glossdef>
5247 <para role="glossdeffirst">
5248<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5249 Specifies the default version of the GNU C Compiler (GCC)
5250 used for compilation.
5251 By default, <filename>GCCVERSION</filename> is set to
5252 "8.x" in the
5253 <filename>meta/conf/distro/include/tcmode-default.inc</filename>
5254 include file:
5255 <literallayout class='monospaced'>
5256 GCCVERSION ?= "8.%"
5257 </literallayout>
5258 You can override this value by setting it in a configuration
5259 file such as the <filename>local.conf</filename>.
5260 </para>
5261 </glossdef>
5262 </glossentry>
5263
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005264 <glossentry id='var-GDB'><glossterm>GDB</glossterm>
5265 <info>
5266 GDB[doc] = "The minimal command and arguments to run the GNU Debugger."
5267 </info>
5268 <glossdef>
5269 <para role="glossdeffirst">
5270<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5271 The minimal command and arguments to run the GNU Debugger.
5272 </para>
5273 </glossdef>
5274 </glossentry>
5275
5276 <glossentry id='var-GITDIR'><glossterm>GITDIR</glossterm>
5277 <info>
5278 GITDIR[doc] = "The directory where Git clones will be stored."
5279 </info>
5280 <glossdef>
5281 <para role="glossdeffirst">
5282<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5283 The directory in which a local copy of a Git repository
5284 is stored when it is cloned.
5285 </para>
5286 </glossdef>
5287 </glossentry>
5288
5289 <glossentry id='var-GLIBC_GENERATE_LOCALES'><glossterm>GLIBC_GENERATE_LOCALES</glossterm>
5290 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04005291 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 -05005292 </info>
5293 <glossdef>
5294 <para role="glossdeffirst">
5295<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5296 Specifies the list of GLIBC locales to generate should you
Brad Bishop316dfdd2018-06-25 12:45:53 -04005297 not wish to generate all LIBC locals, which can be time
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005298 consuming.
5299 <note>
5300 If you specifically remove the locale
5301 <filename>en_US.UTF-8</filename>, you must set
5302 <link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link>
5303 appropriately.
5304 </note>
5305 </para>
5306
5307 <para>
5308 You can set <filename>GLIBC_GENERATE_LOCALES</filename>
5309 in your <filename>local.conf</filename> file.
5310 By default, all locales are generated.
5311 <literallayout class='monospaced'>
5312 GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
5313 </literallayout>
5314 </para>
5315 </glossdef>
5316 </glossentry>
5317
5318 <glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm>
5319 <info>
5320 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."
5321 </info>
5322 <glossdef>
5323 <para role="glossdeffirst">
5324<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5325 When inheriting the
5326 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
5327 class, this variable
5328 specifies for a package what parameters should be passed
5329 to the <filename>groupadd</filename> command
5330 if you wish to add a group to the system when the package
5331 is installed.
5332 </para>
5333
5334 <para>
5335 Here is an example from the <filename>dbus</filename>
5336 recipe:
5337 <literallayout class='monospaced'>
5338 GROUPADD_PARAM_${PN} = "-r netdev"
5339 </literallayout>
5340 For information on the standard Linux shell command
5341 <filename>groupadd</filename>, see
5342 <ulink url='http://linux.die.net/man/8/groupadd'></ulink>.
5343 </para>
5344 </glossdef>
5345 </glossentry>
5346
5347 <glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm>
5348 <info>
5349 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."
5350 </info>
5351 <glossdef>
5352 <para role="glossdeffirst">
5353<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5354 When inheriting the
5355 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
5356 class, this variable
5357 specifies for a package what parameters should be passed
5358 to the <filename>groupmems</filename> command
5359 if you wish to modify the members of a group when the
5360 package is installed.
5361 </para>
5362
5363 <para>
5364 For information on the standard Linux shell command
5365 <filename>groupmems</filename>, see
5366 <ulink url='http://linux.die.net/man/8/groupmems'></ulink>.
5367 </para>
5368 </glossdef>
5369 </glossentry>
5370
5371 <glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm>
5372 <info>
5373 GRUB_GFXSERIAL[doc] = "Configures the GNU GRand Unified Bootloader (GRUB) to have graphics and serial in the boot menu."
5374 </info>
5375 <glossdef>
5376 <para role="glossdeffirst">
5377<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5378 Configures the GNU GRand Unified Bootloader (GRUB) to have
5379 graphics and serial in the boot menu.
5380 Set this variable to "1" in your
5381 <filename>local.conf</filename> or distribution
5382 configuration file to enable graphics and serial
5383 in the menu.
5384 </para>
5385
5386 <para>
5387 See the
5388 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5389 class for more information on how this variable is used.
5390 </para>
5391 </glossdef>
5392 </glossentry>
5393
5394 <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm>
5395 <info>
5396 GRUB_OPTS[doc] = "Additional options to add to the GNU GRand Unified Bootloader (GRUB) configuration."
5397 </info>
5398 <glossdef>
5399 <para role="glossdeffirst">
5400<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5401 Additional options to add to the GNU GRand Unified
5402 Bootloader (GRUB) configuration.
5403 Use a semi-colon character (<filename>;</filename>) to
5404 separate multiple options.
5405 </para>
5406
5407 <para>
5408 The <filename>GRUB_OPTS</filename> variable is optional.
5409 See the
5410 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5411 class for more information on how this variable is used.
5412 </para>
5413 </glossdef>
5414 </glossentry>
5415
5416 <glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm>
5417 <info>
5418 GRUB_TIMEOUT[doc] = "Specifies the timeout before executing the default LABEL in the GNU GRand Unified Bootloader (GRUB)."
5419 </info>
5420 <glossdef>
5421 <para role="glossdeffirst">
5422<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5423 Specifies the timeout before executing the default
5424 <filename>LABEL</filename> in the GNU GRand Unified
5425 Bootloader (GRUB).
5426 </para>
5427
5428 <para>
5429 The <filename>GRUB_TIMEOUT</filename> variable is optional.
5430 See the
5431 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5432 class for more information on how this variable is used.
5433 </para>
5434 </glossdef>
5435 </glossentry>
5436
5437 <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm>
5438 <info>
5439 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."
5440 </info>
5441 <glossdef>
5442 <para role="glossdeffirst">
5443<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5444 When inheriting the
5445 <link linkend='ref-classes-gtk-immodules-cache'><filename>gtk-immodules-cache</filename></link>
5446 class, this variable specifies the packages that contain the
5447 GTK+ input method modules being installed when the modules
5448 are in packages other than the main package.
5449 </para>
5450 </glossdef>
5451 </glossentry>
5452
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005453 </glossdiv>
5454
5455 <glossdiv id='var-glossary-h'><title>H</title>
5456
5457 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
5458 <info>
5459 HOMEPAGE[doc] = "Website where more information about the software the recipe is building can be found."
5460 </info>
5461 <glossdef>
5462 <para role="glossdeffirst">
5463<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5464 Website where more information about the software the recipe is building
5465 can be found.
5466 </para>
5467 </glossdef>
5468 </glossentry>
5469
5470 <glossentry id='var-HOST_ARCH'><glossterm>HOST_ARCH</glossterm>
5471 <info>
5472 HOST_ARCH[doc] = "The name of the target architecture. Normally same as the TARGET_ARCH."
5473
5474 </info>
5475 <glossdef>
5476 <para role="glossdeffirst">
5477<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5478 The name of the target architecture, which is normally
5479 the same as
5480 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
5481 The OpenEmbedded build system supports many
5482 architectures.
5483 Here is an example list of architectures supported.
5484 This list is by no means complete as the architecture
5485 is configurable:
5486 <literallayout class='monospaced'>
5487 arm
5488 i586
5489 x86_64
5490 powerpc
5491 powerpc64
5492 mips
5493 mipsel
5494 </literallayout>
5495 </para>
5496 </glossdef>
5497 </glossentry>
5498
5499 <glossentry id='var-HOST_CC_ARCH'><glossterm>HOST_CC_ARCH</glossterm>
5500 <info>
5501 HOST_CC_ARCH[doc] = "The name of the host architecture. Normally same as the TARGET_CC_ARCH."
5502 </info>
5503 <glossdef>
5504 <para role="glossdeffirst">
5505<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5506 Specifies architecture-specific compiler flags that are
5507 passed to the C compiler.
5508 </para>
5509
5510 <para>
5511 Default initialization for <filename>HOST_CC_ARCH</filename>
5512 varies depending on what is being built:
5513 <itemizedlist>
5514 <listitem><para>
5515 <link linkend='var-TARGET_CC_ARCH'><filename>TARGET_CC_ARCH</filename></link>
5516 when building for the target
5517 </para></listitem>
5518 <listitem><para>
5519 <filename>BUILD_CC_ARCH</filename>
5520 when building for the build host (i.e.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05005521 <filename>-native</filename>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005522 </para></listitem>
5523 <listitem><para>
5524 <filename>BUILDSDK_CC_ARCH</filename>
5525 when building for an SDK (i.e.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05005526 <filename>nativesdk-</filename>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005527 </para></listitem>
5528 </itemizedlist>
5529 </para>
5530 </glossdef>
5531 </glossentry>
5532
5533 <glossentry id='var-HOST_OS'><glossterm>HOST_OS</glossterm>
5534 <info>
5535 HOST_OS[doc] = "The name of the target operating system. Normally the same as the TARGET_OS."
5536 </info>
5537 <glossdef>
5538 <para role="glossdeffirst">
5539<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5540 Specifies the name of the target operating system, which
5541 is normally the same as the
5542 <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>.
5543 The variable can be set to "linux" for <filename>glibc</filename>-based systems and
Brad Bishop37a0e4d2017-12-04 01:01:44 -05005544 to "linux-musl" for <filename>musl</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005545 For ARM/EABI targets, there are also "linux-gnueabi" and
Brad Bishop37a0e4d2017-12-04 01:01:44 -05005546 "linux-musleabi" values possible.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005547 </para>
5548 </glossdef>
5549 </glossentry>
5550
5551 <glossentry id='var-HOST_PREFIX'><glossterm>HOST_PREFIX</glossterm>
5552 <info>
5553 HOST_PREFIX[doc] = "The prefix for the cross compile toolchain. Normally same as the TARGET_PREFIX."
5554 </info>
5555 <glossdef>
5556 <para role="glossdeffirst">
5557<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5558 Specifies the prefix for the cross-compile toolchain.
5559 <filename>HOST_PREFIX</filename> is normally the same as
5560 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>.
5561 </para>
5562 </glossdef>
5563 </glossentry>
5564
5565 <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
5566 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04005567 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 -05005568 </info>
5569 <glossdef>
5570 <para role="glossdeffirst">
5571<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5572 Specifies the system, including the architecture and the
5573 operating system, for which the build is occurring
5574 in the context of the current recipe.
5575 </para>
5576
5577 <para>
5578 The OpenEmbedded build system automatically sets this
5579 variable based on
5580 <link linkend='var-HOST_ARCH'><filename>HOST_ARCH</filename></link>,
5581 <link linkend='var-HOST_VENDOR'><filename>HOST_VENDOR</filename></link>,
5582 and
5583 <link linkend='var-HOST_OS'><filename>HOST_OS</filename></link>
5584 variables.
5585 <note>
5586 You do not need to set the variable yourself.
5587 </note>
5588 </para>
5589
5590 <para>
5591 Consider these two examples:
5592 <itemizedlist>
5593 <listitem><para>Given a native recipe on a 32-bit
5594 x86 machine running Linux, the value is
5595 "i686-linux".
5596 </para></listitem>
5597 <listitem><para>Given a recipe being built for a
5598 little-endian MIPS target running Linux,
5599 the value might be "mipsel-linux".
5600 </para></listitem>
5601 </itemizedlist>
5602 </para>
5603 </glossdef>
5604 </glossentry>
5605
Brad Bishop6e60e8b2018-02-01 10:27:11 -05005606 <glossentry id='var-HOSTTOOLS'><glossterm>HOSTTOOLS</glossterm>
5607 <info>
5608 HOSTTOOLS[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks."
5609 </info>
5610 <glossdef>
5611 <para role="glossdeffirst">
5612<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5613 A space-separated list (filter) of tools on the build host
5614 that should be allowed to be called from within build tasks.
5615 Using this filter helps reduce the possibility of host
5616 contamination.
5617 If a tool specified in the value of
5618 <filename>HOSTTOOLS</filename> is not found on the
5619 build host, the OpenEmbedded build system produces
5620 an error and the build is not started.
5621 </para>
5622
5623 <para>
5624 For additional information, see
5625 <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link>.
5626 </para>
5627 </glossdef>
5628 </glossentry>
5629
5630 <glossentry id='var-HOSTTOOLS_NONFATAL'><glossterm>HOSTTOOLS_NONFATAL</glossterm>
5631 <info>
5632 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."
5633 </info>
5634 <glossdef>
5635 <para role="glossdeffirst">
5636<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5637 A space-separated list (filter) of tools on the build host
5638 that should be allowed to be called from within build tasks.
5639 Using this filter helps reduce the possibility of host
5640 contamination.
5641 Unlike
5642 <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link>,
Brad Bishop316dfdd2018-06-25 12:45:53 -04005643 the OpenEmbedded build system does not produce an error
Brad Bishop6e60e8b2018-02-01 10:27:11 -05005644 if a tool specified in the value of
5645 <filename>HOSTTOOLS_NONFATAL</filename> is not found on the
5646 build host.
5647 Thus, you can use <filename>HOSTTOOLS_NONFATAL</filename>
5648 to filter optional host tools.
5649 </para>
5650 </glossdef>
5651 </glossentry>
5652
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005653 <glossentry id='var-HOST_VENDOR'><glossterm>HOST_VENDOR</glossterm>
5654 <info>
5655 HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR."
5656 </info>
5657 <glossdef>
5658 <para role="glossdeffirst">
5659<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5660 Specifies the name of the vendor.
5661 <filename>HOST_VENDOR</filename> is normally the same as
Brad Bishop316dfdd2018-06-25 12:45:53 -04005662 <link linkend='var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005663 </para>
5664 </glossdef>
5665 </glossentry>
5666
5667 </glossdiv>
5668
5669 <glossdiv id='var-glossary-i'><title>I</title>
5670
5671 <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm>
5672 <info>
5673 ICECC_DISABLED[doc] = "Disables or enables the icecc (Icecream) function."
5674 </info>
5675 <glossdef>
5676 <para role="glossdeffirst">
5677<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5678 Disables or enables the <filename>icecc</filename>
5679 (Icecream) function.
5680 For more information on this function and best practices
5681 for using this variable, see the
5682 "<link linkend='ref-classes-icecc'><filename>icecc.bbclass</filename></link>"
5683 section.
5684 </para>
5685
5686 <para>
5687 Setting this variable to "1" in your
5688 <filename>local.conf</filename> disables the function:
5689 <literallayout class='monospaced'>
5690 ICECC_DISABLED ??= "1"
5691 </literallayout>
5692 To enable the function, set the variable as follows:
5693 <literallayout class='monospaced'>
5694 ICECC_DISABLED = ""
5695 </literallayout>
5696 </para>
5697 </glossdef>
5698 </glossentry>
5699
5700 <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm>
5701 <info>
5702 ICECC_ENV_EXEC[doc] = "Points to the icecc-create-env script that you provide."
5703 </info>
5704 <glossdef>
5705 <para role="glossdeffirst">
5706<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5707 Points to the <filename>icecc-create-env</filename> script
5708 that you provide.
5709 This variable is used by the
5710 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5711 class.
5712 You set this variable in your
5713 <filename>local.conf</filename> file.
5714 </para>
5715
5716 <para>
5717 If you do not point to a script that you provide, the
5718 OpenEmbedded build system uses the default script provided
5719 by the <filename>icecc-create-env.bb</filename> recipe,
5720 which is a modified version and not the one that comes with
5721 <filename>icecc</filename>.
5722 </para>
5723 </glossdef>
5724 </glossentry>
5725
5726 <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm>
5727 <info>
5728 ICECC_PARALLEL_MAKE[doc] = "Extra options passed to the make command during the do_compile task that specify parallel compilation."
5729 </info>
5730 <glossdef>
5731 <para role="glossdeffirst">
5732<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5733 Extra options passed to the <filename>make</filename>
5734 command during the
5735 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
5736 task that specify parallel compilation.
5737 This variable usually takes the form of
5738 "-j <replaceable>x</replaceable>", where
5739 <replaceable>x</replaceable> represents the maximum
5740 number of parallel threads <filename>make</filename> can
5741 run.
5742 <note>
5743 The options passed affect builds on all enabled
5744 machines on the network, which are machines running the
5745 <filename>iceccd</filename> daemon.
5746 </note>
5747 </para>
5748
5749 <para>
5750 If your enabled machines support multiple cores,
5751 coming up with the maximum number of parallel threads
5752 that gives you the best performance could take some
5753 experimentation since machine speed, network lag,
5754 available memory, and existing machine loads can all
5755 affect build time.
5756 Consequently, unlike the
5757 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
5758 variable, there is no rule-of-thumb for setting
5759 <filename>ICECC_PARALLEL_MAKE</filename> to achieve
5760 optimal performance.
5761 </para>
5762
5763 <para>
5764 If you do not set <filename>ICECC_PARALLEL_MAKE</filename>,
5765 the build system does not use it (i.e. the system does
5766 not detect and assign the number of cores as is done with
5767 <filename>PARALLEL_MAKE</filename>).
5768 </para>
5769 </glossdef>
5770 </glossentry>
5771
5772 <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm>
5773 <info>
5774 ICECC_PATH[doc] = "The location of the icecc binary."
5775 </info>
5776 <glossdef>
5777 <para role="glossdeffirst">
5778<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5779 The location of the <filename>icecc</filename> binary.
5780 You can set this variable in your
5781 <filename>local.conf</filename> file.
5782 If your <filename>local.conf</filename> file does not define
5783 this variable, the
5784 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5785 class attempts to define it by locating
5786 <filename>icecc</filename> using <filename>which</filename>.
5787 </para>
5788 </glossdef>
5789 </glossentry>
5790
5791 <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm>
5792 <info>
5793 ICECC_USER_CLASS_BL[doc] = "Identifies user classes that you do not want the Icecream distributed compile support to consider."
5794 </info>
5795 <glossdef>
5796 <para role="glossdeffirst">
5797<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5798 Identifies user classes that you do not want the
5799 Icecream distributed compile support to consider.
5800 This variable is used by the
5801 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5802 class.
5803 You set this variable in your
5804 <filename>local.conf</filename> file.
5805 </para>
5806
5807 <para>
5808 When you list classes using this variable, you are
5809 "blacklisting" them from distributed compilation across
5810 remote hosts.
5811 Any classes you list will be distributed and compiled
5812 locally.
5813 </para>
5814 </glossdef>
5815 </glossentry>
5816
5817 <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm>
5818 <info>
5819 ICECC_USER_PACKAGE_BL[doc] = "Identifies user recipes that you do not want the Icecream distributed compile support to consider."
5820 </info>
5821 <glossdef>
5822 <para role="glossdeffirst">
5823<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5824 Identifies user recipes that you do not want the
5825 Icecream distributed compile support to consider.
5826 This variable is used by the
5827 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5828 class.
5829 You set this variable in your
5830 <filename>local.conf</filename> file.
5831 </para>
5832
5833 <para>
5834 When you list packages using this variable, you are
5835 "blacklisting" them from distributed compilation across
5836 remote hosts.
5837 Any packages you list will be distributed and compiled
5838 locally.
5839 </para>
5840 </glossdef>
5841 </glossentry>
5842
5843 <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm>
5844 <info>
5845 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."
5846 </info>
5847 <glossdef>
5848 <para role="glossdeffirst">
5849<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5850 Identifies user recipes that use an empty
5851 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
5852 variable that you want to force remote distributed
5853 compilation on using the Icecream distributed compile
5854 support.
5855 This variable is used by the
5856 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5857 class.
5858 You set this variable in your
5859 <filename>local.conf</filename> file.
5860 </para>
5861 </glossdef>
5862 </glossentry>
5863
5864 <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
5865 <info>
5866 IMAGE_BASENAME[doc] = "The base name of image output files."
5867 </info>
5868 <glossdef>
5869 <para role="glossdeffirst">
5870<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5871 The base name of image output files.
5872 This variable defaults to the recipe name
5873 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
5874 </para>
5875 </glossdef>
5876 </glossentry>
5877
5878 <glossentry id='var-IMAGE_BOOT_FILES'><glossterm>IMAGE_BOOT_FILES</glossterm>
5879 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04005880 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 -05005881 </info>
5882 <glossdef>
5883 <para role="glossdeffirst">
5884<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5885 A space-separated list of files installed into the
Brad Bishop316dfdd2018-06-25 12:45:53 -04005886 boot partition when preparing an image using the Wic tool
5887 with the <filename>bootimg-partition</filename> source
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005888 plugin.
Brad Bishop316dfdd2018-06-25 12:45:53 -04005889 By default, the files are installed under the same name as
5890 the source files.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005891 To change the installed name, separate it from the
5892 original name with a semi-colon (;).
5893 Source files need to be located in
5894 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>.
5895 Here are two examples:
5896
5897 <literallayout class="monospaced">
5898 IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
5899 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
5900 </literallayout>
5901 </para>
5902
5903 <para>
5904 Alternatively, source files can be picked up using
5905 a glob pattern.
Brad Bishop316dfdd2018-06-25 12:45:53 -04005906 In this case, the destination file must have the same name
5907 as the base name of the source file path.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005908 To install files into a directory within the
5909 target location, pass its name after a semi-colon
5910 (;).
5911 Here are two examples:
5912 <literallayout class="monospaced">
5913 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
5914 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"
5915 </literallayout>
5916 The first example installs all files from
5917 <filename>${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles</filename>
5918 into the root of the target partition.
5919 The second example installs the same files into a
5920 <filename>boot</filename> directory within the
5921 target partition.
5922 </para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04005923
5924 <para>
5925 You can find information on how to use the Wic tool in the
5926 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
5927 section of the Yocto Project Development Tasks Manual.
5928 Reference material for Wic is located in the
5929 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>OpenEmbedded Kickstart (.wks) Reference</ulink>"
5930 chapter.
5931 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005932 </glossdef>
5933 </glossentry>
5934
5935 <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
5936 <info>
5937 IMAGE_CLASSES[doc] = "A list of classes that all images should inherit."
5938 </info>
5939 <glossdef>
5940 <para role="glossdeffirst">
5941<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5942 A list of classes that all images should inherit.
5943 You typically use this variable to specify the list of
5944 classes that register the different types of images
5945 the OpenEmbedded build system creates.
5946 </para>
5947
5948 <para>
5949 The default value for <filename>IMAGE_CLASSES</filename> is
5950 <filename>image_types</filename>.
5951 You can set this variable in your
5952 <filename>local.conf</filename> or in a distribution
5953 configuration file.
5954 </para>
5955
5956 <para>
5957 For more information, see
5958 <filename>meta/classes/image_types.bbclass</filename> in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005959 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005960 </para>
5961 </glossdef>
5962 </glossentry>
5963
5964 <glossentry id='var-IMAGE_CMD'><glossterm>IMAGE_CMD</glossterm>
5965 <info>
5966 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)."
5967 </info>
5968 <glossdef>
5969 <para role="glossdeffirst">
5970<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5971 Specifies the command to create the image file for a
5972 specific image type, which corresponds to the value set
5973 set in
5974 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
5975 (e.g. <filename>ext3</filename>,
5976 <filename>btrfs</filename>, and so forth).
5977 When setting this variable, you should use
5978 an override for the associated type.
5979 Here is an example:
5980 <literallayout class='monospaced'>
5981 IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \
5982 --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \
5983 ${EXTRA_IMAGECMD}"
5984 </literallayout>
5985 </para>
5986
5987 <para>
5988 You typically do not need to set this variable unless
5989 you are adding support for a new image type.
5990 For more examples on how to set this variable, see the
5991 <link linkend='ref-classes-image_types'><filename>image_types</filename></link>
5992 class file, which is
5993 <filename>meta/classes/image_types.bbclass</filename>.
5994 </para>
5995 </glossdef>
5996 </glossentry>
5997
5998 <glossentry id='var-IMAGE_DEVICE_TABLES'><glossterm>IMAGE_DEVICE_TABLES</glossterm>
5999 <info>
6000 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."
6001 </info>
6002 <glossdef>
6003 <para role="glossdeffirst">
6004<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6005 Specifies one or more files that contain custom device
6006 tables that are passed to the
6007 <filename>makedevs</filename> command as part of creating
6008 an image.
6009 These files list basic device nodes that should be
6010 created under <filename>/dev</filename> within the image.
6011 If <filename>IMAGE_DEVICE_TABLES</filename> is not set,
6012 <filename>files/device_table-minimal.txt</filename> is
6013 used, which is located by
6014 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
6015 For details on how you should write device table files,
6016 see <filename>meta/files/device_table-minimal.txt</filename>
6017 as an example.
6018 </para>
6019 </glossdef>
6020 </glossentry>
6021
6022 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
6023 <info>
6024 IMAGE_FEATURES[doc] = "The primary list of features to include in an image. Configure this variable in an image recipe."
6025 </info>
6026 <glossdef>
6027 <para role="glossdeffirst">
6028<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6029 The primary list of features to include in an image.
6030 Typically, you configure this variable in an image recipe.
6031 Although you can use this variable from your
6032 <filename>local.conf</filename> file, which is found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006033 <link linkend='build-directory'>Build Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006034 best practices dictate that you do not.
6035 <note>
6036 To enable extra features from outside the image recipe,
6037 use the
6038 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
6039 </note>
6040 </para>
6041
6042 <para>
6043 For a list of image features that ships with the Yocto
6044 Project, see the
6045 "<link linkend="ref-features-image">Image Features</link>"
6046 section.
6047 </para>
6048
6049 <para>
6050 For an example that shows how to customize your image by
6051 using this variable, see the
6052 "<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 -05006053 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006054 </para>
6055 </glossdef>
6056 </glossentry>
6057
6058 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
6059 <info>
6060 IMAGE_FSTYPES[doc] = "Formats of root filesystem images that you want to have created."
6061 </info>
6062 <glossdef>
6063 <para role="glossdeffirst">
6064<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6065 Specifies the formats the OpenEmbedded build system uses
6066 during the build when creating the root filesystem.
6067 For example, setting <filename>IMAGE_FSTYPES</filename>
6068 as follows causes the build system to create root
6069 filesystems using two formats: <filename>.ext3</filename>
6070 and <filename>.tar.bz2</filename>:
6071 <literallayout class='monospaced'>
6072 IMAGE_FSTYPES = "ext3 tar.bz2"
6073 </literallayout>
6074 </para>
6075
6076 <para>
6077 For the complete list of supported image formats from which
6078 you can choose, see
6079 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
6080 </para>
6081
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006082 <note><title>Notes</title>
6083 <itemizedlist>
6084 <listitem><para>
Brad Bishop19323692019-04-05 15:28:33 -04006085 If an image recipe uses the "inherit image" line
6086 and you are setting
6087 <filename>IMAGE_FSTYPES</filename> inside the
6088 recipe, you must set
6089 <filename>IMAGE_FSTYPES</filename> prior to
6090 using the "inherit image" line.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006091 </para></listitem>
6092 <listitem><para>
6093 Due to the way the OpenEmbedded build system
6094 processes this variable, you cannot update its
6095 contents by using <filename>_append</filename> or
6096 <filename>_prepend</filename>.
6097 You must use the <filename>+=</filename>
6098 operator to add one or more options to the
6099 <filename>IMAGE_FSTYPES</filename> variable.
6100 </para></listitem>
6101 </itemizedlist>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006102 </note>
6103 </glossdef>
6104 </glossentry>
6105
6106 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
6107 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006108 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 -05006109 </info>
6110 <glossdef>
6111 <para role="glossdeffirst">
6112<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -04006113 Used by recipes to specify the packages to install into an
6114 image through the
6115 <link linkend='ref-classes-image'><filename>image</filename></link>
6116 class.
6117 Use the <filename>IMAGE_INSTALL</filename> variable with
6118 care to avoid ordering issues.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006119 </para>
6120
6121 <para>
6122 Image recipes set <filename>IMAGE_INSTALL</filename>
6123 to specify the packages to install into an image through
6124 <filename>image.bbclass</filename>.
Brad Bishop316dfdd2018-06-25 12:45:53 -04006125 Additionally, "helper" classes such as the
6126 <link linkend='ref-classes-core-image'><filename>core-image</filename></link>
6127 class exist that can take lists used with
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006128 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006129 and turn them into auto-generated entries in
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006130 <filename>IMAGE_INSTALL</filename> in addition to its
6131 default contents.
6132 </para>
6133
6134 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006135 When you use this variable, it is best to use it as follows:
6136 <literallayout class='monospaced'>
6137 IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>"
6138 </literallayout>
6139 Be sure to include the space between the quotation character
6140 and the start of the package name or names.
Brad Bishop316dfdd2018-06-25 12:45:53 -04006141 <note><title>Caution</title>
6142 <itemizedlist>
6143 <listitem><para>
6144 When working with a
6145 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
6146 image, do not use the
6147 <filename>IMAGE_INSTALL</filename> variable to
6148 specify packages for installation.
6149 Instead, use the
6150 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
6151 variable, which allows the initial RAM
6152 filesystem (initramfs) recipe to use a fixed
6153 set of packages and not be affected by
6154 <filename>IMAGE_INSTALL</filename>.
6155 For information on creating an initramfs, see
6156 the
6157 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
6158 section in the Yocto Project Development Tasks
6159 Manual.
6160 </para></listitem>
6161 <listitem><para>
6162 Using <filename>IMAGE_INSTALL</filename> with
6163 the
6164 <ulink url='&YOCTO_DOCS_BB_URL;#appending-and-prepending'><filename>+=</filename></ulink>
6165 BitBake operator within the
6166 <filename>/conf/local.conf</filename> file or
6167 from within an image recipe is not recommended.
6168 Use of this operator in these ways can cause
6169 ordering issues.
6170 Since <filename>core-image.bbclass</filename>
6171 sets <filename>IMAGE_INSTALL</filename> to a
6172 default value using the
6173 <ulink url='&YOCTO_DOCS_BB_URL;#setting-a-default-value'><filename>?=</filename></ulink>
6174 operator, using a <filename>+=</filename>
6175 operation against
6176 <filename>IMAGE_INSTALL</filename> results in
6177 unexpected behavior when used within
6178 <filename>conf/local.conf</filename>.
6179 Furthermore, the same operation from within
6180 an image recipe may or may not succeed
6181 depending on the specific situation.
6182 In both these cases, the behavior is contrary
6183 to how most users expect the
6184 <filename>+=</filename> operator to work.
6185 </para></listitem>
6186 </itemizedlist>
6187 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006188 </para>
6189 </glossdef>
6190 </glossentry>
6191
6192 <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
6193 <info>
6194 IMAGE_LINGUAS[doc] = "Specifies the list of locales to install into the image during the root filesystem construction process."
6195 </info>
6196 <glossdef>
6197 <para role="glossdeffirst">
6198<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6199 Specifies the list of locales to install into the image
6200 during the root filesystem construction process.
6201 The OpenEmbedded build system automatically splits locale
6202 files, which are used for localization, into separate
6203 packages.
6204 Setting the <filename>IMAGE_LINGUAS</filename> variable
6205 ensures that any locale packages that correspond to packages
6206 already selected for installation into the image are also
6207 installed.
6208 Here is an example:
6209 <literallayout class='monospaced'>
6210 IMAGE_LINGUAS = "pt-br de-de"
6211 </literallayout>
6212 </para>
6213
6214 <para>
6215 In this example, the build system ensures any Brazilian
6216 Portuguese and German locale files that correspond to
6217 packages in the image are installed (i.e.
6218 <filename>*-locale-pt-br</filename>
6219 and <filename>*-locale-de-de</filename> as well as
6220 <filename>*-locale-pt</filename>
6221 and <filename>*-locale-de</filename>, since some software
6222 packages only provide locale files by language and not by
6223 country-specific language).
6224 </para>
6225
6226 <para>
6227 See the
6228 <link linkend='var-GLIBC_GENERATE_LOCALES'><filename>GLIBC_GENERATE_LOCALES</filename></link>
6229 variable for information on generating GLIBC locales.
6230 </para>
6231 </glossdef>
6232 </glossentry>
6233
6234 <glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm>
6235 <info>
6236 IMAGE_MANIFEST[doc] = "The manifest file for the image. This file lists all the installed packages that make up the image."
6237 </info>
6238 <glossdef>
6239 <para role="glossdeffirst">
6240<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6241 The manifest file for the image.
6242 This file lists all the installed packages that make up
6243 the image.
6244 The file contains package information on a line-per-package
6245 basis as follows:
6246 <literallayout class='monospaced'>
6247 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
6248 </literallayout>
6249 </para>
6250
6251 <para>
6252 The
6253 <link linkend='ref-classes-image'><filename>image</filename></link>
6254 class defines the manifest file as follows:
6255 <literallayout class='monospaced'>
6256 IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"
6257 </literallayout>
6258 The location is derived using the
6259 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
6260 and
6261 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>
6262 variables.
6263 You can find information on how the image
6264 is created in the
Brad Bishop316dfdd2018-06-25 12:45:53 -04006265 "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
6266 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006267 </para>
6268 </glossdef>
6269 </glossentry>
6270
6271 <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
6272 <info>
6273 IMAGE_NAME[doc] = "The name of the output image files minus the extension."
6274 </info>
6275 <glossdef>
6276 <para role="glossdeffirst">
6277<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6278 The name of the output image files minus the extension.
6279 This variable is derived using the
6280 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
6281 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
6282 and
6283 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
6284 variables:
6285 <literallayout class='monospaced'>
6286 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
6287 </literallayout>
6288 </para>
6289 </glossdef>
6290 </glossentry>
6291
6292 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
6293 <info>
6294 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."
6295 </info>
6296 <glossdef>
6297 <para role="glossdeffirst">
6298<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6299 Defines a multiplier that the build system applies to the initial image
6300 size for cases when the multiplier times the returned disk usage value
6301 for the image is greater than the sum of
6302 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
6303 and
6304 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
6305 The result of the multiplier applied to the initial image size creates
6306 free disk space in the image as overhead.
6307 By default, the build process uses a multiplier of 1.3 for this variable.
6308 This default value results in 30% free disk space added to the image when this
6309 method is used to determine the final generated image size.
6310 You should be aware that post install scripts and the package management
6311 system uses disk space inside this overhead area.
6312 Consequently, the multiplier does not produce an image with
6313 all the theoretical free disk space.
6314 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
6315 for information on how the build system determines the overall image size.
6316 </para>
6317
6318 <para>
6319 The default 30% free disk space typically gives the image enough room to boot
6320 and allows for basic post installs while still leaving a small amount of
6321 free disk space.
6322 If 30% free space is inadequate, you can increase the default value.
6323 For example, the following setting gives you 50% free space added to the image:
6324 <literallayout class='monospaced'>
6325 IMAGE_OVERHEAD_FACTOR = "1.5"
6326 </literallayout>
6327 </para>
6328
6329 <para>
6330 Alternatively, you can ensure a specific amount of free disk space is added
6331 to the image by using the
6332 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
6333 variable.
6334 </para>
6335 </glossdef>
6336 </glossentry>
6337
6338 <glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm>
6339 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006340 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 -05006341 </info>
6342 <glossdef>
6343 <para role="glossdeffirst">
6344<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -04006345 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006346 by the OpenEmbedded build system.
6347 The variable is defined appropriately by the
6348 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
6349 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
6350 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
6351 or
6352 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
6353 class.
6354 <note><title>Warning</title>
6355 The <filename>package_tar</filename> class is broken
6356 and is not supported.
6357 It is recommended that you do not use it.
6358 </note>
6359 </para>
6360
6361 <para>
6362 The
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006363 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_*</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006364 and
6365 <link linkend='ref-classes-image'><filename>image</filename></link>
6366 classes use the <filename>IMAGE_PKGTYPE</filename> for
6367 packaging up images and SDKs.
6368 </para>
6369
6370 <para>
6371 You should not set the <filename>IMAGE_PKGTYPE</filename>
6372 manually.
6373 Rather, the variable is set indirectly through the
6374 appropriate
6375 <link linkend='ref-classes-package'><filename>package_*</filename></link>
6376 class using the
6377 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
6378 variable.
6379 The OpenEmbedded build system uses the first package type
6380 (e.g. DEB, RPM, or IPK) that appears with the variable
6381 <note>
6382 Files using the <filename>.tar</filename> format are
6383 never used as a substitute packaging format for DEB,
6384 RPM, and IPK formatted files for your image or SDK.
6385 </note>
6386 </para>
6387 </glossdef>
6388 </glossentry>
6389
6390 <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
6391 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006392 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 -05006393 </info>
6394 <glossdef>
6395 <para role="glossdeffirst">
6396<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6397 Specifies a list of functions to call once the
Brad Bishop316dfdd2018-06-25 12:45:53 -04006398 OpenEmbedded build system creates the final image
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006399 output files.
6400 You can specify functions separated by semicolons:
6401 <literallayout class='monospaced'>
6402 IMAGE_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
6403 </literallayout>
6404 </para>
6405
6406 <para>
6407 If you need to pass the root filesystem path to a command
6408 within the function, you can use
6409 <filename>${IMAGE_ROOTFS}</filename>, which points to
6410 the directory that becomes the root filesystem image.
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006411 See the
6412 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
6413 variable for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006414 </para>
6415 </glossdef>
6416 </glossentry>
6417
6418 <glossentry id='var-IMAGE_PREPROCESS_COMMAND'><glossterm>IMAGE_PREPROCESS_COMMAND</glossterm>
6419 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006420 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 -05006421 </info>
6422 <glossdef>
6423 <para role="glossdeffirst">
6424<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6425 Specifies a list of functions to call before the
Brad Bishop316dfdd2018-06-25 12:45:53 -04006426 OpenEmbedded build system creates the final image
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006427 output files.
6428 You can specify functions separated by semicolons:
6429 <literallayout class='monospaced'>
6430 IMAGE_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
6431 </literallayout>
6432 </para>
6433
6434 <para>
6435 If you need to pass the root filesystem path to a command
6436 within the function, you can use
6437 <filename>${IMAGE_ROOTFS}</filename>, which points to
6438 the directory that becomes the root filesystem image.
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006439 See the
6440 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
6441 variable for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006442 </para>
6443 </glossdef>
6444 </glossentry>
6445
6446 <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
6447 <info>
6448 IMAGE_ROOTFS[doc] = "The location of the root filesystem while it is under construction (i.e. during do_rootfs)."
6449 </info>
6450 <glossdef>
6451 <para role="glossdeffirst">
6452<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6453 The location of the root filesystem while it is under
6454 construction (i.e. during the
6455 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
6456 task).
6457 This variable is not configurable.
6458 Do not change it.
6459 </para>
6460 </glossdef>
6461 </glossentry>
6462
6463 <glossentry id='var-IMAGE_ROOTFS_ALIGNMENT'><glossterm>IMAGE_ROOTFS_ALIGNMENT</glossterm>
6464 <info>
6465 IMAGE_ROOTFS_ALIGNMENT[doc] = "Specifies the alignment for the output image file in Kbytes."
6466 </info>
6467 <glossdef>
6468 <para role="glossdeffirst">
6469<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6470 Specifies the alignment for the output image file in
6471 Kbytes.
6472 If the size of the image is not a multiple of
6473 this value, then the size is rounded up to the nearest
6474 multiple of the value.
6475 The default value is "1".
6476 See
6477 <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
6478 for additional information.
6479 </para>
6480 </glossdef>
6481 </glossentry>
6482
6483 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
6484 <info>
6485 IMAGE_ROOTFS_EXTRA_SPACE[doc] = "Defines additional free disk space created in the image in Kbytes. By default, this variable is set to '0'."
6486 </info>
6487 <glossdef>
6488 <para role="glossdeffirst">
6489<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6490 Defines additional free disk space created in the image in Kbytes.
6491 By default, this variable is set to "0".
6492 This free disk space is added to the image after the build system determines
6493 the image size as described in
6494 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
6495 </para>
6496
6497 <para>
6498 This variable is particularly useful when you want to ensure that a
6499 specific amount of free disk space is available on a device after an image
6500 is installed and running.
6501 For example, to be sure 5 Gbytes of free disk space is available, set the
6502 variable as follows:
6503 <literallayout class='monospaced'>
6504 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
6505 </literallayout>
6506 </para>
6507
6508 <para>
6509 For example, the Yocto Project Build Appliance specifically requests 40 Gbytes
6510 of extra space with the line:
6511 <literallayout class='monospaced'>
6512 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
6513 </literallayout>
6514 </para>
6515 </glossdef>
6516 </glossentry>
6517
6518 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
6519 <info>
6520 IMAGE_ROOTFS_SIZE[doc] = "Defines the size in Kbytes for the generated image."
6521 </info>
6522 <glossdef>
6523 <para role="glossdeffirst">
6524<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6525 Defines the size in Kbytes for the generated image.
6526 The OpenEmbedded build system determines the final size for the generated
6527 image using an algorithm that takes into account the initial disk space used
6528 for the generated image, a requested size for the image, and requested
6529 additional free disk space to be added to the image.
6530 Programatically, the build system determines the final size of the
6531 generated image as follows:
6532 <literallayout class='monospaced'>
6533 if (image-du * overhead) &lt; rootfs-size:
6534 internal-rootfs-size = rootfs-size + xspace
6535 else:
6536 internal-rootfs-size = (image-du * overhead) + xspace
6537
6538 where:
6539
6540 image-du = Returned value of the du command on
6541 the image.
6542
6543 overhead = IMAGE_OVERHEAD_FACTOR
6544
6545 rootfs-size = IMAGE_ROOTFS_SIZE
6546
6547 internal-rootfs-size = Initial root filesystem
6548 size before any modifications.
6549
6550 xspace = IMAGE_ROOTFS_EXTRA_SPACE
6551 </literallayout>
6552 </para>
6553
6554 <para>
6555 See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
6556 and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
6557 variables for related information.
6558<!-- In the above example, <filename>overhead</filename> is defined by the
6559 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
6560 variable, <filename>xspace</filename> is defined by the
6561 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
6562 variable, and <filename>du</filename> is the results of the disk usage command
6563 on the initially generated image. -->
6564 </para>
6565 </glossdef>
6566 </glossentry>
6567
6568 <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm>
6569 <info>
6570 IMAGE_TYPEDEP[doc] = "Specifies a dependency from one image type on another."
6571 </info>
6572 <glossdef>
6573 <para role="glossdeffirst">
6574<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6575 Specifies a dependency from one image type on another.
6576 Here is an example from the
6577 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
6578 class:
6579 <literallayout class='monospaced'>
6580 IMAGE_TYPEDEP_live = "ext3"
6581 </literallayout>
6582 </para>
6583
6584 <para>
6585 In the previous example, the variable ensures that when
6586 "live" is listed with the
6587 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6588 variable, the OpenEmbedded build system produces an
6589 <filename>ext3</filename> image first since one of the
6590 components of the live
6591 image is an <filename>ext3</filename>
6592 formatted partition containing the root
6593 filesystem.
6594 </para>
6595 </glossdef>
6596 </glossentry>
6597
6598 <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
6599 <info>
6600 IMAGE_TYPES[doc] = "Specifies the complete list of supported image types by default."
6601 </info>
6602 <glossdef>
6603 <para role="glossdeffirst">
6604<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6605 Specifies the complete list of supported image types
6606 by default:
6607 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006608 btrfs
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006609 cpio
6610 cpio.gz
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006611 cpio.lz4
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006612 cpio.lzma
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006613 cpio.xz
6614 cramfs
6615 elf
6616 ext2
6617 ext2.bz2
6618 ext2.gz
6619 ext2.lzma
6620 ext3
6621 ext3.gz
6622 ext4
6623 ext4.gz
6624 hdddirect
6625 hddimg
6626 iso
6627 jffs2
6628 jffs2.sum
6629 multiubi
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006630 squashfs
6631 squashfs-lzo
6632 squashfs-xz
6633 tar
6634 tar.bz2
6635 tar.gz
6636 tar.lz4
6637 tar.xz
6638 ubi
6639 ubifs
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006640 wic
6641 wic.bz2
6642 wic.gz
6643 wic.lzma
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006644 </literallayout>
6645 </para>
6646
6647 <para>
6648 For more information about these types of images, see
6649 <filename>meta/classes/image_types*.bbclass</filename>
6650 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006651 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006652 </para>
6653 </glossdef>
6654 </glossentry>
6655
6656 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
6657 <info>
6658 INC_PR[doc] = "Helps define the recipe revision for recipes that share a common include file."
6659 </info>
6660 <glossdef>
6661 <para role="glossdeffirst">
6662<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6663 Helps define the recipe revision for recipes that share
6664 a common <filename>include</filename> file.
6665 You can think of this variable as part of the recipe revision
6666 as set from within an include file.
6667 </para>
6668
6669 <para>
6670 Suppose, for example, you have a set of recipes that
6671 are used across several projects.
6672 And, within each of those recipes the revision
6673 (its <link linkend='var-PR'><filename>PR</filename></link>
6674 value) is set accordingly.
6675 In this case, when the revision of those recipes changes,
6676 the burden is on you to find all those recipes and
6677 be sure that they get changed to reflect the updated
6678 version of the recipe.
6679 In this scenario, it can get complicated when recipes
6680 that are used in many places and provide common functionality
6681 are upgraded to a new revision.
6682 </para>
6683
6684 <para>
6685 A more efficient way of dealing with this situation is
6686 to set the <filename>INC_PR</filename> variable inside
6687 the <filename>include</filename> files that the recipes
6688 share and then expand the <filename>INC_PR</filename>
6689 variable within the recipes to help
6690 define the recipe revision.
6691 </para>
6692
6693 <para>
6694 The following provides an example that shows how to use
6695 the <filename>INC_PR</filename> variable
6696 given a common <filename>include</filename> file that
6697 defines the variable.
6698 Once the variable is defined in the
6699 <filename>include</filename> file, you can use the
6700 variable to set the <filename>PR</filename> values in
6701 each recipe.
6702 You will notice that when you set a recipe's
6703 <filename>PR</filename> you can provide more granular
6704 revisioning by appending values to the
6705 <filename>INC_PR</filename> variable:
6706 <literallayout class='monospaced'>
Brad Bishopb1114e52019-02-13 07:56:10 -05006707 recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
6708 recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
6709 recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
6710 recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006711 </literallayout>
6712 The first line of the example establishes the baseline
6713 revision to be used for all recipes that use the
6714 <filename>include</filename> file.
6715 The remaining lines in the example are from individual
6716 recipes and show how the <filename>PR</filename> value
6717 is set.
6718 </para>
6719 </glossdef>
6720 </glossentry>
6721
6722 <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
6723 <info>
6724 INCOMPATIBLE_LICENSE[doc] = "Specifies a space-separated list of license names (as they would appear in LICENSE) that should be excluded from the build."
6725 </info>
6726 <glossdef>
6727 <para role="glossdeffirst">
6728<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6729 Specifies a space-separated list of license names
6730 (as they would appear in
6731 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
6732 that should be excluded from the build.
6733 Recipes that provide no alternatives to listed incompatible
6734 licenses are not built.
6735 Packages that are individually licensed with the specified
6736 incompatible licenses will be deleted.
6737 </para>
6738
6739 <note>
6740 This functionality is only regularly tested using
6741 the following setting:
6742 <literallayout class='monospaced'>
6743 INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
6744 </literallayout>
6745 Although you can use other settings, you might be required
6746 to remove dependencies on or provide alternatives to
6747 components that are required to produce a functional system
6748 image.
6749 </note>
6750 </glossdef>
6751 </glossentry>
6752
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006753 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
6754 <info>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05006755 INHERIT[doc] = "Causes the named class or classes to be inherited globally."
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006756 </info>
6757 <glossdef>
6758 <para role="glossdeffirst">
6759<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop6e60e8b2018-02-01 10:27:11 -05006760 Causes the named class or classes to be inherited globally.
6761 Anonymous functions in the class or classes
6762 are not executed for the
6763 base configuration and in each individual recipe.
6764 The OpenEmbedded build system ignores changes to
6765 <filename>INHERIT</filename> in individual recipes.
6766 </para>
6767
6768 <para>
6769 For more information on <filename>INHERIT</filename>, see
6770 the
6771 "<ulink url="&YOCTO_DOCS_BB_URL;#inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -04006772 section in the Bitbake User Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006773 </para>
6774 </glossdef>
6775 </glossentry>
6776
6777 <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm>
6778 <info>
6779 INHERIT_DISTRO[doc] = "Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable."
6780 </info>
6781 <glossdef>
6782 <para role="glossdeffirst">
6783<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6784 Lists classes that will be inherited at the
6785 distribution level.
6786 It is unlikely that you want to edit this variable.
6787 </para>
6788
6789 <para>
6790 The default value of the variable is set as follows in the
6791 <filename>meta/conf/distro/defaultsetup.conf</filename>
6792 file:
6793 <literallayout class='monospaced'>
6794 INHERIT_DISTRO ?= "debian devshell sstate license"
6795 </literallayout>
6796 </para>
6797 </glossdef>
6798 </glossentry>
6799
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006800 <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
6801 <info>
6802 INHIBIT_DEFAULT_DEPS[doc] = "Prevents the default dependencies, namely the C compiler and standard C library (libc), from being added to DEPENDS."
6803 </info>
6804 <glossdef>
6805 <para role="glossdeffirst">
6806<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6807 Prevents the default dependencies, namely the C compiler
6808 and standard C library (libc), from being added to
6809 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
6810 This variable is usually used within recipes that do not
6811 require any compilation using the C compiler.
6812 </para>
6813
6814 <para>
6815 Set the variable to "1" to prevent the default dependencies
6816 from being added.
6817 </para>
6818 </glossdef>
6819 </glossentry>
6820
6821 <glossentry id='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><glossterm>INHIBIT_PACKAGE_DEBUG_SPLIT</glossterm>
6822 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006823 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 -05006824 </info>
6825 <glossdef>
6826 <para role="glossdeffirst">
6827<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6828 Prevents the OpenEmbedded build system from splitting
6829 out debug information during packaging.
6830 By default, the build system splits out debugging
6831 information during the
6832 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
6833 task.
6834 For more information on how debug information is split out,
6835 see the
6836 <link linkend='var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></link>
6837 variable.
6838 </para>
6839
6840 <para>
6841 To prevent the build system from splitting out
6842 debug information during packaging, set the
6843 <filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename> variable
6844 as follows:
6845 <literallayout class='monospaced'>
6846 INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
6847 </literallayout>
6848 </para>
6849 </glossdef>
6850 </glossentry>
6851
6852 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
6853 <info>
6854 INHIBIT_PACKAGE_STRIP[doc] = "If set to "1", causes the build to not strip binaries in resulting packages."
6855 </info>
6856 <glossdef>
6857 <para role="glossdeffirst">
6858<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006859 If set to "1", causes the build to not strip binaries in
6860 resulting packages and prevents the
6861 <filename>-dbg</filename> package from containing the
6862 source files.
6863 </para>
6864
6865 <para>
6866 By default, the OpenEmbedded build system strips
6867 binaries and puts the debugging symbols into
6868 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-dbg</filename>.
6869 Consequently, you should not set
6870 <filename>INHIBIT_PACKAGE_STRIP</filename> when you plan
6871 to debug in general.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006872 </para>
6873 </glossdef>
6874 </glossentry>
6875
Brad Bishop19323692019-04-05 15:28:33 -04006876 <glossentry id='var-INHIBIT_SYSROOT_STRIP'><glossterm>INHIBIT_SYSROOT_STRIP</glossterm>
6877 <info>
6878 INHIBIT_SYSROOT_STRIP[doc] = "If set to "1", causes the build to not strip binaries in the resulting sysroot."
6879 </info>
6880 <glossdef>
6881 <para role="glossdeffirst">
6882<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6883 If set to "1", causes the build to not strip binaries in
6884 the resulting sysroot.
6885 </para>
6886
6887 <para>
6888 By default, the OpenEmbedded build system strips
6889 binaries in the resulting sysroot.
6890 When you specifically set the
6891 <filename>INHIBIT_SYSROOT_STRIP</filename> variable to
6892 "1" in your recipe, you inhibit this stripping.
6893 </para>
6894
6895 <para>
6896 If you want to use this variable, include the
6897 <link linkend='ref-classes-staging'><filename>staging</filename></link>
6898 class.
6899 This class uses a <filename>sys_strip()</filename>
6900 function to test for the variable and acts accordingly.
6901 <note>
6902 Use of the <filename>INHIBIT_SYSROOT_STRIP</filename>
6903 variable occurs in rare and special circumstances.
6904 For example, suppose you are building bare-metal
6905 firmware by using an external GCC toolchain.
6906 Furthermore, even if the toolchain's binaries are
6907 strippable, other files exist that are needed for the
6908 build that are not strippable.
6909 </note>
6910 </para>
6911 </glossdef>
6912 </glossentry>
6913
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006914 <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
6915 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006916 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 -05006917 </info>
6918 <glossdef>
6919 <para role="glossdeffirst">
6920<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6921 Defines the format for the output image of an initial
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006922 RAM filesystem (initramfs), which is used during boot.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006923 Supported formats are the same as those supported by the
6924 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6925 variable.
6926 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006927
6928 <para>
6929 The default value of this variable, which is set in the
6930 <filename>meta/conf/bitbake.conf</filename> configuration
6931 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006932 <link linkend='source-directory'>Source Directory</link>,
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006933 is "cpio.gz".
6934 The Linux kernel's initramfs mechanism, as opposed to the
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006935 initial RAM filesystem
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006936 <ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink>
6937 mechanism, expects an optionally compressed cpio
6938 archive.
6939 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006940 </glossdef>
6941 </glossentry>
6942
6943 <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>
6944 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006945 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 -05006946 </info>
6947 <glossdef>
6948 <para role="glossdeffirst">
6949<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006950 Specifies the
6951 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
6952 name of an image recipe that is used to build an initial
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006953 RAM filesystem (initramfs) image.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006954 In other words, the <filename>INITRAMFS_IMAGE</filename>
6955 variable causes an additional recipe to be built as
6956 a dependency to whatever root filesystem recipe you
6957 might be using (e.g. <filename>core-image-sato</filename>).
6958 The initramfs image recipe you provide should set
6959 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6960 to
6961 <link linkend='var-INITRAMFS_FSTYPES'><filename>INITRAMFS_FSTYPES</filename></link>.
6962 </para>
6963
6964 <para>
6965 An initramfs image provides a temporary root filesystem
6966 used for early system initialization (e.g. loading of
6967 modules needed to locate and mount the "real" root
6968 filesystem).
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006969 <note>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006970 See the <filename>meta/recipes-core/images/core-image-minimal-initramfs.bb</filename>
6971 recipe in the
6972 <link linkend='source-directory'>Source Directory</link>
6973 for an example initramfs recipe.
6974 To select this sample recipe as the one built
6975 to provide the initramfs image,
6976 set <filename>INITRAMFS_IMAGE</filename> to
6977 "core-image-minimal-initramfs".
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006978 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006979 </para>
6980
6981 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006982 You can also find more information by referencing the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006983 <filename>meta-poky/conf/local.conf.sample.extended</filename>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006984 configuration file in the Source Directory,
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006985 the
6986 <link linkend='ref-classes-image'><filename>image</filename></link>
6987 class, and the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006988 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006989 class to see how to use the
6990 <filename>INITRAMFS_IMAGE</filename> variable.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006991 </para>
6992
6993 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006994 If <filename>INITRAMFS_IMAGE</filename> is empty, which is
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006995 the default, then no initramfs image is built.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006996 </para>
6997
6998 <para>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006999 For more information, you can also see the
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007000 <link linkend='var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></link>
7001 variable, which allows the generated image to be bundled
7002 inside the kernel image.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007003 Additionally, for information on creating an initramfs
7004 image, see the
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007005 "<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 -05007006 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007007 </para>
7008 </glossdef>
7009 </glossentry>
7010
7011 <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
7012 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007013 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 -05007014 </info>
7015 <glossdef>
7016 <para role="glossdeffirst">
7017<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7018 Controls whether or not the image recipe specified by
7019 <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007020 is run through an extra pass
7021 (<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>)
7022 during kernel compilation in order to build a single binary
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007023 that contains both the kernel image and the initial RAM
7024 filesystem (initramfs) image.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007025 This makes use of the
7026 <link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link>
7027 kernel feature.
7028 <note>
7029 Using an extra compilation pass to bundle the initramfs
7030 avoids a circular dependency between the kernel recipe and
7031 the initramfs recipe should the initramfs include kernel
7032 modules.
7033 Should that be the case, the initramfs recipe depends on
7034 the kernel for the kernel modules, and the kernel depends
7035 on the initramfs recipe since the initramfs is bundled
7036 inside the kernel image.
7037 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007038 </para>
7039
7040 <para>
7041 The combined binary is deposited into the
7042 <filename>tmp/deploy</filename> directory, which is part
7043 of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007044 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007045 </para>
7046
7047 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007048 Setting the variable to "1" in a configuration file causes the
7049 OpenEmbedded build system to generate a kernel image with the
Brad Bishop316dfdd2018-06-25 12:45:53 -04007050 initramfs specified in <filename>INITRAMFS_IMAGE</filename>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007051 bundled within:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007052 <literallayout class='monospaced'>
7053 INITRAMFS_IMAGE_BUNDLE = "1"
7054 </literallayout>
7055 By default, the
7056 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
7057 class sets this variable to a null string as follows:
7058 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007059 INITRAMFS_IMAGE_BUNDLE ?= ""
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007060 </literallayout>
7061 <note>
7062 You must set the
7063 <filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in
7064 a configuration file.
7065 You cannot set the variable in a recipe file.
7066 </note>
7067 See the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05007068 <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 -05007069 file for additional information.
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007070 Also, for information on creating an initramfs, see the
7071 "<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 -05007072 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007073 </para>
7074 </glossdef>
7075 </glossentry>
7076
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007077 <glossentry id='var-INITRAMFS_LINK_NAME'><glossterm>INITRAMFS_LINK_NAME</glossterm>
7078 <info>
7079 INITRAMFS_LINK_NAME[doc] = "The link name of the initial RAM filesystem image."
7080 </info>
7081 <glossdef>
7082 <para role="glossdeffirst">
7083<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7084 The link name of the initial RAM filesystem image.
7085 This variable is set in the
7086 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7087 file as follows:
7088 <literallayout class='monospaced'>
7089 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"
7090 </literallayout>
7091 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7092 variable, which is set in the same file, has the following
7093 value:
7094 <literallayout class='monospaced'>
7095 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7096 </literallayout>
7097 </para>
7098
7099 <para>
7100 See the
7101 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7102 variable for additional information.
7103 </para>
7104 </glossdef>
7105 </glossentry>
7106
7107 <glossentry id='var-INITRAMFS_NAME'><glossterm>INITRAMFS_NAME</glossterm>
7108 <info>
7109 INITRAMFS_NAME[doc] = "The base name of the initial RAM filesystem image."
7110 </info>
7111 <glossdef>
7112 <para role="glossdeffirst">
7113<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7114 The base name of the initial RAM filesystem image.
7115 This variable is set in the
7116 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7117 file as follows:
7118 <literallayout class='monospaced'>
7119 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"
7120 </literallayout>
7121 The value of the
7122 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7123 variable, which is set in the same file, has the following
7124 value:
7125 <literallayout class='monospaced'>
7126 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7127 </literallayout>
7128 </para>
7129 </glossdef>
7130 </glossentry>
7131
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007132 <glossentry id='var-INITRD'><glossterm>INITRD</glossterm>
7133 <info>
7134 INITRD[doc] = "Indicates a list of filesystem images to concatenate and use as an initial RAM disk (initrd)."
7135 </info>
7136 <glossdef>
7137 <para role="glossdeffirst">
7138<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7139 Indicates list of filesystem images to concatenate and use
7140 as an initial RAM disk (<filename>initrd</filename>).
7141 </para>
7142
7143 <para>
7144 The <filename>INITRD</filename> variable is an optional
7145 variable used with the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05007146 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007147 class.
7148 </para>
7149 </glossdef>
7150 </glossentry>
7151
7152 <glossentry id='var-INITRD_IMAGE'><glossterm>INITRD_IMAGE</glossterm>
7153 <info>
7154 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."
7155 </info>
7156 <glossdef>
7157 <para role="glossdeffirst">
7158<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7159 When building a "live" bootable image (i.e. when
7160 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
7161 contains "live"), <filename>INITRD_IMAGE</filename>
7162 specifies the image recipe that should be built
7163 to provide the initial RAM disk image.
7164 The default value is "core-image-minimal-initramfs".
7165 </para>
7166
7167 <para>
7168 See the
7169 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
7170 class for more information.
7171 </para>
7172 </glossdef>
7173 </glossentry>
7174
7175 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
7176 <info>
7177 INITSCRIPT_NAME[doc] = "The filename of the initialization script as installed to ${sysconfdir}/init.d."
7178 </info>
7179 <glossdef>
7180 <para role="glossdeffirst">
7181<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7182 The filename of the initialization script as installed to
7183 <filename>${sysconfdir}/init.d</filename>.
7184 </para>
7185
7186 <para>
7187 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
7188 The variable is mandatory.
7189 </para>
7190 </glossdef>
7191 </glossentry>
7192
7193 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
7194 <info>
7195 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."
7196 </info>
7197 <glossdef>
7198 <para role="glossdeffirst">
7199<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7200 A list of the packages that contain initscripts.
7201 If multiple packages are specified, you need to append the package name
7202 to the other <filename>INITSCRIPT_*</filename> as an override.
7203 </para>
7204
7205 <para>
7206 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
7207 The variable is optional and defaults to the
7208 <link linkend='var-PN'><filename>PN</filename></link> variable.
7209 </para>
7210 </glossdef>
7211 </glossentry>
7212
7213 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
7214 <info>
7215 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."
7216 </info>
7217 <glossdef>
7218 <para role="glossdeffirst">
7219<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7220 Specifies the options to pass to <filename>update-rc.d</filename>.
7221 Here is an example:
7222 <literallayout class='monospaced'>
7223 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
7224 </literallayout>
7225 </para>
7226
7227 <para>
7228 In this example, the script has a runlevel of 99,
7229 starts the script in initlevels 2 and 5, and
7230 stops the script in levels 0, 1 and 6.
7231 </para>
7232
7233 <para>
7234 The variable's default value is "defaults", which is
7235 set in the
7236 <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
7237 class.
7238 </para>
7239
7240 <para>
7241 The value in
7242 <filename>INITSCRIPT_PARAMS</filename> is passed through
7243 to the <filename>update-rc.d</filename> command.
7244 For more information on valid parameters, please see the
7245 <filename>update-rc.d</filename> manual page at
7246 <ulink url='http://www.tin.org/bin/man.cgi?section=8&amp;topic=update-rc.d'></ulink>.
7247 </para>
7248 </glossdef>
7249 </glossentry>
7250
7251 <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
7252 <info>
7253 INSANE_SKIP[doc] = "Specifies the QA checks to skip for a specific package within a recipe."
7254 </info>
7255 <glossdef>
7256 <para role="glossdeffirst">
7257<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7258 Specifies the QA checks to skip for a specific package
7259 within a recipe.
7260 For example, to skip the check for symbolic link
7261 <filename>.so</filename> files in the main package of a
7262 recipe, add the following to the recipe.
7263 The package name override must be used, which in this
7264 example is <filename>${PN}</filename>:
7265 <literallayout class='monospaced'>
7266 INSANE_SKIP_${PN} += "dev-so"
7267 </literallayout>
7268 </para>
7269
7270 <para>
7271 See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
7272 section for a list of the valid QA checks you can
7273 specify using this variable.
7274 </para>
7275 </glossdef>
7276 </glossentry>
7277
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05007278 <glossentry id='var-INSTALL_TIMEZONE_FILE'><glossterm>INSTALL_TIMEZONE_FILE</glossterm>
7279 <info>
7280 INSTALL_TIMEZONE_FILE[doc] = "Enables installation of the /etc/timezone file."
7281 </info>
7282 <glossdef>
7283 <para role="glossdeffirst">
7284<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7285 By default, the <filename>tzdata</filename> recipe packages
7286 an <filename>/etc/timezone</filename> file.
7287 Set the <filename>INSTALL_TIMEZONE_FILE</filename>
7288 variable to "0" at the configuration level to disable this
7289 behavior.
7290 </para>
7291 </glossdef>
7292 </glossentry>
7293
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007294 <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
7295 <info>
7296 IPK_FEED_URIS[doc] = "List of ipkg feed records to put into generated image."
7297 </info>
7298 <glossdef>
7299 <para role="glossdeffirst">
7300<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7301 When the IPK backend is in use and package management
7302 is enabled on the target, you can use this variable to
7303 set up <filename>opkg</filename> in the target image
7304 to point to package feeds on a nominated server.
7305 Once the feed is established, you can perform
7306 installations or upgrades using the package manager
7307 at runtime.
7308 </para>
7309 </glossdef>
7310 </glossentry>
7311
7312<!--
7313 <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
7314 <glossdef>
7315 <para>
7316 An environment variable that defines the directory where
7317 post installation hooks are installed for the
7318 post install environment.
7319 This variable is fixed as follows:
7320 <literallayout class='monospaced'>
7321 ${WORKDIR}/intercept_scripts
7322 </literallayout>
7323 </para>
7324
7325 <para>
7326 After installation of a target's root filesystem,
7327 post installation scripts, which are essentially bash scripts,
7328 are all executed just a single time.
7329 Limiting execution of these scripts minimizes installation
7330 time that would be lengthened due to certain packages
7331 triggering redundant operations.
7332 For example, consider the installation of font packages
7333 as a common example.
7334 Without limiting the execution of post installation scripts,
7335 all font directories would be rescanned to create the
7336 cache after each individual font package was installed.
7337 </para>
7338
7339 <para>
7340 Do not edit the <filename>INTERCEPT_DIR</filename>
7341 variable.
7342 </para>
7343 </glossdef>
7344 </glossentry>
7345-->
7346
7347 </glossdiv>
7348
7349<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
7350<!-- </glossdiv>-->
7351
7352 <glossdiv id='var-glossary-k'><title>K</title>
7353
7354 <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
7355 <info>
7356 KARCH[doc] = "Defines the kernel architecture used when assembling the configuration. You define the KARCH variable in the BSP Descriptions."
7357 </info>
7358 <glossdef>
7359 <para role="glossdeffirst">
7360<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7361 Defines the kernel architecture used when assembling
7362 the configuration.
7363 Architectures supported for this release are:
7364 <literallayout class='monospaced'>
7365 powerpc
7366 i386
7367 x86_64
7368 arm
7369 qemu
7370 mips
7371 </literallayout>
7372 </para>
7373
7374 <para>
7375 You define the <filename>KARCH</filename> variable in the
7376 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
7377 </para>
7378 </glossdef>
7379 </glossentry>
7380
7381 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
7382 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04007383 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 -05007384 </info>
7385 <glossdef>
7386 <para role="glossdeffirst">
7387<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7388 A regular expression used by the build process to explicitly
7389 identify the kernel branch that is validated, patched,
7390 and configured during a build.
7391 You must set this variable to ensure the exact kernel
7392 branch you want is being used by the build process.
7393 </para>
7394
7395 <para>
7396 Values for this variable are set in the kernel's recipe
7397 file and the kernel's append file.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007398 For example, if you are using the
7399 <filename>linux-yocto_4.12</filename> kernel, the kernel
7400 recipe file is the
7401 <filename>meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007402 file.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007403 <filename>KBRANCH</filename> is set as follows in that
7404 kernel recipe file:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007405 <literallayout class='monospaced'>
7406 KBRANCH ?= "standard/base"
7407 </literallayout>
7408 </para>
7409
7410 <para>
7411 This variable is also used from the kernel's append file
7412 to identify the kernel branch specific to a particular
7413 machine or target hardware.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007414 Continuing with the previous kernel example, the kernel's
7415 append file (i.e.
7416 <filename>linux-yocto_4.12.bbappend</filename>) is located
7417 in the BSP layer for a given machine.
7418 For example, the append file for the Beaglebone,
7419 EdgeRouter, and generic versions of both 32 and 64-bit IA
7420 machines (<filename>meta-yocto-bsp</filename>) is named
7421 <filename>meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend</filename>.
7422 Here are the related statements from that append file:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007423 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007424 KBRANCH_genericx86 = "standard/base"
7425 KBRANCH_genericx86-64 = "standard/base"
7426 KBRANCH_edgerouter = "standard/edgerouter"
7427 KBRANCH_beaglebone = "standard/beaglebone"
7428 KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007429 </literallayout>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007430 The <filename>KBRANCH</filename> statements identify
7431 the kernel branch to use when building for each
7432 supported BSP.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007433 </para>
7434 </glossdef>
7435 </glossentry>
7436
7437 <glossentry id='var-KBUILD_DEFCONFIG'><glossterm>KBUILD_DEFCONFIG</glossterm>
7438 <info>
7439 KBUILD_DEFCONFIG[doc] = "Specifies an "in-tree" kernel configuration file for use during a kernel build."
7440 </info>
7441 <glossdef>
7442 <para role="glossdeffirst">
7443<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7444 When used with the
7445 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
7446 class, specifies an "in-tree" kernel configuration file
7447 for use during a kernel build.
7448 </para>
7449
7450 <para>
7451 Typically, when using a <filename>defconfig</filename> to
7452 configure a kernel during a build, you place the
7453 file in your layer in the same manner as you would
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007454 place patch files and configuration fragment files (i.e.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007455 "out-of-tree").
7456 However, if you want to use a <filename>defconfig</filename>
7457 file that is part of the kernel tree (i.e. "in-tree"),
7458 you can use the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007459 <filename>KBUILD_DEFCONFIG</filename> variable and append
7460 the
7461 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
7462 variable to point to the <filename>defconfig</filename>
7463 file.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007464 </para>
7465
7466 <para>
7467 To use the variable, set it in the append file for your
7468 kernel recipe using the following form:
7469 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007470 KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007471 </literallayout>
7472 Here is an example from a "raspberrypi2"
7473 <filename>KMACHINE</filename> build that uses a
7474 <filename>defconfig</filename> file named
7475 "bcm2709_defconfig":
7476 <literallayout class='monospaced'>
7477 KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig"
7478 </literallayout>
7479 As an alternative, you can use the following within your
7480 append file:
7481 <literallayout class='monospaced'>
7482 KBUILD_DEFCONFIG_pn-linux-yocto ?= <replaceable>defconfig_file</replaceable>
7483 </literallayout>
7484 For more information on how to use the
7485 <filename>KBUILD_DEFCONFIG</filename> variable, see the
7486 "<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 -04007487 section in the Yocto Project Linux Kernel Development
7488 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007489 </para>
7490 </glossdef>
7491 </glossentry>
7492
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007493 <glossentry id='var-KERNEL_ALT_IMAGETYPE'><glossterm>KERNEL_ALT_IMAGETYPE</glossterm>
7494 <info>
7495 KERNEL_ALT_IMAGETYPE[doc] = "Specifies an alternate kernel image type for creation."
7496 </info>
7497 <glossdef>
7498 <para role="glossdeffirst">
7499<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7500 Specifies an alternate kernel image type for creation in
7501 addition to the kernel image type specified using the
7502 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
7503 variable.
7504 </para>
7505 </glossdef>
7506 </glossentry>
7507
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007508 <glossentry id='var-KERNEL_ARTIFACT_NAME'><glossterm>KERNEL_ARTIFACT_NAME</glossterm>
7509 <info>
7510 KERNEL_ARTIFACT_NAME[doc] = "Specifies the name of all of the build artifacts."
7511 </info>
7512 <glossdef>
7513 <para role="glossdeffirst">
7514<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7515 Specifies the name of all of the build artifacts.
7516 You can change the name of the artifacts by changing the
7517 <filename>KERNEL_ARTIFACT_NAME</filename> variable.
7518 </para>
7519
7520 <para>
7521 The value of <filename>KERNEL_ARTIFACT_NAME</filename>,
7522 which is set in the
7523 <filename> meta/classes/kernel-artifact-names.bbclass</filename>
7524 file, has the following default value:
7525 <literallayout class='monospaced'>
7526 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7527 </literallayout>
7528 </para>
7529
7530 <para>
7531 See the
7532 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
7533 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
7534 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
7535 and
7536 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7537 variables for additional information.
7538 <note>
7539 The <filename>IMAGE_VERSION_SUFFIX</filename> variable
7540 is set to
7541 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>.
7542 </note>
7543 </para>
7544 </glossdef>
7545 </glossentry>
7546
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007547 <glossentry id='var-KERNEL_CLASSES'><glossterm>KERNEL_CLASSES</glossterm>
7548 <info>
7549 KERNEL_CLASSES[doc] = "A list of classes defining kernel image types that kernel class should inherit."
7550 </info>
7551 <glossdef>
7552 <para role="glossdeffirst">
7553<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7554 A list of classes defining kernel image types that the
7555 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
7556 class should inherit.
7557 You typically append this variable to enable extended image
7558 types.
7559 An example is the "kernel-fitimage", which enables
7560 fitImage support and resides in
7561 <filename>meta/classes/kernel-fitimage.bbclass</filename>.
7562 You can register custom kernel image types with the
7563 <filename>kernel</filename> class using this variable.
7564 </para>
7565 </glossdef>
7566 </glossentry>
7567
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007568 <glossentry id='var-KERNEL_DEVICETREE'><glossterm>KERNEL_DEVICETREE</glossterm>
7569 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04007570 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 -05007571 </info>
7572 <glossdef>
7573 <para role="glossdeffirst">
7574<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7575 Specifies the name of the generated Linux kernel device tree
7576 (i.e. the <filename>.dtb</filename>) file.
7577 <note>
7578 Legacy support exists for specifying the full path
7579 to the device tree.
7580 However, providing just the <filename>.dtb</filename>
7581 file is preferred.
7582 </note>
7583 In order to use this variable, you must have the include
7584 files in your kernel recipe:
7585 <literallayout class='monospaced'>
7586 require recipes-kernel/linux/linux-dtb.inc
7587 </literallayout>
7588 or
7589 <literallayout class='monospaced'>
7590 require recipes-kernel/linux/linux-yocto.inc
7591 </literallayout>
7592 </para>
7593 </glossdef>
7594 </glossentry>
7595
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007596 <glossentry id='var-KERNEL_DTB_LINK_NAME'><glossterm>KERNEL_DTB_LINK_NAME</glossterm>
7597 <info>
7598 KERNEL_DTB_LINK_NAME[doc] = "The link name of the kernel device tree binary (DTB)."
7599 </info>
7600 <glossdef>
7601 <para role="glossdeffirst">
7602<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7603 The link name of the kernel device tree binary (DTB).
7604 This variable is set in the
7605 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7606 file as follows:
7607 <literallayout class='monospaced'>
7608 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7609 </literallayout>
7610 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7611 variable, which is set in the same file, has the following
7612 value:
7613 <literallayout class='monospaced'>
7614 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7615 </literallayout>
7616 </para>
7617
7618 <para>
7619 See the
7620 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7621 variable for additional information.
7622 </para>
7623 </glossdef>
7624 </glossentry>
7625
7626 <glossentry id='var-KERNEL_DTB_NAME'><glossterm>KERNEL_DTB_NAME</glossterm>
7627 <info>
7628 KERNEL_DTB_NAME[doc] = "The base name of the kernel device tree binary (DTB)."
7629 </info>
7630 <glossdef>
7631 <para role="glossdeffirst">
7632<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7633 The base name of the kernel device tree binary (DTB).
7634 This variable is set in the
7635 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7636 file as follows:
7637 <literallayout class='monospaced'>
7638 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7639 </literallayout>
7640 The value of the
7641 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7642 variable, which is set in the same file, has the following
7643 value:
7644 <literallayout class='monospaced'>
7645 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7646 </literallayout>
7647 </para>
7648 </glossdef>
7649 </glossentry>
7650
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007651 <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
7652 <info>
7653 KERNEL_EXTRA_ARGS[doc] = "Specifies additional make command-line arguments the OpenEmbedded build system passes on when compiling the kernel."
7654 </info>
7655 <glossdef>
7656 <para role="glossdeffirst">
7657<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7658 Specifies additional <filename>make</filename>
7659 command-line arguments the OpenEmbedded build system
7660 passes on when compiling the kernel.
7661 </para>
7662 </glossdef>
7663 </glossentry>
7664
7665 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
7666 <info>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007667 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 -05007668 </info>
7669 <glossdef>
7670 <para role="glossdeffirst">
7671<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007672 Includes additional kernel metadata.
7673 In the OpenEmbedded build system, the default Board Support
7674 Packages (BSPs)
7675 <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007676 is provided through
7677 the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007678 and
7679 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>
7680 variables.
7681 You can use the <filename>KERNEL_FEATURES</filename>
7682 variable from within the kernel recipe or kernel append
7683 file to further add metadata for all BSPs or specific
7684 BSPs.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007685 </para>
7686
7687 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007688 The metadata you add through this variable includes config
7689 fragments and features descriptions,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007690 which usually includes patches as well as config fragments.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007691 You typically override the
7692 <filename>KERNEL_FEATURES</filename> variable for a
7693 specific machine.
7694 In this way, you can provide validated, but optional,
7695 sets of kernel configurations and features.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007696 </para>
7697
7698 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007699 For example, the following example from the
7700 <filename>linux-yocto-rt_4.12</filename> kernel recipe
7701 adds "netfilter" and "taskstats" features to all BSPs
7702 as well as "virtio" configurations to all QEMU machines.
7703 The last two statements add specific configurations to
7704 targeted machine types:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007705 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007706 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
7707 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007708 KERNEL_FEATURES_append_qemuall = " cfg/virtio.scc"
7709 KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"
7710 KERNEL_FEATURES_append_qemux86-64 = " cfg/sound.scc" </literallayout></para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007711 </glossdef>
7712 </glossentry>
7713
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007714 <glossentry id='var-KERNEL_FIT_LINK_NAME'><glossterm>KERNEL_FIT_LINK_NAME</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007715 <info>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007716 KERNEL_FIT_LINK_NAME[doc] = "The link name of the kernel flattened image tree (FIT) image."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007717 </info>
7718 <glossdef>
7719 <para role="glossdeffirst">
7720<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007721 The link name of the kernel flattened image tree (FIT) image.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007722 This variable is set in the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007723 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7724 file as follows:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007725 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007726 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7727 </literallayout>
7728 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7729 variable, which is set in the same file, has the following
7730 value:
7731 <literallayout class='monospaced'>
7732 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007733 </literallayout>
7734 </para>
7735
7736 <para>
7737 See the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007738 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7739 variable for additional information.
7740 </para>
7741 </glossdef>
7742 </glossentry>
7743
7744 <glossentry id='var-KERNEL_FIT_NAME'><glossterm>KERNEL_FIT_NAME</glossterm>
7745 <info>
7746 KERNEL_FIT_NAME[doc] = "The base name of the kernel flattened image tree (FIT) image."
7747 </info>
7748 <glossdef>
7749 <para role="glossdeffirst">
7750<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7751 The base name of the kernel flattened image tree (FIT) image.
7752 This variable is set in the
7753 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7754 file as follows:
7755 <literallayout class='monospaced'>
7756 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7757 </literallayout>
7758 The value of the
7759 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7760 variable, which is set in the same file, has the following
7761 value:
7762 <literallayout class='monospaced'>
7763 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7764 </literallayout>
7765 </para>
7766 </glossdef>
7767 </glossentry>
7768
7769 <glossentry id='var-KERNEL_IMAGE_LINK_NAME'><glossterm>KERNEL_IMAGE_LINK_NAME</glossterm>
7770 <info>
7771 KERNEL_IMAGE_LINK_NAME[doc] = "The link name for the kernel image."
7772 </info>
7773 <glossdef>
7774 <para role="glossdeffirst">
7775<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7776 The link name for the kernel image.
7777 This variable is set in the
7778 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7779 file as follows:
7780 <literallayout class='monospaced'>
7781 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7782 </literallayout>
7783 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7784 variable, which is set in the same file, has the following
7785 value:
7786 <literallayout class='monospaced'>
7787 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7788 </literallayout>
7789 </para>
7790
7791 <para>
7792 See the
7793 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7794 variable for additional information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007795 </para>
7796 </glossdef>
7797 </glossentry>
7798
7799 <glossentry id='var-KERNEL_IMAGE_MAXSIZE'><glossterm>KERNEL_IMAGE_MAXSIZE</glossterm>
7800 <info>
7801 KERNEL_IMAGE_MAXSIZE[doc] = "The maximum allowable size in kilobytes of the kernel image file."
7802 </info>
7803 <glossdef>
7804 <para role="glossdeffirst">
7805<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7806 Specifies the maximum size of the kernel image file in
7807 kilobytes.
7808 If <filename>KERNEL_IMAGE_MAXSIZE</filename> is set,
7809 the size of the kernel image file is checked against
7810 the set value during the
7811 <link linkend='ref-tasks-sizecheck'><filename>do_sizecheck</filename></link>
7812 task.
7813 The task fails if the kernel image file is larger than
7814 the setting.
7815 </para>
7816
7817 <para>
7818 <filename>KERNEL_IMAGE_MAXSIZE</filename> is useful for
7819 target devices that have a limited amount of space in
7820 which the kernel image must be stored.
7821 </para>
7822
7823 <para>
7824 By default, this variable is not set, which means the
7825 size of the kernel image is not checked.
7826 </para>
7827 </glossdef>
7828 </glossentry>
7829
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007830 <glossentry id='var-KERNEL_IMAGE_NAME'><glossterm>KERNEL_IMAGE_NAME</glossterm>
7831 <info>
7832 KERNEL_IMAGE_NAME[doc] = "The base name of the kernel image."
7833 </info>
7834 <glossdef>
7835 <para role="glossdeffirst">
7836<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7837 The base name of the kernel image.
7838 This variable is set in the
7839 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7840 file as follows:
7841 <literallayout class='monospaced'>
7842 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7843 </literallayout>
7844 The value of the
7845 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7846 variable, which is set in the same file, has the following
7847 value:
7848 <literallayout class='monospaced'>
7849 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7850 </literallayout>
7851 </para>
7852 </glossdef>
7853 </glossentry>
7854
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007855 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
7856 <info>
7857 KERNEL_IMAGETYPE[doc] = "The type of kernel to build for a device, usually set by the machine configuration files and defaults to 'zImage'."
7858 </info>
7859 <glossdef>
7860 <para role="glossdeffirst">
7861<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7862 The type of kernel to build for a device, usually set by the
7863 machine configuration files and defaults to "zImage".
7864 This variable is used
7865 when building the kernel and is passed to <filename>make</filename> as the target to
7866 build.
7867 </para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007868
7869 <para>
7870 If you want to build an alternate kernel image type, use the
7871 <link linkend='var-KERNEL_ALT_IMAGETYPE'><filename>KERNEL_ALT_IMAGETYPE</filename></link>
7872 variable.
7873 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007874 </glossdef>
7875 </glossentry>
7876
7877 <glossentry id='var-KERNEL_MODULE_AUTOLOAD'><glossterm>KERNEL_MODULE_AUTOLOAD</glossterm>
7878 <info>
7879 KERNEL_MODULE_AUTOLOAD[doc] = "Lists kernel modules that need to be auto-loaded during boot"
7880 </info>
7881 <glossdef>
7882 <para role="glossdeffirst">
7883<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7884 Lists kernel modules that need to be auto-loaded during
7885 boot.
7886 <note>
7887 This variable replaces the deprecated
7888 <link linkend='var-module_autoload'><filename>module_autoload</filename></link>
7889 variable.
7890 </note>
7891 </para>
7892
7893 <para>
7894 You can use the <filename>KERNEL_MODULE_AUTOLOAD</filename>
7895 variable anywhere that it can be
7896 recognized by the kernel recipe or by an out-of-tree kernel
7897 module recipe (e.g. a machine configuration file, a
7898 distribution configuration file, an append file for the
7899 recipe, or the recipe itself).
7900 </para>
7901
7902 <para>
7903 Specify it as follows:
7904 <literallayout class='monospaced'>
7905 KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name1</replaceable> <replaceable>module_name2</replaceable> <replaceable>module_name3</replaceable>"
7906 </literallayout>
7907 </para>
7908
7909 <para>
7910 Including <filename>KERNEL_MODULE_AUTOLOAD</filename> causes
7911 the OpenEmbedded build system to populate the
7912 <filename>/etc/modules-load.d/modname.conf</filename>
7913 file with the list of modules to be auto-loaded on boot.
7914 The modules appear one-per-line in the file.
7915 Here is an example of the most common use case:
7916 <literallayout class='monospaced'>
7917 KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name</replaceable>"
7918 </literallayout>
7919 </para>
7920
7921 <para>
7922 For information on how to populate the
7923 <filename>modname.conf</filename> file with
7924 <filename>modprobe.d</filename> syntax lines, see the
7925 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
7926 variable.
7927 </para>
7928 </glossdef>
7929 </glossentry>
7930
7931 <glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm>KERNEL_MODULE_PROBECONF</glossterm>
7932 <info>
7933 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."
7934 </info>
7935 <glossdef>
7936 <para role="glossdeffirst">
7937<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7938 Provides a list of modules for which the OpenEmbedded
7939 build system expects to find
7940 <filename>module_conf_</filename><replaceable>modname</replaceable>
7941 values that specify configuration for each of the modules.
7942 For information on how to provide those module
7943 configurations, see the
7944 <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
7945 variable.
7946 </para>
7947 </glossdef>
7948 </glossentry>
7949
7950 <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
7951 <info>
7952 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)."
7953 </info>
7954 <glossdef>
7955 <para role="glossdeffirst">
7956<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7957 The location of the kernel sources.
7958 This variable is set to the value of the
7959 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
7960 within the
7961 <link linkend='ref-classes-module'><filename>module</filename></link>
7962 class.
7963 For information on how this variable is used, see the
7964 "<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 -04007965 section in the Yocto Project Linux Kernel Development
7966 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007967 </para>
7968
7969 <para>
7970 To help maximize compatibility with out-of-tree drivers
7971 used to build modules, the OpenEmbedded build system also
7972 recognizes and uses the
7973 <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
7974 variable, which is identical to the
7975 <filename>KERNEL_PATH</filename> variable.
7976 Both variables are common variables used by external
7977 Makefiles to point to the kernel source directory.
7978 </para>
7979 </glossdef>
7980 </glossentry>
7981
7982 <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
7983 <info>
7984 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)."
7985 </info>
7986 <glossdef>
7987 <para role="glossdeffirst">
7988<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7989 The location of the kernel sources.
7990 This variable is set to the value of the
7991 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
7992 within the
7993 <link linkend='ref-classes-module'><filename>module</filename></link>
7994 class.
7995 For information on how this variable is used, see the
7996 "<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 -04007997 section in the Yocto Project Linux Kernel Development
7998 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007999 </para>
8000
8001 <para>
8002 To help maximize compatibility with out-of-tree drivers
8003 used to build modules, the OpenEmbedded build system also
8004 recognizes and uses the
8005 <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
8006 variable, which is identical to the
8007 <filename>KERNEL_SRC</filename> variable.
8008 Both variables are common variables used by external
8009 Makefiles to point to the kernel source directory.
8010 </para>
8011 </glossdef>
8012 </glossentry>
8013
Patrick Williamsf1e5d692016-03-30 15:21:19 -05008014 <glossentry id='var-KERNEL_VERSION'><glossterm>KERNEL_VERSION</glossterm>
8015 <info>
8016 KERNEL_VERSION[doc] = "Specifies the version of the kernel as extracted from version.h or utsrelease.h within the kernel sources."
8017 </info>
8018 <glossdef>
8019 <para role="glossdeffirst">
8020<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8021 Specifies the version of the kernel as extracted from
8022 <filename>version.h</filename> or
8023 <filename>utsrelease.h</filename> within the kernel sources.
8024 Effects of setting this variable do not take affect until
8025 the kernel has been configured.
8026 Consequently, attempting to refer to this variable in
8027 contexts prior to configuration will not work.
8028 </para>
8029 </glossdef>
8030 </glossentry>
8031
8032 <glossentry id='var-KERNELDEPMODDEPEND'><glossterm>KERNELDEPMODDEPEND</glossterm>
8033 <info>
8034 KERNELDEPMODDEPEND[doc] = "Specifies whether or not to use the data referenced through the PKGDATA_DIR directory."
8035 </info>
8036 <glossdef>
8037 <para role="glossdeffirst">
8038<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8039 Specifies whether the data referenced through
8040 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
8041 is needed or not.
8042 The <filename>KERNELDEPMODDEPEND</filename> does not
8043 control whether or not that data exists,
8044 but simply whether or not it is used.
8045 If you do not need to use the data, set the
8046 <filename>KERNELDEPMODDEPEND</filename> variable in your
8047 <filename>initramfs</filename> recipe.
8048 Setting the variable there when the data is not needed
8049 avoids a potential dependency loop.
8050 </para>
8051 </glossdef>
8052 </glossentry>
8053
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008054 <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
8055 <info>
8056 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."
8057 </info>
8058 <glossdef>
8059 <para role="glossdeffirst">
8060<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8061 Provides a short description of a configuration fragment.
8062 You use this variable in the <filename>.scc</filename>
8063 file that describes a configuration fragment file.
8064 Here is the variable used in a file named
8065 <filename>smp.scc</filename> to describe SMP being
8066 enabled:
8067 <literallayout class='monospaced'>
8068 define KFEATURE_DESCRIPTION "Enable SMP"
8069 </literallayout>
8070 </para>
8071 </glossdef>
8072 </glossentry>
8073
8074 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
8075 <info>
8076 KMACHINE[doc] = "The machine as known by the kernel."
8077 </info>
8078 <glossdef>
8079 <para role="glossdeffirst">
8080<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8081 The machine as known by the kernel.
8082 Sometimes the machine name used by the kernel does not
8083 match the machine name used by the OpenEmbedded build
8084 system.
8085 For example, the machine name that the OpenEmbedded build
8086 system understands as
8087 <filename>core2-32-intel-common</filename> goes by a
8088 different name in the Linux Yocto kernel.
8089 The kernel understands that machine as
8090 <filename>intel-core2-32</filename>.
8091 For cases like these, the <filename>KMACHINE</filename>
8092 variable maps the kernel machine name to the OpenEmbedded
8093 build system machine name.
8094 </para>
8095
8096 <para>
8097 These mappings between different names occur in the
8098 Yocto Linux Kernel's <filename>meta</filename> branch.
8099 As an example take a look in the
8100 <filename>common/recipes-kernel/linux/linux-yocto_3.19.bbappend</filename>
8101 file:
8102 <literallayout class='monospaced'>
8103 LINUX_VERSION_core2-32-intel-common = "3.19.0"
8104 COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}"
8105 SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"
8106 SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
8107 KMACHINE_core2-32-intel-common = "intel-core2-32"
8108 KBRANCH_core2-32-intel-common = "standard/base"
8109 KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"
8110 </literallayout>
8111 The <filename>KMACHINE</filename> statement says that
8112 the kernel understands the machine name as
8113 "intel-core2-32".
8114 However, the OpenEmbedded build system understands the
8115 machine as "core2-32-intel-common".
8116 </para>
8117
8118 </glossdef>
8119 </glossentry>
8120
8121 <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
8122 <info>
8123 KTYPE[doc] = "Defines the kernel type to be used in assembling the configuration."
8124 </info>
8125 <glossdef>
8126 <para role="glossdeffirst">
8127<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8128 Defines the kernel type to be used in assembling the
8129 configuration.
8130 The linux-yocto recipes define "standard", "tiny",
8131 and "preempt-rt" kernel types.
8132 See the
8133 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
8134 section in the Yocto Project Linux Kernel Development
8135 Manual for more information on kernel types.
8136 </para>
8137
8138 <para>
8139 You define the <filename>KTYPE</filename> variable in the
8140 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
8141 The value you use must match the value used for the
8142 <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
8143 value used by the kernel recipe.
8144 </para>
8145 </glossdef>
8146 </glossentry>
8147 </glossdiv>
8148
8149 <glossdiv id='var-glossary-l'><title>L</title>
8150
8151 <glossentry id='var-LABELS'><glossterm>LABELS</glossterm>
8152 <info>
8153 LABELS[doc] = "Provides a list of targets for automatic configuration."
8154 </info>
8155 <glossdef>
8156 <para role="glossdeffirst">
8157<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8158 Provides a list of targets for automatic configuration.
8159 </para>
8160
8161 <para>
8162 See the
8163 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
8164 class for more information on how this variable is used.
8165 </para>
8166 </glossdef>
8167 </glossentry>
8168
8169 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
8170 <info>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05008171 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 -05008172 </info>
8173 <glossdef>
8174 <para role="glossdeffirst">
8175<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop6e60e8b2018-02-01 10:27:11 -05008176 Lists the layers, separated by spaces, on which this
8177 recipe depends.
8178 Optionally, you can specify a specific layer version for a
8179 dependency by adding it to the end of the layer name.
8180 Here is an example:
8181 <literallayout class='monospaced'>
8182 LAYERDEPENDS_mylayer = "anotherlayer (=3)"
8183 </literallayout>
8184 In this previous example, version 3 of "anotherlayer"
8185 is compared against
8186 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>.
8187 </para>
8188
8189 <para>
8190 An error is produced if any dependency is missing or
8191 the version numbers (if specified) do not match exactly.
8192 This variable is used in the
8193 <filename>conf/layer.conf</filename> file and must be
8194 suffixed with the name of the specific layer (e.g.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008195 <filename>LAYERDEPENDS_mylayer</filename>).
8196 </para>
8197 </glossdef>
8198 </glossentry>
8199
8200 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
8201 <info>
8202 LAYERDIR[doc] = "When used inside the layer.conf configuration file, this variable provides the path of the current layer."
8203 </info>
8204 <glossdef>
8205 <para role="glossdeffirst">
8206<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8207 When used inside the <filename>layer.conf</filename> configuration
8208 file, this variable provides the path of the current layer.
8209 This variable is not available outside of <filename>layer.conf</filename>
8210 and references are expanded immediately when parsing of the file completes.
8211 </para>
8212 </glossdef>
8213 </glossentry>
8214
Brad Bishop6e60e8b2018-02-01 10:27:11 -05008215 <glossentry id='var-LAYERRECOMMENDS'><glossterm>LAYERRECOMMENDS</glossterm>
8216 <info>
8217 LAYERRECOMMENDS[doc] = "Lists the layers, separated by spaces, recommended for use with this layer."
8218 </info>
8219 <glossdef>
8220 <para role="glossdeffirst">
8221<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8222 Lists the layers, separated by spaces, recommended for
8223 use with this layer.
8224 </para>
8225
8226 <para>
8227 Optionally, you can specify a specific layer version for a
8228 recommendation by adding the version to the end of the
8229 layer name.
8230 Here is an example:
8231 <literallayout class='monospaced'>
8232 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"
8233 </literallayout>
8234 In this previous example, version 3 of "anotherlayer" is
8235 compared against
8236 <filename>LAYERVERSION_anotherlayer</filename>.
8237 </para>
8238
8239 <para>
8240 This variable is used in the
8241 <filename>conf/layer.conf</filename> file and must be
8242 suffixed with the name of the specific layer (e.g.
8243 <filename>LAYERRECOMMENDS_mylayer</filename>).
8244 </para>
8245 </glossdef>
8246 </glossentry>
8247
Brad Bishop316dfdd2018-06-25 12:45:53 -04008248 <glossentry id='var-LAYERSERIES_COMPAT'><glossterm>LAYERSERIES_COMPAT</glossterm>
8249 <info>
8250 LAYERSERIES_COMPAT[doc] = "Lists the OpenEmbedded-Core versions for which a layer is compatible."
8251 </info>
8252 <glossdef>
8253 <para role="glossdeffirst">
8254<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8255 Lists the versions of the
8256 <link linkend='oe-core'>OpenEmbedded-Core</link> for which
8257 a layer is compatible.
8258 Using the <filename>LAYERSERIES_COMPAT</filename> variable
8259 allows the layer maintainer to indicate which combinations
8260 of the layer and OE-Core can be expected to work.
8261 The variable gives the system a way to detect when a layer
8262 has not been tested with new releases of OE-Core (e.g.
8263 the layer is not maintained).
8264 </para>
8265
8266 <para>
8267 To specify the OE-Core versions for which a layer is
8268 compatible, use this variable in your layer's
8269 <filename>conf/layer.conf</filename> configuration file.
8270 For the list, use the Yocto Project
8271 <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Release Name</ulink>
8272 (e.g. &DISTRO_NAME_NO_CAP;).
8273 To specify multiple OE-Core versions for the layer,
8274 use a space-separated list:
8275 <literallayout class='monospaced'>
8276 LAYERSERIES_COMPAT_<replaceable>layer_root_name</replaceable> = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;"
8277 </literallayout>
8278 <note>
8279 Setting <filename>LAYERSERIES_COMPAT</filename> is
8280 required by the Yocto Project Compatible version 2
8281 standard.
8282 The OpenEmbedded build system produces a warning if
8283 the variable is not set for any given layer.
8284 </note>
8285 </para>
8286
8287 <para>
8288 See the
8289 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-layer'>Creating Your Own Layer</ulink>"
8290 section in the Yocto Project Development Tasks Manual.
8291 </para>
8292 </glossdef>
8293 </glossentry>
8294
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008295 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
8296 <info>
8297 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."
8298 </info>
8299 <glossdef>
8300 <para role="glossdeffirst">
8301<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8302 Optionally specifies the version of a layer as a single number.
8303 You can use this within
8304 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
8305 for another layer in order to depend on a specific version
8306 of the layer.
8307 This variable is used in the <filename>conf/layer.conf</filename> file
8308 and must be suffixed with the name of the specific layer (e.g.
8309 <filename>LAYERVERSION_mylayer</filename>).
8310 </para>
8311 </glossdef>
8312 </glossentry>
8313
8314 <glossentry id='var-LD'><glossterm>LD</glossterm>
8315 <info>
8316 LD[doc] = "Minimal command and arguments to run the linker."
8317 </info>
8318 <glossdef>
8319 <para role="glossdeffirst">
8320<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8321 The minimal command and arguments used to run the
8322 linker.
8323 </para>
8324 </glossdef>
8325 </glossentry>
8326
8327 <glossentry id='var-LDFLAGS'><glossterm>LDFLAGS</glossterm>
8328 <info>
8329 LDFLAGS[doc] = "Specifies the flags to pass to the linker."
8330 </info>
8331 <glossdef>
8332 <para role="glossdeffirst">
8333<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8334 Specifies the flags to pass to the linker.
8335 This variable is exported to an environment
8336 variable and thus made visible to the software being
8337 built during the compilation step.
8338 </para>
8339
8340 <para>
8341 Default initialization for <filename>LDFLAGS</filename>
8342 varies depending on what is being built:
8343 <itemizedlist>
8344 <listitem><para>
8345 <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link>
8346 when building for the target
8347 </para></listitem>
8348 <listitem><para>
8349 <link linkend='var-BUILD_LDFLAGS'><filename>BUILD_LDFLAGS</filename></link>
8350 when building for the build host (i.e.
8351 <filename>-native</filename>)
8352 </para></listitem>
8353 <listitem><para>
8354 <link linkend='var-BUILDSDK_LDFLAGS'><filename>BUILDSDK_LDFLAGS</filename></link>
8355 when building for an SDK (i.e.
8356 <filename>nativesdk-</filename>)
8357 </para></listitem>
8358 </itemizedlist>
8359 </para>
8360 </glossdef>
8361 </glossentry>
8362
8363 <glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>
8364 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04008365 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 -05008366 </info>
8367 <glossdef>
8368 <para role="glossdeffirst">
8369<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8370 Specifies the lead (or primary) compiled library file
Brad Bishop316dfdd2018-06-25 12:45:53 -04008371 (i.e. <filename>.so</filename>) that the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008372 <link linkend='ref-classes-debian'><filename>debian</filename></link>
8373 class applies its naming policy to given a recipe that
8374 packages multiple libraries.
8375 </para>
8376
8377 <para>
8378 This variable works in conjunction with the
8379 <filename>debian</filename> class.
8380 </para>
8381 </glossdef>
8382 </glossentry>
8383
8384 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
8385 <info>
8386 LIC_FILES_CHKSUM[doc] = "Checksums of the license text in the recipe source code."
8387 </info>
8388 <glossdef>
8389 <para role="glossdeffirst">
8390<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8391 Checksums of the license text in the recipe source code.
8392 </para>
8393
8394 <para>
8395 This variable tracks changes in license text of the source
8396 code files.
8397 If the license text is changed, it will trigger a build
8398 failure, which gives the developer an opportunity to review any
8399 license change.
8400 </para>
8401
8402 <para>
8403 This variable must be defined for all recipes (unless
8404 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8405 is set to "CLOSED").</para>
8406 <para>For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04008407 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
8408 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008409 </para>
8410 </glossdef>
8411 </glossentry>
8412
8413 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
8414 <info>
8415 LICENSE[doc] = "The list of source licenses for the recipe. The logical operators &amp;, '|', and parentheses can be used."
8416 </info>
8417 <glossdef>
8418 <para role="glossdeffirst">
8419<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8420 The list of source licenses for the recipe.
8421 Follow these rules:
8422 <itemizedlist>
8423 <listitem><para>Do not use spaces within individual
8424 license names.</para></listitem>
8425 <listitem><para>Separate license names using
8426 | (pipe) when there is a choice between licenses.
8427 </para></listitem>
8428 <listitem><para>Separate license names using
8429 &amp; (ampersand) when multiple licenses exist
8430 that cover different parts of the source.
8431 </para></listitem>
8432 <listitem><para>You can use spaces between license
8433 names.</para></listitem>
8434 <listitem><para>For standard licenses, use the names
8435 of the files in
8436 <filename>meta/files/common-licenses/</filename>
8437 or the
8438 <link linkend='var-SPDXLICENSEMAP'><filename>SPDXLICENSEMAP</filename></link>
8439 flag names defined in
8440 <filename>meta/conf/licenses.conf</filename>.
8441 </para></listitem>
8442 </itemizedlist>
8443 </para>
8444
8445 <para>
8446 Here are some examples:
8447 <literallayout class='monospaced'>
8448 LICENSE = "LGPLv2.1 | GPLv3"
8449 LICENSE = "MPL-1 &amp; LGPLv2.1"
8450 LICENSE = "GPLv2+"
8451 </literallayout>
8452 The first example is from the recipes for Qt, which the user
8453 may choose to distribute under either the LGPL version
8454 2.1 or GPL version 3.
8455 The second example is from Cairo where two licenses cover
8456 different parts of the source code.
8457 The final example is from <filename>sysstat</filename>,
8458 which presents a single license.
8459 </para>
8460
8461 <para>
8462 You can also specify licenses on a per-package basis to
8463 handle situations where components of the output have
8464 different licenses.
8465 For example, a piece of software whose code is
8466 licensed under GPLv2 but has accompanying documentation
8467 licensed under the GNU Free Documentation License 1.2 could
8468 be specified as follows:
8469 <literallayout class='monospaced'>
8470 LICENSE = "GFDL-1.2 &amp; GPLv2"
8471 LICENSE_${PN} = "GPLv2"
8472 LICENSE_${PN}-doc = "GFDL-1.2"
8473 </literallayout>
8474 </para>
8475 </glossdef>
8476 </glossentry>
8477
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05008478 <glossentry id='var-LICENSE_CREATE_PACKAGE'><glossterm>LICENSE_CREATE_PACKAGE</glossterm>
8479 <info>
8480 LICENSE_CREATE_PACKAGE[doc] = "Creates an extra package (i.e. ${PN}-lic) for each recipe and adds that package to the RRECOMMENDS+${PN}."
8481 </info>
8482 <glossdef>
8483 <para role="glossdeffirst">
8484<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8485 Setting <filename>LICENSE_CREATE_PACKAGE</filename>
8486 to "1" causes the OpenEmbedded build system to create
8487 an extra package (i.e.
8488 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-lic</filename>)
8489 for each recipe and to add those packages to the
8490 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link><filename>_${PN}</filename>.
8491 </para>
8492
8493 <para>
8494 The <filename>${PN}-lic</filename> package installs a
8495 directory in <filename>/usr/share/licenses</filename>
8496 named <filename>${PN}</filename>, which is the recipe's
8497 base name, and installs files in that directory that
8498 contain license and copyright information (i.e. copies of
8499 the appropriate license files from
8500 <filename>meta/common-licenses</filename> that match the
8501 licenses specified in the
8502 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8503 variable of the recipe metadata and copies of files marked
8504 in
8505 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
8506 as containing license text).
8507 </para>
8508
8509 <para>
8510 For related information on providing license text, see the
8511 <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
8512 variable, the
8513 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
8514 variable, and the
8515 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008516 section in the Yocto Project Development Tasks Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05008517 </para>
8518 </glossdef>
8519 </glossentry>
8520
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008521 <glossentry id='var-LICENSE_FLAGS'><glossterm>LICENSE_FLAGS</glossterm>
8522 <info>
8523 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."
8524 </info>
8525 <glossdef>
8526 <para role="glossdeffirst">
8527<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8528 Specifies additional flags for a recipe you must
8529 whitelist through
8530 <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
8531 in order to allow the recipe to be built.
8532 When providing multiple flags, separate them with
8533 spaces.
8534 </para>
8535
8536 <para>
8537 This value is independent of
8538 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8539 and is typically used to mark recipes that might
8540 require additional licenses in order to be used in a
8541 commercial product.
8542 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04008543 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8544 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008545 </para>
8546 </glossdef>
8547 </glossentry>
8548
8549 <glossentry id='var-LICENSE_FLAGS_WHITELIST'><glossterm>LICENSE_FLAGS_WHITELIST</glossterm>
8550 <info>
8551 LICENSE_FLAGS_WHITELIST[doc] = "Lists license flags that when specified in LICENSE_FLAGS within a recipe should not prevent that recipe from being built."
8552 </info>
8553 <glossdef>
8554 <para role="glossdeffirst">
8555<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8556 Lists license flags that when specified in
8557 <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
8558 within a recipe should not prevent that recipe from being
8559 built.
8560 This practice is otherwise known as "whitelisting"
8561 license flags.
8562 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04008563 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8564 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008565 </para>
8566 </glossdef>
8567 </glossentry>
8568
8569 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
8570 <info>
8571 LICENSE_PATH[doc] = "Path to additional licenses used during the build."
8572 </info>
8573 <glossdef>
8574 <para role="glossdeffirst">
8575<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8576 Path to additional licenses used during the build.
8577 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
8578 to define the directory that holds common license text used during the build.
8579 The <filename>LICENSE_PATH</filename> variable allows you to extend that
8580 location to other areas that have additional licenses:
8581 <literallayout class='monospaced'>
8582 LICENSE_PATH += "<replaceable>path-to-additional-common-licenses</replaceable>"
8583 </literallayout>
8584 </para>
8585 </glossdef>
8586 </glossentry>
8587
8588 <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
8589 <info>
8590 LINUX_KERNEL_TYPE[doc] = "Defines the kernel type to be used in assembling the configuration."
8591 </info>
8592 <glossdef>
8593 <para role="glossdeffirst">
8594<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8595 Defines the kernel type to be used in assembling the
8596 configuration.
8597 The linux-yocto recipes define "standard", "tiny", and
8598 "preempt-rt" kernel types.
8599 See the
8600 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
8601 section in the Yocto Project Linux Kernel Development
8602 Manual for more information on kernel types.
8603 </para>
8604
8605 <para>
8606 If you do not specify a
8607 <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
8608 "standard".
8609 Together with
8610 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
8611 the <filename>LINUX_KERNEL_TYPE</filename> variable
8612 defines the search
8613 arguments used by the kernel tools to find the appropriate
8614 description within the kernel
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008615 <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008616 with which to build out the sources and configuration.
8617 </para>
8618 </glossdef>
8619 </glossentry>
8620
8621 <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
8622 <info>
8623 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."
8624 </info>
8625 <glossdef>
8626 <para role="glossdeffirst">
8627<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8628 The Linux version from <filename>kernel.org</filename>
8629 on which the Linux kernel image being built using the
8630 OpenEmbedded build system is based.
8631 You define this variable in the kernel recipe.
8632 For example, the <filename>linux-yocto-3.4.bb</filename>
8633 kernel recipe found in
8634 <filename>meta/recipes-kernel/linux</filename>
8635 defines the variables as follows:
8636 <literallayout class='monospaced'>
8637 LINUX_VERSION ?= "3.4.24"
8638 </literallayout>
8639 </para>
8640
8641 <para>
8642 The <filename>LINUX_VERSION</filename> variable is used to
8643 define <link linkend='var-PV'><filename>PV</filename></link>
8644 for the recipe:
8645 <literallayout class='monospaced'>
8646 PV = "${LINUX_VERSION}+git${SRCPV}"
8647 </literallayout>
8648 </para>
8649 </glossdef>
8650 </glossentry>
8651
8652 <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
8653 <info>
8654 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."
8655 </info>
8656 <glossdef>
8657 <para role="glossdeffirst">
8658<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8659 A string extension compiled into the version
8660 string of the Linux kernel built with the OpenEmbedded
8661 build system.
8662 You define this variable in the kernel recipe.
8663 For example, the linux-yocto kernel recipes all define
8664 the variable as follows:
8665 <literallayout class='monospaced'>
8666 LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
8667 </literallayout>
8668 </para>
8669
8670 <para>
8671 Defining this variable essentially sets the
8672 Linux kernel configuration item
8673 <filename>CONFIG_LOCALVERSION</filename>, which is visible
8674 through the <filename>uname</filename> command.
8675 Here is an example that shows the extension assuming it
8676 was set as previously shown:
8677 <literallayout class='monospaced'>
8678 $ uname -r
8679 3.7.0-rc8-custom
8680 </literallayout>
8681 </para>
8682 </glossdef>
8683 </glossentry>
8684
8685 <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
8686 <info>
8687 LOG_DIR[doc] = "Specifies the directory to which the OpenEmbedded build system writes overall log files. The default directory is ${TMPDIR}/log"
8688 </info>
8689 <glossdef>
8690 <para role="glossdeffirst">
8691<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8692 Specifies the directory to which the OpenEmbedded build
8693 system writes overall log files.
8694 The default directory is <filename>${TMPDIR}/log</filename>.
8695 </para>
8696
8697 <para>
8698 For the directory containing logs specific to each task,
8699 see the <link linkend='var-T'><filename>T</filename></link>
8700 variable.
8701 </para>
8702 </glossdef>
8703 </glossentry>
8704
8705 </glossdiv>
8706
8707 <glossdiv id='var-glossary-m'><title>M</title>
8708
8709 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
8710 <info>
8711 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."
8712 </info>
8713 <glossdef>
8714 <para role="glossdeffirst">
8715<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8716 Specifies the target device for which the image is built.
8717 You define <filename>MACHINE</filename> in the
8718 <filename>local.conf</filename> file found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008719 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008720 By default, <filename>MACHINE</filename> is set to
8721 "qemux86", which is an x86-based architecture machine to
8722 be emulated using QEMU:
8723 <literallayout class='monospaced'>
8724 MACHINE ?= "qemux86"
8725 </literallayout>
8726 </para>
8727
8728 <para>
8729 The variable corresponds to a machine configuration file of the
8730 same name, through which machine-specific configurations are set.
8731 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
8732 exists the corresponding <filename>qemux86.conf</filename> machine
8733 configuration file, which can be found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008734 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008735 in <filename>meta/conf/machine</filename>.
8736 </para>
8737
8738 <para>
8739 The list of machines supported by the Yocto Project as
8740 shipped include the following:
8741 <literallayout class='monospaced'>
8742 MACHINE ?= "qemuarm"
8743 MACHINE ?= "qemuarm64"
8744 MACHINE ?= "qemumips"
8745 MACHINE ?= "qemumips64"
8746 MACHINE ?= "qemuppc"
8747 MACHINE ?= "qemux86"
8748 MACHINE ?= "qemux86-64"
8749 MACHINE ?= "genericx86"
8750 MACHINE ?= "genericx86-64"
8751 MACHINE ?= "beaglebone"
8752 MACHINE ?= "mpc8315e-rdb"
8753 MACHINE ?= "edgerouter"
8754 </literallayout>
8755 The last five are Yocto Project reference hardware boards, which
8756 are provided in the <filename>meta-yocto-bsp</filename> layer.
8757 <note>Adding additional Board Support Package (BSP) layers
8758 to your configuration adds new possible settings for
8759 <filename>MACHINE</filename>.
8760 </note>
8761 </para>
8762 </glossdef>
8763 </glossentry>
8764
8765 <glossentry id='var-MACHINE_ARCH'><glossterm>MACHINE_ARCH</glossterm>
8766 <info>
8767 MACHINE_ARCH[doc] = "Specifies the name of the machine-specific architecture. This variable is set automatically from MACHINE or TUNE_PKGARCH."
8768 </info>
8769 <glossdef>
8770 <para role="glossdeffirst">
8771<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8772 Specifies the name of the machine-specific architecture.
8773 This variable is set automatically from
8774 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
8775 or
8776 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>.
8777 You should not hand-edit the
8778 <filename>MACHINE_ARCH</filename> variable.
8779 </para>
8780 </glossdef>
8781 </glossentry>
8782
8783 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
8784 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04008785 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 -05008786 </info>
8787 <glossdef>
8788 <para role="glossdeffirst">
8789<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8790 A list of required machine-specific packages to install as part of
8791 the image being built.
8792 The build process depends on these packages being present.
Brad Bishop316dfdd2018-06-25 12:45:53 -04008793 Furthermore, because this is a "machine-essential" variable, the list of
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008794 packages are essential for the machine to boot.
8795 The impact of this variable affects images based on
8796 <filename>packagegroup-core-boot</filename>,
8797 including the <filename>core-image-minimal</filename> image.
8798 </para>
8799
8800 <para>
8801 This variable is similar to the
8802 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
8803 variable with the exception that the image being built has a build
8804 dependency on the variable's list of packages.
8805 In other words, the image will not build if a file in this list is not found.
8806 </para>
8807
8808 <para>
8809 As an example, suppose the machine for which you are building requires
8810 <filename>example-init</filename> to be run during boot to initialize the hardware.
8811 In this case, you would use the following in the machine's
8812 <filename>.conf</filename> configuration file:
8813 <literallayout class='monospaced'>
8814 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
8815 </literallayout>
8816 </para>
8817 </glossdef>
8818 </glossentry>
8819
8820 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
8821 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04008822 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 -05008823 </info>
8824 <glossdef>
8825 <para role="glossdeffirst">
8826<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8827 A list of recommended machine-specific packages to install as part of
8828 the image being built.
8829 The build process does not depend on these packages being present.
Brad Bishop316dfdd2018-06-25 12:45:53 -04008830 However, because this is a "machine-essential" variable, the list of
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008831 packages are essential for the machine to boot.
8832 The impact of this variable affects images based on
8833 <filename>packagegroup-core-boot</filename>,
8834 including the <filename>core-image-minimal</filename> image.
8835 </para>
8836
8837 <para>
8838 This variable is similar to the
8839 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
8840 variable with the exception that the image being built does not have a build
8841 dependency on the variable's list of packages.
8842 In other words, the image will still build if a package in this list is not found.
8843 Typically, this variable is used to handle essential kernel modules, whose
8844 functionality may be selected to be built into the kernel rather than as a module,
8845 in which case a package will not be produced.
8846 </para>
8847
8848 <para>
8849 Consider an example where you have a custom kernel where a specific touchscreen
8850 driver is required for the machine to be usable.
8851 However, the driver can be built as a module or
8852 into the kernel depending on the kernel configuration.
8853 If the driver is built as a module, you want it to be installed.
8854 But, when the driver is built into the kernel, you still want the
8855 build to succeed.
8856 This variable sets up a "recommends" relationship so that in the latter case,
8857 the build will not fail due to the missing package.
8858 To accomplish this, assuming the package for the module was called
8859 <filename>kernel-module-ab123</filename>, you would use the
8860 following in the machine's <filename>.conf</filename> configuration
8861 file:
8862 <literallayout class='monospaced'>
8863 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
8864 </literallayout>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05008865 <note>
8866 In this example, the
8867 <filename>kernel-module-ab123</filename> recipe
8868 needs to explicitly set its
8869 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
8870 variable to ensure that BitBake does not use the
8871 kernel recipe's
8872 <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link>
8873 variable to satisfy the dependency.
8874 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008875 </para>
8876
8877 <para>
8878 Some examples of these machine essentials are flash, screen, keyboard, mouse,
8879 or touchscreen drivers (depending on the machine).
8880 </para>
8881 </glossdef>
8882 </glossentry>
8883
8884 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
8885 <info>
8886 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."
8887 </info>
8888 <glossdef>
8889 <para role="glossdeffirst">
8890<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8891 A list of machine-specific packages to install as part of the
8892 image being built that are not essential for the machine to boot.
8893 However, the build process for more fully-featured images
8894 depends on the packages being present.
8895 </para>
8896
8897 <para>
8898 This variable affects all images based on
8899 <filename>packagegroup-base</filename>, which does not include the
8900 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
8901 images.
8902 </para>
8903
8904 <para>
8905 The variable is similar to the
8906 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
8907 variable with the exception that the image being built has a build
8908 dependency on the variable's list of packages.
8909 In other words, the image will not build if a file in this list is not found.
8910 </para>
8911
8912 <para>
8913 An example is a machine that has WiFi capability but is not
8914 essential for the machine to boot the image.
8915 However, if you are building a more fully-featured image, you want to enable
8916 the WiFi.
8917 The package containing the firmware for the WiFi hardware is always
8918 expected to exist, so it is acceptable for the build process to depend upon
8919 finding the package.
8920 In this case, assuming the package for the firmware was called
8921 <filename>wifidriver-firmware</filename>, you would use the following in the
8922 <filename>.conf</filename> file for the machine:
8923 <literallayout class='monospaced'>
8924 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
8925 </literallayout>
8926 </para>
8927 </glossdef>
8928 </glossentry>
8929
8930 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
8931 <info>
8932 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."
8933 </info>
8934 <glossdef>
8935 <para role="glossdeffirst">
8936<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8937 A list of machine-specific packages to install as part of the
8938 image being built that are not essential for booting the machine.
8939 The image being built has no build dependency on this list of packages.
8940 </para>
8941
8942 <para>
8943 This variable affects only images based on
8944 <filename>packagegroup-base</filename>, which does not include the
8945 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
8946 images.
8947 </para>
8948
8949 <para>
8950 This variable is similar to the
8951 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
8952 variable with the exception that the image being built does not have a build
8953 dependency on the variable's list of packages.
8954 In other words, the image will build if a file in this list is not found.
8955 </para>
8956
8957 <para>
8958 An example is a machine that has WiFi capability but is not essential
8959 For the machine to boot the image.
8960 However, if you are building a more fully-featured image, you want to enable
8961 WiFi.
8962 In this case, the package containing the WiFi kernel module will not be produced
8963 if the WiFi driver is built into the kernel, in which case you still want the
8964 build to succeed instead of failing as a result of the package not being found.
8965 To accomplish this, assuming the package for the module was called
8966 <filename>kernel-module-examplewifi</filename>, you would use the
8967 following in the <filename>.conf</filename> file for the machine:
8968 <literallayout class='monospaced'>
8969 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
8970 </literallayout>
8971 </para>
8972 </glossdef>
8973 </glossentry>
8974
8975 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
8976 <info>
8977 MACHINE_FEATURES[doc] = "Specifies the list of hardware features the MACHINE supports."
8978 </info>
8979 <glossdef>
8980 <para role="glossdeffirst">
8981<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8982 Specifies the list of hardware features the
8983 <link linkend='var-MACHINE'><filename>MACHINE</filename></link> is capable
8984 of supporting.
8985 For related information on enabling features, see the
8986 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>,
8987 <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>,
8988 and
8989 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
8990 variables.
8991 </para>
8992
8993 <para>
8994 For a list of hardware features supported by the Yocto
8995 Project as shipped, see the
8996 "<link linkend='ref-features-machine'>Machine Features</link>"
8997 section.
8998 </para>
8999 </glossdef>
9000 </glossentry>
9001
9002 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
9003 <info>
9004 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."
9005 </info>
9006 <glossdef>
9007 <para role="glossdeffirst">
9008<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9009 Features to be added to
9010 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
9011 if not also present in
9012 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
9013 </para>
9014
9015 <para>
9016 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
9017 It is not intended to be user-configurable.
9018 It is best to just reference the variable to see which machine features are
9019 being backfilled for all machine configurations.
Brad Bishop316dfdd2018-06-25 12:45:53 -04009020 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009021 more information.
9022 </para>
9023 </glossdef>
9024 </glossentry>
9025
9026 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
9027 <info>
9028 MACHINE_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from MACHINE_FEATURES_BACKFILL that should not be backfilled (i.e. added to MACHINE_FEATURES) during the build."
9029 </info>
9030 <glossdef>
9031 <para role="glossdeffirst">
9032<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9033 Features from
9034 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
9035 that should not be backfilled (i.e. added to
9036 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
9037 during the build.
Brad Bishop316dfdd2018-06-25 12:45:53 -04009038 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009039 more information.
9040 </para>
9041 </glossdef>
9042 </glossentry>
9043
9044 <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
9045 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009046 MACHINEOVERRIDES[doc] = "A colon-separated list of overrides that apply to the current machine."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009047 </info>
9048 <glossdef>
9049 <para role="glossdeffirst">
9050<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009051 A colon-separated list of overrides that apply to the
9052 current machine.
9053 By default, this list includes the value of
9054 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009055 </para>
9056
9057 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009058 You can extend <filename>MACHINEOVERRIDES</filename>
9059 to add extra overrides that should apply to a machine.
9060 For example, all machines emulated in QEMU (e.g.
9061 <filename>qemuarm</filename>, <filename>qemux86</filename>,
9062 and so forth) include a file named
9063 <filename>meta/conf/machine/include/qemu.inc</filename>
9064 that prepends the following override to
9065 <filename>MACHINEOVERRIDES</filename>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009066 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009067 MACHINEOVERRIDES =. "qemuall:"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009068 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009069 This override allows variables to be overriden for all
9070 machines emulated in QEMU, like in the following example
9071 from the <filename>connman-conf</filename> recipe:
9072 <literallayout class='monospaced'>
9073 SRC_URI_append_qemuall = "file://wired.config \
9074 file://wired-setup \
9075 "
9076 </literallayout>
9077 The underlying mechanism behind
9078 <filename>MACHINEOVERRIDES</filename> is simply that it is
9079 included in the default value of
9080 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009081 </para>
9082 </glossdef>
9083 </glossentry>
9084
9085 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
9086 <info>
9087 MAINTAINER[doc] = "The email address of the distribution maintainer."
9088 </info>
9089 <glossdef>
9090 <para role="glossdeffirst">
9091<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9092 The email address of the distribution maintainer.
9093 </para>
9094 </glossdef>
9095 </glossentry>
9096
9097 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
9098 <info>
9099 MIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."
9100 </info>
9101 <glossdef>
9102 <para role="glossdeffirst">
9103<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9104 Specifies additional paths from which the OpenEmbedded
9105 build system gets source code.
9106 When the build system searches for source code, it first
9107 tries the local download directory.
9108 If that location fails, the build system tries locations
9109 defined by
9110 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
9111 the upstream source, and then locations specified by
9112 <filename>MIRRORS</filename> in that order.
9113 </para>
9114
9115 <para>
9116 Assuming your distribution
9117 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
9118 is "poky", the default value for
9119 <filename>MIRRORS</filename> is defined in the
9120 <filename>conf/distro/poky.conf</filename> file in the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05009121 <filename>meta-poky</filename> Git repository.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009122 </para>
9123 </glossdef>
9124 </glossentry>
9125
9126 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
9127 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04009128 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 -05009129 </info>
9130 <glossdef>
9131 <para role="glossdeffirst">
9132<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9133 Specifies a prefix has been added to
9134 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
Brad Bishop316dfdd2018-06-25 12:45:53 -04009135 of a recipe or package (i.e. a Multilib version).
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009136 The variable is used in places where the prefix needs to be
9137 added to or removed from a the name (e.g. the
9138 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
9139 <filename>MLPREFIX</filename> gets set when a prefix has been
9140 added to <filename>PN</filename>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009141 <note>
9142 The "ML" in <filename>MLPREFIX</filename> stands for
9143 "MultiLib".
9144 This representation is historical and comes from
9145 a time when <filename>nativesdk</filename> was a suffix
9146 rather than a prefix on the recipe name.
9147 When <filename>nativesdk</filename> was turned into a
9148 prefix, it made sense to set
9149 <filename>MLPREFIX</filename> for it as well.
9150 </note>
9151 </para>
9152
9153 <para>
9154 To help understand when <filename>MLPREFIX</filename>
9155 might be needed, consider when
9156 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
9157 is used to provide a <filename>nativesdk</filename> version
9158 of a recipe in addition to the target version.
9159 If that recipe declares build-time dependencies on tasks in
9160 other recipes by using
9161 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>,
9162 then a dependency on "foo" will automatically get rewritten
9163 to a dependency on "nativesdk-foo".
9164 However, dependencies like the following will not get
9165 rewritten automatically:
9166 <literallayout class='monospaced'>
9167 do_foo[depends] += "<replaceable>recipe</replaceable>:do_foo"
9168 </literallayout>
9169 If you want such a dependency to also get transformed,
9170 you can do the following:
9171 <literallayout class='monospaced'>
9172 do_foo[depends] += "${MLPREFIX}<replaceable>recipe</replaceable>:do_foo"
9173 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009174 </para>
9175 </glossdef>
9176 </glossentry>
9177
9178 <glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm>
9179 <info>
9180 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."
9181 </info>
9182 <glossdef>
9183 <para role="glossdeffirst">
9184<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9185 This variable has been replaced by the
9186 <filename>KERNEL_MODULE_AUTOLOAD</filename> variable.
9187 You should replace all occurrences of
9188 <filename>module_autoload</filename> with additions to
9189 <filename>KERNEL_MODULE_AUTOLOAD</filename>, for example:
9190 <literallayout class='monospaced'>
9191 module_autoload_rfcomm = "rfcomm"
9192 </literallayout>
9193 </para>
9194
9195 <para>
9196 should now be replaced with:
9197 <literallayout class='monospaced'>
9198 KERNEL_MODULE_AUTOLOAD += "rfcomm"
9199 </literallayout>
9200 See the
9201 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
9202 variable for more information.
9203 </para>
9204 </glossdef>
9205 </glossentry>
9206
9207 <glossentry id='var-module_conf'><glossterm>module_conf</glossterm>
9208 <info>
9209 module_conf[doc] = "Specifies modprobe.d syntax lines for inclusion in the /etc/modprobe.d/modname.conf file."
9210 </info>
9211 <glossdef>
9212 <para role="glossdeffirst">
9213<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9214 Specifies
9215 <ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink>
9216 syntax lines for inclusion in the
9217 <filename>/etc/modprobe.d/modname.conf</filename> file.
9218 </para>
9219
9220 <para>
9221 You can use this variable anywhere that it can be
9222 recognized by the kernel recipe or out-of-tree kernel
9223 module recipe (e.g. a machine configuration file, a
9224 distribution configuration file, an append file for the
9225 recipe, or the recipe itself).
9226 If you use this variable, you must also be sure to list
9227 the module name in the
9228 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
9229 variable.
9230 </para>
9231
9232 <para>
9233 Here is the general syntax:
9234 <literallayout class='monospaced'>
9235 module_conf_<replaceable>module_name</replaceable> = "<replaceable>modprobe.d-syntax</replaceable>"
9236 </literallayout>
9237 You must use the kernel module name override.
9238 </para>
9239
9240 <para>
9241 Run <filename>man modprobe.d</filename> in the shell to
9242 find out more information on the exact syntax
9243 you want to provide with <filename>module_conf</filename>.
9244 </para>
9245
9246 <para>
9247 Including <filename>module_conf</filename> causes the
9248 OpenEmbedded build system to populate the
9249 <filename>/etc/modprobe.d/modname.conf</filename>
9250 file with <filename>modprobe.d</filename> syntax lines.
9251 Here is an example that adds the options
9252 <filename>arg1</filename> and <filename>arg2</filename>
9253 to a module named <filename>mymodule</filename>:
9254 <literallayout class='monospaced'>
9255 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
9256 </literallayout>
9257 </para>
9258
9259 <para>
9260 For information on how to specify kernel modules to
9261 auto-load on boot, see the
9262 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
9263 variable.
9264 </para>
9265 </glossdef>
9266 </glossentry>
9267
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009268 <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
9269 <info>
9270 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."
9271 </info>
9272 <glossdef>
9273 <para role="glossdeffirst">
9274<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9275 Controls creation of the <filename>modules-*.tgz</filename>
9276 file.
9277 Set this variable to "0" to disable creation of this
9278 file, which contains all of the kernel modules resulting
9279 from a kernel build.
9280 </para>
9281 </glossdef>
9282 </glossentry>
9283
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08009284 <glossentry id='var-MODULE_TARBALL_LINK_NAME'><glossterm>MODULE_TARBALL_LINK_NAME</glossterm>
9285 <info>
9286 MODULE_TARBALL_LINK_NAME[doc] = "The link name of the kernel module tarball."
9287 </info>
9288 <glossdef>
9289 <para role="glossdeffirst">
9290<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9291 The link name of the kernel module tarball.
9292 This variable is set in the
9293 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
9294 file as follows:
9295 <literallayout class='monospaced'>
9296 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
9297 </literallayout>
9298 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
9299 variable, which is set in the same file, has the following
9300 value:
9301 <literallayout class='monospaced'>
9302 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
9303 </literallayout>
9304 </para>
9305
9306 <para>
9307 See the
9308 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
9309 variable for additional information.
9310 </para>
9311 </glossdef>
9312 </glossentry>
9313
9314 <glossentry id='var-MODULE_TARBALL_NAME'><glossterm>MODULE_TARBALL_NAME</glossterm>
9315 <info>
9316 MODULE_TARBALL_NAME[doc] = "The base name of the kernel module tarball."
9317 </info>
9318 <glossdef>
9319 <para role="glossdeffirst">
9320<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9321 The base name of the kernel module tarball.
9322 This variable is set in the
9323 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
9324 file as follows:
9325 <literallayout class='monospaced'>
9326 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"
9327 </literallayout>
9328 The value of the
9329 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
9330 variable, which is set in the same file, has the following
9331 value:
9332 <literallayout class='monospaced'>
9333 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
9334 </literallayout>
9335 </para>
9336 </glossdef>
9337 </glossentry>
9338
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009339<!--
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009340 <glossentry id='var-MULTIMACH_HOST_SYS'><glossterm>MULTIMACH_HOST_SYS</glossterm>
9341 <info>
9342 MULTIMACH_HOST_SYS[doc] = "Separates files for different machines such that you can build for multiple host machines using the same output directories."
9343 </info>
9344 <glossdef>
9345 <para role="glossdeffirst">
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009346-->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009347<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009348<!--
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009349 Serves the same purpose as
9350 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
9351 but for the "HOST" system, in situations that involve a
9352 "HOST" and a "TARGET" system.
9353 See the
9354 <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link>
9355 variable for more information.
9356 </para>
9357
9358 <para>
9359 The default value of this variable is:
9360 <literallayout class='monospaced'>
9361 ${PACKAGE_ARCH}${HOST_VENDOR}-${HOST_OS}
9362 </literallayout>
9363 </para>
9364 </glossdef>
9365 </glossentry>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009366-->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009367
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009368 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
9369 <info>
9370 MULTIMACH_TARGET_SYS[doc] = "Separates files for different machines such that you can build for multiple target machines using the same output directories."
9371 </info>
9372 <glossdef>
9373 <para role="glossdeffirst">
9374<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009375 Uniquely identifies the type of the target system for
9376 which packages are being built.
9377 This variable allows output for different types of target
9378 systems to be put into different subdirectories of the same
9379 output directory.
9380 </para>
9381
9382 <para>
9383 The default value of this variable is:
9384 <literallayout class='monospaced'>
9385 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}
9386 </literallayout>
9387 Some classes (e.g.
9388 <link linkend='ref-classes-cross-canadian'><filename>cross-canadian</filename></link>)
9389 modify the <filename>MULTIMACH_TARGET_SYS</filename> value.
9390 </para>
9391
9392 <para>
9393 See the
9394 <link linkend='var-STAMP'><filename>STAMP</filename></link>
9395 variable for an example.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009396 See the
9397 <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link>
9398 variable for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009399 </para>
9400 </glossdef>
9401 </glossentry>
9402
9403 </glossdiv>
9404
9405 <glossdiv id='var-glossary-n'><title>N</title>
9406
9407 <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
9408 <info>
9409 NATIVELSBSTRING[doc] = "A string identifying the host distribution."
9410 </info>
9411 <glossdef>
9412 <para role="glossdeffirst">
9413<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9414 A string identifying the host distribution.
9415 Strings consist of the host distributor ID
9416 followed by the release, as reported by the
9417 <filename>lsb_release</filename> tool
9418 or as read from <filename>/etc/lsb-release</filename>.
9419 For example, when running a build on Ubuntu 12.10, the value
9420 is "Ubuntu-12.10".
9421 If this information is unable to be determined, the value
9422 resolves to "Unknown".
9423 </para>
9424
9425 <para>
9426 This variable is used by default to isolate native shared
9427 state packages for different distributions (e.g. to avoid
9428 problems with <filename>glibc</filename> version
9429 incompatibilities).
9430 Additionally, the variable is checked against
9431 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
9432 if that variable is set.
9433 </para>
9434 </glossdef>
9435 </glossentry>
9436
9437 <glossentry id='var-NM'><glossterm>NM</glossterm>
9438 <info>
9439 NM[doc] = "Minimal command and arguments to run 'nm'."
9440 </info>
9441 <glossdef>
9442 <para role="glossdeffirst">
9443<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9444 The minimal command and arguments to run
9445 <filename>nm</filename>.
9446 </para>
9447 </glossdef>
9448 </glossentry>
9449
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08009450 <glossentry id='var-NO_GENERIC_LICENSE'><glossterm>NO_GENERIC_LICENSE</glossterm>
9451 <info>
9452 NO_GENERIC_LICENSE[doc] = "Used to allow copying a license that does not exist in common licenses."
9453 </info>
9454 <glossdef>
9455 <para role="glossdeffirst">
9456<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9457 Avoids QA errors when you use a non-common, non-CLOSED
9458 license in a recipe.
9459 Packages exist, such as the linux-firmware package, with
9460 many licenses that are not in any way common.
9461 Also, new licenses are added occasionally to avoid
9462 introducing a lot of common license files, which are only
9463 applicable to a specific package.
9464 <filename>NO_GENERIC_LICENSE</filename> is used to allow
9465 copying a license that does not exist in common licenses.
9466 </para>
9467
9468 <para>
9469 The following example shows how to add
9470 <filename>NO_GENERIC_LICENSE</filename> to a recipe:
9471 <literallayout class='monospaced'>
9472 NO_GENERIC_LICENSE[<replaceable>license_name</replaceable>] = "<replaceable>license_file_in_fetched_source</replaceable>"
9473 </literallayout>
9474 The following is an example that uses the
9475 <filename>LICENSE.Abilis.txt</filename> file as the license
9476 from the fetched source:
9477 <literallayout class='monospaced'>
9478 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
9479 </literallayout>
9480 </para>
9481 </glossdef>
9482 </glossentry>
9483
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009484 <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
9485 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04009486 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 -05009487 </info>
9488 <glossdef>
9489 <para role="glossdeffirst">
9490<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9491 Prevents installation of all "recommended-only" packages.
9492 Recommended-only packages are packages installed only
9493 through the
9494 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
9495 variable).
9496 Setting the <filename>NO_RECOMMENDATIONS</filename> variable
9497 to "1" turns this feature on:
9498 <literallayout class='monospaced'>
9499 NO_RECOMMENDATIONS = "1"
9500 </literallayout>
9501 </para>
9502
9503 <para>
9504 You can set this variable globally in your
9505 <filename>local.conf</filename> file or you can attach it to
9506 a specific image recipe by using the recipe name override:
9507 <literallayout class='monospaced'>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009508 NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "1"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009509 </literallayout>
9510 </para>
9511
9512 <para>
9513 It is important to realize that if you choose to not install
9514 packages using this variable and some other packages are
9515 dependent on them (i.e. listed in a recipe's
9516 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
9517 variable), the OpenEmbedded build system ignores your
9518 request and will install the packages to avoid dependency
9519 errors.
9520 <note>
9521 Some recommended packages might be required for certain
9522 system functionality, such as kernel modules.
9523 It is up to you to add packages with the
9524 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
9525 variable.
9526 </note>
9527 </para>
9528
9529 <para>
9530 Support for this variable exists only when using the
9531 IPK and RPM packaging backend.
9532 Support does not exist for DEB.
9533 </para>
9534
9535 <para>
9536 See the
9537 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
9538 and the
9539 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
9540 variables for related information.
9541 </para>
9542 </glossdef>
9543 </glossentry>
9544
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009545 <glossentry id='var-NOAUTOPACKAGEDEBUG'><glossterm>NOAUTOPACKAGEDEBUG</glossterm>
9546 <info>
9547 NOAUTOPACKAGEDEBUG[doc] = "Disables auto package from splitting .debug files."
9548 </info>
9549 <glossdef>
9550 <para role="glossdeffirst">
9551<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9552 Disables auto package from splitting
9553 <filename>.debug</filename> files. If a recipe requires
9554 <filename>FILES_${PN}-dbg</filename> to be set manually,
9555 the <filename>NOAUTOPACKAGEDEBUG</filename> can be defined
9556 allowing you to define the content of the debug package.
9557 For example:
9558 <literallayout class='monospaced'>
9559 NOAUTOPACKAGEDEBUG = "1"
9560 FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
9561 FILES_${PN}-dbg = "/usr/src/debug/"
9562 FILES_${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"
9563 </literallayout>
9564 </para>
9565 </glossdef>
9566 </glossentry>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009567 </glossdiv>
9568
9569 <glossdiv id='var-glossary-o'><title>O</title>
9570
9571 <glossentry id='var-OBJCOPY'><glossterm>OBJCOPY</glossterm>
9572 <info>
9573 OBJCOPY[doc] = "Minimal command and arguments to run 'objcopy'."
9574 </info>
9575 <glossdef>
9576 <para role="glossdeffirst">
9577<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9578 The minimal command and arguments to run
9579 <filename>objcopy</filename>.
9580 </para>
9581 </glossdef>
9582 </glossentry>
9583
9584 <glossentry id='var-OBJDUMP'><glossterm>OBJDUMP</glossterm>
9585 <info>
9586 OBJDUMP[doc] = "Minimal command and arguments to run 'objdump'."
9587 </info>
9588 <glossdef>
9589 <para role="glossdeffirst">
9590<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9591 The minimal command and arguments to run
9592 <filename>objdump</filename>.
9593 </para>
9594 </glossdef>
9595 </glossentry>
9596
9597 <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
9598 <info>
9599 OE_BINCONFIG_EXTRA_MANGLE[doc] = "When a recipe inherits the binconfig.bbclass class, this variable specifies additional arguments passed to the "sed" command."
9600 </info>
9601 <glossdef>
9602 <para role="glossdeffirst">
9603<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9604 When inheriting the
9605 <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
9606 class, this variable
9607 specifies additional arguments passed to the "sed" command.
9608 The sed command alters any paths in configuration scripts
9609 that have been set up during compilation.
9610 Inheriting this class results in all paths in these scripts
9611 being changed to point into the
9612 <filename>sysroots/</filename> directory so that all builds
9613 that use the script will use the correct directories
9614 for the cross compiling layout.
9615 </para>
9616
9617 <para>
9618 See the <filename>meta/classes/binconfig.bbclass</filename>
9619 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009620 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009621 for details on how this class applies these additional
9622 sed command arguments.
9623 For general information on the
Brad Bishop316dfdd2018-06-25 12:45:53 -04009624 <filename>binconfig</filename> class, see the
9625 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009626 section.
9627 </para>
9628 </glossdef>
9629 </glossentry>
9630
9631 <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
9632 <info>
9633 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."
9634 </info>
9635 <glossdef>
9636 <para role="glossdeffirst">
9637<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9638 An internal variable used to tell the OpenEmbedded build
9639 system what Python modules to import for every Python
9640 function run by the system.
9641 </para>
9642
9643 <note>
9644 Do not set this variable.
9645 It is for internal use only.
9646 </note>
9647 </glossdef>
9648 </glossentry>
9649
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05009650 <glossentry id='var-OE_INIT_ENV_SCRIPT'><glossterm>OE_INIT_ENV_SCRIPT</glossterm>
9651 <info>
9652 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."
9653 </info>
9654 <glossdef>
9655 <para role="glossdeffirst">
9656<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9657 The name of the build environment setup script for the
9658 purposes of setting up the environment within the
9659 extensible SDK.
9660 The default value is "oe-init-build-env".
9661 </para>
9662
9663 <para>
9664 If you use a custom script to set up your build
9665 environment, set the
9666 <filename>OE_INIT_ENV_SCRIPT</filename> variable to its
9667 name.
9668 </para>
9669 </glossdef>
9670 </glossentry>
9671
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009672 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
9673 <info>
9674 OE_TERMINAL[doc] = "Controls how the OpenEmbedded build system spawns interactive terminals on the host development system."
9675 </info>
9676 <glossdef>
9677 <para role="glossdeffirst">
9678<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9679 Controls how the OpenEmbedded build system spawns
9680 interactive terminals on the host development system
9681 (e.g. using the BitBake command with the
9682 <filename>-c devshell</filename> command-line option).
9683 For more information, see the
9684 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009685 in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009686 </para>
9687
9688 <para>
9689 You can use the following values for the
9690 <filename>OE_TERMINAL</filename> variable:
9691 <literallayout class='monospaced'>
9692 auto
9693 gnome
9694 xfce
9695 rxvt
9696 screen
9697 konsole
9698 none
9699 </literallayout>
9700 </para>
9701 </glossdef>
9702 </glossentry>
9703
9704 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
9705 <info>
9706 OEROOT[doc] = "The directory from which the top-level build environment setup script is sourced."
9707 </info>
9708 <glossdef>
9709 <para role="glossdeffirst">
9710<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9711 The directory from which the top-level build environment
9712 setup script is sourced.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009713 The Yocto Project provides a top-level build environment
9714 setup script:
9715 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
9716 When you run this script, the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009717 <filename>OEROOT</filename> variable resolves to the
9718 directory that contains the script.
9719 </para>
9720
9721 <para>
9722 For additional information on how this variable is used,
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009723 see the initialization script.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009724 </para>
9725 </glossdef>
9726 </glossentry>
9727
9728 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
9729 <info>
9730 OLDEST_KERNEL[doc] = "Declares the oldest version of the Linux kernel that the produced binaries must support."
9731 </info>
9732 <glossdef>
9733 <para role="glossdeffirst">
9734<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9735 Declares the oldest version of the Linux kernel that the
9736 produced binaries must support.
9737 This variable is passed into the build of the Embedded
9738 GNU C Library (<filename>glibc</filename>).
9739 </para>
9740
9741 <para>
9742 The default for this variable comes from the
9743 <filename>meta/conf/bitbake.conf</filename> configuration
9744 file.
9745 You can override this default by setting the variable
9746 in a custom distribution configuration file.
9747 </para>
9748 </glossdef>
9749 </glossentry>
9750
9751 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
9752 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009753 OVERRIDES[doc] = "A colon-separated list of overrides that currently apply."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009754 </info>
9755 <glossdef>
9756 <para role="glossdeffirst">
9757<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009758 A colon-separated list of overrides that currently apply.
9759 Overrides are a BitBake mechanism that allows variables to
9760 be selectively overridden at the end of parsing.
9761 The set of overrides in <filename>OVERRIDES</filename>
9762 represents the "state" during building, which includes
9763 the current recipe being built, the machine for which
9764 it is being built, and so forth.
9765 </para>
9766
9767 <para>
9768 As an example, if the string "an-override" appears as an
9769 element in the colon-separated list in
9770 <filename>OVERRIDES</filename>, then the following
9771 assignment will override <filename>FOO</filename> with the
9772 value "overridden" at the end of parsing:
9773 <literallayout class='monospaced'>
9774 FOO_an-override = "overridden"
9775 </literallayout>
9776 See the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009777 "<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009778 section in the BitBake User Manual for more information on
9779 the overrides mechanism.
9780 </para>
9781
9782 <para>
9783 The default value of <filename>OVERRIDES</filename>
9784 includes the values of the
9785 <link linkend='var-CLASSOVERRIDE'><filename>CLASSOVERRIDE</filename></link>,
9786 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>,
9787 and
9788 <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
9789 variables.
9790 Another important override included by default is
9791 <filename>pn-${PN}</filename>.
9792 This override allows variables to be set for a single
9793 recipe within configuration (<filename>.conf</filename>)
9794 files.
9795 Here is an example:
9796 <literallayout class='monospaced'>
9797 FOO_pn-myrecipe = "myrecipe-specific value"
9798 </literallayout>
9799 <note><title>Tip</title>
9800 An easy way to see what overrides apply is to search for
9801 <filename>OVERRIDES</filename> in the output of the
9802 <filename>bitbake -e</filename> command.
9803 See the
Brad Bishop316dfdd2018-06-25 12:45:53 -04009804 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-debugging-viewing-variable-values'>Viewing Variable Values</ulink>"
9805 section in the Yocto Project Development Tasks
9806 Manual for more information.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009807 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009808 </para>
9809 </glossdef>
9810 </glossentry>
9811 </glossdiv>
9812
9813 <glossdiv id='var-glossary-p'><title>P</title>
9814
9815 <glossentry id='var-P'><glossterm>P</glossterm>
9816 <info>
9817 P[doc] = "The recipe name and version. P is comprised of ${PN}-${PV}."
9818 </info>
9819 <glossdef>
9820 <para role="glossdeffirst">
9821<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9822 The recipe name and version.
9823 <filename>P</filename> is comprised of the following:
9824 <literallayout class='monospaced'>
9825 ${PN}-${PV}
9826 </literallayout>
9827 </para>
9828 </glossdef>
9829 </glossentry>
9830
9831 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
9832 <info>
9833 PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages."
9834 </info>
9835 <glossdef>
9836 <para role="glossdeffirst">
9837<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9838 The architecture of the resulting package or packages.
9839 </para>
9840
9841 <para>
9842 By default, the value of this variable is set to
9843 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
9844 when building for the target,
Brad Bishop316dfdd2018-06-25 12:45:53 -04009845 <link linkend='var-BUILD_ARCH'><filename>BUILD_ARCH</filename></link>
9846 when building for the
9847 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009848 for the SDK.
Brad Bishop316dfdd2018-06-25 12:45:53 -04009849 <note>
9850 See
9851 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>
9852 for more information.
9853 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009854 However, if your recipe's output packages are built
Brad Bishop316dfdd2018-06-25 12:45:53 -04009855 specific to the target machine rather than generally for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009856 the architecture of the machine, you should set
9857 <filename>PACKAGE_ARCH</filename> to the value of
9858 <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>
9859 in the recipe as follows:
9860 <literallayout class='monospaced'>
9861 PACKAGE_ARCH = "${MACHINE_ARCH}"
9862 </literallayout>
9863 </para>
9864 </glossdef>
9865 </glossentry>
9866
9867 <glossentry id='var-PACKAGE_ARCHS'><glossterm>PACKAGE_ARCHS</glossterm>
9868 <info>
9869 PACKAGE_ARCHS[doc] = "A list of architectures compatible with the given target in order of priority."
9870 </info>
9871 <glossdef>
9872 <para role="glossdeffirst">
9873<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9874 Specifies a list of architectures compatible with
9875 the target machine.
9876 This variable is set automatically and should not
9877 normally be hand-edited.
9878 Entries are separated using spaces and listed in order
9879 of priority.
9880 The default value for
9881 <filename>PACKAGE_ARCHS</filename> is "all any noarch
9882 ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
9883 </para>
9884 </glossdef>
9885 </glossentry>
9886
9887 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
9888 <info>
9889 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."
9890 </info>
9891 <glossdef>
9892 <para role="glossdeffirst">
9893<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9894 Enables easily adding packages to
9895 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
9896 before <filename>${<link linkend='var-PN'>PN</link>}</filename>
9897 so that those added packages can pick up files that would normally be
9898 included in the default package.
9899 </para>
9900 </glossdef>
9901 </glossentry>
9902
9903 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
9904 <info>
9905 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."
9906 </info>
9907 <glossdef>
9908 <para role="glossdeffirst">
9909<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9910 This variable, which is set in the
9911 <filename>local.conf</filename> configuration file found in
9912 the <filename>conf</filename> folder of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009913 <link linkend='build-directory'>Build Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009914 specifies the package manager the OpenEmbedded build system
9915 uses when packaging data.
9916 </para>
9917
9918 <para>
9919 You can provide one or more of the following arguments for
9920 the variable:
9921 <literallayout class='monospaced'>
9922 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"
9923 </literallayout>
9924 <note><title>Warning</title>
9925 While it is a legal option, the
Brad Bishop316dfdd2018-06-25 12:45:53 -04009926 <filename>package_tar</filename> class has limited
9927 functionality due to no support for package
9928 dependencies by that backend.
9929 Therefore, it is recommended that you do not use it.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009930 </note>
9931 The build system uses only the first argument in the list
9932 as the package manager when creating your image or SDK.
9933 However, packages will be created using any additional
9934 packaging classes you specify.
9935 For example, if you use the following in your
9936 <filename>local.conf</filename> file:
9937 <literallayout class='monospaced'>
9938 PACKAGE_CLASSES ?= "package_ipk"
9939 </literallayout>
9940 The OpenEmbedded build system uses the IPK package manager
9941 to create your image or SDK.
9942 </para>
9943
9944 <para>
9945 For information on packaging and build performance effects
9946 as a result of the package manager in use, see the
9947 "<link linkend='ref-classes-package'><filename>package.bbclass</filename></link>"
9948 section.
9949 </para>
9950 </glossdef>
9951 </glossentry>
9952
9953 <glossentry id='var-PACKAGE_DEBUG_SPLIT_STYLE'><glossterm>PACKAGE_DEBUG_SPLIT_STYLE</glossterm>
9954 <info>
9955 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)."
9956 </info>
9957 <glossdef>
9958 <para role="glossdeffirst">
9959<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9960 Determines how to split up the binary and debug information
9961 when creating <filename>*-dbg</filename> packages to be
9962 used with the GNU Project Debugger (GDB).
9963 </para>
9964
9965 <para>
9966 With the
9967 <filename>PACKAGE_DEBUG_SPLIT_STYLE</filename> variable,
9968 you can control where debug information, which can include
9969 or exclude source files, is stored:
9970 <itemizedlist>
9971 <listitem><para>
9972 ".debug": Debug symbol files are placed next
9973 to the binary in a <filename>.debug</filename>
9974 directory on the target.
9975 For example, if a binary is installed into
9976 <filename>/bin</filename>, the corresponding debug
9977 symbol files are installed in
9978 <filename>/bin/.debug</filename>.
9979 Source files are placed in
9980 <filename>/usr/src/debug</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009981 </para></listitem>
9982 <listitem><para>
9983 "debug-file-directory": Debug symbol files are
9984 placed under <filename>/usr/lib/debug</filename>
9985 on the target, and separated by the path from where
9986 the binary is installed.
9987 For example, if a binary is installed in
9988 <filename>/bin</filename>, the corresponding debug
9989 symbols are installed in
9990 <filename>/usr/lib/debug/bin</filename>.
9991 Source files are placed in
9992 <filename>/usr/src/debug</filename>.
9993 </para></listitem>
9994 <listitem><para>
9995 "debug-without-src": The same behavior as
9996 ".debug" previously described with the exception
9997 that no source files are installed.
9998 </para></listitem>.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08009999 <listitem><para>
10000 "debug-with-srcpkg": The same behavior as
10001 ".debug" previously described with the exception
10002 that all source files are placed in a separate
10003 <filename>*-src</filename> pkg.
Brad Bishop19323692019-04-05 15:28:33 -040010004 This is the default behavior.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010005 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010006 </itemizedlist>
10007 </para>
10008
10009 <para>
10010 You can find out more about debugging using GDB by reading
10011 the
10012 "<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 -050010013 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010014 </para>
10015 </glossdef>
10016 </glossentry>
10017
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010018 <glossentry id='var-PACKAGE_EXCLUDE_COMPLEMENTARY'><glossterm>PACKAGE_EXCLUDE_COMPLEMENTARY</glossterm>
10019 <info>
10020 PACKAGE_EXCLUDE_COMPLEMENTARY[doc] = "Prevents specific packages from being installed when you are installing complementary packages."
10021 </info>
10022 <glossdef>
10023 <para role="glossdeffirst">
10024<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10025 Prevents specific packages from being installed when
10026 you are installing complementary packages.
10027 </para>
10028
10029 <para>
10030 You might find that you want to prevent installing certain
10031 packages when you are installing complementary packages.
10032 For example, if you are using
10033 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
10034 to install <filename>dev-pkgs</filename>, you might not want
10035 to install all packages from a particular multilib.
10036 If you find yourself in this situation, you can use the
10037 <filename>PACKAGE_EXCLUDE_COMPLEMENTARY</filename> variable
10038 to specify regular expressions to match the packages you
10039 want to exclude.
10040 </para>
10041 </glossdef>
10042 </glossentry>
10043
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010044 <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
10045 <info>
10046 PACKAGE_EXCLUDE[doc] = "Packages to exclude from the installation. If a listed package is required, an error is generated."
10047 </info>
10048 <glossdef>
10049 <para role="glossdeffirst">
10050<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10051 Lists packages that should not be installed into an image.
10052 For example:
10053 <literallayout class='monospaced'>
10054 PACKAGE_EXCLUDE = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."
10055 </literallayout>
10056 </para>
10057
10058 <para>
10059 You can set this variable globally in your
10060 <filename>local.conf</filename> file or you can attach it to
10061 a specific image recipe by using the recipe name override:
10062 <literallayout class='monospaced'>
10063 PACKAGE_EXCLUDE_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"
10064 </literallayout>
10065 </para>
10066
10067 <para>
10068 If you choose to not install
10069 a package using this variable and some other package is
10070 dependent on it (i.e. listed in a recipe's
10071 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
10072 variable), the OpenEmbedded build system generates a fatal
10073 installation error.
10074 Because the build system halts the process with a fatal
10075 error, you can use the variable with an iterative
10076 development process to remove specific components from a
10077 system.
10078 </para>
10079
10080 <para>
10081 Support for this variable exists only when using the
10082 IPK and RPM packaging backend.
10083 Support does not exist for DEB.
10084 </para>
10085
10086 <para>
10087 See the
10088 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
10089 and the
10090 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
10091 variables for related information.
10092 </para>
10093 </glossdef>
10094 </glossentry>
10095
10096 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
10097 <info>
10098 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."
10099 </info>
10100 <glossdef>
10101 <para role="glossdeffirst">
10102<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10103 Specifies the list of architectures compatible with the device CPU.
10104 This variable is useful when you build for several different devices that use
10105 miscellaneous processors such as XScale and ARM926-EJS.
10106 </para>
10107 </glossdef>
10108 </glossentry>
10109
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010110 <glossentry id='var-PACKAGE_FEED_ARCHS'><glossterm>PACKAGE_FEED_ARCHS</glossterm>
10111 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040010112 PACKAGE_FEED_ARCHS[doc] = "Optionally specifies user-defined package architectures when constructing package feed URIs."
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010113 </info>
10114 <glossdef>
10115 <para role="glossdeffirst">
10116<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040010117 Optionally specifies the package architectures used as
10118 part of the package feed URIs during the build.
10119 When used, the <filename>PACKAGE_FEED_ARCHS</filename>
10120 variable is appended to the final package feed URI, which
10121 is constructed using the
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010122 <link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
10123 and
10124 <link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>
10125 variables.
Brad Bishop316dfdd2018-06-25 12:45:53 -040010126 <note><title>Tip</title>
10127 You can use the <filename>PACKAGE_FEEDS_ARCHS</filename>
10128 variable to whitelist specific package architectures.
10129 If you do not need to whitelist specific architectures,
10130 which is a common case, you can omit this variable.
10131 Omitting the variable results in all available
10132 architectures for the current machine being included
10133 into remote package feeds.
10134 </note>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010135 </para>
10136
10137 <para>
10138 Consider the following example where the
10139 <filename>PACKAGE_FEED_URIS</filename>,
10140 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
10141 <filename>PACKAGE_FEED_ARCHS</filename> variables are
10142 defined in your <filename>local.conf</filename> file:
10143 <literallayout class='monospaced'>
10144 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
10145 https://example.com/packagerepos/updates"
10146 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
10147 PACKAGE_FEED_ARCHS = "all core2-64"
10148 </literallayout>
10149 Given these settings, the resulting package feeds are
10150 as follows:
10151 <literallayout class='monospaced'>
10152 https://example.com/packagerepos/release/rpm/all
10153 https://example.com/packagerepos/release/rpm/core2-64
10154 https://example.com/packagerepos/release/rpm-dev/all
10155 https://example.com/packagerepos/release/rpm-dev/core2-64
10156 https://example.com/packagerepos/updates/rpm/all
10157 https://example.com/packagerepos/updates/rpm/core2-64
10158 https://example.com/packagerepos/updates/rpm-dev/all
10159 https://example.com/packagerepos/updates/rpm-dev/core2-64
10160 </literallayout>
10161 </para>
10162 </glossdef>
10163 </glossentry>
10164
10165 <glossentry id='var-PACKAGE_FEED_BASE_PATHS'><glossterm>PACKAGE_FEED_BASE_PATHS</glossterm>
10166 <info>
10167 PACKAGE_FEED_BASE_PATHS[doc] = "Specifies base path used when constructing package feed URIs."
10168 </info>
10169 <glossdef>
10170 <para role="glossdeffirst">
10171<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10172 Specifies the base path used when constructing package feed
10173 URIs.
10174 The <filename>PACKAGE_FEED_BASE_PATHS</filename> variable
10175 makes up the middle portion of a package feed URI used
10176 by the OpenEmbedded build system.
10177 The base path lies between the
10178 <link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
10179 and
10180 <link linkend='var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></link>
10181 variables.
10182 </para>
10183
10184 <para>
10185 Consider the following example where the
10186 <filename>PACKAGE_FEED_URIS</filename>,
10187 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
10188 <filename>PACKAGE_FEED_ARCHS</filename> variables are
10189 defined in your <filename>local.conf</filename> file:
10190 <literallayout class='monospaced'>
10191 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
10192 https://example.com/packagerepos/updates"
10193 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
10194 PACKAGE_FEED_ARCHS = "all core2-64"
10195 </literallayout>
10196 Given these settings, the resulting package feeds are
10197 as follows:
10198 <literallayout class='monospaced'>
10199 https://example.com/packagerepos/release/rpm/all
10200 https://example.com/packagerepos/release/rpm/core2-64
10201 https://example.com/packagerepos/release/rpm-dev/all
10202 https://example.com/packagerepos/release/rpm-dev/core2-64
10203 https://example.com/packagerepos/updates/rpm/all
10204 https://example.com/packagerepos/updates/rpm/core2-64
10205 https://example.com/packagerepos/updates/rpm-dev/all
10206 https://example.com/packagerepos/updates/rpm-dev/core2-64
10207 </literallayout>
10208 </para>
10209 </glossdef>
10210 </glossentry>
10211
10212 <glossentry id='var-PACKAGE_FEED_URIS'><glossterm>PACKAGE_FEED_URIS</glossterm>
10213 <info>
10214 PACKAGE_FEED_URIS[doc] = "Specifies the front portion of the package feed URI used by the OpenEmbedded build system."
10215 </info>
10216 <glossdef>
10217 <para role="glossdeffirst">
10218<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10219 Specifies the front portion of the package feed URI
10220 used by the OpenEmbedded build system.
10221 Each final package feed URI is comprised of
10222 <filename>PACKAGE_FEED_URIS</filename>,
10223 <link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>,
10224 and
10225 <link linkend='var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></link>
10226 variables.
10227 </para>
10228
10229 <para>
10230 Consider the following example where the
10231 <filename>PACKAGE_FEED_URIS</filename>,
10232 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
10233 <filename>PACKAGE_FEED_ARCHS</filename> variables are
10234 defined in your <filename>local.conf</filename> file:
10235 <literallayout class='monospaced'>
10236 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
10237 https://example.com/packagerepos/updates"
10238 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
10239 PACKAGE_FEED_ARCHS = "all core2-64"
10240 </literallayout>
10241 Given these settings, the resulting package feeds are
10242 as follows:
10243 <literallayout class='monospaced'>
10244 https://example.com/packagerepos/release/rpm/all
10245 https://example.com/packagerepos/release/rpm/core2-64
10246 https://example.com/packagerepos/release/rpm-dev/all
10247 https://example.com/packagerepos/release/rpm-dev/core2-64
10248 https://example.com/packagerepos/updates/rpm/all
10249 https://example.com/packagerepos/updates/rpm/core2-64
10250 https://example.com/packagerepos/updates/rpm-dev/all
10251 https://example.com/packagerepos/updates/rpm-dev/core2-64
10252 </literallayout>
10253 </para>
10254 </glossdef>
10255 </glossentry>
10256
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010257 <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
10258 <info>
10259 PACKAGE_GROUP[doc] = "Defines one or more packages to include in an image when a specific item is included in IMAGE_FEATURES."
10260 </info>
10261 <glossdef>
10262 <para role="glossdeffirst">
10263<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10264 The <filename>PACKAGE_GROUP</filename> variable has been
10265 renamed to
10266 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>.
10267 See the variable description for
10268 <filename>FEATURE_PACKAGES</filename> for information.
10269 </para>
10270
10271 <para>
10272 If if you use the <filename>PACKAGE_GROUP</filename>
10273 variable, the OpenEmbedded build system issues a warning
10274 message.
10275 </para>
10276 </glossdef>
10277 </glossentry>
10278
10279 <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
10280 <info>
10281 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."
10282 </info>
10283 <glossdef>
10284 <para role="glossdeffirst">
10285<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10286 The final list of packages passed to the package manager
10287 for installation into the image.
10288 </para>
10289
10290 <para>
10291 Because the package manager controls actual installation
10292 of all packages, the list of packages passed using
10293 <filename>PACKAGE_INSTALL</filename> is not the final list
10294 of packages that are actually installed.
10295 This variable is internal to the image construction
10296 code.
10297 Consequently, in general, you should use the
10298 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
10299 variable to specify packages for installation.
10300 The exception to this is when working with
10301 the
10302 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
10303 image.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050010304 When working with an initial RAM filesystem (initramfs)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010305 image, use the <filename>PACKAGE_INSTALL</filename>
10306 variable.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050010307 For information on creating an initramfs, see the
10308 "<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 -050010309 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010310 </para>
10311 </glossdef>
10312 </glossentry>
10313
10314 <glossentry id='var-PACKAGE_INSTALL_ATTEMPTONLY'><glossterm>PACKAGE_INSTALL_ATTEMPTONLY</glossterm>
10315 <info>
10316 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."
10317 </info>
10318 <glossdef>
10319 <para role="glossdeffirst">
10320<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10321 Specifies a list of packages the OpenEmbedded build
10322 system attempts to install when creating an image.
10323 If a listed package fails to install, the build system
10324 does not generate an error.
10325 This variable is generally not user-defined.
10326 </para>
10327 </glossdef>
10328 </glossentry>
10329
10330 <glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm>PACKAGE_PREPROCESS_FUNCS</glossterm>
10331 <info>
10332 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."
10333 </info>
10334 <glossdef>
10335 <para role="glossdeffirst">
10336<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10337 Specifies a list of functions run to pre-process the
10338 <link linkend='var-PKGD'><filename>PKGD</filename></link>
10339 directory prior to splitting the files out to individual
10340 packages.
10341 </para>
10342 </glossdef>
10343 </glossentry>
10344
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010345 <glossentry id='var-PACKAGE_WRITE_DEPS'><glossterm>PACKAGE_WRITE_DEPS</glossterm>
10346 <info>
10347 PACKAGE_WRITE_DEPS[doc] = "Specifies post-installation and pre-installation script dependencies on native/cross tools."
10348 </info>
10349 <glossdef>
10350 <para role="glossdeffirst">
10351<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10352 Specifies a list of dependencies for post-installation and
10353 pre-installation scripts on native/cross tools.
10354 If your post-installation or pre-installation script can
10355 execute at rootfs creation time rather than on the
10356 target but depends on a native tool in order to execute,
10357 you need to list the tools in
Brad Bishopd5ae7d92018-06-14 09:52:03 -070010358 <filename>PACKAGE_WRITE_DEPS</filename>.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010359 </para>
10360
10361 <para>
10362 For information on running post-installation scripts, see
10363 the
10364 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010365 section in the Yocto Project Development Tasks Manual.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010366 </para>
10367 </glossdef>
10368 </glossentry>
10369
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010370 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
10371 <info>
10372 PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis."
10373 </info>
10374 <glossdef>
10375 <para role="glossdeffirst">
10376<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10377 This variable provides a means of enabling or disabling
10378 features of a recipe on a per-recipe basis.
10379 <filename>PACKAGECONFIG</filename> blocks are defined
10380 in recipes when you specify features and then arguments
10381 that define feature behaviors.
10382 Here is the basic block structure:
10383 <literallayout class='monospaced'>
10384 PACKAGECONFIG ??= "f1 f2 f3 ..."
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010385 PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1,rt-recs-f1"
10386 PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2,rt-recs-f2"
10387 PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3,rt-recs-f3"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010388 </literallayout>
10389 </para>
10390
10391 <para>
10392 The <filename>PACKAGECONFIG</filename>
10393 variable itself specifies a space-separated list of the
10394 features to enable.
10395 Following the features, you can determine the behavior of
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010396 each feature by providing up to five order-dependent
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010397 arguments, which are separated by commas.
10398 You can omit any argument you like but must retain the
10399 separating commas.
10400 The order is important and specifies the following:
10401 <orderedlist>
10402 <listitem><para>Extra arguments
10403 that should be added to the configure script
10404 argument list
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010405 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
10406 or
10407 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010408 if the feature is enabled.</para></listitem>
10409 <listitem><para>Extra arguments
10410 that should be added to <filename>EXTRA_OECONF</filename>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010411 or <filename>PACKAGECONFIG_CONFARGS</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010412 if the feature is disabled.
10413 </para></listitem>
10414 <listitem><para>Additional build dependencies
10415 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
10416 that should be added if the feature is enabled.
10417 </para></listitem>
10418 <listitem><para>Additional runtime dependencies
10419 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
10420 that should be added if the feature is enabled.
10421 </para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010422 <listitem><para>Additional runtime recommendations
10423 (<link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)
10424 that should be added if the feature is enabled.
10425 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010426 </orderedlist>
10427 </para>
10428
10429 <para>
10430 Consider the following
10431 <filename>PACKAGECONFIG</filename> block taken from the
10432 <filename>librsvg</filename> recipe.
10433 In this example the feature is <filename>croco</filename>,
10434 which has three arguments that determine the feature's
10435 behavior.
10436 <literallayout class='monospaced'>
10437 PACKAGECONFIG ??= "croco"
10438 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
10439 </literallayout>
10440 The <filename>--with-croco</filename> and
10441 <filename>libcroco</filename> arguments apply only if
10442 the feature is enabled.
10443 In this case, <filename>--with-croco</filename> is
10444 added to the configure script argument list and
10445 <filename>libcroco</filename> is added to
Brad Bishop316dfdd2018-06-25 12:45:53 -040010446 <filename>DEPENDS</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010447 On the other hand, if the feature is disabled say through
10448 a <filename>.bbappend</filename> file in another layer, then
10449 the second argument <filename>--without-croco</filename> is
10450 added to the configure script rather than
10451 <filename>--with-croco</filename>.
10452 </para>
10453
10454 <para>
10455 The basic <filename>PACKAGECONFIG</filename> structure
10456 previously described holds true regardless of whether you
10457 are creating a block or changing a block.
10458 When creating a block, use the structure inside your
10459 recipe.
10460 </para>
10461
10462 <para>
10463 If you want to change an existing
10464 <filename>PACKAGECONFIG</filename> block, you can do so
10465 one of two ways:
10466 <itemizedlist>
10467 <listitem><para><emphasis>Append file:</emphasis>
10468 Create an append file named
10469 <replaceable>recipename</replaceable><filename>.bbappend</filename>
10470 in your layer and override the value of
10471 <filename>PACKAGECONFIG</filename>.
10472 You can either completely override the variable:
10473 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010474 PACKAGECONFIG = "f4 f5"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010475 </literallayout>
10476 Or, you can just append the variable:
10477 <literallayout class='monospaced'>
10478 PACKAGECONFIG_append = " f4"
10479 </literallayout></para></listitem>
10480 <listitem><para><emphasis>Configuration file:</emphasis>
10481 This method is identical to changing the block
10482 through an append file except you edit your
10483 <filename>local.conf</filename> or
10484 <filename><replaceable>mydistro</replaceable>.conf</filename> file.
10485 As with append files previously described,
10486 you can either completely override the variable:
10487 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010488 PACKAGECONFIG_pn-<replaceable>recipename</replaceable> = "f4 f5"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010489 </literallayout>
10490 Or, you can just amend the variable:
10491 <literallayout class='monospaced'>
10492 PACKAGECONFIG_append_pn-<replaceable>recipename</replaceable> = " f4"
10493 </literallayout></para></listitem>
10494 </itemizedlist>
10495 </para>
10496 </glossdef>
10497 </glossentry>
10498
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010499 <glossentry id='var-PACKAGECONFIG_CONFARGS'><glossterm>PACKAGECONFIG_CONFARGS</glossterm>
10500 <info>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010501 PACKAGECONFIG_CONFARGS[doc] = "A space-separated list of configuration options generated from the PACKAGECONFIG setting."
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010502 </info>
10503 <glossdef>
10504 <para role="glossdeffirst">
10505<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10506 A space-separated list of configuration options generated
10507 from the
10508 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
10509 setting.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010510 </para>
10511
10512 <para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010513 Classes such as
10514 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
10515 and
10516 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
10517 use <filename>PACKAGECONFIG_CONFARGS</filename> to pass
Brad Bishop316dfdd2018-06-25 12:45:53 -040010518 <filename>PACKAGECONFIG</filename> options to
10519 <filename>configure</filename> and
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010520 <filename>cmake</filename>, respectively.
10521 If you are using
10522 <filename>PACKAGECONFIG</filename> but not a class that
10523 handles the <filename>do_configure</filename> task, then
10524 you need to use
10525 <filename>PACKAGECONFIG_CONFARGS</filename> appropriately.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010526 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010527 </glossdef>
10528 </glossentry>
10529
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010530 <glossentry id='var-PACKAGEGROUP_DISABLE_COMPLEMENTARY'><glossterm>PACKAGEGROUP_DISABLE_COMPLEMENTARY</glossterm>
10531 <info>
10532 PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents automatic creation of the normal complementary packages such as -dev and -dbg in a packagegroup recipe."
10533 </info>
10534 <glossdef>
10535 <para role="glossdeffirst">
10536<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10537 For recipes inheriting the
10538 <link linkend='ref-classes-packagegroup'><filename>packagegroup</filename></link>
10539 class, setting
10540 <filename>PACKAGEGROUP_DISABLE_COMPLEMENTARY</filename> to
10541 "1" specifies that the normal complementary packages
10542 (i.e. <filename>-dev</filename>,
10543 <filename>-dbg</filename>, and so forth) should not be
10544 automatically created by the
10545 <filename>packagegroup</filename> recipe, which is the
10546 default behavior.
10547 </para>
10548 </glossdef>
10549 </glossentry>
10550
10551 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
10552 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040010553 PACKAGES[doc] = "The list of packages the recipe creates."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010554 </info>
10555 <glossdef>
10556 <para role="glossdeffirst">
10557<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040010558 The list of packages the recipe creates.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010559 The default value is the following:
10560 <literallayout class='monospaced'>
10561 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
10562 </literallayout>
10563 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010564
10565 <para>
10566 During packaging, the
10567 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
10568 task goes through <filename>PACKAGES</filename> and uses
10569 the
10570 <link linkend='var-FILES'><filename>FILES</filename></link>
10571 variable corresponding to each package to assign files to
10572 the package.
10573 If a file matches the <filename>FILES</filename> variable
10574 for more than one package in <filename>PACKAGES</filename>,
10575 it will be assigned to the earliest (leftmost) package.
10576 </para>
10577
10578 <para>
10579 Packages in the variable's list that are empty (i.e. where
10580 none of the patterns in
10581 <filename>FILES_</filename><replaceable>pkg</replaceable>
10582 match any files installed by the
10583 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
10584 task) are not generated, unless generation is forced through
10585 the
10586 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>
10587 variable.
10588 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010589 </glossdef>
10590 </glossentry>
10591
10592 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
10593 <info>
10594 PACKAGES_DYNAMIC[doc] = "A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes."
10595 </info>
10596 <glossdef>
10597 <para role="glossdeffirst">
10598<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10599 A promise that your recipe satisfies runtime dependencies
10600 for optional modules that are found in other recipes.
10601 <filename>PACKAGES_DYNAMIC</filename>
10602 does not actually satisfy the dependencies, it only states that
10603 they should be satisfied.
10604 For example, if a hard, runtime dependency
10605 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
10606 of another package is satisfied
10607 at build time through the <filename>PACKAGES_DYNAMIC</filename>
10608 variable, but a package with the module name is never actually
10609 produced, then the other package will be broken.
10610 Thus, if you attempt to include that package in an image,
10611 you will get a dependency failure from the packaging system
10612 during the
10613 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
10614 task.
10615 </para>
10616
10617 <para>
10618 Typically, if there is a chance that such a situation can
10619 occur and the package that is not created is valid
10620 without the dependency being satisfied, then you should use
10621 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
10622 (a soft runtime dependency) instead of
10623 <filename>RDEPENDS</filename>.
10624 </para>
10625
10626 <para>
10627 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
10628 variable when you are splitting packages, see the
10629 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010630 in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010631 </para>
10632 </glossdef>
10633 </glossentry>
10634
10635 <glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm>
10636 <info>
10637 PACKAGESPLITFUNCS[doc] = "Specifies a list of functions run to perform additional splitting of files into individual packages."
10638 </info>
10639 <glossdef>
10640 <para role="glossdeffirst">
10641<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10642 Specifies a list of functions run to perform additional
10643 splitting of files into individual packages.
10644 Recipes can either prepend to this variable or prepend
10645 to the <filename>populate_packages</filename> function
10646 in order to perform additional package splitting.
10647 In either case, the function should set
10648 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>,
10649 <link linkend='var-FILES'><filename>FILES</filename></link>,
10650 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
10651 and other packaging variables appropriately in order to
10652 perform the desired splitting.
10653 </para>
10654 </glossdef>
10655 </glossentry>
10656
10657 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
10658 <info>
10659 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."
10660 </info>
10661 <glossdef>
10662 <para role="glossdeffirst">
10663<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10664 Extra options passed to the <filename>make</filename>
10665 command during the
10666 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
10667 task in order to specify parallel compilation on the local
10668 build host.
10669 This variable is usually in the form "-j <replaceable>x</replaceable>",
10670 where <replaceable>x</replaceable> represents the maximum
10671 number of parallel threads <filename>make</filename> can
10672 run.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010673 <note><title>Caution</title>
10674 In order for <filename>PARALLEL_MAKE</filename> to be
10675 effective, <filename>make</filename> must be called
10676 with
10677 <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.
10678 An easy way to ensure this is to use the
10679 <filename>oe_runmake</filename> function.
10680 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010681 </para>
10682
10683 <para>
10684 By default, the OpenEmbedded build system automatically
10685 sets this variable to be equal to the number of cores the
10686 build system uses.
10687 <note>
10688 If the software being built experiences dependency
10689 issues during the <filename>do_compile</filename>
10690 task that result in race conditions, you can clear
10691 the <filename>PARALLEL_MAKE</filename> variable within
10692 the recipe as a workaround.
10693 For information on addressing race conditions, see the
10694 "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010695 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010696 </note>
10697 For single socket systems (i.e. one CPU), you should not
10698 have to override this variable to gain optimal parallelism
10699 during builds.
10700 However, if you have very large systems that employ
10701 multiple physical CPUs, you might want to make sure the
10702 <filename>PARALLEL_MAKE</filename> variable is not
10703 set higher than "-j 20".
10704 </para>
10705
10706 <para>
10707 For more information on speeding up builds, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040010708 "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"
10709 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010710 </para>
10711 </glossdef>
10712 </glossentry>
10713
10714 <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
10715 <info>
10716 PARALLEL_MAKEINST[doc] = "Extra options passed to the make install command during the do_install task in order to specify parallel installation."
10717 </info>
10718 <glossdef>
10719 <para role="glossdeffirst">
10720<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10721 Extra options passed to the
10722 <filename>make install</filename> command during the
10723 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
10724 task in order to specify parallel installation.
10725 This variable defaults to the value of
10726 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010727 <note><title>Notes and Cautions</title>
10728 <para>In order for <filename>PARALLEL_MAKEINST</filename>
10729 to be
10730 effective, <filename>make</filename> must be called
10731 with
10732 <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.
10733 An easy way to ensure this is to use the
10734 <filename>oe_runmake</filename> function.</para>
10735
10736 <para>If the software being built experiences
10737 dependency issues during the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010738 <filename>do_install</filename> task that result in
10739 race conditions, you can clear the
10740 <filename>PARALLEL_MAKEINST</filename> variable within
10741 the recipe as a workaround.
10742 For information on addressing race conditions, see the
10743 "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010744 section in the Yocto Project Development Tasks Manual.
10745 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010746 </note>
10747 </para>
10748 </glossdef>
10749 </glossentry>
10750
10751 <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
10752 <info>
10753 PATCHRESOLVE[doc] = "Enable or disable interactive patch resolution."
10754 </info>
10755 <glossdef>
10756 <para role="glossdeffirst">
10757<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10758 Determines the action to take when a patch fails.
10759 You can set this variable to one of two values: "noop" and
10760 "user".
10761 </para>
10762
10763 <para>
10764 The default value of "noop" causes the build to simply fail
10765 when the OpenEmbedded build system cannot successfully
10766 apply a patch.
10767 Setting the value to "user" causes the build system to
10768 launch a shell and places you in the right location so that
10769 you can manually resolve the conflicts.
10770 </para>
10771
10772 <para>
10773 Set this variable in your
10774 <filename>local.conf</filename> file.
10775 </para>
10776 </glossdef>
10777 </glossentry>
10778
10779 <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
10780 <info>
10781 PATCHTOOL[doc] = "Specifies the utility used to apply patches for a recipe during do_patch."
10782 </info>
10783 <glossdef>
10784 <para role="glossdeffirst">
10785<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10786 Specifies the utility used to apply patches for a recipe
10787 during the
10788 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
10789 task.
10790 You can specify one of three utilities: "patch", "quilt", or
10791 "git".
10792 The default utility used is "quilt" except for the
10793 quilt-native recipe itself.
10794 Because the quilt tool is not available at the
10795 time quilt-native is being patched, it uses "patch".
10796 </para>
10797
10798 <para>
10799 If you wish to use an alternative patching tool, set the
10800 variable in the recipe using one of the following:
10801 <literallayout class='monospaced'>
10802 PATCHTOOL = "patch"
10803 PATCHTOOL = "quilt"
10804 PATCHTOOL = "git"
10805 </literallayout>
10806 </para>
10807 </glossdef>
10808 </glossentry>
10809
10810 <glossentry id='var-PE'><glossterm>PE</glossterm>
10811 <info>
10812 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."
10813 </info>
10814 <glossdef>
10815 <para role="glossdeffirst">
10816<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10817 The epoch of the recipe.
10818 By default, this variable is unset.
10819 The variable is used to make upgrades possible when the
10820 versioning scheme changes in some backwards incompatible
10821 way.
10822 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010823
10824 <para>
10825 <filename>PE</filename> is the default value of the
10826 <link linkend='var-PKGE'><filename>PKGE</filename></link>
10827 variable.
10828 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010829 </glossdef>
10830 </glossentry>
10831
10832 <glossentry id='var-PF'><glossterm>PF</glossterm>
10833 <info>
10834 PF[doc] = "Specifies the recipe or package name and includes all version and revision numbers. This variable is comprised of ${PN}-${EXTENDPE}${PV}-${PR}."
10835 </info>
10836 <glossdef>
10837 <para role="glossdeffirst">
10838<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10839 Specifies the recipe or package name and includes all version and revision
10840 numbers (i.e. <filename>glibc-2.13-r20+svnr15508/</filename> and
10841 <filename>bash-4.2-r1/</filename>).
10842 This variable is comprised of the following:
10843 <literallayout class='monospaced'>
10844 ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
10845 </literallayout>
10846 </para>
10847 </glossdef>
10848 </glossentry>
10849
10850 <glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm>
10851 <info>
10852 PIXBUF_PACKAGES[doc] = "When a recipe inherits the pixbufcache class, this variable identifies packages that contain the pixbuf loaders used with gdk-pixbuf."
10853 </info>
10854 <glossdef>
10855 <para role="glossdeffirst">
10856<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10857 When inheriting the
10858 <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link>
10859 class, this variable identifies packages that contain
10860 the pixbuf loaders used with
10861 <filename>gdk-pixbuf</filename>.
10862 By default, the <filename>pixbufcache</filename> class
10863 assumes that the loaders are in the recipe's main package
10864 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
10865 Use this variable if the loaders you need are in a package
10866 other than that main package.
10867 </para>
10868 </glossdef>
10869 </glossentry>
10870
10871 <glossentry id='var-PKG'><glossterm>PKG</glossterm>
10872 <info>
10873 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."
10874 </info>
10875 <glossdef>
10876 <para role="glossdeffirst">
10877<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10878 The name of the resulting package created by the
10879 OpenEmbedded build system.
10880 <note>
10881 When using the <filename>PKG</filename> variable, you
10882 must use a package name override.
10883 </note>
10884 </para>
10885
10886 <para>
10887 For example, when the
10888 <link linkend='ref-classes-debian'><filename>debian</filename></link>
10889 class renames the output package, it does so by setting
10890 <filename>PKG_<replaceable>packagename</replaceable></filename>.
10891 </para>
10892 </glossdef>
10893 </glossentry>
10894
10895 <glossentry id='var-PKG_CONFIG_PATH'><glossterm>PKG_CONFIG_PATH</glossterm>
10896 <info>
10897 PKG_CONFIG_PATH[doc] = "Path to pkg-config files for the current build context."
10898 </info>
10899 <glossdef>
10900 <para role="glossdeffirst">
10901<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10902 The path to <filename>pkg-config</filename> files for the
10903 current build context.
10904 <filename>pkg-config</filename> reads this variable
10905 from the environment.
10906 </para>
10907 </glossdef>
10908 </glossentry>
10909
10910 <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
10911 <info>
10912 PKGD[doc] = "Points to the destination directory for files to be packaged before they are split into individual packages."
10913 </info>
10914 <glossdef>
10915 <para role="glossdeffirst">
10916<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10917 Points to the destination directory for files to be
10918 packaged before they are split into individual packages.
10919 This directory defaults to the following:
10920 <literallayout class='monospaced'>
10921 ${WORKDIR}/package
10922 </literallayout>
10923 </para>
10924
10925 <para>
10926 Do not change this default.
10927 </para>
10928 </glossdef>
10929 </glossentry>
10930
10931 <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
10932 <info>
10933 PKGDATA_DIR[doc] = "Points to a shared, global-state directory that holds data generated during the packaging process."
10934 </info>
10935 <glossdef>
10936 <para role="glossdeffirst">
10937<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10938 Points to a shared, global-state directory that holds data
10939 generated during the packaging process.
10940 During the packaging process, the
10941 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
10942 task packages data for each recipe and installs it into
10943 this temporary, shared area.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010944 This directory defaults to the following, which you should
10945 not change:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010946 <literallayout class='monospaced'>
10947 ${STAGING_DIR_HOST}/pkgdata
10948 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010949 For examples of how this data is used, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040010950 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
10951 section in the Yocto Project Overview and Concepts Manual
10952 and the
10953 "<ulink url='&YOCTO_DOCS_DEV_URL;#viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></ulink>"
10954 section in the Yocto Project Development Tasks Manual.
10955 For more information on the shared, global-state directory,
10956 see
10957 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010958 </para>
10959 </glossdef>
10960 </glossentry>
10961
10962 <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
10963 <info>
10964 PKGDEST[doc] = "Points to the parent directory for files to be packaged after they have been split into individual packages."
10965 </info>
10966 <glossdef>
10967 <para role="glossdeffirst">
10968<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10969 Points to the parent directory for files to be packaged
10970 after they have been split into individual packages.
10971 This directory defaults to the following:
10972 <literallayout class='monospaced'>
10973 ${WORKDIR}/packages-split
10974 </literallayout>
10975 </para>
10976
10977 <para>
10978 Under this directory, the build system creates
10979 directories for each package specified in
10980 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
10981 Do not change this default.
10982 </para>
10983 </glossdef>
10984 </glossentry>
10985
10986 <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
10987 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010988 PKGDESTWORK[doc] = "Points to a temporary work area where the do_package task saves package metadata."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010989 </info>
10990 <glossdef>
10991 <para role="glossdeffirst">
10992<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010993 Points to a temporary work area where the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010994 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010995 task saves package metadata.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010996 The <filename>PKGDESTWORK</filename> location defaults to
10997 the following:
10998 <literallayout class='monospaced'>
10999 ${WORKDIR}/pkgdata
11000 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011001 Do not change this default.
11002 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011003
11004 <para>
11005 The
11006 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
11007 task copies the package metadata from
11008 <filename>PKGDESTWORK</filename> to
11009 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
11010 to make it available globally.
11011 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011012 </glossdef>
11013 </glossentry>
11014
11015 <glossentry id='var-PKGE'><glossterm>PKGE</glossterm>
11016 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011017 PKGE[doc] = "The epoch of the package(s) built by the recipe."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011018 </info>
11019 <glossdef>
11020 <para role="glossdeffirst">
11021<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011022 The epoch of the package(s) built by the recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011023 By default, <filename>PKGE</filename> is set to
11024 <link linkend='var-PE'><filename>PE</filename></link>.
11025 </para>
11026 </glossdef>
11027 </glossentry>
11028
11029 <glossentry id='var-PKGR'><glossterm>PKGR</glossterm>
11030 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011031 PKGR[doc] = "The revision of the package(s) built by the recipe."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011032 </info>
11033 <glossdef>
11034 <para role="glossdeffirst">
11035<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011036 The revision of the package(s) built by the recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011037 By default, <filename>PKGR</filename> is set to
11038 <link linkend='var-PR'><filename>PR</filename></link>.
11039 </para>
11040 </glossdef>
11041 </glossentry>
11042
11043 <glossentry id='var-PKGV'><glossterm>PKGV</glossterm>
11044 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011045 PKGV[doc] = "The version of the package(s) built by the recipe."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011046 </info>
11047 <glossdef>
11048 <para role="glossdeffirst">
11049<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011050 The version of the package(s) built by the
11051 recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011052 By default, <filename>PKGV</filename> is set to
11053 <link linkend='var-PV'><filename>PV</filename></link>.
11054 </para>
11055 </glossdef>
11056 </glossentry>
11057
11058 <glossentry id='var-PN'><glossterm>PN</glossterm>
11059 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011060 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 -050011061 </info>
11062 <glossdef>
11063 <para role="glossdeffirst">
11064<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11065 This variable can have two separate functions depending on the context: a recipe
11066 name or a resulting package name.
11067 </para>
11068
11069 <para>
11070 <filename>PN</filename> refers to a recipe name in the context of a file used
11071 by the OpenEmbedded build system as input to create a package.
11072 The name is normally extracted from the recipe file name.
11073 For example, if the recipe is named
11074 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
11075 will be "expat".
11076 </para>
11077
11078 <para>
11079 The variable refers to a package name in the context of a file created or produced by the
11080 OpenEmbedded build system.
11081 </para>
11082
11083 <para>
11084 If applicable, the <filename>PN</filename> variable also contains any special
11085 suffix or prefix.
11086 For example, using <filename>bash</filename> to build packages for the native
11087 machine, <filename>PN</filename> is <filename>bash-native</filename>.
11088 Using <filename>bash</filename> to build packages for the target and for Multilib,
11089 <filename>PN</filename> would be <filename>bash</filename> and
11090 <filename>lib64-bash</filename>, respectively.
11091 </para>
11092 </glossdef>
11093 </glossentry>
11094
11095 <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>
11096 <info>
11097 PNBLACKLIST[doc] = "Lists recipes you do not want the OpenEmbedded build system to build."
11098 </info>
11099 <glossdef>
11100 <para role="glossdeffirst">
11101<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11102 Lists recipes you do not want the OpenEmbedded build system
11103 to build.
11104 This variable works in conjunction with the
11105 <link linkend='ref-classes-blacklist'><filename>blacklist</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011106 class, which is inherited globally.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011107 </para>
11108
11109 <para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011110 To prevent a recipe from being built, use the
11111 <filename>PNBLACKLIST</filename> variable in your
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011112 <filename>local.conf</filename> file.
11113 Here is an example that prevents
11114 <filename>myrecipe</filename> from being built:
11115 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011116 PNBLACKLIST[myrecipe] = "Not supported by our organization."
11117 </literallayout>
11118 </para>
11119 </glossdef>
11120 </glossentry>
11121
11122 <glossentry id='var-POPULATE_SDK_POST_HOST_COMMAND'><glossterm>POPULATE_SDK_POST_HOST_COMMAND</glossterm>
11123 <info>
11124 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."
11125 </info>
11126 <glossdef>
11127 <para role="glossdeffirst">
11128<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11129 Specifies a list of functions to call once the
11130 OpenEmbedded build system has created the host part of
11131 the SDK.
11132 You can specify functions separated by semicolons:
11133 <literallayout class='monospaced'>
11134 POPULATE_SDK_POST_HOST_COMMAND += "<replaceable>function</replaceable>; ... "
11135 </literallayout>
11136 </para>
11137
11138 <para>
11139 If you need to pass the SDK path to a command
11140 within a function, you can use
11141 <filename>${SDK_DIR}</filename>, which points to
11142 the parent directory used by the OpenEmbedded build
11143 system when creating SDK output.
11144 See the
11145 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
11146 variable for more information.
11147 </para>
11148 </glossdef>
11149 </glossentry>
11150
11151 <glossentry id='var-POPULATE_SDK_POST_TARGET_COMMAND'><glossterm>POPULATE_SDK_POST_TARGET_COMMAND</glossterm>
11152 <info>
11153 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."
11154 </info>
11155 <glossdef>
11156 <para role="glossdeffirst">
11157<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11158 Specifies a list of functions to call once the
11159 OpenEmbedded build system has created the target part of
11160 the SDK.
11161 You can specify functions separated by semicolons:
11162 <literallayout class='monospaced'>
11163 POPULATE_SDK_POST_TARGET_COMMAND += "<replaceable>function</replaceable>; ... "
11164 </literallayout>
11165 </para>
11166
11167 <para>
11168 If you need to pass the SDK path to a command
11169 within a function, you can use
11170 <filename>${SDK_DIR}</filename>, which points to
11171 the parent directory used by the OpenEmbedded build
11172 system when creating SDK output.
11173 See the
11174 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
11175 variable for more information.
11176 </para>
11177 </glossdef>
11178 </glossentry>
11179
11180 <glossentry id='var-PR'><glossterm>PR</glossterm>
11181 <info>
11182 PR[doc] = "The revision of the recipe. The default value for this variable is 'r0'."
11183 </info>
11184 <glossdef>
11185 <para role="glossdeffirst">
11186<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011187 The revision of the recipe. The default value for this
11188 variable is "r0".
11189 Subsequent revisions of the recipe conventionally have the
11190 values "r1", "r2", and so forth.
11191 When
11192 <link linkend='var-PV'><filename>PV</filename></link>
11193 increases, <filename>PR</filename> is conventionally reset
11194 to "r0".
11195 <note>
11196 The OpenEmbedded build system does not need the aid of
11197 <filename>PR</filename> to know when to rebuild a
11198 recipe.
11199 The build system uses the task
Brad Bishop316dfdd2018-06-25 12:45:53 -040011200 <ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>input checksums</ulink>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011201 along with the
11202 <link linkend='structure-build-tmp-stamps'>stamp</link>
11203 and
Brad Bishop316dfdd2018-06-25 12:45:53 -040011204 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state cache</ulink>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011205 mechanisms.
11206 </note>
11207 The <filename>PR</filename> variable primarily becomes
11208 significant when a package manager dynamically installs
11209 packages on an already built image.
11210 In this case, <filename>PR</filename>, which is the default
11211 value of
11212 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
11213 helps the package manager distinguish which package is the
11214 most recent one in cases where many packages have the same
11215 <filename>PV</filename> (i.e. <filename>PKGV</filename>).
11216 A component having many packages with the same
11217 <filename>PV</filename> usually means that the packages all
11218 install the same upstream version, but with later
11219 (<filename>PR</filename>) version packages including
11220 packaging fixes.
11221 <note>
11222 <filename>PR</filename> does not need to be increased
11223 for changes that do not change the package contents or
11224 metadata.
11225 </note>
11226 Because manually managing <filename>PR</filename> can be
11227 cumbersome and error-prone, an automated solution exists.
11228 See the
11229 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011230 section in the Yocto Project Development Tasks Manual
11231 for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011232 </para>
11233 </glossdef>
11234 </glossentry>
11235
11236 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
11237 <info>
11238 PREFERRED_PROVIDER[doc] = "If multiple recipes provide an item, this variable determines which recipe should be given preference."
11239 </info>
11240 <glossdef>
11241 <para role="glossdeffirst">
11242<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040011243 If multiple recipes provide the same item, this variable
11244 determines which recipe is preferred and thus provides
11245 the item (i.e. the preferred provider).
11246 You should always suffix this variable with the name of the
11247 provided item.
11248 And, you should define the variable using the preferred
11249 recipe's name
11250 (<link linkend='var-PN'><filename>PN</filename></link>).
11251 Here is a common example:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011252 <literallayout class='monospaced'>
11253 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
Brad Bishop316dfdd2018-06-25 12:45:53 -040011254 </literallayout>
11255 In the previous example, multiple recipes are providing
11256 "virtual/kernel".
11257 The <filename>PREFERRED_PROVIDER</filename> variable is
11258 set with the name (<filename>PN</filename>) of the recipe
11259 you prefer to provide "virtual/kernel".
11260 </para>
11261
11262 <para>
11263 Following are more examples:
11264 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011265 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
11266 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
11267 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011268 For more information, see the
11269 "<ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>Using Virtual Providers</ulink>"
11270 section in the Yocto Project Development Tasks Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011271 <note>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011272 If you use a <filename>virtual/*</filename> item
11273 with <filename>PREFERRED_PROVIDER</filename>, then any
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011274 recipe that
11275 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011276 that item but is not selected (defined) by
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011277 <filename>PREFERRED_PROVIDER</filename> is prevented
11278 from building, which is usually desirable since this
11279 mechanism is designed to select between mutually
11280 exclusive alternative providers.
11281 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011282 </para>
11283 </glossdef>
11284 </glossentry>
11285
11286 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
11287 <info>
11288 PREFERRED_VERSION[doc] = "If there are multiple versions of recipes available, this variable determines which recipe should be given preference."
11289 </info>
11290 <glossdef>
11291 <para role="glossdeffirst">
11292<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011293 If multiple versions of recipes exist, this
11294 variable determines which version is given preference.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011295 You must always suffix the variable with the
11296 <link linkend='var-PN'><filename>PN</filename></link>
11297 you want to select, and you should set the
11298 <link linkend='var-PV'><filename>PV</filename></link>
11299 accordingly for precedence.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011300 </para>
11301
11302 <para>
11303 The <filename>PREFERRED_VERSION</filename> variable
11304 supports limited wildcard use through the
11305 "<filename>%</filename>" character.
11306 You can use the character to match any number of
11307 characters, which can be useful when specifying versions
11308 that contain long revision numbers that potentially change.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011309 Here are two examples:
11310 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011311 PREFERRED_VERSION_python = "3.4.0"
Brad Bishopc342db32019-05-15 21:57:59 -040011312 PREFERRED_VERSION_linux-yocto = "5.0%"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011313 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011314 <note><title>Important</title>
11315 The use of the "<filename>%</filename>" character
11316 is limited in that it only works at the end of the
11317 string.
11318 You cannot use the wildcard character in any other
11319 location of the string.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011320 </note>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011321 </para>
11322
11323 <para>
11324 The specified version is matched against
11325 <link linkend='var-PV'><filename>PV</filename></link>,
11326 which does not necessarily match the version part of
11327 the recipe's filename.
11328 For example, consider two recipes
11329 <filename>foo_1.2.bb</filename> and
11330 <filename>foo_git.bb</filename> where
11331 <filename>foo_git.bb</filename> contains the following
11332 assignment:
11333 <literallayout class='monospaced'>
11334 PV = "1.1+git${SRCPV}"
11335 </literallayout>
11336 In this case, the correct way to select
11337 <filename>foo_git.bb</filename> is by using an
11338 assignment such as the following:
11339 <literallayout class='monospaced'>
11340 PREFERRED_VERSION_foo = "1.1+git%"
11341 </literallayout>
11342 Compare that previous example against the following
11343 incorrect example, which does not work:
11344 <literallayout class='monospaced'>
11345 PREFERRED_VERSION_foo = "git"
11346 </literallayout>
11347 </para>
11348
11349 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011350 Sometimes the <filename>PREFERRED_VERSION</filename>
11351 variable can be set by configuration files in a way that
11352 is hard to change.
11353 You can use
11354 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
11355 to set a machine-specific override.
11356 Here is an example:
11357 <literallayout class='monospaced'>
Brad Bishopc342db32019-05-15 21:57:59 -040011358 PREFERRED_VERSION_linux-yocto_qemux86 = "5.0%"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011359 </literallayout>
11360 Although not recommended, worst case, you can also use the
11361 "forcevariable" override, which is the strongest override
11362 possible.
11363 Here is an example:
11364 <literallayout class='monospaced'>
Brad Bishopc342db32019-05-15 21:57:59 -040011365 PREFERRED_VERSION_linux-yocto_forcevariable = "5.0%"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011366 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011367 <note>
11368 The <filename>_forcevariable</filename> override is
11369 not handled specially.
11370 This override only works because the default value of
Brad Bishop316dfdd2018-06-25 12:45:53 -040011371 <filename>OVERRIDES</filename> includes
11372 "forcevariable".
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011373 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011374 </para>
11375 </glossdef>
11376 </glossentry>
11377
11378 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
11379 <info>
11380 PREMIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."
11381 </info>
11382 <glossdef>
11383 <para role="glossdeffirst">
11384<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11385 Specifies additional paths from which the OpenEmbedded
11386 build system gets source code.
11387 When the build system searches for source code, it first
11388 tries the local download directory.
11389 If that location fails, the build system tries locations
11390 defined by <filename>PREMIRRORS</filename>, the upstream
11391 source, and then locations specified by
11392 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
11393 in that order.
11394 </para>
11395
11396 <para>
11397 Assuming your distribution
11398 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
11399 is "poky", the default value for
11400 <filename>PREMIRRORS</filename> is defined in the
11401 <filename>conf/distro/poky.conf</filename> file in the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011402 <filename>meta-poky</filename> Git repository.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011403 </para>
11404
11405 <para>
11406 Typically, you could add a specific server for the
11407 build system to attempt before any others by adding
11408 something like the following to the
11409 <filename>local.conf</filename> configuration file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011410 <link linkend='build-directory'>Build Directory</link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011411 <literallayout class='monospaced'>
11412 PREMIRRORS_prepend = "\
11413 git://.*/.* http://www.yoctoproject.org/sources/ \n \
11414 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
11415 http://.*/.* http://www.yoctoproject.org/sources/ \n \
11416 https://.*/.* http://www.yoctoproject.org/sources/ \n"
11417 </literallayout>
11418 These changes cause the build system to intercept
11419 Git, FTP, HTTP, and HTTPS requests and direct them to
11420 the <filename>http://</filename> sources mirror.
11421 You can use <filename>file://</filename> URLs to point
11422 to local directories or network shares as well.
11423 </para>
11424 </glossdef>
11425 </glossentry>
11426
11427 <glossentry id='var-PRIORITY'><glossterm>PRIORITY</glossterm>
11428 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011429 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 -050011430 </info>
11431 <glossdef>
11432 <para role="glossdeffirst">
11433<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11434 Indicates the importance of a package.
11435 </para>
11436
11437 <para>
11438 <filename>PRIORITY</filename> is considered to be part of
11439 the distribution policy because the importance of any given
11440 recipe depends on the purpose for which the distribution
11441 is being produced.
11442 Thus, <filename>PRIORITY</filename> is not normally set
11443 within recipes.
11444 </para>
11445
11446 <para>
11447 You can set <filename>PRIORITY</filename> to "required",
11448 "standard", "extra", and "optional", which is the default.
11449 </para>
11450 </glossdef>
11451 </glossentry>
11452
11453 <glossentry id='var-PRIVATE_LIBS'><glossterm>PRIVATE_LIBS</glossterm>
11454 <info>
11455 PRIVATE_LIBS[doc] = "Specifies libraries installed within a recipe that should be ignored by the OpenEmbedded build system's shared library resolver."
11456 </info>
11457 <glossdef>
11458 <para role="glossdeffirst">
11459<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11460 Specifies libraries installed within a recipe that
11461 should be ignored by the OpenEmbedded build system's
11462 shared library resolver.
11463 This variable is typically used when software being
11464 built by a recipe has its own private versions of a
11465 library normally provided by another recipe.
11466 In this case, you would not want the package containing
11467 the private libraries to be set as a dependency on other
11468 unrelated packages that should instead depend on the
11469 package providing the standard version of the library.
11470 </para>
11471
11472 <para>
11473 Libraries specified in this variable should be specified
11474 by their file name.
11475 For example, from the Firefox recipe in meta-browser:
11476 <literallayout class='monospaced'>
11477 PRIVATE_LIBS = "libmozjs.so \
11478 libxpcom.so \
11479 libnspr4.so \
11480 libxul.so \
11481 libmozalloc.so \
11482 libplc4.so \
11483 libplds4.so"
11484 </literallayout>
11485 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011486
11487 <para>
11488 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040011489 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
11490 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011491 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011492 </glossdef>
11493 </glossentry>
11494
11495 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
11496 <info>
11497 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."
11498 </info>
11499 <glossdef>
11500 <para role="glossdeffirst">
11501<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11502 A list of aliases by which a particular recipe can be
11503 known.
11504 By default, a recipe's own
11505 <filename><link linkend='var-PN'>PN</link></filename>
11506 is implicitly already in its <filename>PROVIDES</filename>
11507 list.
11508 If a recipe uses <filename>PROVIDES</filename>, the
11509 additional aliases are synonyms for the recipe and can
11510 be useful satisfying dependencies of other recipes during
11511 the build as specified by
11512 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
11513 </para>
11514
11515 <para>
11516 Consider the following example
11517 <filename>PROVIDES</filename> statement from a recipe
11518 file <filename>libav_0.8.11.bb</filename>:
11519 <literallayout class='monospaced'>
11520 PROVIDES += "libpostproc"
11521 </literallayout>
11522 The <filename>PROVIDES</filename> statement results in
11523 the "libav" recipe also being known as "libpostproc".
11524 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011525
11526 <para>
11527 In addition to providing recipes under alternate names,
11528 the <filename>PROVIDES</filename> mechanism is also used
11529 to implement virtual targets.
11530 A virtual target is a name that corresponds to some
11531 particular functionality (e.g. a Linux kernel).
11532 Recipes that provide the functionality in question list the
11533 virtual target in <filename>PROVIDES</filename>.
11534 Recipes that depend on the functionality in question can
Brad Bishop316dfdd2018-06-25 12:45:53 -040011535 include the virtual target in <filename>DEPENDS</filename>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011536 to leave the choice of provider open.
11537 </para>
11538
11539 <para>
11540 Conventionally, virtual targets have names on the form
11541 "virtual/function" (e.g. "virtual/kernel").
11542 The slash is simply part of the name and has no
11543 syntactical significance.
11544 </para>
11545
11546 <para>
11547 The
11548 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
11549 variable is used to select which particular recipe
11550 provides a virtual target.
11551 <note>
11552 <para>A corresponding mechanism for virtual runtime
11553 dependencies (packages) exists.
11554 However, the mechanism does not depend on any special
11555 functionality beyond ordinary variable assignments.
11556 For example,
11557 <filename>VIRTUAL-RUNTIME_dev_manager</filename>
11558 refers to the package of the component that manages
11559 the <filename>/dev</filename> directory.</para>
11560
11561 <para>Setting the "preferred provider" for runtime
11562 dependencies is as simple as using the following
11563 assignment in a configuration file:</para>
11564 <literallayout class='monospaced'>
11565 VIRTUAL-RUNTIME_dev_manager = "udev"
11566 </literallayout>
11567 </note>
11568 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011569 </glossdef>
11570 </glossentry>
11571
11572 <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
11573 <info>
11574 PRSERV_HOST[doc] = "The network based PR service host and port."
11575 </info>
11576 <glossdef>
11577 <para role="glossdeffirst">
11578<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11579 The network based
11580 <link linkend='var-PR'><filename>PR</filename></link>
11581 service host and port.
11582 </para>
11583
11584 <para>
11585 The <filename>conf/local.conf.sample.extended</filename>
11586 configuration file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011587 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011588 shows how the <filename>PRSERV_HOST</filename> variable is
11589 set:
11590 <literallayout class='monospaced'>
11591 PRSERV_HOST = "localhost:0"
11592 </literallayout>
11593 You must set the variable if you want to automatically
11594 start a local
11595 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.
11596 You can set <filename>PRSERV_HOST</filename> to other
11597 values to use a remote PR service.
11598 </para>
11599 </glossdef>
11600 </glossentry>
11601
11602 <glossentry id='var-PTEST_ENABLED'><glossterm>PTEST_ENABLED</glossterm>
11603 <info>
11604 PRSERV_HOST[doc] = "Specifies whether or not Package Test (ptest) functionality is enabled when building a recipe."
11605 </info>
11606 <glossdef>
11607 <para role="glossdeffirst">
11608<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11609 Specifies whether or not
11610 <ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Package Test</ulink>
11611 (ptest) functionality is enabled when building a recipe.
11612 You should not set this variable directly.
11613 Enabling and disabling building Package Tests
11614 at build time should be done by adding "ptest" to (or
11615 removing it from)
11616 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
11617 </para>
11618 </glossdef>
11619 </glossentry>
11620
11621 <glossentry id='var-PV'><glossterm>PV</glossterm>
11622 <info>
11623 PV[doc] = "The version of the recipe. The version is normally extracted from the recipe filename."
11624 </info>
11625 <glossdef>
11626 <para role="glossdeffirst">
11627<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11628 The version of the recipe.
11629 The version is normally extracted from the recipe filename.
11630 For example, if the recipe is named
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011631 <filename>expat_2.0.1.bb</filename>, then the default value
11632 of <filename>PV</filename> will be "2.0.1".
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011633 <filename>PV</filename> is generally not overridden within
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011634 a recipe unless it is building an unstable (i.e.
11635 development) version from a source code repository
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011636 (e.g. Git or Subversion).
11637 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011638
11639 <para>
11640 <filename>PV</filename> is the default value of the
11641 <link linkend='var-PKGV'><filename>PKGV</filename></link>
11642 variable.
11643 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011644 </glossdef>
11645 </glossentry>
11646
11647 <glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>
11648 <info>
11649 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."
11650 </info>
11651 <glossdef>
11652 <para role="glossdeffirst">
11653<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11654 When used by recipes that inherit the
11655 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
11656 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
11657 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
11658 or
11659 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
11660 classes, denotes the Application Binary Interface (ABI)
11661 currently in use for Python.
11662 By default, the ABI is "m".
11663 You do not have to set this variable as the OpenEmbedded
11664 build system sets it for you.
11665 </para>
11666
11667 <para>
11668 The OpenEmbedded build system uses the ABI to construct
11669 directory names used when installing the Python headers
11670 and libraries in sysroot
11671 (e.g. <filename>.../python3.3m/...</filename>).
11672 </para>
11673
11674 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011675 Recipes that inherit the <filename>distutils</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011676 class during cross-builds also use this variable to
11677 locate the headers and libraries of the appropriate Python
11678 that the extension is targeting.
11679 </para>
11680 </glossdef>
11681 </glossentry>
11682
11683 <glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>
11684 <info>
11685 PYTHON_PN[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, specifies the major Python version being built."
11686 </info>
11687 <glossdef>
11688 <para role="glossdeffirst">
11689<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11690 When used by recipes that inherit the
11691 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
11692 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
11693 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
11694 or
11695 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
11696 classes, specifies the major Python version being built.
11697 For Python 2.x, <filename>PYTHON_PN</filename> would
11698 be "python2". For Python 3.x, the variable would be
11699 "python3".
11700 You do not have to set this variable as the
11701 OpenEmbedded build system automatically sets it for you.
11702 </para>
11703
11704 <para>
11705 The variable allows recipes to use common infrastructure
11706 such as the following:
11707 <literallayout class='monospaced'>
11708 DEPENDS += "${PYTHON_PN}-native"
11709 </literallayout>
11710 In the previous example, the version of the dependency
11711 is <filename>PYTHON_PN</filename>.
11712 </para>
11713 </glossdef>
11714 </glossentry>
11715
11716 </glossdiv>
11717
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011718 <glossdiv id='var-glossary-r'><title>R</title>
11719
11720 <glossentry id='var-RANLIB'><glossterm>RANLIB</glossterm>
11721 <info>
11722 RANLIB[doc] = "Minimal command and arguments to run 'ranlib'."
11723 </info>
11724 <glossdef>
11725 <para role="glossdeffirst">
11726<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11727 The minimal command and arguments to run
11728 <filename>ranlib</filename>.
11729 </para>
11730 </glossdef>
11731 </glossentry>
11732
11733 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
11734 <info>
11735 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."
11736 </info>
11737 <glossdef>
11738 <para role="glossdeffirst">
11739<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11740 The list of packages that conflict with packages.
11741 Note that packages will not be installed if conflicting
11742 packages are not first removed.
11743 </para>
11744
11745 <para>
11746 Like all package-controlling variables, you must always use
11747 them in conjunction with a package name override.
11748 Here is an example:
11749 <literallayout class='monospaced'>
11750 RCONFLICTS_${PN} = "<replaceable>another_conflicting_package_name</replaceable>"
11751 </literallayout>
11752 </para>
11753
11754 <para>
11755 BitBake, which the OpenEmbedded build system uses, supports
11756 specifying versioned dependencies.
11757 Although the syntax varies depending on the packaging
11758 format, BitBake hides these differences from you.
11759 Here is the general syntax to specify versions with
11760 the <filename>RCONFLICTS</filename> variable:
11761 <literallayout class='monospaced'>
11762 RCONFLICTS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
11763 </literallayout>
11764 For <filename>operator</filename>, you can specify the
11765 following:
11766 <literallayout class='monospaced'>
11767 =
11768 &lt;
11769 &gt;
11770 &lt;=
11771 &gt;=
11772 </literallayout>
11773 For example, the following sets up a dependency on version
11774 1.2 or greater of the package <filename>foo</filename>:
11775 <literallayout class='monospaced'>
11776 RCONFLICTS_${PN} = "foo (>= 1.2)"
11777 </literallayout>
11778 </para>
11779 </glossdef>
11780 </glossentry>
11781
11782 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
11783 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011784 RDEPENDS[doc] = "Lists runtime dependencies of a package."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011785 </info>
11786 <glossdef>
11787 <para role="glossdeffirst">
11788<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011789 Lists runtime dependencies of a package.
11790 These dependencies are other packages that must be
11791 installed in order for the package to function correctly.
11792 As an example, the following assignment declares that the
11793 package <filename>foo</filename> needs the packages
11794 <filename>bar</filename> and <filename>baz</filename> to
11795 be installed:
11796 <literallayout class='monospaced'>
11797 RDEPENDS_foo = "bar baz"
11798 </literallayout>
11799 The most common types of package runtime dependencies are
11800 automatically detected and added.
11801 Therefore, most recipes do not need to set
11802 <filename>RDEPENDS</filename>.
11803 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040011804 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
11805 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011806 </para>
11807
11808 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011809 The practical effect of the above
11810 <filename>RDEPENDS</filename> assignment is that
11811 <filename>bar</filename> and <filename>baz</filename>
11812 will be declared as dependencies inside the package
11813 <filename>foo</filename> when it is written out by one of
11814 the
11815 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>
11816 tasks.
11817 Exactly how this is done depends on which package format
11818 is used, which is determined by
11819 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>.
11820 When the corresponding package manager installs the
11821 package, it will know to also install the packages on
11822 which it depends.
11823 </para>
11824
11825 <para>
11826 To ensure that the packages <filename>bar</filename> and
11827 <filename>baz</filename> get built, the previous
11828 <filename>RDEPENDS</filename> assignment also causes a task
11829 dependency to be added.
11830 This dependency is from the recipe's
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011831 <link linkend='ref-tasks-build'><filename>do_build</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011832 (not to be confused with
11833 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>)
11834 task to the <filename>do_package_write_*</filename>
11835 task of the recipes that build <filename>bar</filename> and
11836 <filename>baz</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011837 </para>
11838
11839 <para>
11840 The names of the packages you list within
11841 <filename>RDEPENDS</filename> must be the names of other
11842 packages - they cannot be recipe names.
11843 Although package names and recipe names usually match,
11844 the important point here is that you are
11845 providing package names within the
11846 <filename>RDEPENDS</filename> variable.
11847 For an example of the default list of packages created from
11848 a recipe, see the
11849 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
11850 variable.
11851 </para>
11852
11853 <para>
11854 Because the <filename>RDEPENDS</filename> variable applies
11855 to packages being built, you should always use the variable
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011856 in a form with an attached package name (remember that a
11857 single recipe can build multiple packages).
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011858 For example, suppose you are building a development package
11859 that depends on the <filename>perl</filename> package.
11860 In this case, you would use the following
11861 <filename>RDEPENDS</filename> statement:
11862 <literallayout class='monospaced'>
11863 RDEPENDS_${PN}-dev += "perl"
11864 </literallayout>
11865 In the example, the development package depends on
11866 the <filename>perl</filename> package.
11867 Thus, the <filename>RDEPENDS</filename> variable has the
11868 <filename>${PN}-dev</filename> package name as part of the
11869 variable.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011870 <note>
11871 <title>Caution</title>
11872 <filename>RDEPENDS_${PN}-dev</filename> includes
11873 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>
11874 by default.
11875 This default is set in the BitBake configuration file
11876 (<filename>meta/conf/bitbake.conf</filename>).
11877 Be careful not to accidentally remove
11878 <filename>${PN}</filename> when modifying
11879 <filename>RDEPENDS_${PN}-dev</filename>.
11880 Use the "+=" operator rather than the "=" operator.
11881 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011882 </para>
11883
11884 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011885 The package names you use with
11886 <filename>RDEPENDS</filename> must appear as they would in
11887 the <filename>PACKAGES</filename> variable.
11888 The
11889 <link linkend='var-PKG'><filename>PKG</filename></link>
11890 variable allows a different name to be used for
11891 the final package (e.g. the
11892 <link linkend='ref-classes-debian'><filename>debian</filename></link>
11893 class uses this to rename packages), but this final package
11894 name cannot be used with <filename>RDEPENDS</filename>,
11895 which makes sense as <filename>RDEPENDS</filename> is meant
11896 to be independent of the package format used.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011897 </para>
11898
11899 <para>
11900 BitBake, which the OpenEmbedded build system uses, supports
11901 specifying versioned dependencies.
11902 Although the syntax varies depending on the packaging
11903 format, BitBake hides these differences from you.
11904 Here is the general syntax to specify versions with
11905 the <filename>RDEPENDS</filename> variable:
11906 <literallayout class='monospaced'>
11907 RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
11908 </literallayout>
Brad Bishop37a0e4d2017-12-04 01:01:44 -050011909 For <replaceable>operator</replaceable>, you can specify the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011910 following:
11911 <literallayout class='monospaced'>
11912 =
11913 &lt;
11914 &gt;
11915 &lt;=
11916 &gt;=
11917 </literallayout>
Brad Bishop37a0e4d2017-12-04 01:01:44 -050011918 For <replaceable>version</replaceable>, provide the version
11919 number.
11920 <note><title>Tip</title>
11921 You can use
11922 <link linkend='var-EXTENDPKGV'><filename>EXTENDPKGV</filename></link>
11923 to provide a full package version specification.
11924 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011925 For example, the following sets up a dependency on version
11926 1.2 or greater of the package <filename>foo</filename>:
11927 <literallayout class='monospaced'>
11928 RDEPENDS_${PN} = "foo (>= 1.2)"
11929 </literallayout>
11930 </para>
11931
11932 <para>
11933 For information on build-time dependencies, see the
11934 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
11935 variable.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011936 You can also see the
11937 "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
11938 "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
11939 sections in the BitBake User Manual for additional
11940 information on tasks and dependencies.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011941 </para>
11942 </glossdef>
11943 </glossentry>
11944
11945 <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm>
11946 <info>
11947 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."
11948 </info>
11949 <glossdef>
11950 <para role="glossdeffirst">
11951<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11952 When inheriting the
11953 <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link>
11954 class, this
11955 variable identifies distribution features that must
11956 exist in the current configuration in order for the
11957 OpenEmbedded build system to build the recipe.
11958 In other words, if the
11959 <filename>REQUIRED_DISTRO_FEATURES</filename> variable
11960 lists a feature that does not appear in
11961 <filename>DISTRO_FEATURES</filename> within the
11962 current configuration, an error occurs and the
11963 build stops.
11964 </para>
11965 </glossdef>
11966 </glossentry>
11967
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011968 <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
11969 <info>
11970 RM_WORK_EXCLUDE[doc] = "With rm_work enabled, this variable specifies a list of packages whose work directories should not be removed."
11971 </info>
11972 <glossdef>
11973 <para role="glossdeffirst">
11974<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11975 With <filename>rm_work</filename> enabled, this
11976 variable specifies a list of recipes whose work directories
11977 should not be removed.
11978 See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
11979 section for more details.
11980 </para>
11981 </glossdef>
11982 </glossentry>
11983
11984 <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm>
11985 <info>
11986 ROOT_HOME[doc] = "Defines the root home directory."
11987 </info>
11988 <glossdef>
11989 <para role="glossdeffirst">
11990<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11991 Defines the root home directory.
11992 By default, this directory is set as follows in the
11993 BitBake configuration file:
11994 <literallayout class='monospaced'>
11995 ROOT_HOME ??= "/home/root"
11996 </literallayout>
11997 <note>
11998 This default value is likely used because some
11999 embedded solutions prefer to have a read-only root
12000 filesystem and prefer to keep writeable data in one
12001 place.
12002 </note>
12003 </para>
12004
12005 <para>
12006 You can override the default by setting the variable
12007 in any layer or in the <filename>local.conf</filename> file.
12008 Because the default is set using a "weak" assignment
12009 (i.e. "??="), you can use either of the following forms
12010 to define your override:
12011 <literallayout class='monospaced'>
12012 ROOT_HOME = "/root"
12013 ROOT_HOME ?= "/root"
12014 </literallayout>
12015 These override examples use <filename>/root</filename>,
12016 which is probably the most commonly used override.
12017 </para>
12018 </glossdef>
12019 </glossentry>
12020
12021 <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>
12022 <info>
12023 ROOTFS[doc] = "Indicates a filesystem image to include as the root filesystem."
12024 </info>
12025 <glossdef>
12026 <para role="glossdeffirst">
12027<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12028 Indicates a filesystem image to include as the root
12029 filesystem.
12030 </para>
12031
12032 <para>
12033 The <filename>ROOTFS</filename> variable is an optional
12034 variable used with the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012035 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012036 class.
12037 </para>
12038 </glossdef>
12039 </glossentry>
12040
12041 <glossentry id='var-ROOTFS_POSTINSTALL_COMMAND'><glossterm>ROOTFS_POSTINSTALL_COMMAND</glossterm>
12042 <info>
12043 ROOTFS_POSTINSTALL_COMMAND[doc] = "Specifies a list of functions to call after installing packages."
12044 </info>
12045 <glossdef>
12046 <para role="glossdeffirst">
12047<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12048 Specifies a list of functions to call after the
12049 OpenEmbedded build system has installed packages.
12050 You can specify functions separated by semicolons:
12051 <literallayout class='monospaced'>
12052 ROOTFS_POSTINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
12053 </literallayout>
12054 </para>
12055
12056 <para>
12057 If you need to pass the root filesystem path to a command
12058 within a function, you can use
12059 <filename>${IMAGE_ROOTFS}</filename>, which points to
12060 the directory that becomes the root filesystem image.
12061 See the
12062 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12063 variable for more information.
12064 </para>
12065 </glossdef>
12066 </glossentry>
12067
12068 <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
12069 <info>
12070 ROOTFS_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the root filesystem."
12071 </info>
12072 <glossdef>
12073 <para role="glossdeffirst">
12074<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12075 Specifies a list of functions to call once the
12076 OpenEmbedded build system has created the root filesystem.
12077 You can specify functions separated by semicolons:
12078 <literallayout class='monospaced'>
12079 ROOTFS_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
12080 </literallayout>
12081 </para>
12082
12083 <para>
12084 If you need to pass the root filesystem path to a command
12085 within a function, you can use
12086 <filename>${IMAGE_ROOTFS}</filename>, which points to
12087 the directory that becomes the root filesystem image.
12088 See the
12089 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12090 variable for more information.
12091 </para>
12092 </glossdef>
12093 </glossentry>
12094
12095 <glossentry id='var-ROOTFS_POSTUNINSTALL_COMMAND'><glossterm>ROOTFS_POSTUNINSTALL_COMMAND</glossterm>
12096 <info>
12097 ROOTFS_POSTUNINSTALL_COMMAND[doc] = "Specifies a list of functions to call after removal of unneeded packages."
12098 </info>
12099 <glossdef>
12100 <para role="glossdeffirst">
12101<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12102 Specifies a list of functions to call after the
12103 OpenEmbedded build system has removed unnecessary
12104 packages.
12105 When runtime package management is disabled in the
12106 image, several packages are removed including
12107 <filename>base-passwd</filename>,
12108 <filename>shadow</filename>, and
12109 <filename>update-alternatives</filename>.
12110 You can specify functions separated by semicolons:
12111 <literallayout class='monospaced'>
12112 ROOTFS_POSTUNINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
12113 </literallayout>
12114 </para>
12115
12116 <para>
12117 If you need to pass the root filesystem path to a command
12118 within a function, you can use
12119 <filename>${IMAGE_ROOTFS}</filename>, which points to
12120 the directory that becomes the root filesystem image.
12121 See the
12122 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12123 variable for more information.
12124 </para>
12125 </glossdef>
12126 </glossentry>
12127
12128 <glossentry id='var-ROOTFS_PREPROCESS_COMMAND'><glossterm>ROOTFS_PREPROCESS_COMMAND</glossterm>
12129 <info>
12130 ROOTFS_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the root filesystem."
12131 </info>
12132 <glossdef>
12133 <para role="glossdeffirst">
12134<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12135 Specifies a list of functions to call before the
12136 OpenEmbedded build system has created the root filesystem.
12137 You can specify functions separated by semicolons:
12138 <literallayout class='monospaced'>
12139 ROOTFS_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
12140 </literallayout>
12141 </para>
12142
12143 <para>
12144 If you need to pass the root filesystem path to a command
12145 within a function, you can use
12146 <filename>${IMAGE_ROOTFS}</filename>, which points to
12147 the directory that becomes the root filesystem image.
12148 See the
12149 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12150 variable for more information.
12151 </para>
12152 </glossdef>
12153 </glossentry>
12154
12155 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
12156 <info>
12157 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."
12158 </info>
12159 <glossdef>
12160 <para role="glossdeffirst">
12161<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12162 A list of package name aliases that a package also provides.
12163 These aliases are useful for satisfying runtime dependencies
12164 of other packages both during the build and on the target
12165 (as specified by
12166 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
12167 <note>
12168 A package's own name is implicitly already in its
12169 <filename>RPROVIDES</filename> list.
12170 </note>
12171 </para>
12172
12173 <para>
12174 As with all package-controlling variables, you must always
12175 use the variable in conjunction with a package name override.
12176 Here is an example:
12177 <literallayout class='monospaced'>
12178 RPROVIDES_${PN} = "widget-abi-2"
12179 </literallayout>
12180 </para>
12181 </glossdef>
12182 </glossentry>
12183
12184 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
12185 <info>
12186 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."
12187 </info>
12188 <glossdef>
12189 <para role="glossdeffirst">
12190<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12191 A list of packages that extends the usability of a package
12192 being built.
12193 The package being built does not depend on this list of
12194 packages in order to successfully build, but rather
12195 uses them for extended usability.
12196 To specify runtime dependencies for packages, see the
12197 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
12198 variable.
12199 </para>
12200
12201 <para>
12202 The package manager will automatically install the
12203 <filename>RRECOMMENDS</filename> list of packages when
12204 installing the built package.
12205 However, you can prevent listed packages from being
12206 installed by using the
12207 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
12208 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
12209 and
12210 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
12211 variables.
12212 </para>
12213
12214 <para>
12215 Packages specified in
12216 <filename>RRECOMMENDS</filename> need not actually be
12217 produced.
12218 However, a recipe must exist that provides each package,
12219 either through the
12220 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
12221 or
12222 <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link>
12223 variables or the
12224 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>
12225 variable, or an error will occur during the build.
12226 If such a recipe does exist and the package is not produced,
12227 the build continues without error.
12228 </para>
12229
12230 <para>
12231 Because the <filename>RRECOMMENDS</filename> variable
12232 applies to packages being built, you should always attach
12233 an override to the variable to specify the particular
12234 package whose usability is being extended.
12235 For example, suppose you are building a development package
12236 that is extended to support wireless functionality.
12237 In this case, you would use the following:
12238 <literallayout class='monospaced'>
12239 RRECOMMENDS_${PN}-dev += "<replaceable>wireless_package_name</replaceable>"
12240 </literallayout>
12241 In the example, the package name
12242 (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
12243 must appear as it would in the
Brad Bishop316dfdd2018-06-25 12:45:53 -040012244 <filename>PACKAGES</filename> namespace before any renaming
12245 of the output package by classes such as
12246 <filename>debian.bbclass</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012247 </para>
12248
12249 <para>
12250 BitBake, which the OpenEmbedded build system uses, supports
12251 specifying versioned recommends.
12252 Although the syntax varies depending on the packaging
12253 format, BitBake hides these differences from you.
12254 Here is the general syntax to specify versions with
12255 the <filename>RRECOMMENDS</filename> variable:
12256 <literallayout class='monospaced'>
12257 RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
12258 </literallayout>
12259 For <filename>operator</filename>, you can specify the
12260 following:
12261 <literallayout class='monospaced'>
12262 =
12263 &lt;
12264 &gt;
12265 &lt;=
12266 &gt;=
12267 </literallayout>
12268 For example, the following sets up a recommend on version
12269 1.2 or greater of the package <filename>foo</filename>:
12270 <literallayout class='monospaced'>
12271 RRECOMMENDS_${PN} = "foo (>= 1.2)"
12272 </literallayout>
12273 </para>
12274 </glossdef>
12275 </glossentry>
12276
12277 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
12278 <info>
12279 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."
12280 </info>
12281 <glossdef>
12282 <para role="glossdeffirst">
12283<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12284 A list of packages replaced by a package.
12285 The package manager uses this variable to determine which
12286 package should be installed to replace other package(s)
12287 during an upgrade.
12288 In order to also have the other package(s) removed at the
12289 same time, you must add the name of the other
12290 package to the
12291 <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
12292 </para>
12293
12294 <para>
12295 As with all package-controlling variables, you must use
12296 this variable in conjunction with a package name
12297 override.
12298 Here is an example:
12299 <literallayout class='monospaced'>
12300 RREPLACES_${PN} = "<replaceable>other_package_being_replaced</replaceable>"
12301 </literallayout>
12302 </para>
12303
12304 <para>
12305 BitBake, which the OpenEmbedded build system uses, supports
12306 specifying versioned replacements.
12307 Although the syntax varies depending on the packaging
12308 format, BitBake hides these differences from you.
12309 Here is the general syntax to specify versions with
12310 the <filename>RREPLACES</filename> variable:
12311 <literallayout class='monospaced'>
12312 RREPLACES_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
12313 </literallayout>
12314 For <filename>operator</filename>, you can specify the
12315 following:
12316 <literallayout class='monospaced'>
12317 =
12318 &lt;
12319 &gt;
12320 &lt;=
12321 &gt;=
12322 </literallayout>
12323 For example, the following sets up a replacement using
12324 version 1.2 or greater of the package
12325 <filename>foo</filename>:
12326 <literallayout class='monospaced'>
12327 RREPLACES_${PN} = "foo (>= 1.2)"
12328 </literallayout>
12329 </para>
12330 </glossdef>
12331 </glossentry>
12332
12333 <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
12334 <info>
12335 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."
12336 </info>
12337 <glossdef>
12338 <para role="glossdeffirst">
12339<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12340 A list of additional packages that you can suggest for
12341 installation by the package manager at the time a package
12342 is installed.
12343 Not all package managers support this functionality.
12344 </para>
12345
12346 <para>
12347 As with all package-controlling variables, you must always
12348 use this variable in conjunction with a package name
12349 override.
12350 Here is an example:
12351 <literallayout class='monospaced'>
12352 RSUGGESTS_${PN} = "<replaceable>useful_package</replaceable> <replaceable>another_package</replaceable>"
12353 </literallayout>
12354 </para>
12355 </glossdef>
12356 </glossentry>
12357
12358 </glossdiv>
12359
12360 <glossdiv id='var-glossary-s'><title>S</title>
12361
12362 <glossentry id='var-S'><glossterm>S</glossterm>
12363 <info>
12364 S[doc] = "The location in the Build Directory where unpacked package source code resides."
12365 </info>
12366 <glossdef>
12367 <para role="glossdeffirst">
12368<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12369 The location in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050012370 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012371 where unpacked recipe source code resides.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012372 By default, this directory is
12373 <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>,
12374 where <filename>${BPN}</filename> is the base recipe name
12375 and <filename>${PV}</filename> is the recipe version.
12376 If the source tarball extracts the code to a directory
12377 named anything other than <filename>${BPN}-${PV}</filename>,
Brad Bishopd7bf8c12018-02-25 22:55:05 -050012378 or if the source code is fetched from an SCM such as
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012379 Git or Subversion, then you must set <filename>S</filename>
12380 in the recipe so that the OpenEmbedded build system
12381 knows where to find the unpacked source.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012382 </para>
12383
12384 <para>
12385 As an example, assume a
Brad Bishopd7bf8c12018-02-25 22:55:05 -050012386 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012387 top-level folder named <filename>poky</filename> and a
12388 default Build Directory at <filename>poky/build</filename>.
12389 In this case, the work directory the build system uses
12390 to keep the unpacked recipe for <filename>db</filename>
12391 is the following:
12392 <literallayout class='monospaced'>
12393 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
12394 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012395 The unpacked source code resides in the
12396 <filename>db-5.1.19</filename> folder.
12397 </para>
12398
12399 <para>
12400 This next example assumes a Git repository.
12401 By default, Git repositories are cloned to
12402 <filename>${WORKDIR}/git</filename> during
12403 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>.
12404 Since this path is different from the default value of
12405 <filename>S</filename>, you must set it specifically
12406 so the source can be located:
12407 <literallayout class='monospaced'>
12408 SRC_URI = "git://path/to/repo.git"
12409 S = "${WORKDIR}/git"
12410 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012411 </para>
12412 </glossdef>
12413 </glossentry>
12414
12415 <glossentry id='var-SANITY_REQUIRED_UTILITIES'><glossterm>SANITY_REQUIRED_UTILITIES</glossterm>
12416 <info>
12417 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."
12418 </info>
12419 <glossdef>
12420 <para role="glossdeffirst">
12421<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12422 Specifies a list of command-line utilities that should be
12423 checked for during the initial sanity checking process when
12424 running BitBake.
12425 If any of the utilities are not installed on the build host,
12426 then BitBake immediately exits with an error.
12427 </para>
12428 </glossdef>
12429 </glossentry>
12430
12431 <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
12432 <info>
12433 SANITY_TESTED_DISTROS[doc] = "A list of the host distribution identifiers that the build system has been tested against."
12434 </info>
12435 <glossdef>
12436 <para role="glossdeffirst">
12437<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12438 A list of the host distribution identifiers that the
12439 build system has been tested against.
12440 Identifiers consist of the host distributor ID
12441 followed by the release,
12442 as reported by the <filename>lsb_release</filename> tool
12443 or as read from <filename>/etc/lsb-release</filename>.
12444 Separate the list items with explicit newline
12445 characters (<filename>\n</filename>).
12446 If <filename>SANITY_TESTED_DISTROS</filename> is not empty
12447 and the current value of
12448 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
12449 does not appear in the list, then the build system reports
12450 a warning that indicates the current host distribution has
12451 not been tested as a build host.
12452 </para>
12453 </glossdef>
12454 </glossentry>
12455
12456 <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
12457 <info>
12458 SDK_ARCH[doc] = "The target architecture for the SDK."
12459 </info>
12460 <glossdef>
12461 <para role="glossdeffirst">
12462<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12463 The target architecture for the SDK.
12464 Typically, you do not directly set this variable.
12465 Instead, use
12466 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
12467 </para>
12468 </glossdef>
12469 </glossentry>
12470
12471 <glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>
12472 <info>
12473 SDK_DEPLOY[doc] = "The directory set up and used by the populate_sdk_base to which the SDK is deployed."
12474 </info>
12475 <glossdef>
12476 <para role="glossdeffirst">
12477<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12478 The directory set up and used by the
12479 <link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012480 class to which the SDK is deployed.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012481 The <filename>populate_sdk_base</filename> class defines
12482 <filename>SDK_DEPLOY</filename> as follows:
12483 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012484 SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012485 </literallayout>
12486 </para>
12487 </glossdef>
12488 </glossentry>
12489
12490 <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm>
12491 <info>
12492 SDK_DIR[doc] = "The parent directory used by the OpenEmbedded build system when creating SDK output."
12493 </info>
12494 <glossdef>
12495 <para role="glossdeffirst">
12496<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12497 The parent directory used by the OpenEmbedded build system
12498 when creating SDK output.
12499 The
12500 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12501 class defines the variable as follows:
12502 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012503 SDK_DIR = "${WORKDIR}/sdk"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012504 </literallayout>
12505 <note>
12506 The <filename>SDK_DIR</filename> directory is a
12507 temporary directory as it is part of
12508 <filename>WORKDIR</filename>.
12509 The final output directory is
12510 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
12511 </note>
12512 </para>
12513 </glossdef>
12514 </glossentry>
12515
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012516 <glossentry id='var-SDK_EXT_TYPE'><glossterm>SDK_EXT_TYPE</glossterm>
12517 <info>
12518 SDK_EXT_TYPE[doc] = "Controls whether or not shared state artifacts are copied into the extensible SDK."
12519 </info>
12520 <glossdef>
12521 <para role="glossdeffirst">
12522<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12523 Controls whether or not shared state artifacts are copied
12524 into the extensible SDK.
12525 The default value of "full" copies all of the required
12526 shared state artifacts into the extensible SDK.
12527 The value "minimal" leaves these artifacts out of the
12528 SDK.
12529 <note>
12530 If you set the variable to "minimal", you need to
12531 ensure
12532 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
12533 is set in the SDK's configuration to enable the
12534 artifacts to be fetched as needed.
12535 </note>
12536 </para>
12537 </glossdef>
12538 </glossentry>
12539
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012540 <glossentry id='var-SDK_HOST_MANIFEST'><glossterm>SDK_HOST_MANIFEST</glossterm>
12541 <info>
12542 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."
12543 </info>
12544 <glossdef>
12545 <para role="glossdeffirst">
12546<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12547 The manifest file for the host part of the SDK.
12548 This file lists all the installed packages that make up
Brad Bishop316dfdd2018-06-25 12:45:53 -040012549 the host part of the SDK.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012550 The file contains package information on a line-per-package
12551 basis as follows:
12552 <literallayout class='monospaced'>
12553 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
12554 </literallayout>
12555 </para>
12556
12557 <para>
12558 The
12559 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12560 class defines the manifest file as follows:
12561 <literallayout class='monospaced'>
12562 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"
12563 </literallayout>
12564 The location is derived using the
12565 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>
12566 and
12567 <link linkend='var-TOOLCHAIN_OUTPUTNAME'><filename>TOOLCHAIN_OUTPUTNAME</filename></link>
12568 variables.
12569 </para>
12570 </glossdef>
12571 </glossentry>
12572
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012573 <glossentry id='var-SDK_INCLUDE_PKGDATA'><glossterm>SDK_INCLUDE_PKGDATA</glossterm>
12574 <info>
12575 SDK_INCLUDE_PKGDATA[doc] = "When set to "1", specifies to include the packagedata for all recipes in the "world" target in the extensible SDK."
12576 </info>
12577 <glossdef>
12578 <para role="glossdeffirst">
12579<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12580 When set to "1", specifies to include the packagedata for
12581 all recipes in the "world" target in the extensible SDK.
12582 Including this data allows the
12583 <filename>devtool search</filename> command to find these
12584 recipes in search results, as well as allows the
12585 <filename>devtool add</filename> command to map
12586 dependencies more effectively.
12587 <note>
12588 Enabling the <filename>SDK_INCLUDE_PKGDATA</filename>
12589 variable significantly increases build time because
12590 all of world needs to be built.
12591 Enabling the variable also slightly increases the size
12592 of the extensible SDK.
12593 </note>
12594 </para>
12595 </glossdef>
12596 </glossentry>
12597
Patrick Williamsc0f7c042017-02-23 20:41:17 -060012598 <glossentry id='var-SDK_INCLUDE_TOOLCHAIN'><glossterm>SDK_INCLUDE_TOOLCHAIN</glossterm>
12599 <info>
12600 SDK_INCLUDE_TOOLCHAIN[doc] = "When set to "1", specifies to include the toolchain in the extensible SDK."
12601 </info>
12602 <glossdef>
12603 <para role="glossdeffirst">
12604<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12605 When set to "1", specifies to include the toolchain in the
12606 extensible SDK.
12607 Including the toolchain is useful particularly when
12608 <link linkend='var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></link>
12609 is set to "minimal" to keep the SDK reasonably small
12610 but you still want to provide a usable toolchain.
12611 For example, suppose you want to use the toolchain from an
Brad Bishopc342db32019-05-15 21:57:59 -040012612 IDE or from other tools and you do not
Patrick Williamsc0f7c042017-02-23 20:41:17 -060012613 want to perform additional steps to install the toolchain.
12614 </para>
12615
12616 <para>
12617 The <filename>SDK_INCLUDE_TOOLCHAIN</filename> variable
12618 defaults to "0" if <filename>SDK_EXT_TYPE</filename>
12619 is set to "minimal", and defaults to "1" if
12620 <filename>SDK_EXT_TYPE</filename> is set to "full".
12621 </para>
12622 </glossdef>
12623 </glossentry>
12624
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012625 <glossentry id='var-SDK_INHERIT_BLACKLIST'><glossterm>SDK_INHERIT_BLACKLIST</glossterm>
12626 <info>
12627 SDK_INHERIT_BLACKLIST[doc] = "A list of classes to remove from the INHERIT value globally within the extensible SDK configuration."
12628 </info>
12629 <glossdef>
12630 <para role="glossdeffirst">
12631<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12632 A list of classes to remove from the
12633 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
12634 value globally within the extensible SDK configuration.
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012635 The
12636 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12637 class sets the default value:
12638 <literallayout class='monospaced'>
12639 SDK_INHERIT_BLACKLIST ?= "buildhistory icecc"
12640 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012641 </para>
12642
12643 <para>
12644 Some classes are not generally applicable within
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012645 the extensible SDK context.
12646 You can use this variable to disable those classes.
12647 </para>
12648
12649 <para>
12650 For additional information on how to customize the
12651 extensible SDK's configuration, see the
12652 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12653 section in the Yocto Project Application Development and
12654 the Extensible Software Development Kit (eSDK) manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012655 </para>
12656 </glossdef>
12657 </glossentry>
12658
12659 <glossentry id='var-SDK_LOCAL_CONF_BLACKLIST'><glossterm>SDK_LOCAL_CONF_BLACKLIST</glossterm>
12660 <info>
12661 SDK_LOCAL_CONF_BLACKLIST[doc] = "A list of variables not allowed through from the build system configuration into the extensible SDK configuration."
12662 </info>
12663 <glossdef>
12664 <para role="glossdeffirst">
12665<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012666 A list of variables not allowed through from the
12667 OpenEmbedded build system configuration into the extensible
12668 SDK configuration.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012669 Usually, these are variables that are specific to the
12670 machine on which the build system is running and thus
12671 would be potentially problematic within the extensible SDK.
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012672 </para>
12673
12674 <para>By default,
12675 <filename>SDK_LOCAL_CONF_BLACKLIST</filename> is set in the
12676 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12677 class and excludes the following variables:
12678 <literallayout class='monospaced'>
12679 <link linkend='var-CONF_VERSION'>CONF_VERSION</link>
12680 <link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link>
12681 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'>BB_NUMBER_PARSE_THREADS</ulink>
12682 <link linkend='var-PARALLEL_MAKE'>PARALLEL_MAKE</link>
12683 <link linkend='var-PRSERV_HOST'>PRSERV_HOST</link>
12684 <link linkend='var-SSTATE_MIRRORS'>SSTATE_MIRRORS</link>
12685 <link linkend='var-DL_DIR'>DL_DIR</link>
12686 <link linkend='var-SSTATE_DIR'>SSTATE_DIR</link>
12687 <link linkend='var-TMPDIR'>TMPDIR</link>
12688 <link linkend='var-BB_SERVER_TIMEOUT'>BB_SERVER_TIMEOUT</link>
12689 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012690 </para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012691
12692 <para>
12693 For additional information on how to customize the
12694 extensible SDK's configuration, see the
12695 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12696 section in the Yocto Project Application Development and
12697 the Extensible Software Development Kit (eSDK) manual.
12698 </para>
12699
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012700 </glossdef>
12701 </glossentry>
12702
12703 <glossentry id='var-SDK_LOCAL_CONF_WHITELIST'><glossterm>SDK_LOCAL_CONF_WHITELIST</glossterm>
12704 <info>
12705 SDK_LOCAL_CONF_WHITELIST[doc] = "A list of variables allowed through from the build system configuration into the extensible SDK configuration."
12706 </info>
12707 <glossdef>
12708 <para role="glossdeffirst">
12709<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012710 A list of variables allowed through from the OpenEmbedded
12711 build system configuration into the extensible SDK
12712 configuration.
12713 By default, the list of variables is empty and is set in
12714 the
12715 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12716 class.
12717 </para>
12718
12719 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012720 This list overrides the variables specified using the
12721 <link linkend='var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></link>
12722 variable as well as any variables identified by automatic
12723 blacklisting due to the "/" character being found at the
12724 start of the value, which is usually indicative of being a
12725 path and thus might not be valid on the system where the
12726 SDK is installed.
12727 </para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012728
12729 <para>
12730 For additional information on how to customize the
12731 extensible SDK's configuration, see the
12732 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12733 section in the Yocto Project Application Development and
12734 the Extensible Software Development Kit (eSDK) manual.
12735 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012736 </glossdef>
12737 </glossentry>
12738
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012739 <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
12740 <info>
12741 SDK_NAME[doc] = "The base name for SDK output files."
12742 </info>
12743 <glossdef>
12744 <para role="glossdeffirst">
12745<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12746 The base name for SDK output files.
12747 The name is derived from the
12748 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
12749 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
12750 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
12751 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
12752 and
12753 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
12754 variables:
12755 <literallayout class='monospaced'>
12756 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
12757 </literallayout>
12758 </para>
12759 </glossdef>
12760 </glossentry>
12761
12762 <glossentry id='var-SDK_OS'><glossterm>SDK_OS</glossterm>
12763 <info>
12764 SDK_OS[doc] = "The operating system for which the SDK will be built."
12765 </info>
12766 <glossdef>
12767 <para role="glossdeffirst">
12768<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12769 Specifies the operating system for which the SDK
12770 will be built.
12771 The default value is the value of
12772 <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>.
12773 </para>
12774 </glossdef>
12775 </glossentry>
12776
12777 <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>
12778 <info>
12779 SDK_OUTPUT[doc] = "The location used by the OpenEmbedded build system when creating SDK output."
12780 </info>
12781 <glossdef>
12782 <para role="glossdeffirst">
12783<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12784 The location used by the OpenEmbedded build system when
12785 creating SDK output.
12786 The
12787 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12788 class defines the variable as follows:
12789 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012790 SDK_DIR = "${WORKDIR}/sdk"
12791 SDK_OUTPUT = "${SDK_DIR}/image"
12792 SDK_DEPLOY = "${DEPLOY_DIR}/sdk"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012793 </literallayout>
12794 <note>
12795 The <filename>SDK_OUTPUT</filename> directory is a
12796 temporary directory as it is part of
Brad Bishop316dfdd2018-06-25 12:45:53 -040012797 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
12798 by way of
12799 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012800 The final output directory is
12801 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
12802 </note>
12803 </para>
12804 </glossdef>
12805 </glossentry>
12806
12807 <glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm>
12808 <info>
12809 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."
12810 </info>
12811 <glossdef>
12812 <para role="glossdeffirst">
12813<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12814 Specifies a list of architectures compatible with
12815 the SDK machine.
12816 This variable is set automatically and should not
12817 normally be hand-edited.
12818 Entries are separated using spaces and listed in order
12819 of priority.
12820 The default value for
12821 <filename>SDK_PACKAGE_ARCHS</filename> is "all any noarch
12822 ${SDK_ARCH}-${SDKPKGSUFFIX}".
12823 </para>
12824 </glossdef>
12825 </glossentry>
12826
12827 <glossentry id='var-SDK_POSTPROCESS_COMMAND'><glossterm>SDK_POSTPROCESS_COMMAND</glossterm>
12828 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012829 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 -050012830 </info>
12831 <glossdef>
12832 <para role="glossdeffirst">
12833<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12834 Specifies a list of functions to call once the
Brad Bishop316dfdd2018-06-25 12:45:53 -040012835 OpenEmbedded build system creates the SDK.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012836 You can specify functions separated by semicolons:
12837 <literallayout class='monospaced'>
12838 SDK_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
12839 </literallayout>
12840 </para>
12841
12842 <para>
12843 If you need to pass an SDK path to a command within a
12844 function, you can use
12845 <filename>${SDK_DIR}</filename>, which points to
12846 the parent directory used by the OpenEmbedded build system
12847 when creating SDK output.
12848 See the
12849 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
12850 variable for more information.
12851 </para>
12852 </glossdef>
12853 </glossentry>
12854
12855 <glossentry id='var-SDK_PREFIX'><glossterm>SDK_PREFIX</glossterm>
12856 <info>
12857 SDK_PREFIX[doc] = "The toolchain binary prefix used for nativesdk recipes."
12858 </info>
12859 <glossdef>
12860 <para role="glossdeffirst">
12861<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012862 The toolchain binary prefix used for
12863 <filename>nativesdk</filename> recipes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012864 The OpenEmbedded build system uses the
12865 <filename>SDK_PREFIX</filename> value to set the
12866 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
12867 when building <filename>nativesdk</filename> recipes.
12868 The default value is "${SDK_SYS}-".
12869 </para>
12870 </glossdef>
12871 </glossentry>
12872
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012873 <glossentry id='var-SDK_RECRDEP_TASKS'><glossterm>SDK_RECRDEP_TASKS</glossterm>
12874 <info>
12875 SDK_RECRDEP_TASKS[doc] = "A list of shared state tasks added to the extensible SDK."
12876 </info>
12877 <glossdef>
12878 <para role="glossdeffirst">
12879<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12880 A list of shared state tasks added to the extensible SDK.
12881 By default, the following tasks are added:
12882 <literallayout class='monospaced'>
12883 do_populate_lic
12884 do_package_qa
12885 do_populate_sysroot
12886 do_deploy
12887 </literallayout>
12888 Despite the default value of "" for the
12889 <filename>SDK_RECRDEP_TASKS</filename> variable, the
12890 above four tasks are always added to the SDK.
12891 To specify tasks beyond these four, you need to use
12892 the <filename>SDK_RECRDEP_TASKS</filename> variable (e.g.
12893 you are defining additional tasks that are needed in
12894 order to build
12895 <link linkend='var-SDK_TARGETS'><filename>SDK_TARGETS</filename></link>).
12896 </para>
12897 </glossdef>
12898 </glossentry>
12899
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012900 <glossentry id='var-SDK_SYS'><glossterm>SDK_SYS</glossterm>
12901 <info>
12902 SDK_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the SDK will be built."
12903 </info>
12904 <glossdef>
12905 <para role="glossdeffirst">
12906<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12907 Specifies the system, including the architecture and the
12908 operating system, for which the SDK will be built.
12909 </para>
12910
12911 <para>
12912 The OpenEmbedded build system automatically sets this
12913 variable based on
12914 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
12915 <link linkend='var-SDK_VENDOR'><filename>SDK_VENDOR</filename></link>,
12916 and
12917 <link linkend='var-SDK_OS'><filename>SDK_OS</filename></link>.
12918 You do not need to set the <filename>SDK_SYS</filename>
12919 variable yourself.
12920 </para>
12921 </glossdef>
12922 </glossentry>
12923
12924 <glossentry id='var-SDK_TARGET_MANIFEST'><glossterm>SDK_TARGET_MANIFEST</glossterm>
12925 <info>
12926 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."
12927 </info>
12928 <glossdef>
12929 <para role="glossdeffirst">
12930<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12931 The manifest file for the target part of the SDK.
12932 This file lists all the installed packages that make up
12933 the target part of the SDK.
12934 The file contains package information on a line-per-package
12935 basis as follows:
12936 <literallayout class='monospaced'>
12937 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
12938 </literallayout>
12939 </para>
12940
12941 <para>
12942 The
12943 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12944 class defines the manifest file as follows:
12945 <literallayout class='monospaced'>
12946 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"
12947 </literallayout>
12948 The location is derived using the
12949 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>
12950 and
12951 <link linkend='var-TOOLCHAIN_OUTPUTNAME'><filename>TOOLCHAIN_OUTPUTNAME</filename></link>
12952 variables.
12953 </para>
12954 </glossdef>
12955 </glossentry>
12956
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012957 <glossentry id='var-SDK_TARGETS'><glossterm>SDK_TARGETS</glossterm>
12958 <info>
12959 SDK_TARGETS[doc] = "A list of targets to install from shared state as part of the standard or extensible SDK installation."
12960 </info>
12961 <glossdef>
12962 <para role="glossdeffirst">
12963<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12964 A list of targets to install from shared state as part of
12965 the standard or extensible SDK installation.
12966 The default value is "${PN}" (i.e. the image from which
12967 the SDK is built).
12968 </para>
12969
12970 <para>
12971 The <filename>SDK_TARGETS</filename> variable is an
12972 internal variable and typically would not be changed.
12973 </para>
12974 </glossdef>
12975 </glossentry>
12976
12977 <glossentry id='var-SDK_TITLE'><glossterm>SDK_TITLE</glossterm>
12978 <info>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080012979 SDK_TITLE[doc] = "The title to be printed when running the SDK installer."
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012980 </info>
12981 <glossdef>
12982 <para role="glossdeffirst">
12983<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080012984 The title to be printed when running the SDK installer.
12985 By default, this title is based on the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012986 <link linkend='var-DISTRO_NAME'><filename>DISTRO_NAME</filename></link>
12987 or
12988 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080012989 variable and is set in the
12990 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12991 class as follows:
12992 <literallayout class='monospaced'>
12993 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
12994 </literallayout>
12995 For the default distribution "poky",
12996 <filename>SDK_TITLE</filename> is set to
12997 "Poky (Yocto Project Reference Distro)".
12998 </para>
12999
13000 <para>
13001 For information on how to change this default title,
13002 see the
13003 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-changing-the-sdk-installer-title'>Changing the Extensible SDK Installer Title</ulink>"
13004 section in the Yocto Project Application Development and
13005 the Extensible Software Development Kit (eSDK) manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013006 </para>
13007 </glossdef>
13008 </glossentry>
13009
13010 <glossentry id='var-SDK_UPDATE_URL'><glossterm>SDK_UPDATE_URL</glossterm>
13011 <info>
13012 SDK_UPDATE_URL[doc] = "An optional URL for an update server for the extensible SDK."
13013 </info>
13014 <glossdef>
13015 <para role="glossdeffirst">
13016<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13017 An optional URL for an update server for the extensible
13018 SDK.
13019 If set, the value is used as the default update server when
13020 running <filename>devtool sdk-update</filename> within the
13021 extensible SDK.
13022 </para>
13023 </glossdef>
13024 </glossentry>
13025
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013026 <glossentry id='var-SDK_VENDOR'><glossterm>SDK_VENDOR</glossterm>
13027 <info>
13028 SDK_VENDOR[doc] = "Specifies the name of the SDK vendor."
13029 </info>
13030 <glossdef>
13031 <para role="glossdeffirst">
13032<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13033 Specifies the name of the SDK vendor.
13034 </para>
13035 </glossdef>
13036 </glossentry>
13037
13038 <glossentry id='var-SDK_VERSION'><glossterm>SDK_VERSION</glossterm>
13039 <info>
13040 SDK_VERSION[doc] = "Specifies the version for the SDK."
13041 </info>
13042 <glossdef>
13043 <para role="glossdeffirst">
13044<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13045 Specifies the version of the SDK.
13046 The distribution configuration file (e.g.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013047 <filename>/meta-poky/conf/distro/poky.conf</filename>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013048 defines the <filename>SDK_VERSION</filename> as follows:
13049 <literallayout class='monospaced'>
Brad Bishop19323692019-04-05 15:28:33 -040013050 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013051 </literallayout>
13052 </para>
13053
13054 <para>
13055 For additional information, see the
13056 <link linkend='var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></link>
13057 and
13058 <link linkend='var-DATE'><filename>DATE</filename></link>
13059 variables.
13060 </para>
13061 </glossdef>
13062 </glossentry>
13063
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080013064 <glossentry id='var-SDKEXTPATH'><glossterm>SDKEXTPATH</glossterm>
13065 <info>
13066 SDKEXTPATH[doc] = "The default installation directory for the extensible SDK."
13067 </info>
13068 <glossdef>
13069 <para role="glossdeffirst">
13070<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13071 The default installation directory for the Extensible SDK.
13072 By default, this directory is based on the
13073 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
13074 variable and is set in the
13075 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
13076 class as follows:
13077 <literallayout class='monospaced'>
13078 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
13079 </literallayout>
13080 For the default distribution "poky", the
13081 <filename>SDKEXTPATH</filename> is set to "poky_sdk".
13082 </para>
13083
13084 <para>
13085 For information on how to change this default directory,
13086 see the
13087 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-changing-the-default-sdk-installation-directory'>Changing the Default SDK Installation Directory</ulink>"
13088 section in the Yocto Project Application Development and
13089 the Extensible Software Development Kit (eSDK) manual.
13090 </para>
13091 </glossdef>
13092 </glossentry>
13093
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013094 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
13095 <info>
13096 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'."
13097 </info>
13098 <glossdef>
13099 <para role="glossdeffirst">
13100<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13101 Equivalent to
13102 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
13103 However, this variable applies to the SDK generated from an
13104 image using the following command:
13105 <literallayout class='monospaced'>
13106 $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
13107 </literallayout>
13108 </para>
13109 </glossdef>
13110 </glossentry>
13111
13112 <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
13113 <info>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013114 SDKMACHINE[doc] = "Specifies the architecture (i.e. i686 or x86_64) for which to build SDK items."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013115 </info>
13116 <glossdef>
13117 <para role="glossdeffirst">
13118<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013119 The machine for which the SDK is built.
13120 In other words, the SDK is built such that it
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013121 runs on the target you specify with the
13122 <filename>SDKMACHINE</filename> value.
13123 The value points to a corresponding
13124 <filename>.conf</filename> file under
13125 <filename>conf/machine-sdk/</filename>.
13126 </para>
13127
13128 <para>
13129 You can use "i686" and "x86_64" as possible values
13130 for this variable. The variable defaults to "i686"
13131 and is set in the local.conf file in the Build Directory.
13132 <literallayout class='monospaced'>
13133 SDKMACHINE ?= "i686"
13134 </literallayout>
13135 <note>
13136 You cannot set the <filename>SDKMACHINE</filename>
13137 variable in your distribution configuration file.
13138 If you do, the configuration will not take affect.
13139 </note>
13140 </para>
13141 </glossdef>
13142 </glossentry>
13143
13144 <glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>
13145 <info>
13146 SDKPATH[doc] = "Defines the path offered to the user for installation of the SDK that is generated by the OpenEmbedded build system."
13147 </info>
13148 <glossdef>
13149 <para role="glossdeffirst">
13150<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13151 Defines the path offered to the user for installation
13152 of the SDK that is generated by the OpenEmbedded build
13153 system.
13154 The path appears as the default location for installing
13155 the SDK when you run the SDK's installation script.
13156 You can override the offered path when you run the
13157 script.
13158 </para>
13159 </glossdef>
13160 </glossentry>
13161
13162 <glossentry id='var-SDKTARGETSYSROOT'><glossterm>SDKTARGETSYSROOT</glossterm>
13163 <info>
13164 SDKTARGETSYSROOT[doc] = "Full path to the sysroot used for cross-compilation within an SDK as it will be when installed into the default SDKPATH."
13165 </info>
13166 <glossdef>
13167 <para role="glossdeffirst">
13168<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13169 The full path to the sysroot used for cross-compilation
13170 within an SDK as it will be when installed into the
13171 default
13172 <link linkend='var-SDKPATH'><filename>SDKPATH</filename></link>.
13173 </para>
13174 </glossdef>
13175 </glossentry>
13176
13177 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
13178 <info>
13179 SECTION[doc] = "The section in which packages should be categorized. Package management utilities can make use of this variable."
13180 </info>
13181 <glossdef>
13182 <para role="glossdeffirst">
13183<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13184 The section in which packages should be categorized.
13185 Package management utilities can make use of this variable.
13186 </para>
13187 </glossdef>
13188 </glossentry>
13189
13190 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
13191 <info>
13192 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."
13193 </info>
13194 <glossdef>
13195 <para role="glossdeffirst">
13196<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13197 Specifies the optimization flags passed to the C compiler
13198 when building for the target.
13199 The flags are passed through the default value of the
13200 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
13201 variable.
13202 </para>
13203
13204 <para>
13205 The <filename>SELECTED_OPTIMIZATION</filename> variable
13206 takes the value of
13207 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
13208 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
13209 If that is the case, the value of
13210 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
13211 </para>
13212 </glossdef>
13213 </glossentry>
13214
13215 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
13216 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013217 SERIAL_CONSOLE[doc] = "Defines the serial consoles (TTYs) to enable using getty."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013218 </info>
13219 <glossdef>
13220 <para role="glossdeffirst">
13221<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040013222 Defines a serial console (TTY) to enable using
13223 <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013224 Provide a value that specifies the baud rate followed by
13225 the TTY device name separated by a space.
13226 You cannot specify more than one TTY device:
13227 <literallayout class='monospaced'>
13228 SERIAL_CONSOLE = "115200 ttyS0"
13229 </literallayout>
13230 <note>
13231 The <filename>SERIAL_CONSOLE</filename> variable
13232 is deprecated.
13233 Please use the
13234 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
13235 variable.
13236 </note>
13237 </para>
13238 </glossdef>
13239 </glossentry>
13240
13241 <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
13242 <info>
13243 SERIAL_CONSOLES[doc] = "Defines the serial consoles (TTYs) to enable using getty."
13244 </info>
13245 <glossdef>
13246 <para role="glossdeffirst">
13247<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040013248 Defines a serial console (TTY) to enable using
13249 <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013250 Provide a value that specifies the baud rate followed by
13251 the TTY device name separated by a semicolon.
13252 Use spaces to separate multiple devices:
13253 <literallayout class='monospaced'>
13254 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
13255 </literallayout>
13256 </para>
13257 </glossdef>
13258 </glossentry>
13259
13260 <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
13261 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060013262 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 -050013263 </info>
13264 <glossdef>
13265 <para role="glossdeffirst">
13266<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060013267 Specifies serial consoles, which must be listed in
13268 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>,
13269 to check against <filename>/proc/console</filename>
13270 before enabling them using getty.
13271 This variable allows aliasing in the format:
13272 &lt;device&gt;:&lt;alias&gt;.
13273 If a device was listed as "sclp_line0"
13274 in <filename>/dev/</filename> and "ttyS0" was listed
13275 in <filename>/proc/console</filename>, you would do the
13276 following:
13277 <literallayout class='monospaced'>
13278 SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0"
13279 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013280 This variable is currently only supported with SysVinit
13281 (i.e. not with systemd).
13282 </para>
13283 </glossdef>
13284 </glossentry>
13285
13286 <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
13287 <info>
13288 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."
13289 </info>
13290 <glossdef>
13291 <para role="glossdeffirst">
13292<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13293 A list of recipe dependencies that should not be used to
13294 determine signatures of tasks from one recipe when they
13295 depend on tasks from another recipe.
13296 For example:
13297 <literallayout class='monospaced'>
13298 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
13299 </literallayout>
13300 </para>
13301
13302 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013303 In the previous example, <filename>intone</filename>
13304 depends on <filename>mplayer2</filename>.
13305 </para>
13306
13307 <para>
13308 You can use the special token <filename>"*"</filename> on
13309 the left-hand side of the dependency to match all
13310 recipes except the one on the right-hand side.
13311 Here is an example:
13312 <literallayout class='monospaced'>
13313 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
13314 </literallayout>
13315 </para>
13316
13317 <para>
13318 In the previous example, all recipes except
13319 <filename>quilt-native</filename> ignore task
13320 signatures from the <filename>quilt-native</filename>
13321 recipe when determining their task signatures.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013322 </para>
13323
13324 <para>
13325 Use of this variable is one mechanism to remove dependencies
13326 that affect task signatures and thus force rebuilds when a
13327 recipe changes.
13328 <note><title>Caution</title>
13329 If you add an inappropriate dependency for a recipe
13330 relationship, the software might break during
13331 runtime if the interface of the second recipe was
13332 changed after the first recipe had been built.
13333 </note>
13334 </para>
13335 </glossdef>
13336 </glossentry>
13337
13338 <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
13339 <info>
13340 SIGGEN_EXCLUDERECIPES_ABISAFE[doc] = "A list of recipes that are completely stable and will never change."
13341 </info>
13342 <glossdef>
13343 <para role="glossdeffirst">
13344<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13345 A list of recipes that are completely stable and will
13346 never change.
13347 The ABI for the recipes in the list are presented by
13348 output from the tasks run to build the recipe.
13349 Use of this variable is one way to remove dependencies from
13350 one recipe on another that affect task signatures and
13351 thus force rebuilds when the recipe changes.
13352 <note><title>Caution</title>
13353 If you add an inappropriate variable to this list,
13354 the software might break at runtime if the
13355 interface of the recipe was changed after the other
13356 had been built.
13357 </note>
13358 </para>
13359 </glossdef>
13360 </glossentry>
13361
13362 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
13363 <info>
13364 SITEINFO_BITS[doc] = "Specifies the number of bits for the target system CPU."
13365 </info>
13366 <glossdef>
13367 <para role="glossdeffirst">
13368<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13369 Specifies the number of bits for the target system CPU.
13370 The value should be either "32" or "64".
13371 </para>
13372 </glossdef>
13373 </glossentry>
13374
13375 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
13376 <info>
13377 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'."
13378 </info>
13379 <glossdef>
13380 <para role="glossdeffirst">
13381<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13382 Specifies the endian byte order of the target system.
13383 The value should be either "le" for little-endian or "be" for big-endian.
13384 </para>
13385 </glossdef>
13386 </glossentry>
13387
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013388 <glossentry id='var-SKIP_FILEDEPS'><glossterm>SKIP_FILEDEPS</glossterm>
13389 <info>
13390 SKIP_FILEDEPS[doc] = "Enables you to remove all files from
13391 the "Provides" section of an RPM package."
13392 </info>
13393 <glossdef>
13394 <para role="glossdeffirst">
13395<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13396 Enables removal of all files from the "Provides" section of
13397 an RPM package.
13398 Removal of these files is required for packages containing
13399 prebuilt binaries and libraries such as
13400 <filename>libstdc++</filename> and
13401 <filename>glibc</filename>.
13402 </para>
13403
13404 <para>
13405 To enable file removal, set the variable to "1" in your
13406 <filename>conf/local.conf</filename> configuration file
13407 in your:
Brad Bishopd7bf8c12018-02-25 22:55:05 -050013408 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013409 <literallayout class='monospaced'>
13410 SKIP_FILEDEPS = "1"
13411 </literallayout>
13412 </para>
13413 </glossdef>
13414 </glossentry>
13415
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013416 <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
13417 <info>
13418 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."
13419 </info>
13420 <glossdef>
13421 <para role="glossdeffirst">
13422<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13423 Groups together machines based upon the same family
13424 of SOC (System On Chip).
13425 You typically set this variable in a common
13426 <filename>.inc</filename> file that you include in the
13427 configuration files of all the machines.
13428 <note>
13429 You must include
13430 <filename>conf/machine/include/soc-family.inc</filename>
13431 for this variable to appear in
13432 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
13433 </note>
13434 </para>
13435 </glossdef>
13436 </glossentry>
13437
13438 <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
13439 <info>
13440 SOLIBS[doc] = "Defines the suffix for shared libraries used on the target platform."
13441 </info>
13442 <glossdef>
13443 <para role="glossdeffirst">
13444<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13445 Defines the suffix for shared libraries used on the
13446 target platform.
13447 By default, this suffix is ".so.*" for all Linux-based
13448 systems and is defined in the
13449 <filename>meta/conf/bitbake.conf</filename> configuration
13450 file.
13451 </para>
13452
13453 <para>
13454 You will see this variable referenced in the default values
13455 of <filename>FILES_${PN}</filename>.
13456 </para>
13457 </glossdef>
13458 </glossentry>
13459
13460 <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
13461 <info>
13462 SOLIBSDEV[doc] = "Defines the suffix for the development symbolic link (symlink) for shared libraries on the target platform."
13463 </info>
13464 <glossdef>
13465 <para role="glossdeffirst">
13466<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13467 Defines the suffix for the development symbolic link
13468 (symlink) for shared libraries on the target platform.
13469 By default, this suffix is ".so" for Linux-based
13470 systems and is defined in the
13471 <filename>meta/conf/bitbake.conf</filename> configuration
13472 file.
13473 </para>
13474
13475 <para>
13476 You will see this variable referenced in the default values
13477 of <filename>FILES_${PN}-dev</filename>.
13478 </para>
13479 </glossdef>
13480 </glossentry>
13481
13482 <glossentry id='var-SOURCE_MIRROR_FETCH'><glossterm>SOURCE_MIRROR_FETCH</glossterm>
13483 <info>
13484 SOURCE_MIRROR_FETCH[doc] = "Set as part of a source mirror generation script to skip COMPATIBLE_MACHINE and COMPATIBLE_HOST checks."
13485 </info>
13486 <glossdef>
13487 <para role="glossdeffirst">
13488<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13489 When you are fetching files to create a mirror of sources
13490 (i.e. creating a source mirror), setting
13491 <filename>SOURCE_MIRROR_FETCH</filename> to "1" in your
13492 <filename>local.conf</filename> configuration file ensures
13493 the source for all recipes are fetched regardless of
13494 whether or not a recipe is compatible with the
13495 configuration.
13496 A recipe is considered incompatible with the currently
13497 configured machine when either or both the
13498 <link linkend='var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></link>
13499 variable and
13500 <link linkend='var-COMPATIBLE_HOST'><filename>COMPATIBLE_HOST</filename></link>
13501 variables specify compatibility with a machine other
13502 than that of the current machine or host.
13503 <note><title>Warning</title>
13504 Do not set the
13505 <filename>SOURCE_MIRROR_FETCH</filename> variable
13506 unless you are creating a source mirror.
13507 In other words, do not set the variable during a
13508 normal build.
13509 </note>
13510 </para>
13511 </glossdef>
13512 </glossentry>
13513
13514 <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm>
13515 <info>
13516 SOURCE_MIRROR_URL[doc] = "URL to source mirror that will be used before fetching from original SRC_URI."
13517 </info>
13518 <glossdef>
13519 <para role="glossdeffirst">
13520<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13521 Defines your own
13522 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
13523 from which to first fetch source before attempting to fetch
13524 from the upstream specified in
13525 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
13526 </para>
13527
13528 <para>
13529 To use this variable, you must globally inherit the
13530 <link linkend='ref-classes-own-mirrors'><filename>own-mirrors</filename></link>
13531 class and then provide the URL to your mirrors.
13532 Here is the general syntax:
13533 <literallayout class='monospaced'>
13534 INHERIT += "own-mirrors"
13535 SOURCE_MIRROR_URL = "http://<replaceable>example</replaceable>.com/<replaceable>my_source_mirror</replaceable>"
13536 </literallayout>
13537 <note>
13538 You can specify only a single URL in
13539 <filename>SOURCE_MIRROR_URL</filename>.
13540 </note>
13541 </para>
13542 </glossdef>
13543 </glossentry>
13544
13545 <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>
13546 <info>
13547 SPDXLICENSEMAP[doc] = "Maps commonly used license names to their SPDX counterparts found in meta/files/common-licenses/."
13548 </info>
13549 <glossdef>
13550 <para role="glossdeffirst">
13551<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13552 Maps commonly used license names to their SPDX counterparts
13553 found in <filename>meta/files/common-licenses/</filename>.
13554 For the default <filename>SPDXLICENSEMAP</filename>
13555 mappings, see the
13556 <filename>meta/conf/licenses.conf</filename> file.
13557 </para>
13558
13559 <para>
13560 For additional information, see the
13561 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
13562 variable.
13563 </para>
13564 </glossdef>
13565 </glossentry>
13566
13567 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
13568 <info>
13569 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."
13570 </info>
13571 <glossdef>
13572 <para role="glossdeffirst">
13573<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13574 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
13575 OpenEmbedded build system to create variants of recipes or packages.
13576 The list specifies the prefixes to strip off during certain circumstances
13577 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
13578 </para>
13579 </glossdef>
13580 </glossentry>
13581
Brad Bishop316dfdd2018-06-25 12:45:53 -040013582 <glossentry id='var-SPL_BINARY'><glossterm>SPL_BINARY</glossterm>
13583 <info>
13584 SPL_BINARY[doc] = "The file type of the Secondary Program Loader (SPL)."
13585 </info>
13586 <glossdef>
13587 <para role="glossdeffirst">
13588<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13589 The file type for the Secondary Program Loader (SPL).
13590 Some devices use an SPL from which to boot (e.g. the
13591 BeagleBone development board).
13592 For such cases, you can declare the file type of the
13593 SPL binary in the <filename>u-boot.inc</filename> include
13594 file, which is used in the U-Boot recipe.
13595 </para>
13596
13597 <para>
13598 The SPL file type is set to "null" by default in the
13599 <filename>u-boot.inc</filename> file as follows:
13600 <literallayout class='monospaced'>
13601 # Some versions of u-boot build an SPL (Second Program Loader) image that
13602 # should be packaged along with the u-boot binary as well as placed in the
13603 # deploy directory. For those versions they can set the following variables
13604 # to allow packaging the SPL.
13605 SPL_BINARY ?= ""
13606 SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"
13607 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
13608 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"
13609 </literallayout>
13610 The <filename>SPL_BINARY</filename> variable helps form
13611 various <filename>SPL_*</filename> variables used by
13612 the OpenEmbedded build system.
13613 </para>
13614
13615 <para>
13616 See the BeagleBone machine configuration example in the
13617 "<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>"
13618 section in the Yocto Project Board Support Package
13619 Developer's Guide for additional information.
13620 </para>
13621 </glossdef>
13622 </glossentry>
13623
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013624 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
13625 <info>
13626 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."
13627 </info>
13628 <glossdef>
13629 <para role="glossdeffirst">
13630<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13631 The list of source files - local or remote.
13632 This variable tells the OpenEmbedded build system which bits
13633 to pull in for the build and how to pull them in.
13634 For example, if the recipe or append file only needs to
13635 fetch a tarball from the Internet, the recipe or
13636 append file uses a single <filename>SRC_URI</filename>
13637 entry.
13638 On the other hand, if the recipe or append file needs to
13639 fetch a tarball, apply two patches, and include a custom
13640 file, the recipe or append file would include four
13641 instances of the variable.
13642 </para>
13643
13644 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013645 The following list explains the available URI protocols.
13646 URI protocols are highly dependent on particular BitBake
13647 Fetcher submodules.
13648 Depending on the fetcher BitBake uses, various URL
13649 parameters are employed.
13650 For specifics on the supported Fetchers, see the
13651 "<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"
13652 section in the BitBake User Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013653 <itemizedlist>
13654 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
13655 Fetches files, which are usually files shipped with
13656 the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050013657 <link linkend='metadata'>Metadata</link>,
Brad Bishop316dfdd2018-06-25 12:45:53 -040013658 from the local machine (e.g.
13659 <ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>patch</ulink>
13660 files).
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013661 The path is relative to the
13662 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
13663 variable.
13664 Thus, the build system searches, in order, from the
13665 following directories, which are assumed to be a
13666 subdirectories of the directory in which the
13667 recipe file (<filename>.bb</filename>) or
13668 append file (<filename>.bbappend</filename>)
13669 resides:
13670 <itemizedlist>
13671 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
13672 The base recipe name without any special
13673 suffix or version numbers.
13674 </para></listitem>
13675 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
13676 <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
13677 The base recipe name and version but without
13678 any special package name suffix.
13679 </para></listitem>
13680 <listitem><para><emphasis>files -</emphasis>
13681 Files within a directory, which is named
13682 <filename>files</filename> and is also
13683 alongside the recipe or append file.
13684 </para></listitem>
13685 </itemizedlist>
13686 <note>
13687 If you want the build system to pick up files
13688 specified through a
13689 <filename>SRC_URI</filename>
13690 statement from your append file, you need to be
13691 sure to extend the
13692 <filename>FILESPATH</filename>
13693 variable by also using the
13694 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
13695 variable from within your append file.
13696 </note>
13697 </para></listitem>
13698 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
13699 Bazaar revision control repository.</para></listitem>
13700 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
13701 Git revision control repository.</para></listitem>
13702 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
13703 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
13704 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
13705 a repo (Git) repository.</para></listitem>
13706 <listitem><para><emphasis><filename>ccrc://</filename> -</emphasis>
13707 Fetches files from a ClearCase repository.
13708 </para></listitem>
13709 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
13710 the Internet using <filename>http</filename>.</para></listitem>
13711 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
13712 from the Internet using <filename>https</filename>.</para></listitem>
13713 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
13714 from the Internet using <filename>ftp</filename>.</para></listitem>
13715 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
13716 a CVS revision control repository.</para></listitem>
13717 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
13718 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
13719 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
13720 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
13721 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
13722 a secure shell.</para></listitem>
13723 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
13724 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
Brad Bishopc342db32019-05-15 21:57:59 -040013725 <listitem><para><emphasis><filename>npm://</filename> -</emphasis> Fetches JavaScript
13726 modules from a registry.
13727 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013728 </itemizedlist>
13729 </para>
13730
13731 <para>
13732 Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
13733 Here are standard options:
13734 <itemizedlist>
13735 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
13736 the patch or not.
13737 The default action is to apply the patch.</para></listitem>
13738 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
13739 striplevel to use when applying the patch.
13740 The default level is 1.</para></listitem>
13741 <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
13742 the directory in which the patch should be applied.
13743 The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
13744 </para></listitem>
13745 </itemizedlist>
13746 </para>
13747
13748 <para>
13749 Here are options specific to recipes building code from a revision control system:
13750 <itemizedlist>
13751 <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
13752 Apply the patch only if
13753 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
13754 is equal to or greater than <filename>mindate</filename>.
13755 </para></listitem>
13756 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
13757 Apply the patch only if <filename>SRCDATE</filename>
Andrew Geissler5fa08482019-03-20 15:58:14 -050013758 is not later than <filename>maxdate</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013759 </para></listitem>
13760 <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
13761 Apply the patch only if <filename>SRCREV</filename>
13762 is equal to or greater than <filename>minrev</filename>.
13763 </para></listitem>
13764 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
13765 Apply the patch only if <filename>SRCREV</filename>
13766 is not later than <filename>maxrev</filename>.
13767 </para></listitem>
13768 <listitem><para><emphasis><filename>rev</filename> -</emphasis>
13769 Apply the patch only if <filename>SRCREV</filename>
13770 is equal to <filename>rev</filename>.
13771 </para></listitem>
13772 <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
13773 Apply the patch only if <filename>SRCREV</filename>
13774 is not equal to <filename>rev</filename>.
13775 </para></listitem>
13776 </itemizedlist>
13777 </para>
13778
13779 <para>
13780 Here are some additional options worth mentioning:
13781 <itemizedlist>
13782 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
13783 whether or not to unpack the file if it is an archive.
13784 The default action is to unpack the file.</para></listitem>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013785 <listitem><para><emphasis><filename>destsuffix</filename> -</emphasis> Places the file
13786 (or extracts its contents) into the specified
13787 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
13788 when the Git fetcher is used.
13789 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013790 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
13791 (or extracts its contents) into the specified
Brad Bishop316dfdd2018-06-25 12:45:53 -040013792 subdirectory of <filename>WORKDIR</filename>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013793 when the local (<filename>file://</filename>)
13794 fetcher is used.
13795 </para></listitem>
13796 <listitem><para><emphasis><filename>localdir</filename> -</emphasis> Places the file
13797 (or extracts its contents) into the specified
Brad Bishop316dfdd2018-06-25 12:45:53 -040013798 subdirectory of <filename>WORKDIR</filename> when
13799 the CVS fetcher is used.
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013800 </para></listitem>
13801 <listitem><para><emphasis><filename>subpath</filename> -</emphasis>
13802 Limits the checkout to a specific subpath of the
13803 tree when using the Git fetcher is used.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013804 </para></listitem>
13805 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
13806 name to be used for association with <filename>SRC_URI</filename> checksums
13807 when you have more than one file specified in <filename>SRC_URI</filename>.
13808 </para></listitem>
13809 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
13810 the filename used when storing the downloaded file.</para></listitem>
13811 </itemizedlist>
13812 </para>
13813 </glossdef>
13814 </glossentry>
13815
13816 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
13817 <info>
13818 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."
13819 </info>
13820 <glossdef>
13821 <para role="glossdeffirst">
13822<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13823 By default, the OpenEmbedded build system automatically detects whether
13824 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
13825 contains files that are machine-specific.
13826 If so, the build system automatically changes
13827 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
13828 Setting this variable to "0" disables this behavior.
13829 </para>
13830 </glossdef>
13831 </glossentry>
13832
13833 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
13834 <info>
13835 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)."
13836 </info>
13837 <glossdef>
13838 <para role="glossdeffirst">
13839<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13840 The date of the source code used to build the package.
13841 This variable applies only if the source was fetched from a Source Code Manager (SCM).
13842 </para>
13843 </glossdef>
13844 </glossentry>
13845
13846 <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
13847 <info>
13848 SRCPV[doc] = "Returns the version string of the current package. This string is used to help define the value of PV."
13849 </info>
13850 <glossdef>
13851 <para role="glossdeffirst">
13852<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13853 Returns the version string of the current package.
13854 This string is used to help define the value of
13855 <link linkend='var-PV'><filename>PV</filename></link>.
13856 </para>
13857
13858 <para>
13859 The <filename>SRCPV</filename> variable is defined in the
13860 <filename>meta/conf/bitbake.conf</filename> configuration
13861 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050013862 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013863 as follows:
13864 <literallayout class='monospaced'>
13865 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
13866 </literallayout>
13867 </para>
13868
13869 <para>
13870 Recipes that need to define <filename>PV</filename> do so
13871 with the help of the <filename>SRCPV</filename>.
13872 For example, the <filename>ofono</filename> recipe
13873 (<filename>ofono_git.bb</filename>) located in
13874 <filename>meta/recipes-connectivity</filename> in the
13875 Source Directory defines <filename>PV</filename> as
13876 follows:
13877 <literallayout class='monospaced'>
13878 PV = "0.12-git${SRCPV}"
13879 </literallayout>
13880 </para>
13881 </glossdef>
13882 </glossentry>
13883
13884 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
13885 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013886 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 -050013887 </info>
13888 <glossdef>
13889 <para role="glossdeffirst">
13890<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13891 The revision of the source code used to build the package.
Brad Bishop316dfdd2018-06-25 12:45:53 -040013892 This variable applies to Subversion, Git, Mercurial, and
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013893 Bazaar only.
13894 Note that if you want to build a fixed revision and you
13895 want to avoid performing a query on the remote repository
13896 every time BitBake parses your recipe, you should specify
13897 a <filename>SRCREV</filename> that is a
13898 full revision identifier and not just a tag.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050013899 <note>
13900 For information on limitations when inheriting the
13901 latest revision of software using
13902 <filename>SRCREV</filename>, see the
13903 <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link>
13904 variable description and the
13905 "<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 -050013906 section, which is in the Yocto Project Development
13907 Tasks Manual.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050013908 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013909 </para>
13910
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013911 </glossdef>
13912 </glossentry>
13913
13914 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
13915 <info>
13916 SSTATE_DIR[doc] = "The directory for the shared state cache."
13917 </info>
13918 <glossdef>
13919 <para role="glossdeffirst">
13920<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13921 The directory for the shared state cache.
13922 </para>
13923 </glossdef>
13924 </glossentry>
13925
13926 <glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm>
13927 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013928 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 -050013929 </info>
13930 <glossdef>
13931 <para role="glossdeffirst">
13932<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13933 If set to "1", allows fetches from
13934 mirrors that are specified in
13935 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013936 to work even when fetching from the network is
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013937 disabled by setting <filename>BB_NO_NETWORK</filename>
13938 to "1".
13939 Using the
13940 <filename>SSTATE_MIRROR_ALLOW_NETWORK</filename>
13941 variable is useful if you have set
13942 <filename>SSTATE_MIRRORS</filename> to point to an
13943 internal server for your shared state cache, but
13944 you want to disable any other fetching from the network.
13945 </para>
13946 </glossdef>
13947 </glossentry>
13948
13949 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
13950 <info>
13951 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."
13952 </info>
13953 <glossdef>
13954 <para role="glossdeffirst">
13955<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13956 Configures the OpenEmbedded build system to search other
13957 mirror locations for prebuilt cache data objects before
13958 building out the data.
13959 This variable works like fetcher
13960 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
13961 and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
13962 and points to the cache locations to check for the shared
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080013963 state (sstate) objects.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013964 </para>
13965
13966 <para>
13967 You can specify a filesystem directory or a remote URL such
13968 as HTTP or FTP.
13969 The locations you specify need to contain the shared state
13970 cache (sstate-cache) results from previous builds.
13971 The sstate-cache you point to can also be from builds on
13972 other machines.
13973 </para>
13974
13975 <para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080013976 When pointing to sstate build artifacts on another machine
13977 that uses a different GCC version for native builds,
13978 you must configure <filename>SSTATE_MIRROR</filename>
13979 with a regular expression that maps local search paths
13980 to server paths.
13981 The paths need to take into account
13982 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
13983 set by the
13984 <link linkend='ref-classes-uninative'><filename>uninative</filename></link>
13985 class.
13986 For example, the following maps the local search path
13987 <filename>universal-4.9</filename> to the server-provided
13988 path <replaceable>server_url_sstate_path</replaceable>:
13989 <literallayout class='monospaced'>
13990 SSTATE_MIRRORS ?= file://universal-4.9/(.*) http://<replaceable>server_url_sstate_path</replaceable>/universal-4.8/\1 \n
13991 </literallayout>
13992 </para>
13993
13994 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013995 If a mirror uses the same structure as
13996 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
13997 you need to add
13998 "PATH" at the end as shown in the examples below.
13999 The build system substitutes the correct path within the
14000 directory structure.
14001 <literallayout class='monospaced'>
14002 SSTATE_MIRRORS ?= "\
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014003 file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH;downloadfilename=PATH \n \
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014004 file://.* file:///<replaceable>some-local-dir</replaceable>/sstate/PATH"
14005 </literallayout>
14006 </para>
14007 </glossdef>
14008 </glossentry>
14009
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014010 <glossentry id='var-SSTATE_SCAN_FILES'><glossterm>SSTATE_SCAN_FILES</glossterm>
14011 <info>
14012 SSTATE_SCAN_FILES[doc] = "Controls the list of files the OpenEmbedded build system scans for hardcoded installation paths."
14013 </info>
14014 <glossdef>
14015 <para role="glossdeffirst">
14016<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14017 Controls the list of files the OpenEmbedded build system
14018 scans for hardcoded installation paths. The variable uses a
14019 space-separated list of filenames (not paths) with standard
14020 wildcard characters allowed.
14021 </para>
14022
14023 <para>
14024 During a build, the OpenEmbedded build system creates a
14025 shared state (sstate) object during the first stage of
14026 preparing the sysroots. That object is scanned for
14027 hardcoded paths for original installation locations.
14028 The list of files that are scanned for paths is controlled
14029 by the <filename>SSTATE_SCAN_FILES</filename> variable.
14030 Typically, recipes add files they want to be scanned to the
14031 value of <filename>SSTATE_SCAN_FILES</filename> rather than
14032 the variable being comprehensively set. The
14033 <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
14034 class specifies the default list of files.
14035 </para>
14036
14037 <para>
14038 For details on the process, see the
14039 <link linkend='ref-classes-staging'><filename>staging</filename></link>
14040 class.
14041 </para>
14042 </glossdef>
14043 </glossentry>
14044
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014045 <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm>
14046 <info>
14047 STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host."
14048 </info>
14049 <glossdef>
14050 <para role="glossdeffirst">
14051<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14052 Specifies the path to the <filename>/lib</filename>
14053 subdirectory of the sysroot directory for the
14054 build host.
14055 </para>
14056 </glossdef>
14057 </glossentry>
14058
14059 <glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm>
14060 <info>
14061 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)."
14062 </info>
14063 <glossdef>
14064 <para role="glossdeffirst">
14065<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14066 Specifies the path to the <filename>/lib</filename>
14067 subdirectory of the sysroot directory for the target
14068 for which the current recipe is being built
14069 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14070 </para>
14071 </glossdef>
14072 </glossentry>
14073
14074 <glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm>
14075 <info>
14076 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)."
14077 </info>
14078 <glossdef>
14079 <para role="glossdeffirst">
14080<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14081 Specifies the path to the
14082 <filename>/usr/bin</filename> subdirectory of the
14083 sysroot directory for the target for which the current
14084 recipe is being built
14085 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14086 </para>
14087 </glossdef>
14088 </glossentry>
14089
14090 <glossentry id='var-STAGING_BINDIR_CROSS'><glossterm>STAGING_BINDIR_CROSS</glossterm>
14091 <info>
14092 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."
14093 </info>
14094 <glossdef>
14095 <para role="glossdeffirst">
14096<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14097 Specifies the path to the directory containing binary
14098 configuration scripts.
14099 These scripts provide configuration information for
14100 other software that wants to make use of libraries or
14101 include files provided by the software associated with
14102 the script.
14103 <note>
14104 This style of build configuration has been largely
14105 replaced by <filename>pkg-config</filename>.
14106 Consequently, if <filename>pkg-config</filename>
14107 is supported by the library to which you are linking,
14108 it is recommended you use
14109 <filename>pkg-config</filename> instead of a
14110 provided configuration script.
14111 </note>
14112 </para>
14113 </glossdef>
14114 </glossentry>
14115
14116 <glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm>
14117 <info>
14118 STAGING_BINDIR_NATIVE[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the build host."
14119 </info>
14120 <glossdef>
14121 <para role="glossdeffirst">
14122<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14123 Specifies the path to the
14124 <filename>/usr/bin</filename> subdirectory of the
14125 sysroot directory for the build host.
14126 </para>
14127 </glossdef>
14128 </glossentry>
14129
14130 <glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm>
14131 <info>
14132 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)."
14133 </info>
14134 <glossdef>
14135 <para role="glossdeffirst">
14136<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14137 Specifies the path to the <filename>/usr/share</filename>
14138 subdirectory of the sysroot directory for the target
14139 for which the current recipe is being built
14140 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14141 </para>
14142 </glossdef>
14143 </glossentry>
14144
14145 <glossentry id='var-STAGING_DATADIR_NATIVE'><glossterm>STAGING_DATADIR_NATIVE</glossterm>
14146 <info>
14147 STAGING_DATADIR_NATIVE[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the build host."
14148 </info>
14149 <glossdef>
14150 <para role="glossdeffirst">
14151<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14152 Specifies the path to the <filename>/usr/share</filename>
14153 subdirectory of the sysroot directory for the build host.
14154 </para>
14155 </glossdef>
14156 </glossentry>
14157
14158 <glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm>
14159 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014160 STAGING_DIR[doc] = "Helps construct the recipe-sysroots directory, which is used during packaging."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014161 </info>
14162 <glossdef>
14163 <para role="glossdeffirst">
14164<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040014165 Helps construct the <filename>recipe-sysroots</filename>
14166 directory, which is used during packaging.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014167 </para>
14168
14169 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014170 For information on how staging for recipe-specific
14171 sysroots occurs, see the
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014172 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014173 task, the
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014174 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-sharing-files-between-recipes'>Sharing Files Between Recipes</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -040014175 section in the Yocto Project Development Tasks Manual, the
14176 "<ulink url='&YOCTO_DOCS_OM_URL;#configuration-compilation-and-staging-dev-environment'>Configuration, Compilation, and Staging</ulink>"
14177 section in the Yocto Project Overview and Concepts Manual,
14178 and the
14179 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
14180 variable.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014181 <note>
14182 Recipes should never write files directly under
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014183 the <filename>STAGING_DIR</filename> directory because
14184 the OpenEmbedded build system
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014185 manages the directory automatically.
14186 Instead, files should be installed to
14187 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
14188 within your recipe's
14189 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
14190 task and then the OpenEmbedded build system will
14191 stage a subset of those files into the sysroot.
14192 </note>
14193 </para>
14194 </glossdef>
14195 </glossentry>
14196
14197 <glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm>
14198 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014199 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 -050014200 </info>
14201 <glossdef>
14202 <para role="glossdeffirst">
14203<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014204 Specifies the path to the sysroot directory for the system
Brad Bishop316dfdd2018-06-25 12:45:53 -040014205 on which the component is built to run (the system that
14206 hosts the component).
14207 For most recipes, this sysroot is the one in which that
14208 recipe's
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014209 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014210 task copies files.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014211 Exceptions include <filename>-native</filename> recipes,
14212 where the <filename>do_populate_sysroot</filename> task
14213 instead uses
14214 <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>.
14215 Depending on the type of recipe and the build target,
14216 <filename>STAGING_DIR_HOST</filename> can have the
14217 following values:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014218 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014219 <listitem><para>
14220 For recipes building for the target machine, the
14221 value is
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014222 "${<link linkend='var-STAGING_DIR'>STAGING_DIR</link>}/${<link linkend='var-MACHINE'>MACHINE</link>}".
14223 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014224 <listitem><para>
14225 For native recipes building for the build host, the
14226 value is empty given the assumption that when
14227 building for the build host, the build host's own
14228 directories should be used.
14229 <note>
14230 <para><filename>-native</filename> recipes are
14231 not installed into host paths like such as
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014232 <filename>/usr</filename>.
14233 Rather, these recipes are installed into
14234 <filename>STAGING_DIR_NATIVE</filename>.
14235 When compiling <filename>-native</filename>
14236 recipes, standard build environment variables
14237 such as
14238 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
14239 and
14240 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
14241 are set up so that both host paths and
14242 <filename>STAGING_DIR_NATIVE</filename> are
14243 searched for libraries and headers using, for
14244 example, GCC's <filename>-isystem</filename>
14245 option.</para>
14246
Brad Bishop316dfdd2018-06-25 12:45:53 -040014247 <para>Thus, the emphasis is that the
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014248 <filename>STAGING_DIR*</filename> variables
14249 should be viewed as input variables by tasks
14250 such as
14251 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>,
14252 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
14253 and
14254 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
14255 Having the real system root correspond to
14256 <filename>STAGING_DIR_HOST</filename> makes
14257 conceptual sense for
14258 <filename>-native</filename> recipes, as
14259 they make use of host headers and libraries.
14260 </para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014261 </note>
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014262 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014263 </itemizedlist>
14264 </para>
14265 </glossdef>
14266 </glossentry>
14267
14268 <glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm>
14269 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014270 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 -050014271 </info>
14272 <glossdef>
14273 <para role="glossdeffirst">
14274<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014275 Specifies the path to the sysroot directory used when
14276 building components that run on the build host itself.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014277 </para>
14278 </glossdef>
14279 </glossentry>
14280
14281 <glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm>
14282 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014283 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 -050014284 </info>
14285 <glossdef>
14286 <para role="glossdeffirst">
14287<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014288 Specifies the path to the sysroot used for the system for
14289 which the component generates code.
14290 For components that do not generate code, which is the
14291 majority, <filename>STAGING_DIR_TARGET</filename> is set
14292 to match
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014293 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
14294 </para>
14295
14296 <para>
14297 Some recipes build binaries that can run on the target
14298 system but those binaries in turn generate code for
14299 another different system (e.g. cross-canadian recipes).
14300 Using terminology from GNU, the primary system is referred
14301 to as the "HOST" and the secondary, or different, system is
14302 referred to as the "TARGET".
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014303 Thus, the binaries run on the "HOST" system
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014304 and generate binaries for the "TARGET" system.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014305 The <filename>STAGING_DIR_HOST</filename> variable points
14306 to the sysroot used for the "HOST" system, while
14307 <filename>STAGING_DIR_TARGET</filename>
14308 points to the sysroot used for the "TARGET" system.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014309 </para>
14310 </glossdef>
14311 </glossentry>
14312
14313 <glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm>STAGING_ETCDIR_NATIVE</glossterm>
14314 <info>
14315 STAGING_ETCDIR_NATIVE[doc] = "Specifies the path to the /etc subdirectory of the sysroot directory for the build host."
14316 </info>
14317 <glossdef>
14318 <para role="glossdeffirst">
14319<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14320 Specifies the path to the <filename>/etc</filename>
14321 subdirectory of the sysroot directory for the
14322 build host.
14323 </para>
14324 </glossdef>
14325 </glossentry>
14326
14327 <glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm>
14328 <info>
14329 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)."
14330 </info>
14331 <glossdef>
14332 <para role="glossdeffirst">
14333<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14334 Specifies the path to the <filename>/usr</filename>
14335 subdirectory of the sysroot directory for the target
14336 for which the current recipe is being built
14337 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14338 </para>
14339 </glossdef>
14340 </glossentry>
14341
14342 <glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm>
14343 <info>
14344 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)."
14345 </info>
14346 <glossdef>
14347 <para role="glossdeffirst">
14348<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14349 Specifies the path to the
14350 <filename>/usr/include</filename> subdirectory of the
14351 sysroot directory for the target for which the current
14352 recipe being built
14353 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14354 </para>
14355 </glossdef>
14356 </glossentry>
14357
14358 <glossentry id='var-STAGING_INCDIR_NATIVE'><glossterm>STAGING_INCDIR_NATIVE</glossterm>
14359 <info>
14360 STAGING_INCDIR_NATIVE[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the build host."
14361 </info>
14362 <glossdef>
14363 <para role="glossdeffirst">
14364<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14365 Specifies the path to the <filename>/usr/include</filename>
14366 subdirectory of the sysroot directory for the build host.
14367 </para>
14368 </glossdef>
14369 </glossentry>
14370
Patrick Williamsf1e5d692016-03-30 15:21:19 -050014371 <glossentry id='var-STAGING_KERNEL_BUILDDIR'><glossterm>STAGING_KERNEL_BUILDDIR</glossterm>
14372 <info>
14373 STAGING_KERNEL_BUILDDIR[doc] = "Points to the directory containing the kernel build artifacts."
14374 </info>
14375 <glossdef>
14376 <para role="glossdeffirst">
14377<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14378 Points to the directory containing the kernel build
14379 artifacts.
14380 Recipes building software that needs to access kernel
14381 build artifacts
14382 (e.g. <filename>systemtap-uprobes</filename>) can look in
14383 the directory specified with the
14384 <filename>STAGING_KERNEL_BUILDDIR</filename> variable to
14385 find these artifacts after the kernel has been built.
14386 </para>
14387 </glossdef>
14388 </glossentry>
14389
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014390 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
14391 <info>
14392 STAGING_KERNEL_DIR[doc] = "The directory with kernel headers that are required to build out-of-tree modules."
14393 </info>
14394 <glossdef>
14395 <para role="glossdeffirst">
14396<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14397 The directory with kernel headers that are required to build out-of-tree
14398 modules.
14399 </para>
14400 </glossdef>
14401 </glossentry>
14402
14403 <glossentry id='var-STAGING_LIBDIR'><glossterm>STAGING_LIBDIR</glossterm>
14404 <info>
14405 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)."
14406 </info>
14407 <glossdef>
14408 <para role="glossdeffirst">
14409<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14410 Specifies the path to the <filename>/usr/lib</filename>
14411 subdirectory of the sysroot directory for the target for
14412 which the current recipe is being built
14413 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14414 </para>
14415 </glossdef>
14416 </glossentry>
14417
14418 <glossentry id='var-STAGING_LIBDIR_NATIVE'><glossterm>STAGING_LIBDIR_NATIVE</glossterm>
14419 <info>
14420 STAGING_LIBDIR_NATIVE[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the build host."
14421 </info>
14422 <glossdef>
14423 <para role="glossdeffirst">
14424<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14425 Specifies the path to the <filename>/usr/lib</filename>
14426 subdirectory of the sysroot directory for the build host.
14427 </para>
14428 </glossdef>
14429 </glossentry>
14430
14431 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
14432 <info>
14433 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."
14434 </info>
14435 <glossdef>
14436 <para role="glossdeffirst">
14437<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14438 Specifies the base path used to create recipe stamp files.
14439 The path to an actual stamp file is constructed by evaluating this
14440 string and then appending additional information.
14441 Currently, the default assignment for <filename>STAMP</filename>
14442 as set in the <filename>meta/conf/bitbake.conf</filename> file
14443 is:
14444 <literallayout class='monospaced'>
14445 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
14446 </literallayout>
14447 </para>
14448
14449 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014450 For information on how BitBake uses stamp files to determine
14451 if a task should be rerun, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040014452 "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
14453 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014454 </para>
14455
14456 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014457 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
14458 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
14459 <link linkend='var-PN'><filename>PN</filename></link>,
14460 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
14461 <link linkend='var-PV'><filename>PV</filename></link>, and
14462 <link linkend='var-PR'><filename>PR</filename></link> for related variable
14463 information.
14464 </para>
14465 </glossdef>
14466 </glossentry>
14467
14468 <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
14469 <info>
14470 STAMPS_DIR[doc] = "Specifies the base directory in which the OpenEmbedded build system places stamps."
14471 </info>
14472 <glossdef>
14473 <para role="glossdeffirst">
14474<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14475 Specifies the base directory in which the OpenEmbedded
14476 build system places stamps.
14477 The default directory is
14478 <filename>${TMPDIR}/stamps</filename>.
14479 </para>
14480 </glossdef>
14481 </glossentry>
14482
14483 <glossentry id='var-STRIP'><glossterm>STRIP</glossterm>
14484 <info>
14485 STRIP[doc] = "Minimal command and arguments to run 'strip' (strip symbols)."
14486 </info>
14487 <glossdef>
14488 <para role="glossdeffirst">
14489<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14490 The minimal command and arguments to run
14491 <filename>strip</filename>, which is used to strip
14492 symbols.
14493 </para>
14494 </glossdef>
14495 </glossentry>
14496
14497 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
14498 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014499 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 -050014500 </info>
14501 <glossdef>
14502 <para role="glossdeffirst">
14503<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14504 The short (72 characters or less) summary of the binary package for packaging
Brad Bishop316dfdd2018-06-25 12:45:53 -040014505 systems such as <filename>opkg</filename>, <filename>rpm</filename>, or
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014506 <filename>dpkg</filename>.
14507 By default, <filename>SUMMARY</filename> is used to define
14508 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
14509 variable if <filename>DESCRIPTION</filename> is not set
14510 in the recipe.
14511 </para>
14512 </glossdef>
14513 </glossentry>
14514
14515 <glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm>
14516 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014517 SVNDIR[doc] = "The directory where Subversion checkouts are stored."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014518 </info>
14519 <glossdef>
14520 <para role="glossdeffirst">
14521<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14522 The directory in which files checked out of a Subversion
14523 system are stored.
14524 </para>
14525 </glossdef>
14526 </glossentry>
14527
14528 <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm>
14529 <info>
14530 SYSLINUX_DEFAULT_CONSOLE[doc] = "Specifies the kernel boot default console."
14531 </info>
14532 <glossdef>
14533 <para role="glossdeffirst">
14534<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14535 Specifies the kernel boot default console.
14536 If you want to use a console other than the default,
14537 set this variable in your recipe as follows where "X" is
14538 the console number you want to use:
14539 <literallayout class='monospaced'>
14540 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
14541 </literallayout>
14542 </para>
14543
14544 <para>
14545 The
14546 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14547 class initially sets this variable to null but then checks
14548 for a value later.
14549 </para>
14550 </glossdef>
14551 </glossentry>
14552
14553 <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm>
14554 <info>
14555 SYSLINUX_OPTS[doc] = "Lists additional options to add to the syslinux file."
14556 </info>
14557 <glossdef>
14558 <para role="glossdeffirst">
14559<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14560 Lists additional options to add to the syslinux file.
14561 You need to set this variable in your recipe.
14562 If you want to list multiple options, separate the options
14563 with a semicolon character (<filename>;</filename>).
14564 </para>
14565
14566 <para>
14567 The
14568 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14569 class uses this variable to create a set of options.
14570 </para>
14571 </glossdef>
14572 </glossentry>
14573
14574 <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm>
14575 <info>
14576 SYSLINUX_SERIAL[doc] = "Specifies the alternate serial port or turns it off."
14577 </info>
14578 <glossdef>
14579 <para role="glossdeffirst">
14580<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14581 Specifies the alternate serial port or turns it off.
14582 To turn off serial, set this variable to an empty string
14583 in your recipe.
14584 The variable's default value is set in the
14585 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014586 class as follows:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014587 <literallayout class='monospaced'>
14588 SYSLINUX_SERIAL ?= "0 115200"
14589 </literallayout>
14590 </para>
14591
14592 <para>
14593 The class checks for and uses the variable as needed.
14594 </para>
14595 </glossdef>
14596 </glossentry>
14597
14598 <glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm>
14599 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014600 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 -050014601 </info>
14602 <glossdef>
14603 <para role="glossdeffirst">
14604<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14605 An <filename>.LSS</filename> file used as the background
Brad Bishop316dfdd2018-06-25 12:45:53 -040014606 for the VGA boot menu when you use the boot menu.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014607 You need to set this variable in your recipe.
14608 </para>
14609
14610 <para>
14611 The
14612 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14613 class checks for this variable and if found, the
14614 OpenEmbedded build system installs the splash screen.
14615 </para>
14616 </glossdef>
14617 </glossentry>
14618
14619 <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>
14620 <info>
14621 SYSLINUX_SERIAL_TTY[doc] = "Specifies the alternate console=tty... kernel boot argument."
14622 </info>
14623 <glossdef>
14624 <para role="glossdeffirst">
14625<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14626 Specifies the alternate console=tty... kernel boot argument.
14627 The variable's default value is set in the
14628 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014629 class as follows:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014630 <literallayout class='monospaced'>
14631 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
14632 </literallayout>
14633 </para>
14634
14635 <para>
14636 The class checks for and uses the variable as needed.
14637 </para>
14638 </glossdef>
14639 </glossentry>
14640
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014641 <glossentry id='var-SYSROOT_DESTDIR'><glossterm>SYSROOT_DESTDIR</glossterm>
14642 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014643 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 -050014644 </info>
14645 <glossdef>
14646 <para role="glossdeffirst">
14647<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14648 Points to the temporary directory under the work directory
14649 (default
Brad Bishopd7bf8c12018-02-25 22:55:05 -050014650 "<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/sysroot-destdir</filename>")
Brad Bishop316dfdd2018-06-25 12:45:53 -040014651 where the files populated into the sysroot are assembled
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014652 during the
14653 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14654 task.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014655 </para>
14656 </glossdef>
14657 </glossentry>
14658
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014659 <glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm>
14660 <info>
14661 SYSROOT_DIRS[doc] = "Directories that are staged into the sysroot by the do_populate_sysroot task."
14662 </info>
14663 <glossdef>
14664 <para role="glossdeffirst">
14665<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14666 Directories that are staged into the sysroot by the
14667 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14668 task.
14669 By default, the following directories are staged:
14670 <literallayout class='monospaced'>
14671 SYSROOT_DIRS = " \
14672 ${includedir} \
14673 ${libdir} \
14674 ${base_libdir} \
14675 ${nonarch_base_libdir} \
14676 ${datadir} \
14677 "
14678 </literallayout>
14679 </para>
14680 </glossdef>
14681 </glossentry>
14682
14683 <glossentry id='var-SYSROOT_DIRS_BLACKLIST'><glossterm>SYSROOT_DIRS_BLACKLIST</glossterm>
14684 <info>
14685 SYSROOT_DIRS_BLACKLIST[doc] = "Directories that are not staged into the sysroot by the do_populate_sysroot task."
14686 </info>
14687 <glossdef>
14688 <para role="glossdeffirst">
14689<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14690 Directories that are not staged into the sysroot by the
14691 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14692 task.
14693 You can use this variable to exclude certain subdirectories
14694 of directories listed in
14695 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
14696 from staging.
14697 By default, the following directories are not staged:
14698 <literallayout class='monospaced'>
14699 SYSROOT_DIRS_BLACKLIST = " \
14700 ${mandir} \
14701 ${docdir} \
14702 ${infodir} \
14703 ${datadir}/locale \
14704 ${datadir}/applications \
14705 ${datadir}/fonts \
14706 ${datadir}/pixmaps \
14707 "
14708 </literallayout>
14709 </para>
14710 </glossdef>
14711 </glossentry>
14712
14713 <glossentry id='var-SYSROOT_DIRS_NATIVE'><glossterm>SYSROOT_DIRS_NATIVE</glossterm>
14714 <info>
14715 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."
14716 </info>
14717 <glossdef>
14718 <para role="glossdeffirst">
14719<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14720 Extra directories staged into the sysroot by the
14721 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14722 task for <filename>-native</filename> recipes, in addition
14723 to those specified in
14724 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>.
14725 By default, the following extra directories are staged:
14726 <literallayout class='monospaced'>
14727 SYSROOT_DIRS_NATIVE = " \
14728 ${bindir} \
14729 ${sbindir} \
14730 ${base_bindir} \
14731 ${base_sbindir} \
14732 ${libexecdir} \
14733 ${sysconfdir} \
14734 ${localstatedir} \
14735 "
14736 </literallayout>
14737 <note>
14738 Programs built by <filename>-native</filename> recipes
14739 run directly from the sysroot
14740 (<link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>),
14741 which is why additional directories containing program
14742 executables and supporting files need to be staged.
14743 </note>
14744 </para>
14745 </glossdef>
14746 </glossentry>
14747
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014748 <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
14749 <info>
14750 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."
14751 </info>
14752 <glossdef>
14753 <para role="glossdeffirst">
14754<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14755 A list of functions to execute after files are staged into
14756 the sysroot.
14757 These functions are usually used to apply additional
14758 processing on the staged files, or to stage additional
14759 files.
14760 </para>
14761 </glossdef>
14762 </glossentry>
14763
14764 <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>
14765 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014766 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 -050014767 </info>
14768 <glossdef>
14769 <para role="glossdeffirst">
14770<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14771 When inheriting the
14772 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014773 class, this variable specifies whether the specified service
14774 in
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014775 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014776 should start automatically or not.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014777 By default, the service is enabled to automatically start
14778 at boot time.
14779 The default setting is in the
14780 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14781 class as follows:
14782 <literallayout class='monospaced'>
14783 SYSTEMD_AUTO_ENABLE ??= "enable"
14784 </literallayout>
14785 </para>
14786
14787 <para>
14788 You can disable the service by setting the variable to
14789 "disable".
14790 </para>
14791 </glossdef>
14792 </glossentry>
14793
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014794 <glossentry id='var-SYSTEMD_BOOT_CFG'><glossterm>SYSTEMD_BOOT_CFG</glossterm>
14795 <info>
14796 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."
14797 </info>
14798 <glossdef>
14799 <para role="glossdeffirst">
14800<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14801 When
14802 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14803 is set to "systemd-boot", the
14804 <filename>SYSTEMD_BOOT_CFG</filename> variable specifies the
14805 configuration file that should be used.
14806 By default, the
14807 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14808 class sets the <filename>SYSTEMD_BOOT_CFG</filename> as
14809 follows:
14810 <literallayout class='monospaced'>
14811 SYSTEMD_BOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf"
14812 </literallayout>
14813 </para>
14814
14815 <para>
14816 For information on Systemd-boot, see the
14817 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14818 </para>
14819 </glossdef>
14820 </glossentry>
14821
14822 <glossentry id='var-SYSTEMD_BOOT_ENTRIES'><glossterm>SYSTEMD_BOOT_ENTRIES</glossterm>
14823 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014824 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 -060014825 </info>
14826 <glossdef>
14827 <para role="glossdeffirst">
14828<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14829 When
14830 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14831 is set to "systemd-boot", the
14832 <filename>SYSTEMD_BOOT_ENTRIES</filename> variable specifies
14833 a list of entry files
Brad Bishop316dfdd2018-06-25 12:45:53 -040014834 (<filename>*.conf</filename>) to install that contain
14835 one boot entry per file.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014836 By default, the
14837 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14838 class sets the <filename>SYSTEMD_BOOT_ENTRIES</filename> as
14839 follows:
14840 <literallayout class='monospaced'>
14841 SYSTEMD_BOOT_ENTRIES ?= ""
14842 </literallayout>
14843 </para>
14844
14845 <para>
14846 For information on Systemd-boot, see the
14847 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14848 </para>
14849 </glossdef>
14850 </glossentry>
14851
14852 <glossentry id='var-SYSTEMD_BOOT_TIMEOUT'><glossterm>SYSTEMD_BOOT_TIMEOUT</glossterm>
14853 <info>
14854 SYSTEMD_BOOT_TIMEOUT[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_TIMEOUT variable specifies the boot menu timeout in seconds."
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_TIMEOUT</filename> variable specifies
14863 the boot menu timeout in seconds.
14864 By default, the
14865 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14866 class sets the <filename>SYSTEMD_BOOT_TIMEOUT</filename> as
14867 follows:
14868 <literallayout class='monospaced'>
14869 SYSTEMD_BOOT_TIMEOUT ?= "10"
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
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014880 <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>
14881 <info>
14882 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."
14883 </info>
14884 <glossdef>
14885 <para role="glossdeffirst">
14886<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14887 When inheriting the
14888 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14889 class, this variable locates the systemd unit files when
14890 they are not found in the main recipe's package.
14891 By default, the
14892 <filename>SYSTEMD_PACKAGES</filename> variable is set
14893 such that the systemd unit files are assumed to reside in
14894 the recipes main package:
14895 <literallayout class='monospaced'>
14896 SYSTEMD_PACKAGES ?= "${PN}"
14897 </literallayout>
14898 </para>
14899
14900 <para>
14901 If these unit files are not in this recipe's main
14902 package, you need to use
14903 <filename>SYSTEMD_PACKAGES</filename> to list the package
14904 or packages in which the build system can find the systemd
14905 unit files.
14906 </para>
14907 </glossdef>
14908 </glossentry>
14909
14910 <glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm>
14911 <info>
14912 SYSTEMD_SERVICE[doc] = "For recipes that inherit the systemd class, this variable specifies the systemd service name for a package."
14913 </info>
14914 <glossdef>
14915 <para role="glossdeffirst">
14916<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14917 When inheriting the
14918 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14919 class, this variable specifies the systemd service name for
14920 a package.
14921 </para>
14922
14923 <para>
14924 When you specify this file in your recipe, use a package
14925 name override to indicate the package to which the value
14926 applies.
14927 Here is an example from the connman recipe:
14928 <literallayout class='monospaced'>
14929 SYSTEMD_SERVICE_${PN} = "connman.service"
14930 </literallayout>
14931 </para>
14932 </glossdef>
14933 </glossentry>
14934
14935 <glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>SYSVINIT_ENABLED_GETTYS</glossterm>
14936 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014937 SYSVINIT_ENABLED_GETTYS[doc] = "Specifies which virtual terminals should run a getty, the default is '1'."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014938 </info>
14939 <glossdef>
14940 <para role="glossdeffirst">
14941<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14942 When using
14943 <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
14944 specifies a space-separated list of the virtual terminals
Brad Bishop316dfdd2018-06-25 12:45:53 -040014945 that should run a
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014946 <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
14947 (allowing login), assuming
14948 <link linkend='var-USE_VT'><filename>USE_VT</filename></link>
14949 is not set to "0".
14950 </para>
14951
14952 <para>
14953 The default value for
14954 <filename>SYSVINIT_ENABLED_GETTYS</filename> is "1"
14955 (i.e. only run a getty on the first virtual terminal).
14956 </para>
14957 </glossdef>
14958 </glossentry>
14959
14960 </glossdiv>
14961
14962 <glossdiv id='var-glossary-t'><title>T</title>
14963
14964 <glossentry id='var-T'><glossterm>T</glossterm>
14965 <info>
14966 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."
14967 </info>
14968 <glossdef>
14969 <para role="glossdeffirst">
14970<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14971 This variable points to a directory were BitBake places
14972 temporary files, which consist mostly of task logs and
14973 scripts, when building a particular recipe.
14974 The variable is typically set as follows:
14975 <literallayout class='monospaced'>
14976 T = "${WORKDIR}/temp"
14977 </literallayout>
14978 </para>
14979
14980 <para>
14981 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
14982 is the directory into which BitBake unpacks and builds the
14983 recipe.
14984 The default <filename>bitbake.conf</filename> file sets this variable.</para>
14985 <para>The <filename>T</filename> variable is not to be confused with
14986 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
14987 which points to the root of the directory tree where BitBake
14988 places the output of an entire build.
14989 </para>
14990 </glossdef>
14991 </glossentry>
14992
14993 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
14994 <info>
14995 TARGET_ARCH[doc] = "The architecture of the device being built. The OpenEmbedded build system supports the following architectures: arm, mips, ppc, x86, x86-64."
14996 </info>
14997 <glossdef>
14998 <para role="glossdeffirst">
14999<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15000 The target machine's architecture.
15001 The OpenEmbedded build system supports many
15002 architectures.
15003 Here is an example list of architectures supported.
15004 This list is by no means complete as the architecture
15005 is configurable:
15006 <literallayout class='monospaced'>
15007 arm
15008 i586
15009 x86_64
15010 powerpc
15011 powerpc64
15012 mips
15013 mipsel
15014 </literallayout>
15015 </para>
15016
15017 <para>
15018 For additional information on machine architectures, see
15019 the
15020 <link linkend='var-TUNE_ARCH'><filename>TUNE_ARCH</filename></link>
15021 variable.
15022 </para>
15023 </glossdef>
15024 </glossentry>
15025
15026 <glossentry id='var-TARGET_AS_ARCH'><glossterm>TARGET_AS_ARCH</glossterm>
15027 <info>
15028 TARGET_AS_ARCH[doc] = "Specifies architecture-specific assembler flags for the target system."
15029 </info>
15030 <glossdef>
15031 <para role="glossdeffirst">
15032<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15033 Specifies architecture-specific assembler flags for the
15034 target system.
15035 <filename>TARGET_AS_ARCH</filename> is initialized from
15036 <link linkend='var-TUNE_ASARGS'><filename>TUNE_ASARGS</filename></link>
15037 by default in the BitBake configuration file
15038 (<filename>meta/conf/bitbake.conf</filename>):
15039 <literallayout class='monospaced'>
15040 TARGET_AS_ARCH = "${TUNE_ASARGS}"
15041 </literallayout>
15042 </para>
15043 </glossdef>
15044 </glossentry>
15045
15046 <glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm>
15047 <info>
15048 TARGET_CC_ARCH[doc] = "Specifies architecture-specific C compiler flags for the target system."
15049 </info>
15050 <glossdef>
15051 <para role="glossdeffirst">
15052<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15053 Specifies architecture-specific C compiler flags for the
15054 target system.
15055 <filename>TARGET_CC_ARCH</filename> is initialized from
15056 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
15057 by default.
15058 <note>
15059 It is a common workaround to append
15060 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
15061 to <filename>TARGET_CC_ARCH</filename>
15062 in recipes that build software for the target that
15063 would not otherwise respect the exported
15064 <filename>LDFLAGS</filename> variable.
15065 </note>
15066 </para>
15067 </glossdef>
15068 </glossentry>
15069
15070 <glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm>
15071 <info>
15072 TARGET_CC_KERNEL_ARCH[doc] = "This is a specific kernel compiler flag for a CPU or Application Binary Interface (ABI) tune."
15073 </info>
15074 <glossdef>
15075 <para role="glossdeffirst">
15076<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15077 This is a specific kernel compiler flag for a CPU or
15078 Application Binary Interface (ABI) tune.
15079 The flag is used rarely and only for cases where a
15080 userspace
15081 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
15082 is not compatible with the kernel compilation.
15083 The <filename>TARGET_CC_KERNEL_ARCH</filename> variable
15084 allows the kernel (and associated modules) to use a
15085 different configuration.
15086 See the
15087 <filename>meta/conf/machine/include/arm/feature-arm-thumb.inc</filename>
15088 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015089 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015090 for an example.
15091 </para>
15092 </glossdef>
15093 </glossentry>
15094
15095 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
15096 <info>
15097 TARGET_CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as CFLAGS."
15098 </info>
15099 <glossdef>
15100 <para role="glossdeffirst">
15101<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15102 Specifies the flags to pass to the C compiler when building
15103 for the target.
15104 When building in the target context,
15105 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
15106 is set to the value of this variable by default.
15107 </para>
15108
15109 <para>
15110 Additionally, the SDK's environment setup script sets
Brad Bishop316dfdd2018-06-25 12:45:53 -040015111 the <filename>CFLAGS</filename> variable in the environment
15112 to the <filename>TARGET_CFLAGS</filename> value so that
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015113 executables built using the SDK also have the flags
15114 applied.
15115 </para>
15116 </glossdef>
15117 </glossentry>
15118
15119 <glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm>
15120 <info>
15121 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."
15122 </info>
15123 <glossdef>
15124 <para role="glossdeffirst">
15125<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15126 Specifies the flags to pass to the C pre-processor
15127 (i.e. to both the C and the C++ compilers) when building
15128 for the target.
15129 When building in the target context,
15130 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
15131 is set to the value of this variable by default.
15132 </para>
15133
15134 <para>
15135 Additionally, the SDK's environment setup script sets
Brad Bishop316dfdd2018-06-25 12:45:53 -040015136 the <filename>CPPFLAGS</filename> variable in the
15137 environment to the <filename>TARGET_CPPFLAGS</filename>
15138 value so that executables built using the SDK also have
15139 the flags applied.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015140 </para>
15141 </glossdef>
15142 </glossentry>
15143
15144 <glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm>
15145 <info>
15146 TARGET_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the target."
15147 </info>
15148 <glossdef>
15149 <para role="glossdeffirst">
15150<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15151 Specifies the flags to pass to the C++ compiler when
15152 building for the target.
15153 When building in the target context,
15154 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
15155 is set to the value of this variable by default.
15156 </para>
15157
15158 <para>
15159 Additionally, the SDK's environment setup script sets
Brad Bishop316dfdd2018-06-25 12:45:53 -040015160 the <filename>CXXFLAGS</filename> variable in the
15161 environment to the <filename>TARGET_CXXFLAGS</filename>
15162 value so that executables built using the SDK also have
15163 the flags applied.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015164 </para>
15165 </glossdef>
15166 </glossentry>
15167
15168 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
15169 <info>
15170 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."
15171 </info>
15172 <glossdef>
15173 <para role="glossdeffirst">
15174<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15175 Specifies the method for handling FPU code.
15176 For FPU-less targets, which include most ARM CPUs, the variable must be
15177 set to "soft".
15178 If not, the kernel emulation gets used, which results in a performance penalty.
15179 </para>
15180 </glossdef>
15181 </glossentry>
15182
15183 <glossentry id='var-TARGET_LD_ARCH'><glossterm>TARGET_LD_ARCH</glossterm>
15184 <info>
15185 TARGET_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the target system."
15186 </info>
15187 <glossdef>
15188 <para role="glossdeffirst">
15189<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15190 Specifies architecture-specific linker flags for the
15191 target system.
15192 <filename>TARGET_LD_ARCH</filename> is initialized from
15193 <link linkend='var-TUNE_LDARGS'><filename>TUNE_LDARGS</filename></link>
15194 by default in the BitBake configuration file
15195 (<filename>meta/conf/bitbake.conf</filename>):
15196 <literallayout class='monospaced'>
15197 TARGET_LD_ARCH = "${TUNE_LDARGS}"
15198 </literallayout>
15199 </para>
15200 </glossdef>
15201 </glossentry>
15202
15203 <glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm>
15204 <info>
15205 TARGET_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the target."
15206 </info>
15207 <glossdef>
15208 <para role="glossdeffirst">
15209<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15210 Specifies the flags to pass to the linker when building
15211 for the target.
15212 When building in the target context,
15213 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
15214 is set to the value of this variable by default.
15215 </para>
15216
15217 <para>
15218 Additionally, the SDK's environment setup script sets
15219 the
15220 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
15221 variable in the environment to the
15222 <filename>TARGET_LDFLAGS</filename> value so that
15223 executables built using the SDK also have the flags
15224 applied.
15225 </para>
15226 </glossdef>
15227 </glossentry>
15228
15229 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
15230 <info>
15231 TARGET_OS[doc] = "Specifies the target's operating system."
15232 </info>
15233 <glossdef>
15234 <para role="glossdeffirst">
15235<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15236 Specifies the target's operating system.
Brad Bishop316dfdd2018-06-25 12:45:53 -040015237 The variable can be set to "linux" for glibc-based systems
15238 (GNU C Library) and to "linux-musl" for musl libc.
15239 For ARM/EABI targets, "linux-gnueabi" and "linux-musleabi"
15240 possible values exist.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015241 </para>
15242 </glossdef>
15243 </glossentry>
15244
15245 <glossentry id='var-TARGET_PREFIX'><glossterm>TARGET_PREFIX</glossterm>
15246 <info>
15247 TARGET_PREFIX[doc] = "The prefix used for the toolchain binary target tools."
15248 </info>
15249 <glossdef>
15250 <para role="glossdeffirst">
15251<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15252 Specifies the prefix used for the toolchain binary target
15253 tools.
15254 </para>
15255
15256 <para>
15257 Depending on the type of recipe and the build target,
15258 <filename>TARGET_PREFIX</filename> is set as follows:
15259 <itemizedlist>
15260 <listitem><para>
15261 For recipes building for the target machine,
15262 the value is
15263 "${<link linkend='var-TARGET_SYS'>TARGET_SYS</link>}-".
15264 </para></listitem>
15265 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015266 For native recipes, the build system sets the
15267 variable to the value of
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015268 <filename>BUILD_PREFIX</filename>.
15269 </para></listitem>
15270 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015271 For native SDK recipes
15272 (<filename>nativesdk</filename>), the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015273 build system sets the variable to the value of
15274 <filename>SDK_PREFIX</filename>.
15275 </para></listitem>
15276 </itemizedlist>
15277 </para>
15278 </glossdef>
15279 </glossentry>
15280
15281 <glossentry id='var-TARGET_SYS'><glossterm>TARGET_SYS</glossterm>
15282 <info>
15283 TARGET_SYS[doc] = "The target system is comprised of TARGET_ARCH,TARGET_VENDOR and TARGET_OS."
15284 </info>
15285 <glossdef>
15286 <para role="glossdeffirst">
15287<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15288 Specifies the system, including the architecture and the
15289 operating system, for which the build is occurring in
15290 the context of the current recipe.
15291 </para>
15292
15293 <para>
15294 The OpenEmbedded build system automatically sets this
15295 variable based on
15296 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
15297 <link linkend='var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></link>,
15298 and
15299 <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>
15300 variables.
15301 <note>
15302 You do not need to set the
15303 <filename>TARGET_SYS</filename> variable yourself.
15304 </note>
15305 </para>
15306
15307 <para>
15308 Consider these two examples:
15309 <itemizedlist>
15310 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015311 Given a native recipe on a 32-bit, x86 machine
15312 running Linux, the value is "i686-linux".
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015313 </para></listitem>
15314 <listitem><para>
15315 Given a recipe being built for a little-endian,
15316 MIPS target running Linux, the value might be
15317 "mipsel-linux".
15318 </para></listitem>
15319 </itemizedlist>
15320 </para>
15321 </glossdef>
15322 </glossentry>
15323
15324 <glossentry id='var-TARGET_VENDOR'><glossterm>TARGET_VENDOR</glossterm>
15325 <info>
15326 TARGET_VENDOR[doc] = "The name of the target vendor."
15327 </info>
15328 <glossdef>
15329 <para role="glossdeffirst">
15330<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15331 Specifies the name of the target vendor.
15332 </para>
15333 </glossdef>
15334 </glossentry>
15335
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015336 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
15337 <info>
15338 TCLIBC[doc] = "Specifies GNU standard C library (libc) variant to use during the build process. You can select 'glibc', 'musl' or "newlib."
15339 </info>
15340 <glossdef>
15341 <para role="glossdeffirst">
15342<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15343 Specifies the GNU standard C library
15344 (<filename>libc</filename>) variant to use during the
15345 build process.
15346 This variable replaces <filename>POKYLIBC</filename>,
15347 which is no longer supported.
15348 </para>
15349
15350 <para>
15351 You can select "glibc", "musl", "newlib", or "baremetal"
15352 </para>
15353 </glossdef>
15354 </glossentry>
15355
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015356 <glossentry id='var-TCLIBCAPPEND'><glossterm>TCLIBCAPPEND</glossterm>
15357 <info>
15358 TCLIBCAPPEND[doc] = "Specifies a suffix appended to TMPDIR that identifies the libc variant for the build."
15359 </info>
15360 <glossdef>
15361 <para role="glossdeffirst">
15362<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15363 Specifies a suffix to be appended onto the
15364 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
15365 value.
15366 The suffix identifies the <filename>libc</filename> variant
15367 for building.
15368 When you are building for multiple variants with the same
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015369 <link linkend='build-directory'>Build Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015370 this mechanism ensures that output for different
15371 <filename>libc</filename> variants is kept separate to
15372 avoid potential conflicts.
15373 </para>
15374
15375 <para>
15376 In the <filename>defaultsetup.conf</filename> file, the
15377 default value of <filename>TCLIBCAPPEND</filename> is
15378 "-${TCLIBC}".
15379 However, distros such as poky, which normally only support
15380 one <filename>libc</filename> variant, set
15381 <filename>TCLIBCAPPEND</filename> to "" in their distro
15382 configuration file resulting in no suffix being applied.
15383 </para>
15384 </glossdef>
15385 </glossentry>
15386
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015387 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
15388 <info>
15389 TCMODE[doc] = "Enables an external toolchain (where provided by an additional layer) if set to a value other than 'default'."
15390 </info>
15391 <glossdef>
15392 <para role="glossdeffirst">
15393<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15394 Specifies the toolchain selector.
15395 <filename>TCMODE</filename> controls the characteristics
15396 of the generated packages and images by telling the
15397 OpenEmbedded build system which toolchain profile to use.
15398 By default, the OpenEmbedded build system builds its own
15399 internal toolchain.
15400 The variable's default value is "default", which uses
15401 that internal toolchain.
15402 <note>
15403 If <filename>TCMODE</filename> is set to a value
15404 other than "default", then it is your responsibility
15405 to ensure that the toolchain is compatible with the
15406 default toolchain.
15407 Using older or newer versions of these components
15408 might cause build problems.
Brad Bishop316dfdd2018-06-25 12:45:53 -040015409 See the Release Notes for the Yocto Project release
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015410 for the specific components with which the toolchain
15411 must be compatible.
Brad Bishop316dfdd2018-06-25 12:45:53 -040015412 To access the Release Notes, go to the
15413 <ulink url='&YOCTO_HOME_URL;/software-overview/downloads/'>Downloads</ulink>
15414 page on the Yocto Project website and click on the
15415 "RELEASE INFORMATION" link for the appropriate
15416 release.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015417 </note>
15418 </para>
15419
15420 <para>
15421 The <filename>TCMODE</filename> variable is similar to
15422 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
15423 which controls the variant of the GNU standard C library
15424 (<filename>libc</filename>) used during the build process:
Brad Bishop37a0e4d2017-12-04 01:01:44 -050015425 <filename>glibc</filename> or <filename>musl</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015426 </para>
15427
15428 <para>
15429 With additional layers, it is possible to use a pre-compiled
15430 external toolchain.
15431 One example is the Sourcery G++ Toolchain.
15432 The support for this toolchain resides in the separate
15433 <trademark class='registered'>Mentor Graphics</trademark>
15434 <filename>meta-sourcery</filename> layer at
15435 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
15436 </para>
15437
15438 <para>
15439 The layer's <filename>README</filename> file contains
15440 information on how to use the Sourcery G++ Toolchain as
15441 an external toolchain.
15442 In summary, you must be sure to add the layer to your
15443 <filename>bblayers.conf</filename> file in front of the
15444 <filename>meta</filename> layer and then set the
15445 <filename>EXTERNAL_TOOLCHAIN</filename>
15446 variable in your <filename>local.conf</filename> file
15447 to the location in which you installed the toolchain.
15448 </para>
15449
15450 <para>
15451 The fundamentals used for this example apply to any
15452 external toolchain.
15453 You can use <filename>meta-sourcery</filename> as a
15454 template for adding support for other external toolchains.
15455 </para>
15456 </glossdef>
15457 </glossentry>
15458
15459 <glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>
15460 <info>
15461 TEST_EXPORT_DIR[doc] = "The location the OpenEmbedded build system uses to export tests when the TEST_EXPORT_ONLY variable is set to "1"."
15462 </info>
15463 <glossdef>
15464 <para role="glossdeffirst">
15465<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15466 The location the OpenEmbedded build system uses to export
15467 tests when the
15468 <link linkend='var-TEST_EXPORT_ONLY'><filename>TEST_EXPORT_ONLY</filename></link>
15469 variable is set to "1".
15470 </para>
15471
15472 <para>
15473 The <filename>TEST_EXPORT_DIR</filename> variable defaults
15474 to <filename>"${TMPDIR}/testimage/${PN}"</filename>.
15475 </para>
15476 </glossdef>
15477 </glossentry>
15478
15479 <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>
15480 <info>
15481 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."
15482 </info>
15483 <glossdef>
15484 <para role="glossdeffirst">
15485<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15486 Specifies to export the tests only.
15487 Set this variable to "1" if you do not want to run the
15488 tests but you want them to be exported in a manner that
15489 you to run them outside of the build system.
15490 </para>
15491 </glossdef>
15492 </glossentry>
15493
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015494 <glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm>
15495 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040015496 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 -050015497 </info>
15498 <glossdef>
15499 <para role="glossdeffirst">
15500<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15501 Holds the SSH log and the boot log for QEMU machines.
15502 The <filename>TEST_LOG_DIR</filename> variable defaults
15503 to <filename>"${WORKDIR}/testimage"</filename>.
15504 <note>
15505 Actual test results reside in the task log
15506 (<filename>log.do_testimage</filename>), which is in
15507 the <filename>${WORKDIR}/temp/</filename> directory.
15508 </note>
15509 </para>
15510 </glossdef>
15511 </glossentry>
15512
15513 <glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm>TEST_POWERCONTROL_CMD</glossterm>
15514 <info>
15515 TEST_POWERCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to control the power of the target machine under test"
15516 </info>
15517 <glossdef>
15518 <para role="glossdeffirst">
15519<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15520 For automated hardware testing, specifies the command to
15521 use to control the power of the target machine under test.
15522 Typically, this command would point to a script that
15523 performs the appropriate action (e.g. interacting
15524 with a web-enabled power strip).
15525 The specified command should expect to receive as the last
15526 argument "off", "on" or "cycle" specifying to power off,
15527 on, or cycle (power off and then power on) the device,
15528 respectively.
15529 </para>
15530 </glossdef>
15531 </glossentry>
15532
15533 <glossentry id='var-TEST_POWERCONTROL_EXTRA_ARGS'><glossterm>TEST_POWERCONTROL_EXTRA_ARGS</glossterm>
15534 <info>
15535 TEST_POWERCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_POWERCONTROL_CMD"
15536 </info>
15537 <glossdef>
15538 <para role="glossdeffirst">
15539<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15540 For automated hardware testing, specifies additional
15541 arguments to pass through to the command specified in
15542 <link linkend='var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></link>.
15543 Setting <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
15544 is optional.
15545 You can use it if you wish, for example, to separate the
15546 machine-specific and non-machine-specific parts of the
15547 arguments.
15548 </para>
15549 </glossdef>
15550 </glossentry>
15551
15552 <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
15553 <info>
15554 TEST_QEMUBOOT_TIMEOUT[doc] = "The time in seconds allowed for an image to boot before automated runtime tests begin to run against an image."
15555 </info>
15556 <glossdef>
15557 <para role="glossdeffirst">
15558<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15559 The time in seconds allowed for an image to boot before
15560 automated runtime tests begin to run against an
15561 image.
15562 The default timeout period to allow the boot process to
15563 reach the login prompt is 500 seconds.
15564 You can specify a different value in the
15565 <filename>local.conf</filename> file.
15566 </para>
15567
15568 <para>
15569 For more information on testing images, see the
15570 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015571 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015572 </para>
15573 </glossdef>
15574 </glossentry>
15575
15576 <glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm>TEST_SERIALCONTROL_CMD</glossterm>
15577 <info>
15578 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."
15579 </info>
15580 <glossdef>
15581 <para role="glossdeffirst">
15582<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15583 For automated hardware testing, specifies the command
15584 to use to connect to the serial console of the target
15585 machine under test.
15586 This command simply needs to connect to the serial console
15587 and forward that connection to standard input and output
15588 as any normal terminal program does.
15589 </para>
15590
15591 <para>
15592 For example, to use the Picocom terminal program on
15593 serial device <filename>/dev/ttyUSB0</filename> at
15594 115200bps, you would set the variable as follows:
15595 <literallayout class='monospaced'>
15596 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
15597 </literallayout>
15598 </para>
15599 </glossdef>
15600 </glossentry>
15601
15602 <glossentry id='var-TEST_SERIALCONTROL_EXTRA_ARGS'><glossterm>TEST_SERIALCONTROL_EXTRA_ARGS</glossterm>
15603 <info>
15604 TEST_SERIALCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_SERIALCONTROL_CMD."
15605 </info>
15606 <glossdef>
15607 <para role="glossdeffirst">
15608<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15609 For automated hardware testing, specifies additional
15610 arguments to pass through to the command specified in
15611 <link linkend='var-TEST_SERIALCONTROL_CMD'><filename>TEST_SERIALCONTROL_CMD</filename></link>.
15612 Setting <filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename>
15613 is optional.
15614 You can use it if you wish, for example, to separate the
15615 machine-specific and non-machine-specific parts of the
15616 command.
15617 </para>
15618 </glossdef>
15619 </glossentry>
15620
15621 <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>
15622 <info>
15623 TEST_SERVER_IP[doc] = "The IP address of the build machine (host machine). This IP address is usually automatically detected."
15624 </info>
15625 <glossdef>
15626 <para role="glossdeffirst">
15627<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15628 The IP address of the build machine (host machine).
15629 This IP address is usually automatically detected.
15630 However, if detection fails, this variable needs to be set
15631 to the IP address of the build machine (i.e. where
15632 the build is taking place).
15633 <note>
15634 The <filename>TEST_SERVER_IP</filename> variable
15635 is only used for a small number of tests such as
Brad Bishop6e60e8b2018-02-01 10:27:11 -050015636 the "dnf" test suite, which needs to download
15637 packages from
15638 <filename>WORKDIR/oe-rootfs-repo</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015639 </note>
15640 </para>
15641 </glossdef>
15642 </glossentry>
15643
15644 <glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>
15645 <info>
15646 TEST_TARGET[doc] = "For automated runtime testing, specifies the method of deploying the image and running tests on the target machine."
15647 </info>
15648 <glossdef>
15649 <para role="glossdeffirst">
15650<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15651 Specifies the target controller to use when running tests
15652 against a test image.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015653 The default controller to use is "QemuTarget":
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015654 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015655 TEST_TARGET = "QemuTarget"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015656 </literallayout>
15657 </para>
15658
15659 <para>
15660 A target controller is a class that defines how an
15661 image gets deployed on a target and how a target is started.
15662 A layer can extend the controllers by adding a module
15663 in the layer's <filename>/lib/oeqa/controllers</filename>
15664 directory and by inheriting the
15665 <filename>BaseTarget</filename> class, which is an abstract
15666 class that cannot be used as a value of
15667 <filename>TEST_TARGET</filename>.
15668 </para>
15669
15670 <para>
15671 You can provide the following arguments with
15672 <filename>TEST_TARGET</filename>:
15673 <itemizedlist>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015674 <listitem><para><emphasis>"QemuTarget":</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015675 Boots a QEMU image and runs the tests.
15676 See the
15677 "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015678 section in the Yocto Project Development Tasks
15679 Manual for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015680 </para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015681 <listitem><para><emphasis>"SimpleRemoteTarget":</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015682 Runs the tests on target hardware that is already
15683 up and running.
15684 The hardware can be on the network or it can be
15685 a device running an image on QEMU.
15686 You must also set
15687 <link linkend='var-TEST_TARGET_IP'><filename>TEST_TARGET_IP</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015688 when you use "SimpleRemoteTarget".
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015689 <note>
15690 This argument is defined in
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015691 <filename>meta/lib/oeqa/controllers/simpleremote.py</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015692 </note>
15693 </para></listitem>
15694 </itemizedlist>
15695 </para>
15696
15697 <para>
15698 For information on running tests on hardware, see the
15699 "<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015700 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015701 </para>
15702 </glossdef>
15703 </glossentry>
15704
15705 <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>
15706 <info>
15707 TEST_TARGET_IP[doc] = "The IP address of your hardware under test."
15708 </info>
15709 <glossdef>
15710 <para role="glossdeffirst">
15711<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15712 The IP address of your hardware under test.
15713 The <filename>TEST_TARGET_IP</filename> variable has no
15714 effect when
15715 <link linkend='var-TEST_TARGET'><filename>TEST_TARGET</filename></link>
15716 is set to "qemu".
15717 </para>
15718
15719 <para>
15720 When you specify the IP address, you can also include a
15721 port.
15722 Here is an example:
15723 <literallayout class='monospaced'>
15724 TEST_TARGET_IP = "192.168.1.4:2201"
15725 </literallayout>
15726 Specifying a port is useful when SSH is started on a
15727 non-standard port or in cases when your hardware under test
15728 is behind a firewall or network that is not directly
15729 accessible from your host and you need to do port address
15730 translation.
15731 </para>
15732 </glossdef>
15733 </glossentry>
15734
15735 <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
15736 <info>
15737 TEST_SUITES[doc] = "An ordered list of tests (modules) to run against an image when performing automated runtime testing."
15738 </info>
15739 <glossdef>
15740 <para role="glossdeffirst">
15741<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15742 An ordered list of tests (modules) to run against
15743 an image when performing automated runtime testing.
15744 </para>
15745
15746 <para>
15747 The OpenEmbedded build system provides a core set of tests
15748 that can be used against images.
15749 <note>
15750 Currently, there is only support for running these tests
15751 under QEMU.
15752 </note>
15753 Tests include <filename>ping</filename>,
15754 <filename>ssh</filename>, <filename>df</filename> among
15755 others.
15756 You can add your own tests to the list of tests by
15757 appending <filename>TEST_SUITES</filename> as follows:
15758 <literallayout class='monospaced'>
15759 TEST_SUITES_append = " <replaceable>mytest</replaceable>"
15760 </literallayout>
15761 Alternatively, you can provide the "auto" option to
15762 have all applicable tests run against the image.
15763 <literallayout class='monospaced'>
15764 TEST_SUITES_append = " auto"
15765 </literallayout>
15766 Using this option causes the build system to automatically
15767 run tests that are applicable to the image.
15768 Tests that are not applicable are skipped.
15769 </para>
15770
15771 <para>
15772 The order in which tests are run is important.
15773 Tests that depend on another test must appear later in the
15774 list than the test on which they depend.
15775 For example, if you append the list of tests with two
15776 tests (<filename>test_A</filename> and
15777 <filename>test_B</filename>) where
15778 <filename>test_B</filename> is dependent on
15779 <filename>test_A</filename>, then you must order the tests
15780 as follows:
15781 <literallayout class='monospaced'>
15782 TEST_SUITES = " test_A test_B"
15783 </literallayout>
15784 </para>
15785
15786 <para>
15787 For more information on testing images, see the
15788 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015789 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015790 </para>
15791 </glossdef>
15792 </glossentry>
15793
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015794 <glossentry id='var-TESTIMAGE_AUTO'><glossterm>TESTIMAGE_AUTO</glossterm>
15795 <info>
15796 TESTIMAGE_AUTO[doc] = "Enables automatic testing of an image once it is built."
15797 </info>
15798 <glossdef>
15799 <para role="glossdeffirst">
15800<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15801 Automatically runs the series of automated tests for
15802 images when an image is successfully built.
15803 Setting <filename>TESTIMAGE_AUTO</filename> to "1"
15804 causes any image that successfully builds to automatically
15805 boot under QEMU.
15806 Using the variable also adds in dependencies so that any
15807 SDK for which testing is requested is automatically built
15808 first.
15809 </para>
15810
15811 <para>
15812 These tests are written in Python making use of the
15813 <filename>unittest</filename> module, and the majority of
15814 them run commands on the target system over
15815 <filename>ssh</filename>.
15816 You can set this variable to "1" in your
15817 <filename>local.conf</filename> file in the
15818 <link linkend='build-directory'>Build Directory</link>
15819 to have the OpenEmbedded build system automatically run
15820 these tests after an image successfully builds:
15821 <literallayout class='monospaced'>
15822 TESTIMAGE_AUTO = "1"
15823 </literallayout>
15824 For more information on enabling, running, and writing
15825 these tests, see the
15826 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
15827 section in the Yocto Project Development Tasks Manual and
15828 the
15829 "<link linkend='ref-classes-testimage*'><filename>testimage*.bbclass</filename></link>"
15830 section.
15831 </para>
15832 </glossdef>
15833 </glossentry>
15834
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015835 <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
15836 <info>
15837 THISDIR[doc] = "The directory in which the file BitBake is currently parsing is located."
15838 </info>
15839 <glossdef>
15840 <para role="glossdeffirst">
15841<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15842 The directory in which the file BitBake is currently
15843 parsing is located.
15844 Do not manually set this variable.
15845 </para>
15846 </glossdef>
15847 </glossentry>
15848
15849 <glossentry id='var-TIME'><glossterm>TIME</glossterm>
15850 <info>
15851 TIME[doc] = "The time the build was started using HMS format."
15852 </info>
15853 <glossdef>
15854 <para role="glossdeffirst">
15855<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15856 The time the build was started.
15857 Times appear using the hour, minute, and second (HMS)
15858 format (e.g. "140159" for one minute and fifty-nine
15859 seconds past 1400 hours).
15860 </para>
15861 </glossdef>
15862 </glossentry>
15863
15864 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
15865 <info>
15866 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."
15867 </info>
15868 <glossdef>
15869 <para role="glossdeffirst">
15870<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15871 This variable is the base directory the OpenEmbedded
15872 build system uses for all build output and intermediate
15873 files (other than the shared state cache).
15874 By default, the <filename>TMPDIR</filename> variable points
15875 to <filename>tmp</filename> within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015876 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015877 </para>
15878
15879 <para>
15880 If you want to establish this directory in a location other
15881 than the default, you can uncomment and edit the following
15882 statement in the
15883 <filename>conf/local.conf</filename> file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015884 <link linkend='source-directory'>Source Directory</link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015885 <literallayout class='monospaced'>
15886 #TMPDIR = "${TOPDIR}/tmp"
15887 </literallayout>
15888 An example use for this scenario is to set
15889 <filename>TMPDIR</filename> to a local disk, which does
15890 not use NFS, while having the Build Directory use NFS.
15891 </para>
15892
15893 <para>
15894 The filesystem used by <filename>TMPDIR</filename> must
15895 have standard filesystem semantics (i.e. mixed-case files
15896 are unique, POSIX file locking, and persistent inodes).
15897 Due to various issues with NFS and bugs in some
15898 implementations, NFS does not meet this minimum
15899 requirement.
15900 Consequently, <filename>TMPDIR</filename> cannot be on
15901 NFS.
15902 </para>
15903 </glossdef>
15904 </glossentry>
15905
15906 <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
15907 <info>
15908 TOOLCHAIN_HOST_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when building an SDK, which contains a cross-development environment."
15909 </info>
15910 <glossdef>
15911 <para role="glossdeffirst">
15912<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15913 This variable lists packages the OpenEmbedded build system
15914 uses when building an SDK, which contains a
15915 cross-development environment.
15916 The packages specified by this variable are part of the
15917 toolchain set that runs on the
15918 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
15919 and each package should usually have the prefix
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015920 <filename>nativesdk-</filename>.
15921 For example, consider the following command when
15922 building an SDK:
15923 <literallayout class='monospaced'>
15924 $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
15925 </literallayout>
15926 In this case, a default list of packages is set in this
15927 variable, but you can add additional packages to the list.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050015928 See the
15929 "<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 -050015930 section in the Yocto Project Application Development and
15931 the Extensible Software Development Kit (eSDK) manual
15932 for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015933 </para>
15934
15935 <para>
15936 For background information on cross-development toolchains
15937 in the Yocto Project development environment, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040015938 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
15939 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015940 For information on setting up a cross-development
15941 environment, see the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015942 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
15943 manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015944 </para>
15945 </glossdef>
15946 </glossentry>
15947
15948 <glossentry id='var-TOOLCHAIN_OUTPUTNAME'><glossterm>TOOLCHAIN_OUTPUTNAME</glossterm>
15949 <info>
15950 TOOLCHAIN_OUTPUTNAME[doc] = "Defines the name used for the toolchain output."
15951 </info>
15952 <glossdef>
15953 <para role="glossdeffirst">
15954<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15955 This variable defines the name used for the toolchain
15956 output.
15957 The
15958 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
15959 class sets the
15960 <filename>TOOLCHAIN_OUTPUTNAME</filename> variable as
15961 follows:
15962 <literallayout class='monospaced'>
15963 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"
15964 </literallayout>
15965 See the
15966 <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
15967 and
15968 <link linkend='var-SDK_VERSION'><filename>SDK_VERSION</filename></link>
15969 variables for additional information.
15970 </para>
15971 </glossdef>
15972 </glossentry>
15973
15974 <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
15975 <info>
15976 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."
15977 </info>
15978 <glossdef>
15979 <para role="glossdeffirst">
15980<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15981 This variable lists packages the OpenEmbedded build system
15982 uses when it creates the target part of an SDK
15983 (i.e. the part built for the target hardware), which
15984 includes libraries and headers.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050015985 Use this variable to add individual packages to the
15986 part of the SDK that runs on the target.
15987 See the
15988 "<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 -050015989 section in the Yocto Project Application Development and
15990 the Extensible Software Development Kit (eSDK) manual for
15991 more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015992 </para>
15993
15994 <para>
15995 For background information on cross-development toolchains
15996 in the Yocto Project development environment, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040015997 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
15998 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015999 For information on setting up a cross-development
16000 environment, see the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016001 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
16002 manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016003 </para>
16004 </glossdef>
16005 </glossentry>
16006
16007 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
16008 <info>
16009 TOPDIR[doc] = "The Build Directory. BitBake automatically sets this variable. The OpenEmbedded build system uses the Build Directory when building images."
16010 </info>
16011 <glossdef>
16012 <para role="glossdeffirst">
16013<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16014 The top-level
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016015 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016016 BitBake automatically sets this variable when you
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016017 initialize your build environment using
16018 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016019 </para>
16020 </glossdef>
16021 </glossentry>
16022
16023 <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
16024 <info>
16025 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."
16026 </info>
16027 <glossdef>
16028 <para role="glossdeffirst">
16029<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16030 A sanitized version of
16031 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
16032 This variable is used where the architecture is needed in
16033 a value where underscores are not allowed, for example
16034 within package filenames.
16035 In this case, dash characters replace any underscore
Brad Bishop316dfdd2018-06-25 12:45:53 -040016036 characters used in <filename>TARGET_ARCH</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016037 </para>
16038
16039 <para>
16040 Do not edit this variable.
16041 </para>
16042 </glossdef>
16043 </glossentry>
16044
16045 <glossentry id='var-TUNE_ARCH'><glossterm>TUNE_ARCH</glossterm>
16046 <info>
16047 TUNE_ARCH[doc] = "The GNU canonical architecture for a specific architecture (i.e. arm, armeb, mips, mips64, and so forth)."
16048 </info>
16049 <glossdef>
16050 <para role="glossdeffirst">
16051<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16052 The GNU canonical architecture for a specific architecture
16053 (i.e. <filename>arm</filename>,
16054 <filename>armeb</filename>,
16055 <filename>mips</filename>,
16056 <filename>mips64</filename>, and so forth).
16057 BitBake uses this value to setup configuration.
16058 </para>
16059
16060 <para>
16061 <filename>TUNE_ARCH</filename> definitions are specific to
16062 a given architecture.
16063 The definitions can be a single static definition, or
16064 can be dynamically adjusted.
16065 You can see details for a given CPU family by looking at
16066 the architecture's <filename>README</filename> file.
16067 For example, the
16068 <filename>meta/conf/machine/include/mips/README</filename>
16069 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016070 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016071 provides information for <filename>TUNE_ARCH</filename>
16072 specific to the <filename>mips</filename> architecture.
16073 </para>
16074
16075 <para>
16076 <filename>TUNE_ARCH</filename> is tied closely to
16077 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
16078 which defines the target machine's architecture.
16079 The BitBake configuration file
16080 (<filename>meta/conf/bitbake.conf</filename>) sets
16081 <filename>TARGET_ARCH</filename> as follows:
16082 <literallayout class='monospaced'>
16083 TARGET_ARCH = "${TUNE_ARCH}"
16084 </literallayout>
16085 </para>
16086
16087 <para>
16088 The following list, which is by no means complete since
16089 architectures are configurable, shows supported machine
16090 architectures:
16091 <literallayout class='monospaced'>
16092 arm
16093 i586
16094 x86_64
16095 powerpc
16096 powerpc64
16097 mips
16098 mipsel
16099 </literallayout>
16100 </para>
16101 </glossdef>
16102 </glossentry>
16103
16104 <glossentry id='var-TUNE_ASARGS'><glossterm>TUNE_ASARGS</glossterm>
16105 <info>
16106 TUNE_ASARGS[doc] = "Specifies architecture-specific assembler flags for the target system."
16107 </info>
16108 <glossdef>
16109 <para role="glossdeffirst">
16110<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16111 Specifies architecture-specific assembler flags for
16112 the target system.
16113 The set of flags is based on the selected tune features.
16114 <filename>TUNE_ASARGS</filename> is set using
16115 the tune include files, which are typically under
16116 <filename>meta/conf/machine/include/</filename> and are
16117 influenced through
16118 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
16119 For example, the
16120 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
16121 file defines the flags for the x86 architecture as follows:
16122 <literallayout class='monospaced'>
16123 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
16124 </literallayout>
16125 <note>
16126 Board Support Packages (BSPs) select the tune.
16127 The selected tune, in turn, affects the tune variables
16128 themselves (i.e. the tune can supply its own
16129 set of flags).
16130 </note>
16131 </para>
16132 </glossdef>
16133 </glossentry>
16134
16135 <glossentry id='var-TUNE_CCARGS'><glossterm>TUNE_CCARGS</glossterm>
16136 <info>
16137 TUNE_CCARGS[doc] = "Specifies architecture-specific C compiler flags for the target system."
16138 </info>
16139 <glossdef>
16140 <para role="glossdeffirst">
16141<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16142 Specifies architecture-specific C compiler flags for
16143 the target system.
16144 The set of flags is based on the selected tune features.
16145 <filename>TUNE_CCARGS</filename> is set using
16146 the tune include files, which are typically under
16147 <filename>meta/conf/machine/include/</filename> and are
16148 influenced through
16149 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
16150 <note>
16151 Board Support Packages (BSPs) select the tune.
16152 The selected tune, in turn, affects the tune variables
16153 themselves (i.e. the tune can supply its own
16154 set of flags).
16155 </note>
16156 </para>
16157 </glossdef>
16158 </glossentry>
16159
16160 <glossentry id='var-TUNE_LDARGS'><glossterm>TUNE_LDARGS</glossterm>
16161 <info>
16162 TUNE_LDARGS[doc] = "Specifies architecture-specific linker flags for the target system."
16163 </info>
16164 <glossdef>
16165 <para role="glossdeffirst">
16166<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16167 Specifies architecture-specific linker flags for
16168 the target system.
16169 The set of flags is based on the selected tune features.
16170 <filename>TUNE_LDARGS</filename> is set using
16171 the tune include files, which are typically under
16172 <filename>meta/conf/machine/include/</filename> and are
16173 influenced through
16174 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
16175 For example, the
16176 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
16177 file defines the flags for the x86 architecture as follows:
16178 <literallayout class='monospaced'>
16179 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
16180 </literallayout>
16181 <note>
16182 Board Support Packages (BSPs) select the tune.
16183 The selected tune, in turn, affects the tune variables
16184 themselves (i.e. the tune can supply its own
16185 set of flags).
16186 </note>
16187 </para>
16188 </glossdef>
16189 </glossentry>
16190
16191 <glossentry id='var-TUNE_FEATURES'><glossterm>TUNE_FEATURES</glossterm>
16192 <info>
16193 TUNE_FEATURES[doc] = "Features used to "tune" a compiler for optimal use given a specific processor."
16194 </info>
16195 <glossdef>
16196 <para role="glossdeffirst">
16197<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16198 Features used to "tune" a compiler for optimal use
16199 given a specific processor.
16200 The features are defined within the tune files and allow
16201 arguments (i.e. <filename>TUNE_*ARGS</filename>) to be
16202 dynamically generated based on the features.
16203 </para>
16204
16205 <para>
16206 The OpenEmbedded build system verifies the features
16207 to be sure they are not conflicting and that they are
16208 supported.
16209 </para>
16210
16211 <para>
16212 The BitBake configuration file
16213 (<filename>meta/conf/bitbake.conf</filename>) defines
16214 <filename>TUNE_FEATURES</filename> as follows:
16215 <literallayout class='monospaced'>
16216 TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}"
16217 </literallayout>
16218 See the
16219 <link linkend='var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></link>
16220 variable for more information.
16221 </para>
16222 </glossdef>
16223 </glossentry>
16224
16225 <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
16226 <info>
16227 TUNE_PKGARCH[doc] = "The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages."
16228 </info>
16229 <glossdef>
16230 <para role="glossdeffirst">
16231<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16232 The package architecture understood by the packaging
16233 system to define the architecture, ABI, and tuning of
16234 output packages.
16235 The specific tune is defined using the "_tune" override
16236 as follows:
16237 <literallayout class='monospaced'>
16238 TUNE_PKGARCH_tune-<replaceable>tune</replaceable> = "<replaceable>tune</replaceable>"
16239 </literallayout>
16240 </para>
16241
16242 <para>
16243 These tune-specific package architectures are defined in
16244 the machine include files.
16245 Here is an example of the "core2-32" tuning as used
16246 in the
16247 <filename>meta/conf/machine/include/tune-core2.inc</filename>
16248 file:
16249 <literallayout class='monospaced'>
16250 TUNE_PKGARCH_tune-core2-32 = "core2-32"
16251 </literallayout>
16252 </para>
16253 </glossdef>
16254 </glossentry>
16255
16256 <glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm>
16257 <info>
16258 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."
16259 </info>
16260 <glossdef>
16261 <para role="glossdeffirst">
16262<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16263 An underlying Application Binary Interface (ABI) used by
16264 a particular tuning in a given toolchain layer.
16265 Providers that use prebuilt libraries can use the
16266 <filename>TUNEABI</filename>,
16267 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
16268 and
16269 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
16270 variables to check compatibility of tunings against their
16271 selection of libraries.
16272 </para>
16273
16274 <para>
16275 If <filename>TUNEABI</filename> is undefined, then every
16276 tuning is allowed.
16277 See the
16278 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
16279 class to see how the variable is used.
16280 </para>
16281 </glossdef>
16282 </glossentry>
16283
16284 <glossentry id='var-TUNEABI_OVERRIDE'><glossterm>TUNEABI_OVERRIDE</glossterm>
16285 <info>
16286 TUNEABI_OVERRIDE[doc] = "If set, ignores TUNEABI_WHITELIST."
16287 </info>
16288 <glossdef>
16289 <para role="glossdeffirst">
16290<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16291 If set, the OpenEmbedded system ignores the
16292 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
16293 variable.
16294 Providers that use prebuilt libraries can use the
16295 <filename>TUNEABI_OVERRIDE</filename>,
16296 <filename>TUNEABI_WHITELIST</filename>,
16297 and
16298 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
16299 variables to check compatibility of a tuning against their
16300 selection of libraries.
16301 </para>
16302
16303 <para>
16304 See the
16305 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
16306 class to see how the variable is used.
16307 </para>
16308 </glossdef>
16309 </glossentry>
16310
16311 <glossentry id='var-TUNEABI_WHITELIST'><glossterm>TUNEABI_WHITELIST</glossterm>
16312 <info>
16313 TUNEABI_WHITELIST[doc] = "A whitelist of permissible TUNEABI values. If the variable is not set, all values are allowed."
16314 </info>
16315 <glossdef>
16316 <para role="glossdeffirst">
16317<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16318 A whitelist of permissible
16319 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
16320 values.
16321 If <filename>TUNEABI_WHITELIST</filename> is not set,
16322 all tunes are allowed.
16323 Providers that use prebuilt libraries can use the
16324 <filename>TUNEABI_WHITELIST</filename>,
16325 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
16326 and <filename>TUNEABI</filename> variables to check
16327 compatibility of a tuning against their selection of
16328 libraries.
16329 </para>
16330
16331 <para>
16332 See the
16333 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
16334 class to see how the variable is used.
16335 </para>
16336 </glossdef>
16337 </glossentry>
16338
16339 <glossentry id='var-TUNECONFLICTS'><glossterm>TUNECONFLICTS[<replaceable>feature</replaceable>]</glossterm>
16340 <info>
16341 TUNECONFLICTS[doc] = "Specifies CPU or Application Binary Interface (ABI) tuning features that conflict with specified feature."
16342 </info>
16343 <glossdef>
16344 <para role="glossdeffirst">
16345<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16346 Specifies CPU or Application Binary Interface (ABI)
16347 tuning features that conflict with <replaceable>feature</replaceable>.
16348 </para>
16349
16350 <para>
16351 Known tuning conflicts are specified in the machine include
16352 files in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016353 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016354 Here is an example from the
16355 <filename>meta/conf/machine/include/mips/arch-mips.inc</filename>
16356 include file that lists the "o32" and "n64" features as
16357 conflicting with the "n32" feature:
16358 <literallayout class='monospaced'>
16359 TUNECONFLICTS[n32] = "o32 n64"
16360 </literallayout>
16361 </para>
16362 </glossdef>
16363 </glossentry>
16364
16365 <glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[<replaceable>feature</replaceable>]</glossterm>
16366 <info>
16367 TUNEVALID[doc] = "Descriptions, stored as flags, of valid tuning features."
16368 </info>
16369 <glossdef>
16370 <para role="glossdeffirst">
16371<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16372 Specifies a valid CPU or Application Binary Interface (ABI)
16373 tuning feature.
16374 The specified feature is stored as a flag.
16375 Valid features are specified in the machine include files
16376 (e.g. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>).
16377 Here is an example from that file:
16378 <literallayout class='monospaced'>
16379 TUNEVALID[bigendian] = "Enable big-endian mode."
16380 </literallayout>
16381 </para>
16382
16383 <para>
16384 See the machine include files in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016385 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016386 for these features.
16387 </para>
16388 </glossdef>
16389 </glossentry>
16390
16391 </glossdiv>
16392
16393 <glossdiv id='var-glossary-u'><title>U</title>
16394
16395 <glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm>
16396 <info>
16397 UBOOT_CONFIG[doc] = "Configures the UBOOT_MACHINE and can also define IMAGE_FSTYPES for individual cases."
16398 </info>
16399 <glossdef>
16400 <para role="glossdeffirst">
16401<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16402 Configures the
16403 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
16404 and can also define
16405 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
16406 for individual cases.
16407 </para>
16408
16409 <para>
16410 Following is an example from the
16411 <filename>meta-fsl-arm</filename> layer.
16412 <literallayout class='monospaced'>
16413 UBOOT_CONFIG ??= "sd"
16414 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
16415 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
16416 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
16417 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
16418 </literallayout>
16419 In this example, "sd" is selected as the configuration
16420 of the possible four for the
16421 <filename>UBOOT_MACHINE</filename>.
16422 The "sd" configuration defines "mx6qsabreauto_config"
16423 as the value for <filename>UBOOT_MACHINE</filename>, while
16424 the "sdcard" specifies the
16425 <filename>IMAGE_FSTYPES</filename> to use for the U-boot
16426 image.
16427 </para>
16428
16429 <para>
16430 For more information on how the
16431 <filename>UBOOT_CONFIG</filename> is handled, see the
16432 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass'><filename>uboot-config</filename></ulink>
16433 class.
16434 </para>
16435 </glossdef>
16436 </glossentry>
16437
16438 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
16439 <info>
16440 UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image."
16441 </info>
16442 <glossdef>
16443 <para role="glossdeffirst">
16444<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16445 Specifies the entry point for the U-Boot image.
16446 During U-Boot image creation, the
16447 <filename>UBOOT_ENTRYPOINT</filename> variable is passed
16448 as a command-line parameter to the
16449 <filename>uboot-mkimage</filename> utility.
16450 </para>
16451 </glossdef>
16452 </glossentry>
16453
16454 <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
16455 <info>
16456 UBOOT_LOADADDRESS[doc] = "Specifies the load address for the U-Boot image."
16457 </info>
16458 <glossdef>
16459 <para role="glossdeffirst">
16460<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16461 Specifies the load address for the U-Boot image.
16462 During U-Boot image creation, the
16463 <filename>UBOOT_LOADADDRESS</filename> variable is passed
16464 as a command-line parameter to the
16465 <filename>uboot-mkimage</filename> utility.
16466 </para>
16467 </glossdef>
16468 </glossentry>
16469
16470 <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>
16471 <info>
16472 UBOOT_LOCALVERSION[doc] = "Appends a string to the name of the local version of the U-Boot image."
16473 </info>
16474 <glossdef>
16475 <para role="glossdeffirst">
16476<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16477 Appends a string to the name of the local version of the
16478 U-Boot image.
16479 For example, assuming the version of the U-Boot image
16480 built was "2013.10, the full version string reported by
16481 U-Boot would be "2013.10-yocto" given the following
16482 statement:
16483 <literallayout class='monospaced'>
16484 UBOOT_LOCALVERSION = "-yocto"
16485 </literallayout>
16486 </para>
16487 </glossdef>
16488 </glossentry>
16489
16490 <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
16491 <info>
16492 UBOOT_MACHINE[doc] = "Specifies the value passed on the make command line when building a U-Boot image."
16493 </info>
16494 <glossdef>
16495 <para role="glossdeffirst">
16496<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16497 Specifies the value passed on the
16498 <filename>make</filename> command line when building
16499 a U-Boot image.
16500 The value indicates the target platform configuration.
16501 You typically set this variable from the machine
16502 configuration file (i.e.
16503 <filename>conf/machine/<replaceable>machine_name</replaceable>.conf</filename>).
16504 </para>
16505
16506 <para>
16507 Please see the "Selection of Processor Architecture and
16508 Board Type" section in the U-Boot README for valid values
16509 for this variable.
16510 </para>
16511 </glossdef>
16512 </glossentry>
16513
16514 <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm>
16515 <info>
16516 UBOOT_MAKE_TARGET[doc] = "Specifies the target called in the Makefile."
16517 </info>
16518 <glossdef>
16519 <para role="glossdeffirst">
16520<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16521 Specifies the target called in the
16522 <filename>Makefile</filename>.
16523 The default target is "all".
16524 </para>
16525 </glossdef>
16526 </glossentry>
16527
16528 <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>
16529 <info>
16530 UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension."
16531 </info>
16532 <glossdef>
16533 <para role="glossdeffirst">
16534<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16535 Points to the generated U-Boot extension.
16536 For example, <filename>u-boot.sb</filename> has a
16537 <filename>.sb</filename> extension.
16538 </para>
16539
16540 <para>
16541 The default U-Boot extension is
16542 <filename>.bin</filename>
16543 </para>
16544 </glossdef>
16545 </glossentry>
16546
16547 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
16548 <info>
16549 UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot."
16550 </info>
16551 <glossdef>
16552 <para role="glossdeffirst">
16553<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16554 Specifies the target used for building U-Boot.
16555 The target is passed directly as part of the "make" command
16556 (e.g. SPL and AIS).
16557 If you do not specifically set this variable, the
16558 OpenEmbedded build process passes and uses "all" for the
16559 target during the U-Boot building process.
16560 </para>
16561 </glossdef>
16562 </glossentry>
16563
16564 <glossentry id='var-UNKNOWN_CONFIGURE_WHITELIST'><glossterm>UNKNOWN_CONFIGURE_WHITELIST</glossterm>
16565 <info>
16566 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."
16567 </info>
16568 <glossdef>
16569 <para role="glossdeffirst">
16570<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16571 Specifies a list of options that, if reported by the
16572 configure script as being invalid, should not generate a
16573 warning during the
16574 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
16575 task.
16576 Normally, invalid configure options are simply not passed
16577 to the configure script (e.g. should be removed from
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016578 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
16579 or
16580 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>).
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016581 However, common options, for example, exist that are passed
16582 to all configure scripts at a class level that might not
16583 be valid for some configure scripts.
16584 It follows that no benefit exists in seeing a warning about
16585 these options.
16586 For these cases, the options are added to
16587 <filename>UNKNOWN_CONFIGURE_WHITELIST</filename>.
16588 </para>
16589
16590 <para>
16591 The configure arguments check that uses
16592 <filename>UNKNOWN_CONFIGURE_WHITELIST</filename> is part
16593 of the
16594 <link linkend='ref-classes-insane'><filename>insane</filename></link>
16595 class and is only enabled if the recipe inherits the
16596 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
16597 class.
16598 </para>
16599 </glossdef>
16600 </glossentry>
16601
16602 <glossentry id='var-UPDATERCPN'><glossterm>UPDATERCPN</glossterm>
16603 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040016604 UPDATERCPN[doc] = "Specifies the package that contains the initscript that is enabled."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016605 </info>
16606 <glossdef>
16607 <para role="glossdeffirst">
16608<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16609 For recipes inheriting the
16610 <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
16611 class, <filename>UPDATERCPN</filename> specifies
Brad Bishop316dfdd2018-06-25 12:45:53 -040016612 the package that contains the initscript that is
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016613 enabled.
16614 </para>
16615
16616 <para>
16617 The default value is "${PN}".
16618 Given that almost all recipes that install initscripts
16619 package them in the main package for the recipe, you
16620 rarely need to set this variable in individual recipes.
16621 </para>
16622 </glossdef>
16623 </glossentry>
16624
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016625 <glossentry id='var-UPSTREAM_CHECK_GITTAGREGEX'><glossterm>UPSTREAM_CHECK_GITTAGREGEX</glossterm>
16626 <info>
16627 UPSTREAM_CHECK_GITTAGREGEX[doc] = "Filters relevant Git tags when fetching source from an upstream Git repository."
16628 </info>
16629 <glossdef>
16630 <para role="glossdeffirst">
16631<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop15ae2502019-06-18 21:44:24 -040016632 You can perform a per-recipe check for what the latest
16633 upstream source code version is by calling
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016634 <filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.
16635 If the recipe source code is provided from Git
16636 repositories, the OpenEmbedded build system determines the
16637 latest upstream version by picking the latest tag from the
16638 list of all repository tags.
Brad Bishop15ae2502019-06-18 21:44:24 -040016639 </para>
16640
16641 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016642 You can use the
16643 <filename>UPSTREAM_CHECK_GITTAGREGEX</filename>
16644 variable to provide a regular expression to filter only the
16645 relevant tags should the default filter not work
16646 correctly.
16647 <literallayout class='monospaced'>
16648 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"
16649 </literallayout>
16650 </para>
16651 </glossdef>
16652 </glossentry>
16653
16654 <glossentry id='var-UPSTREAM_CHECK_REGEX'><glossterm>UPSTREAM_CHECK_REGEX</glossterm>
16655 <info>
16656 UPSTREAM_CHECK_REGEX[doc] = "The regular expression the package checking system uses to parse the page pointed to by UPSTREAM_CHECK_URI."
16657 </info>
16658 <glossdef>
16659 <para role="glossdeffirst">
16660<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop15ae2502019-06-18 21:44:24 -040016661 Use the <filename>UPSTREAM_CHECK_REGEX</filename> variable
16662 to specify a different regular expression instead of the
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016663 default one when the package checking system is parsing
16664 the page found using
16665 <link linkend='var-UPSTREAM_CHECK_URI'><filename>UPSTREAM_CHECK_URI</filename></link>.
16666 <literallayout class='monospaced'>
16667 UPSTREAM_CHECK_REGEX = "package_regex"
16668 </literallayout>
16669 </para>
16670 </glossdef>
16671 </glossentry>
16672
16673 <glossentry id='var-UPSTREAM_CHECK_URI'><glossterm>UPSTREAM_CHECK_URI</glossterm>
16674 <info>
16675 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."
16676 </info>
16677 <glossdef>
16678 <para role="glossdeffirst">
16679<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop15ae2502019-06-18 21:44:24 -040016680 You can perform a per-recipe check for what the latest
16681 upstream source code version is by calling
16682 <filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016683 If the source code is provided from tarballs, the latest
16684 version is determined by fetching the directory listing
16685 where the tarball is and attempting to find a later tarball.
16686 When this approach does not work, you can use
16687 <filename>UPSTREAM_CHECK_URI</filename> to
16688 provide a different URI that contains the link to the
16689 latest tarball.
16690 <literallayout class='monospaced'>
16691 UPSTREAM_CHECK_URI = "recipe_url"
16692 </literallayout>
16693 </para>
16694 </glossdef>
16695 </glossentry>
16696
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016697 <glossentry id='var-USE_DEVFS'><glossterm>USE_DEVFS</glossterm>
16698 <info>
16699 USE_DEVFS[doc] = "Determines if devtmpfs is used for /dev population."
16700 </info>
16701 <glossdef>
16702 <para role="glossdeffirst">
16703<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16704 Determines if <filename>devtmpfs</filename> is used for
16705 <filename>/dev</filename> population.
16706 The default value used for <filename>USE_DEVFS</filename>
16707 is "1" when no value is specifically set.
16708 Typically, you would set <filename>USE_DEVFS</filename>
16709 to "0" for a statically populated <filename>/dev</filename>
16710 directory.
16711 </para>
16712
16713 <para>
16714 See the
16715 "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-dev-manager'>Selecting a Device Manager</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016716 section in the Yocto Project Development Tasks Manual for
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016717 information on how to use this variable.
16718 </para>
16719 </glossdef>
16720 </glossentry>
16721
16722 <glossentry id='var-USE_VT'><glossterm>USE_VT</glossterm>
16723 <info>
16724 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."
16725 </info>
16726 <glossdef>
16727 <para role="glossdeffirst">
16728<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16729 When using
16730 <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
16731 determines whether or not to run a
16732 <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
16733 on any virtual terminals in order to enable logging in
16734 through those terminals.
16735 </para>
16736
16737 <para>
16738 The default value used for <filename>USE_VT</filename>
16739 is "1" when no default value is specifically set.
16740 Typically, you would set <filename>USE_VT</filename>
16741 to "0" in the machine configuration file for machines
16742 that do not have a graphical display attached and
16743 therefore do not need virtual terminal functionality.
16744 </para>
16745 </glossdef>
16746 </glossentry>
16747
16748 <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
16749 <info>
16750 USER_CLASSES[doc] = "List of additional classes to use when building images that enable extra features."
16751 </info>
16752 <glossdef>
16753 <para role="glossdeffirst">
16754<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16755 A list of classes to globally inherit.
16756 These classes are used by the OpenEmbedded build system
16757 to enable extra features (e.g.
16758 <filename>buildstats</filename>,
16759 <filename>image-mklibs</filename>, and so forth).
16760 </para>
16761
16762 <para>
16763 The default list is set in your
16764 <filename>local.conf</filename> file:
16765 <literallayout class='monospaced'>
16766 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
16767 </literallayout>
16768 For more information, see
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050016769 <filename>meta-poky/conf/local.conf.sample</filename> in
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016770 the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016771 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016772 </para>
16773 </glossdef>
16774 </glossentry>
16775
16776 <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>
16777 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016778 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 files/passwd and files/group files. If set to 'warn', a warning will be issued instead."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016779 </info>
16780 <glossdef>
16781 <para role="glossdeffirst">
16782<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016783 If set to "error", forces the OpenEmbedded build system to
16784 produce an error if the user identification
16785 (<filename>uid</filename>) and group identification
16786 (<filename>gid</filename>) values are not defined
16787 in <filename>files/passwd</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016788 and <filename>files/group</filename> files.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016789 If set to "warn", a warning will be issued instead.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016790 </para>
16791
16792 <para>
16793 The default behavior for the build system is to dynamically
16794 apply <filename>uid</filename> and
16795 <filename>gid</filename> values.
16796 Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>
16797 variable is by default not set.
16798 If you plan on using statically assigned
16799 <filename>gid</filename> and <filename>uid</filename>
16800 values, you should set
16801 the <filename>USERADD_ERROR_DYNAMIC</filename> variable in
16802 your <filename>local.conf</filename> file as
16803 follows:
16804 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016805 USERADD_ERROR_DYNAMIC = "error"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016806 </literallayout>
16807 Overriding the default behavior implies you are going to
16808 also take steps to set static <filename>uid</filename> and
16809 <filename>gid</filename> values through use of the
16810 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
16811 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
16812 and
16813 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
16814 variables.
16815 </para>
16816 </glossdef>
16817 </glossentry>
16818
16819 <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>
16820 <info>
16821 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."
16822 </info>
16823 <glossdef>
16824 <para role="glossdeffirst">
16825<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16826 Specifies a password file to use for obtaining static
16827 group identification (<filename>gid</filename>) values
16828 when the OpenEmbedded build system adds a group to the
16829 system during package installation.
16830 </para>
16831
16832 <para>
16833 When applying static group identification
16834 (<filename>gid</filename>) values, the OpenEmbedded build
16835 system looks in
16836 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
16837 for a <filename>files/group</filename> file and then applies
16838 those <filename>uid</filename> values.
16839 Set the variable as follows in your
16840 <filename>local.conf</filename> file:
16841 <literallayout class='monospaced'>
16842 USERADD_GID_TABLES = "files/group"
16843 </literallayout>
16844 </para>
16845
16846 <note>
16847 Setting the
16848 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
16849 variable to "useradd-staticids" causes the build system
16850 to use static <filename>gid</filename> values.
16851 </note>
16852 </glossdef>
16853 </glossentry>
16854
16855 <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>
16856 <info>
16857 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."
16858 </info>
16859 <glossdef>
16860 <para role="glossdeffirst">
16861<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16862 When inheriting the
16863 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
16864 class, this variable
16865 specifies the individual packages within the recipe that
16866 require users and/or groups to be added.
16867 </para>
16868
16869 <para>
16870 You must set this variable if the recipe inherits the
16871 class.
16872 For example, the following enables adding a user for the
16873 main package in a recipe:
16874 <literallayout class='monospaced'>
16875 USERADD_PACKAGES = "${PN}"
16876 </literallayout>
16877 <note>
Andrew Geissler99467da2019-02-25 18:54:23 -060016878 It follows that if you are going to use the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016879 <filename>USERADD_PACKAGES</filename> variable,
16880 you need to set one or more of the
16881 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
16882 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
16883 or
16884 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
16885 variables.
16886 </note>
16887 </para>
16888
16889 </glossdef>
16890 </glossentry>
16891
16892 <glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>
16893 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040016894 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 -050016895 </info>
16896 <glossdef>
16897 <para role="glossdeffirst">
16898<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16899 When inheriting the
16900 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
16901 class, this variable
Brad Bishop316dfdd2018-06-25 12:45:53 -040016902 specifies for a package what parameters should pass
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016903 to the <filename>useradd</filename> command
Brad Bishop316dfdd2018-06-25 12:45:53 -040016904 if you add a user to the system when the package
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016905 is installed.
16906 </para>
16907
16908 <para>
16909 Here is an example from the <filename>dbus</filename>
16910 recipe:
16911 <literallayout class='monospaced'>
16912 USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \
16913 --no-create-home --shell /bin/false \
16914 --user-group messagebus"
16915 </literallayout>
16916 For information on the standard Linux shell command
16917 <filename>useradd</filename>, see
16918 <ulink url='http://linux.die.net/man/8/useradd'></ulink>.
16919 </para>
16920 </glossdef>
16921 </glossentry>
16922
16923 <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>
16924 <info>
16925 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."
16926 </info>
16927 <glossdef>
16928 <para role="glossdeffirst">
16929<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16930 Specifies a password file to use for obtaining static
16931 user identification (<filename>uid</filename>) values
16932 when the OpenEmbedded build system adds a user to the
16933 system during package installation.
16934 </para>
16935
16936 <para>
16937 When applying static user identification
16938 (<filename>uid</filename>) values, the OpenEmbedded build
16939 system looks in
16940 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
16941 for a <filename>files/passwd</filename> file and then applies
16942 those <filename>uid</filename> values.
16943 Set the variable as follows in your
16944 <filename>local.conf</filename> file:
16945 <literallayout class='monospaced'>
16946 USERADD_UID_TABLES = "files/passwd"
16947 </literallayout>
16948 </para>
16949
16950 <note>
16951 Setting the
16952 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
16953 variable to "useradd-staticids" causes the build system
16954 to use static <filename>uid</filename> values.
16955 </note>
16956 </glossdef>
16957 </glossentry>
16958
16959 <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>
16960 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016961 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 -050016962 </info>
16963 <glossdef>
16964 <para role="glossdeffirst">
16965<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16966 When set to "useradd-staticids", causes the
16967 OpenEmbedded build system to base all user and group
16968 additions on a static
16969 <filename>passwd</filename> and
16970 <filename>group</filename> files found in
16971 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
16972 </para>
16973
16974 <para>
16975 To use static user identification (<filename>uid</filename>)
16976 and group identification (<filename>gid</filename>)
16977 values, set the variable
16978 as follows in your <filename>local.conf</filename> file:
16979 <literallayout class='monospaced'>
16980 USERADDEXTENSION = "useradd-staticids"
16981 </literallayout>
16982 <note>
16983 Setting this variable to use static
16984 <filename>uid</filename> and <filename>gid</filename>
16985 values causes the OpenEmbedded build system to employ
16986 the
Patrick Williamsf1e5d692016-03-30 15:21:19 -050016987 <link linkend='ref-classes-useradd'><filename>useradd-staticids</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016988 class.
16989 </note>
16990 </para>
16991
16992 <para>
16993 If you use static <filename>uid</filename> and
16994 <filename>gid</filename> information, you must also
16995 specify the <filename>files/passwd</filename> and
16996 <filename>files/group</filename> files by setting the
16997 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
16998 and
16999 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
17000 variables.
17001 Additionally, you should also set the
17002 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
17003 variable.
17004 </para>
17005 </glossdef>
17006 </glossentry>
17007
17008 </glossdiv>
17009
Brad Bishop6e60e8b2018-02-01 10:27:11 -050017010 <glossdiv id='var-glossary-v'><title>V</title>
17011
17012 <glossentry id='var-VOLATILE_LOG_DIR'><glossterm>VOLATILE_LOG_DIR</glossterm>
17013 <info>
17014 VOLATILE_LOG_DIR[doc] = "Specifies the persistence of the target's /var/log directory, which is used to house postinstall target log files."
17015 </info>
17016 <glossdef>
17017 <para role="glossdeffirst">
17018<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17019 Specifies the persistence of the target's
17020 <filename>/var/log</filename> directory, which is used to
17021 house postinstall target log files.
17022 </para>
17023
17024 <para>
17025 By default, <filename>VOLATILE_LOG_DIR</filename> is set
17026 to "yes", which means the file is not persistent.
17027 You can override this setting by setting the
17028 variable to "no" to make the log directory persistent.
17029 </para>
17030 </glossdef>
17031 </glossentry>
17032
17033 </glossdiv>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017034
17035 <glossdiv id='var-glossary-w'><title>W</title>
17036
17037 <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
17038 <info>
17039 WARN_QA[doc] = "Specifies the quality assurance checks whose failures are reported as warnings by the OpenEmbedded build system."
17040 </info>
17041 <glossdef>
17042 <para role="glossdeffirst">
17043<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17044 Specifies the quality assurance checks whose failures are
17045 reported as warnings by the OpenEmbedded build system.
17046 You set this variable in your distribution configuration
17047 file.
17048 For a list of the checks you can control with this variable,
17049 see the
17050 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
17051 section.
17052 </para>
17053 </glossdef>
17054 </glossentry>
17055
Brad Bishop6e60e8b2018-02-01 10:27:11 -050017056 <glossentry id='var-WKS_FILE_DEPENDS'><glossterm>WKS_FILE_DEPENDS</glossterm>
17057 <info>
17058 WKS_FILE_DEPENDS[doc] = "Lists a recipe's build-time dependencies specific to Wic."
17059 </info>
17060 <glossdef>
17061 <para role="glossdeffirst">
17062 When placed in the recipe that builds your image, this
17063 variable lists build-time dependencies.
17064 The <filename>WKS_FILE_DEPENDS</filename> variable is only
17065 applicable when Wic images are active (i.e. when
17066 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
17067 contains entries related to Wic).
17068 If your recipe does not create Wic images, the variable
17069 has no effect.
17070 </para>
17071
17072 <para>
17073 The <filename>WKS_FILE_DEPENDS</filename> variable is
17074 similar to the
17075 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
17076 variable.
17077 When you use the variable in your recipe that builds the
17078 Wic image, dependencies you list in the
17079 <filename>WIC_FILE_DEPENDS</filename> variable are added to
17080 the <filename>DEPENDS</filename> variable.
17081 </para>
17082
17083 <para>
17084 With the <filename>WKS_FILE_DEPENDS</filename> variable,
17085 you have the possibility to specify a list of additional
17086 dependencies (e.g. native tools, bootloaders, and so forth),
17087 that are required to build Wic images.
17088 Following is an example:
17089 <literallayout class='monospaced'>
17090 WKS_FILE_DEPENDS = "<replaceable>some-native-tool</replaceable>"
17091 </literallayout>
17092 In the previous example,
17093 <replaceable>some-native-tool</replaceable> would be
17094 replaced with an actual native tool on which the build
17095 would depend.
17096 </para>
17097 </glossdef>
17098 </glossentry>
17099
Brad Bishop37a0e4d2017-12-04 01:01:44 -050017100 <glossentry id='var-WKS_FILE'><glossterm>WKS_FILE</glossterm>
17101 <info>
17102 WKS_FILE[doc] = "Specifies the name of the wic kickstart file."
17103 </info>
17104 <glossdef>
17105 <para role="glossdeffirst">
17106 Specifies the location of the Wic
17107 kickstart file that is used by the OpenEmbedded build
17108 system to create a partitioned image
17109 (<replaceable>image</replaceable><filename>.wic</filename>).
Brad Bishopd7bf8c12018-02-25 22:55:05 -050017110 For information on how to create a partitioned image, see
17111 the
17112 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
17113 section in the Yocto Project Development Tasks Manual.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050017114 For details on the kickstart file format, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040017115 "<link linkend='ref-kickstart'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</link>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050017116 Chapter.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050017117 </para>
17118 </glossdef>
17119 </glossentry>
17120
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017121 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
17122 <info>
17123 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."
17124 </info>
17125 <glossdef>
17126 <para role="glossdeffirst">
17127<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17128 The pathname of the work directory in which the OpenEmbedded
17129 build system builds a recipe.
17130 This directory is located within the
17131 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
17132 directory structure and is specific to the recipe being
17133 built and the system for which it is being built.
17134 </para>
17135
17136 <para>
17137 The <filename>WORKDIR</filename> directory is defined as
17138 follows:
17139 <literallayout class='monospaced'>
17140 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
17141 </literallayout>
17142 The actual directory depends on several things:
17143 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -040017144 <listitem><filename>TMPDIR</filename>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017145 The top-level build output directory</listitem>
17146 <listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>:
17147 The target system identifier</listitem>
17148 <listitem><link linkend='var-PN'><filename>PN</filename></link>:
17149 The recipe name</listitem>
17150 <listitem><link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>:
17151 The epoch - (if
17152 <link linkend='var-PE'><filename>PE</filename></link>
17153 is not specified, which is usually the case for most
17154 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
17155 <listitem><link linkend='var-PV'><filename>PV</filename></link>:
17156 The recipe version</listitem>
17157 <listitem><link linkend='var-PR'><filename>PR</filename></link>:
17158 The recipe revision</listitem>
17159 </itemizedlist>
17160 </para>
17161
17162 <para>
17163 As an example, assume a Source Directory top-level folder
17164 name <filename>poky</filename>, a default Build Directory at
17165 <filename>poky/build</filename>, and a
17166 <filename>qemux86-poky-linux</filename> machine target
17167 system.
17168 Furthermore, suppose your recipe is named
17169 <filename>foo_1.3.0-r0.bb</filename>.
17170 In this case, the work directory the build system uses to
17171 build the package would be as follows:
17172 <literallayout class='monospaced'>
17173 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
17174 </literallayout>
17175 </para>
17176 </glossdef>
17177 </glossentry>
17178
17179 </glossdiv>
17180
17181 <glossdiv id='var-glossary-x'><title>X</title>
17182
17183 <glossentry id='var-XSERVER'><glossterm>XSERVER</glossterm>
17184 <info>
17185 XSERVER[doc] = "Specifies the packages that should be installed
17186 to provide an X server and drivers for the current machine."
17187 </info>
17188 <glossdef>
17189 <para role="glossdeffirst">
17190<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17191 Specifies the packages that should be installed to
17192 provide an X server and drivers for the current machine,
17193 assuming your image directly includes
17194 <filename>packagegroup-core-x11-xserver</filename> or,
17195 perhaps indirectly, includes "x11-base" in
17196 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
17197 </para>
17198
17199 <para>
17200 The default value of <filename>XSERVER</filename>, if not
17201 specified in the machine configuration, is
17202 "xserver-xorg xf86-video-fbdev xf86-input-evdev".
17203 </para>
17204 </glossdef>
17205 </glossentry>
17206
17207 </glossdiv>
17208
17209<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
17210<!-- </glossdiv>-->
17211
17212<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
17213<!-- </glossdiv>-->
17214
17215</glossary>
17216</chapter>
17217<!--
17218vim: expandtab tw=80 ts=4
17219-->