blob: 8ad3f9b3ca3f96951b3836867320ff96f12f50c1 [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<!-- Dummy chapter -->
6<chapter id='ref-variables-glos'>
7
8<title>Variables Glossary</title>
9
10<para>
11 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
12 of their function and contents.
13</para>
14
15<glossary id='ref-variables-glossary'>
16
17
18 <para>
19 <link linkend='var-ABIEXTENSION'>A</link>
20 <link linkend='var-B'>B</link>
21 <link linkend='var-CACHE'>C</link>
22 <link linkend='var-D'>D</link>
23 <link linkend='var-EFI_PROVIDER'>E</link>
24 <link linkend='var-FEATURE_PACKAGES'>F</link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040025 <link linkend='var-GCCPIE'>G</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050026 <link linkend='var-HOMEPAGE'>H</link>
27 <link linkend='var-ICECC_DISABLED'>I</link>
28<!-- <link linkend='var-glossary-j'>J</link> -->
29 <link linkend='var-KARCH'>K</link>
30 <link linkend='var-LABELS'>L</link>
31 <link linkend='var-MACHINE'>M</link>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050032 <link linkend='var-NATIVELSBSTRING'>N</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050033 <link linkend='var-OBJCOPY'>O</link>
34 <link linkend='var-P'>P</link>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050035<!-- <link linkend='var-glossary-q'>Q</link> -->
Patrick Williamsc124f4f2015-09-15 14:41:29 -050036 <link linkend='var-RANLIB'>R</link>
37 <link linkend='var-S'>S</link>
38 <link linkend='var-T'>T</link>
39 <link linkend='var-UBOOT_CONFIG'>U</link>
Brad Bishop6e60e8b2018-02-01 10:27:11 -050040 <link linkend='var-VOLATILE_LOG_DIR'>V</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050041 <link linkend='var-WARN_QA'>W</link>
42 <link linkend='var-XSERVER'>X</link>
43<!-- <link linkend='var-glossary-y'>Y</link> -->
44<!-- <link linkend='var-glossary-z'>Z</link>-->
45 </para>
46
47 <glossdiv id='var-glossary-a'><title>A</title>
48
49 <glossentry id='var-ABIEXTENSION'><glossterm>ABIEXTENSION</glossterm>
50 <info>
51 ABIEXTENSION[doc] = "Extension to the Application Binary Interface (ABI) field of the GNU canonical architecture name (e.g. "eabi")."
52 </info>
53 <glossdef>
54 <para role="glossdeffirst">
55<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
56 Extension to the Application Binary Interface (ABI)
57 field of the GNU canonical architecture name
58 (e.g. "eabi").
59 </para>
60
61 <para>
62 ABI extensions are set in the machine include files.
63 For example, the
64 <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>
65 file sets the following extension:
66 <literallayout class='monospaced'>
67 ABIEXTENSION = "eabi"
68 </literallayout>
69 </para>
70 </glossdef>
71 </glossentry>
72
73 <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
74 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040075 ALLOW_EMPTY[doc] = "Specifies whether to produce an output package even if it is empty."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050076 </info>
77 <glossdef>
78 <para role="glossdeffirst">
79<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040080 Specifies whether to produce an output package even if it is
81 empty.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050082 By default, BitBake does not produce empty packages.
83 This default behavior can cause issues when there is an
84 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
85 some other hard runtime requirement on the existence of the package.
86 </para>
87
88 <para>
89 Like all package-controlling variables, you must always use them in
90 conjunction with a package name override, as in:
91 <literallayout class='monospaced'>
92 ALLOW_EMPTY_${PN} = "1"
93 ALLOW_EMPTY_${PN}-dev = "1"
94 ALLOW_EMPTY_${PN}-staticdev = "1"
95 </literallayout>
96 </para>
97 </glossdef>
98 </glossentry>
99
100 <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
101 <info>
102 ALTERNATIVE[doc] = "Lists commands in a package that need an alternative binary naming scheme."
103 </info>
104 <glossdef>
105 <para role="glossdeffirst">
106<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
107 Lists commands in a package that need an alternative
108 binary naming scheme.
109 Sometimes the same command is provided in multiple packages.
110 When this occurs, the OpenEmbedded build system needs to
111 use the alternatives system to create a different binary
112 naming scheme so the commands can co-exist.
113 </para>
114
115 <para>
116 To use the variable, list out the package's commands
117 that also exist as part of another package.
118 For example, if the <filename>busybox</filename> package
119 has four commands that also exist as part of another
120 package, you identify them as follows:
121 <literallayout class='monospaced'>
122 ALTERNATIVE_busybox = "sh sed test bracket"
123 </literallayout>
124 For more information on the alternatives system, see the
125 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
126 section.
127 </para>
128 </glossdef>
129 </glossentry>
130
131 <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
132 <info>
133 ALTERNATIVE_LINK_NAME[doc] = "Used by the alternatives system to map duplicated commands to actual locations."
134 </info>
135 <glossdef>
136 <para role="glossdeffirst">
137<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
138 Used by the alternatives system to map duplicated commands
139 to actual locations.
140 For example, if the <filename>bracket</filename> command
141 provided by the <filename>busybox</filename> package is
142 duplicated through another package, you must use the
143 <filename>ALTERNATIVE_LINK_NAME</filename> variable to
144 specify the actual location:
145 <literallayout class='monospaced'>
146 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
147 </literallayout>
148 </para>
149
150 <para>
151 In this example, the binary for the
152 <filename>bracket</filename> command (i.e.
153 <filename>[</filename>) from the
154 <filename>busybox</filename> package resides in
155 <filename>/usr/bin/</filename>.
156 <note>
157 If <filename>ALTERNATIVE_LINK_NAME</filename> is not
158 defined, it defaults to
159 <filename>${bindir}/<replaceable>name</replaceable></filename>.
160 </note>
161 </para>
162
163 <para>
164 For more information on the alternatives system, see the
165 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
166 section.
167 </para>
168 </glossdef>
169 </glossentry>
170
171 <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
172 <info>
173 ALTERNATIVE_PRIORITY[doc] = "Used by the alternatives system to create default priorities for duplicated commands."
174 </info>
175 <glossdef>
176 <para role="glossdeffirst">
177<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
178 Used by the alternatives system to create default
179 priorities for duplicated commands.
180 You can use the variable to create a single default
181 regardless of the command name or package, a default for
182 specific duplicated commands regardless of the package, or
183 a default for specific commands tied to particular packages.
184 Here are the available syntax forms:
185 <literallayout class='monospaced'>
186 ALTERNATIVE_PRIORITY = "<replaceable>priority</replaceable>"
187 ALTERNATIVE_PRIORITY[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>"
188 ALTERNATIVE_PRIORITY_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>"
189 </literallayout>
190 </para>
191
192 <para>
193 For more information on the alternatives system, see the
194 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
195 section.
196 </para>
197 </glossdef>
198 </glossentry>
199
200 <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
201 <info>
202 ALTERNATIVE_TARGET[doc] = "Used by the alternatives system to create default link locations for duplicated commands."
203 </info>
204 <glossdef>
205 <para role="glossdeffirst">
206<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
207 Used by the alternatives system to create default link
208 locations for duplicated commands.
209 You can use the variable to create a single default
210 location for all duplicated commands regardless of the
211 command name or package, a default for
212 specific duplicated commands regardless of the package, or
213 a default for specific commands tied to particular packages.
214 Here are the available syntax forms:
215 <literallayout class='monospaced'>
216 ALTERNATIVE_TARGET = "<replaceable>target</replaceable>"
217 ALTERNATIVE_TARGET[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>"
218 ALTERNATIVE_TARGET_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>"
219 </literallayout>
220 <note>
221 <para>
222 If <filename>ALTERNATIVE_TARGET</filename> is not
223 defined, it inherits the value from the
224 <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
225 variable.
226 </para>
227
228 <para>
229 If <filename>ALTERNATIVE_LINK_NAME</filename> and
230 <filename>ALTERNATIVE_TARGET</filename> are the
231 same, the target for
232 <filename>ALTERNATIVE_TARGET</filename>
233 has "<filename>.{BPN}</filename>" appended to it.
234 </para>
235
236 <para>
237 Finally, if the file referenced has not been
238 renamed, the alternatives system will rename it to
239 avoid the need to rename alternative files in the
240 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
241 task while
242 retaining support for the command if necessary.
243 </para>
244 </note>
245 </para>
246
247 <para>
248 For more information on the alternatives system, see the
249 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
250 section.
251 </para>
252 </glossdef>
253 </glossentry>
254
255 <glossentry id='var-APPEND'><glossterm>APPEND</glossterm>
256 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400257 APPEND[doc] = "An override list of append strings for target specified using LABELS."
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500258 </info>
259 <glossdef>
260 <para role="glossdeffirst">
261<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -0400262 An override list of append strings for each target
263 specified with
264 <link linkend='var-LABELS'><filename>LABELS</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500265 </para>
266
267 <para>
268 See the
269 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
270 class for more information on how this variable is used.
271 </para>
272 </glossdef>
273 </glossentry>
274
275 <glossentry id='var-AR'><glossterm>AR</glossterm>
276 <info>
277 AR[doc] = "Minimal command and arguments to run 'ar'."
278 </info>
279 <glossdef>
280 <para role="glossdeffirst">
281<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
282 The minimal command and arguments used to run
283 <filename>ar</filename>.
284 </para>
285 </glossdef>
286 </glossentry>
287
288 <glossentry id='var-ARCHIVER_MODE'><glossterm>ARCHIVER_MODE</glossterm>
289 <info>
290 ARCHIVER_MODE[doc] = "Controls archive creation used when releasing source files."
291 </info>
292 <glossdef>
293 <para role="glossdeffirst">
294<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
295 When used with the
296 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
297 class, determines the type of information used to create
298 a released archive.
299 You can use this variable to create archives of patched
300 source, original source, configured source, and so forth
301 by employing the following variable flags (varflags):
302 <literallayout class='monospaced'>
303 ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source
304 # files.
305
306 ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is
307 # the default.
308
309 ARCHIVER_MODE[src] = "configured" # Uses configured source files.
310
311 ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and
312 # do_patch.
313
314 ARCHIVER_MODE[diff-exclude] ?= "<replaceable>file</replaceable> <replaceable>file</replaceable> ..." # Lists files and directories to
315 # exclude from diff.
316
317 ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
318
319 ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
320
321 ARCHIVER_MODE[srpm] = "1" # Uses RPM package files.
322 </literallayout>
323 For information on how the variable works, see the
324 <filename>meta/classes/archiver.bbclass</filename> file
325 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500326 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500327 </para>
328 </glossdef>
329 </glossentry>
330
331 <glossentry id='var-AS'><glossterm>AS</glossterm>
332 <info>
333 AS[doc] = "Minimal command and arguments to run the assembler."
334 </info>
335 <glossdef>
336 <para role="glossdeffirst">
337<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop79641f22019-09-10 07:20:22 -0400338 Minimal command and arguments needed to run the
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500339 assembler.
340 </para>
341 </glossdef>
342 </glossentry>
343
344 <glossentry id='var-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm>
345 <info>
346 ASSUME_PROVIDED[doc] = "Lists recipe names (PN values) BitBake does not attempt to build."
347 </info>
348 <glossdef>
349 <para role="glossdeffirst">
350<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
351 Lists recipe names
352 (<link linkend='var-PN'><filename>PN</filename></link>
353 values) BitBake does not attempt to build.
354 Instead, BitBake assumes these recipes have already been
355 built.
356 </para>
357
358 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400359 In OpenEmbedded-Core, <filename>ASSUME_PROVIDED</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500360 mostly specifies native tools that should not be built.
361 An example is <filename>git-native</filename>, which when
362 specified, allows for the Git binary from the host to be
363 used rather than building <filename>git-native</filename>.
364 </para>
365 </glossdef>
366 </glossentry>
367
368 <glossentry id='var-ASSUME_SHLIBS'><glossterm>ASSUME_SHLIBS</glossterm>
369 <info>
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>
Brad Bishopf3f93bb2019-10-16 14:33:32 -04001347 BBMULTICONFIG[doc] = "Specifies each additional separate configuration when you are building targets with multiple configurations."
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001348 </info>
1349 <glossdef>
1350 <para role="glossdeffirst">
1351<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopf3f93bb2019-10-16 14:33:32 -04001352 Specifies each additional separate configuration when you are
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001353 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'>
Brad Bishop96ff1982019-08-19 13:50:42 -04001361 BBMULTICONFIG = "configA configB configC"
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001362 </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
Brad Bishop79641f22019-09-10 07:20:22 -04006609 container
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006610 cpio
6611 cpio.gz
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006612 cpio.lz4
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006613 cpio.lzma
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006614 cpio.xz
6615 cramfs
6616 elf
6617 ext2
6618 ext2.bz2
6619 ext2.gz
6620 ext2.lzma
6621 ext3
6622 ext3.gz
6623 ext4
6624 ext4.gz
Brad Bishop79641f22019-09-10 07:20:22 -04006625 f2fs
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006626 hddimg
6627 iso
6628 jffs2
6629 jffs2.sum
6630 multiubi
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006631 squashfs
Brad Bishop79641f22019-09-10 07:20:22 -04006632 squashfs-lz4
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006633 squashfs-lzo
6634 squashfs-xz
6635 tar
6636 tar.bz2
6637 tar.gz
6638 tar.lz4
6639 tar.xz
6640 ubi
6641 ubifs
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006642 wic
6643 wic.bz2
6644 wic.gz
6645 wic.lzma
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006646 </literallayout>
6647 </para>
6648
6649 <para>
6650 For more information about these types of images, see
6651 <filename>meta/classes/image_types*.bbclass</filename>
6652 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006653 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006654 </para>
6655 </glossdef>
6656 </glossentry>
6657
6658 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
6659 <info>
6660 INC_PR[doc] = "Helps define the recipe revision for recipes that share a common include file."
6661 </info>
6662 <glossdef>
6663 <para role="glossdeffirst">
6664<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6665 Helps define the recipe revision for recipes that share
6666 a common <filename>include</filename> file.
6667 You can think of this variable as part of the recipe revision
6668 as set from within an include file.
6669 </para>
6670
6671 <para>
6672 Suppose, for example, you have a set of recipes that
6673 are used across several projects.
6674 And, within each of those recipes the revision
6675 (its <link linkend='var-PR'><filename>PR</filename></link>
6676 value) is set accordingly.
6677 In this case, when the revision of those recipes changes,
6678 the burden is on you to find all those recipes and
6679 be sure that they get changed to reflect the updated
6680 version of the recipe.
6681 In this scenario, it can get complicated when recipes
6682 that are used in many places and provide common functionality
6683 are upgraded to a new revision.
6684 </para>
6685
6686 <para>
6687 A more efficient way of dealing with this situation is
6688 to set the <filename>INC_PR</filename> variable inside
6689 the <filename>include</filename> files that the recipes
6690 share and then expand the <filename>INC_PR</filename>
6691 variable within the recipes to help
6692 define the recipe revision.
6693 </para>
6694
6695 <para>
6696 The following provides an example that shows how to use
6697 the <filename>INC_PR</filename> variable
6698 given a common <filename>include</filename> file that
6699 defines the variable.
6700 Once the variable is defined in the
6701 <filename>include</filename> file, you can use the
6702 variable to set the <filename>PR</filename> values in
6703 each recipe.
6704 You will notice that when you set a recipe's
6705 <filename>PR</filename> you can provide more granular
6706 revisioning by appending values to the
6707 <filename>INC_PR</filename> variable:
6708 <literallayout class='monospaced'>
Brad Bishopb1114e52019-02-13 07:56:10 -05006709 recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
6710 recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
6711 recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
6712 recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006713 </literallayout>
6714 The first line of the example establishes the baseline
6715 revision to be used for all recipes that use the
6716 <filename>include</filename> file.
6717 The remaining lines in the example are from individual
6718 recipes and show how the <filename>PR</filename> value
6719 is set.
6720 </para>
6721 </glossdef>
6722 </glossentry>
6723
6724 <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
6725 <info>
6726 INCOMPATIBLE_LICENSE[doc] = "Specifies a space-separated list of license names (as they would appear in LICENSE) that should be excluded from the build."
6727 </info>
6728 <glossdef>
6729 <para role="glossdeffirst">
6730<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6731 Specifies a space-separated list of license names
6732 (as they would appear in
6733 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
6734 that should be excluded from the build.
6735 Recipes that provide no alternatives to listed incompatible
6736 licenses are not built.
6737 Packages that are individually licensed with the specified
6738 incompatible licenses will be deleted.
6739 </para>
6740
6741 <note>
6742 This functionality is only regularly tested using
6743 the following setting:
6744 <literallayout class='monospaced'>
6745 INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
6746 </literallayout>
6747 Although you can use other settings, you might be required
6748 to remove dependencies on or provide alternatives to
6749 components that are required to produce a functional system
6750 image.
6751 </note>
6752 </glossdef>
6753 </glossentry>
6754
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006755 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
6756 <info>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05006757 INHERIT[doc] = "Causes the named class or classes to be inherited globally."
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006758 </info>
6759 <glossdef>
6760 <para role="glossdeffirst">
6761<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop6e60e8b2018-02-01 10:27:11 -05006762 Causes the named class or classes to be inherited globally.
6763 Anonymous functions in the class or classes
6764 are not executed for the
6765 base configuration and in each individual recipe.
6766 The OpenEmbedded build system ignores changes to
6767 <filename>INHERIT</filename> in individual recipes.
6768 </para>
6769
6770 <para>
6771 For more information on <filename>INHERIT</filename>, see
6772 the
6773 "<ulink url="&YOCTO_DOCS_BB_URL;#inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -04006774 section in the Bitbake User Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006775 </para>
6776 </glossdef>
6777 </glossentry>
6778
6779 <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm>
6780 <info>
6781 INHERIT_DISTRO[doc] = "Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable."
6782 </info>
6783 <glossdef>
6784 <para role="glossdeffirst">
6785<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6786 Lists classes that will be inherited at the
6787 distribution level.
6788 It is unlikely that you want to edit this variable.
6789 </para>
6790
6791 <para>
6792 The default value of the variable is set as follows in the
6793 <filename>meta/conf/distro/defaultsetup.conf</filename>
6794 file:
6795 <literallayout class='monospaced'>
6796 INHERIT_DISTRO ?= "debian devshell sstate license"
6797 </literallayout>
6798 </para>
6799 </glossdef>
6800 </glossentry>
6801
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006802 <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
6803 <info>
6804 INHIBIT_DEFAULT_DEPS[doc] = "Prevents the default dependencies, namely the C compiler and standard C library (libc), from being added to DEPENDS."
6805 </info>
6806 <glossdef>
6807 <para role="glossdeffirst">
6808<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6809 Prevents the default dependencies, namely the C compiler
6810 and standard C library (libc), from being added to
6811 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
6812 This variable is usually used within recipes that do not
6813 require any compilation using the C compiler.
6814 </para>
6815
6816 <para>
6817 Set the variable to "1" to prevent the default dependencies
6818 from being added.
6819 </para>
6820 </glossdef>
6821 </glossentry>
6822
6823 <glossentry id='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><glossterm>INHIBIT_PACKAGE_DEBUG_SPLIT</glossterm>
6824 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006825 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 -05006826 </info>
6827 <glossdef>
6828 <para role="glossdeffirst">
6829<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6830 Prevents the OpenEmbedded build system from splitting
6831 out debug information during packaging.
6832 By default, the build system splits out debugging
6833 information during the
6834 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
6835 task.
6836 For more information on how debug information is split out,
6837 see the
6838 <link linkend='var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></link>
6839 variable.
6840 </para>
6841
6842 <para>
6843 To prevent the build system from splitting out
6844 debug information during packaging, set the
6845 <filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename> variable
6846 as follows:
6847 <literallayout class='monospaced'>
6848 INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
6849 </literallayout>
6850 </para>
6851 </glossdef>
6852 </glossentry>
6853
6854 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
6855 <info>
6856 INHIBIT_PACKAGE_STRIP[doc] = "If set to "1", causes the build to not strip binaries in resulting packages."
6857 </info>
6858 <glossdef>
6859 <para role="glossdeffirst">
6860<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006861 If set to "1", causes the build to not strip binaries in
6862 resulting packages and prevents the
6863 <filename>-dbg</filename> package from containing the
6864 source files.
6865 </para>
6866
6867 <para>
6868 By default, the OpenEmbedded build system strips
6869 binaries and puts the debugging symbols into
6870 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-dbg</filename>.
6871 Consequently, you should not set
6872 <filename>INHIBIT_PACKAGE_STRIP</filename> when you plan
6873 to debug in general.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006874 </para>
6875 </glossdef>
6876 </glossentry>
6877
Brad Bishop19323692019-04-05 15:28:33 -04006878 <glossentry id='var-INHIBIT_SYSROOT_STRIP'><glossterm>INHIBIT_SYSROOT_STRIP</glossterm>
6879 <info>
6880 INHIBIT_SYSROOT_STRIP[doc] = "If set to "1", causes the build to not strip binaries in the resulting sysroot."
6881 </info>
6882 <glossdef>
6883 <para role="glossdeffirst">
6884<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6885 If set to "1", causes the build to not strip binaries in
6886 the resulting sysroot.
6887 </para>
6888
6889 <para>
6890 By default, the OpenEmbedded build system strips
6891 binaries in the resulting sysroot.
6892 When you specifically set the
6893 <filename>INHIBIT_SYSROOT_STRIP</filename> variable to
6894 "1" in your recipe, you inhibit this stripping.
6895 </para>
6896
6897 <para>
6898 If you want to use this variable, include the
6899 <link linkend='ref-classes-staging'><filename>staging</filename></link>
6900 class.
6901 This class uses a <filename>sys_strip()</filename>
6902 function to test for the variable and acts accordingly.
6903 <note>
6904 Use of the <filename>INHIBIT_SYSROOT_STRIP</filename>
6905 variable occurs in rare and special circumstances.
6906 For example, suppose you are building bare-metal
6907 firmware by using an external GCC toolchain.
6908 Furthermore, even if the toolchain's binaries are
6909 strippable, other files exist that are needed for the
6910 build that are not strippable.
6911 </note>
6912 </para>
6913 </glossdef>
6914 </glossentry>
6915
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006916 <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
6917 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006918 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 -05006919 </info>
6920 <glossdef>
6921 <para role="glossdeffirst">
6922<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6923 Defines the format for the output image of an initial
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006924 RAM filesystem (initramfs), which is used during boot.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006925 Supported formats are the same as those supported by the
6926 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6927 variable.
6928 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006929
6930 <para>
6931 The default value of this variable, which is set in the
6932 <filename>meta/conf/bitbake.conf</filename> configuration
6933 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006934 <link linkend='source-directory'>Source Directory</link>,
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006935 is "cpio.gz".
6936 The Linux kernel's initramfs mechanism, as opposed to the
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006937 initial RAM filesystem
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006938 <ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink>
6939 mechanism, expects an optionally compressed cpio
6940 archive.
6941 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006942 </glossdef>
6943 </glossentry>
6944
6945 <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>
6946 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006947 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 -05006948 </info>
6949 <glossdef>
6950 <para role="glossdeffirst">
6951<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006952 Specifies the
6953 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
6954 name of an image recipe that is used to build an initial
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006955 RAM filesystem (initramfs) image.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006956 In other words, the <filename>INITRAMFS_IMAGE</filename>
6957 variable causes an additional recipe to be built as
6958 a dependency to whatever root filesystem recipe you
6959 might be using (e.g. <filename>core-image-sato</filename>).
6960 The initramfs image recipe you provide should set
6961 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6962 to
6963 <link linkend='var-INITRAMFS_FSTYPES'><filename>INITRAMFS_FSTYPES</filename></link>.
6964 </para>
6965
6966 <para>
6967 An initramfs image provides a temporary root filesystem
6968 used for early system initialization (e.g. loading of
6969 modules needed to locate and mount the "real" root
6970 filesystem).
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006971 <note>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006972 See the <filename>meta/recipes-core/images/core-image-minimal-initramfs.bb</filename>
6973 recipe in the
6974 <link linkend='source-directory'>Source Directory</link>
6975 for an example initramfs recipe.
6976 To select this sample recipe as the one built
6977 to provide the initramfs image,
6978 set <filename>INITRAMFS_IMAGE</filename> to
6979 "core-image-minimal-initramfs".
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006980 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006981 </para>
6982
6983 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006984 You can also find more information by referencing the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006985 <filename>meta-poky/conf/local.conf.sample.extended</filename>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006986 configuration file in the Source Directory,
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006987 the
6988 <link linkend='ref-classes-image'><filename>image</filename></link>
6989 class, and the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006990 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006991 class to see how to use the
6992 <filename>INITRAMFS_IMAGE</filename> variable.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006993 </para>
6994
6995 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006996 If <filename>INITRAMFS_IMAGE</filename> is empty, which is
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006997 the default, then no initramfs image is built.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006998 </para>
6999
7000 <para>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007001 For more information, you can also see the
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007002 <link linkend='var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></link>
7003 variable, which allows the generated image to be bundled
7004 inside the kernel image.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007005 Additionally, for information on creating an initramfs
7006 image, see the
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007007 "<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 -05007008 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007009 </para>
7010 </glossdef>
7011 </glossentry>
7012
7013 <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
7014 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007015 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 -05007016 </info>
7017 <glossdef>
7018 <para role="glossdeffirst">
7019<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7020 Controls whether or not the image recipe specified by
7021 <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007022 is run through an extra pass
7023 (<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>)
7024 during kernel compilation in order to build a single binary
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007025 that contains both the kernel image and the initial RAM
7026 filesystem (initramfs) image.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007027 This makes use of the
7028 <link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link>
7029 kernel feature.
7030 <note>
7031 Using an extra compilation pass to bundle the initramfs
7032 avoids a circular dependency between the kernel recipe and
7033 the initramfs recipe should the initramfs include kernel
7034 modules.
7035 Should that be the case, the initramfs recipe depends on
7036 the kernel for the kernel modules, and the kernel depends
7037 on the initramfs recipe since the initramfs is bundled
7038 inside the kernel image.
7039 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007040 </para>
7041
7042 <para>
7043 The combined binary is deposited into the
7044 <filename>tmp/deploy</filename> directory, which is part
7045 of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007046 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007047 </para>
7048
7049 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007050 Setting the variable to "1" in a configuration file causes the
7051 OpenEmbedded build system to generate a kernel image with the
Brad Bishop316dfdd2018-06-25 12:45:53 -04007052 initramfs specified in <filename>INITRAMFS_IMAGE</filename>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007053 bundled within:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007054 <literallayout class='monospaced'>
7055 INITRAMFS_IMAGE_BUNDLE = "1"
7056 </literallayout>
7057 By default, the
7058 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
7059 class sets this variable to a null string as follows:
7060 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007061 INITRAMFS_IMAGE_BUNDLE ?= ""
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007062 </literallayout>
7063 <note>
7064 You must set the
7065 <filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in
7066 a configuration file.
7067 You cannot set the variable in a recipe file.
7068 </note>
7069 See the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05007070 <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 -05007071 file for additional information.
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007072 Also, for information on creating an initramfs, see the
7073 "<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 -05007074 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007075 </para>
7076 </glossdef>
7077 </glossentry>
7078
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007079 <glossentry id='var-INITRAMFS_LINK_NAME'><glossterm>INITRAMFS_LINK_NAME</glossterm>
7080 <info>
7081 INITRAMFS_LINK_NAME[doc] = "The link name of the initial RAM filesystem image."
7082 </info>
7083 <glossdef>
7084 <para role="glossdeffirst">
7085<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7086 The link name of the initial RAM filesystem image.
7087 This variable is set in the
7088 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7089 file as follows:
7090 <literallayout class='monospaced'>
7091 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"
7092 </literallayout>
7093 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7094 variable, which is set in the same file, has the following
7095 value:
7096 <literallayout class='monospaced'>
7097 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7098 </literallayout>
7099 </para>
7100
7101 <para>
7102 See the
7103 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7104 variable for additional information.
7105 </para>
7106 </glossdef>
7107 </glossentry>
7108
7109 <glossentry id='var-INITRAMFS_NAME'><glossterm>INITRAMFS_NAME</glossterm>
7110 <info>
7111 INITRAMFS_NAME[doc] = "The base name of the initial RAM filesystem image."
7112 </info>
7113 <glossdef>
7114 <para role="glossdeffirst">
7115<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7116 The base name of the initial RAM filesystem image.
7117 This variable is set in the
7118 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7119 file as follows:
7120 <literallayout class='monospaced'>
7121 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"
7122 </literallayout>
7123 The value of the
7124 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7125 variable, which is set in the same file, has the following
7126 value:
7127 <literallayout class='monospaced'>
7128 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7129 </literallayout>
7130 </para>
7131 </glossdef>
7132 </glossentry>
7133
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007134 <glossentry id='var-INITRD'><glossterm>INITRD</glossterm>
7135 <info>
7136 INITRD[doc] = "Indicates a list of filesystem images to concatenate and use as an initial RAM disk (initrd)."
7137 </info>
7138 <glossdef>
7139 <para role="glossdeffirst">
7140<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7141 Indicates list of filesystem images to concatenate and use
7142 as an initial RAM disk (<filename>initrd</filename>).
7143 </para>
7144
7145 <para>
7146 The <filename>INITRD</filename> variable is an optional
7147 variable used with the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05007148 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007149 class.
7150 </para>
7151 </glossdef>
7152 </glossentry>
7153
7154 <glossentry id='var-INITRD_IMAGE'><glossterm>INITRD_IMAGE</glossterm>
7155 <info>
7156 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."
7157 </info>
7158 <glossdef>
7159 <para role="glossdeffirst">
7160<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7161 When building a "live" bootable image (i.e. when
7162 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
7163 contains "live"), <filename>INITRD_IMAGE</filename>
7164 specifies the image recipe that should be built
7165 to provide the initial RAM disk image.
7166 The default value is "core-image-minimal-initramfs".
7167 </para>
7168
7169 <para>
7170 See the
7171 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
7172 class for more information.
7173 </para>
7174 </glossdef>
7175 </glossentry>
7176
7177 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
7178 <info>
7179 INITSCRIPT_NAME[doc] = "The filename of the initialization script as installed to ${sysconfdir}/init.d."
7180 </info>
7181 <glossdef>
7182 <para role="glossdeffirst">
7183<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7184 The filename of the initialization script as installed to
7185 <filename>${sysconfdir}/init.d</filename>.
7186 </para>
7187
7188 <para>
7189 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
7190 The variable is mandatory.
7191 </para>
7192 </glossdef>
7193 </glossentry>
7194
7195 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
7196 <info>
7197 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."
7198 </info>
7199 <glossdef>
7200 <para role="glossdeffirst">
7201<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7202 A list of the packages that contain initscripts.
7203 If multiple packages are specified, you need to append the package name
7204 to the other <filename>INITSCRIPT_*</filename> as an override.
7205 </para>
7206
7207 <para>
7208 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
7209 The variable is optional and defaults to the
7210 <link linkend='var-PN'><filename>PN</filename></link> variable.
7211 </para>
7212 </glossdef>
7213 </glossentry>
7214
7215 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
7216 <info>
7217 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."
7218 </info>
7219 <glossdef>
7220 <para role="glossdeffirst">
7221<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7222 Specifies the options to pass to <filename>update-rc.d</filename>.
7223 Here is an example:
7224 <literallayout class='monospaced'>
7225 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
7226 </literallayout>
7227 </para>
7228
7229 <para>
7230 In this example, the script has a runlevel of 99,
7231 starts the script in initlevels 2 and 5, and
7232 stops the script in levels 0, 1 and 6.
7233 </para>
7234
7235 <para>
7236 The variable's default value is "defaults", which is
7237 set in the
7238 <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
7239 class.
7240 </para>
7241
7242 <para>
7243 The value in
7244 <filename>INITSCRIPT_PARAMS</filename> is passed through
7245 to the <filename>update-rc.d</filename> command.
7246 For more information on valid parameters, please see the
7247 <filename>update-rc.d</filename> manual page at
7248 <ulink url='http://www.tin.org/bin/man.cgi?section=8&amp;topic=update-rc.d'></ulink>.
7249 </para>
7250 </glossdef>
7251 </glossentry>
7252
7253 <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
7254 <info>
7255 INSANE_SKIP[doc] = "Specifies the QA checks to skip for a specific package within a recipe."
7256 </info>
7257 <glossdef>
7258 <para role="glossdeffirst">
7259<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7260 Specifies the QA checks to skip for a specific package
7261 within a recipe.
7262 For example, to skip the check for symbolic link
7263 <filename>.so</filename> files in the main package of a
7264 recipe, add the following to the recipe.
7265 The package name override must be used, which in this
7266 example is <filename>${PN}</filename>:
7267 <literallayout class='monospaced'>
7268 INSANE_SKIP_${PN} += "dev-so"
7269 </literallayout>
7270 </para>
7271
7272 <para>
7273 See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
7274 section for a list of the valid QA checks you can
7275 specify using this variable.
7276 </para>
7277 </glossdef>
7278 </glossentry>
7279
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05007280 <glossentry id='var-INSTALL_TIMEZONE_FILE'><glossterm>INSTALL_TIMEZONE_FILE</glossterm>
7281 <info>
7282 INSTALL_TIMEZONE_FILE[doc] = "Enables installation of the /etc/timezone file."
7283 </info>
7284 <glossdef>
7285 <para role="glossdeffirst">
7286<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7287 By default, the <filename>tzdata</filename> recipe packages
7288 an <filename>/etc/timezone</filename> file.
7289 Set the <filename>INSTALL_TIMEZONE_FILE</filename>
7290 variable to "0" at the configuration level to disable this
7291 behavior.
7292 </para>
7293 </glossdef>
7294 </glossentry>
7295
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007296 <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
7297 <info>
7298 IPK_FEED_URIS[doc] = "List of ipkg feed records to put into generated image."
7299 </info>
7300 <glossdef>
7301 <para role="glossdeffirst">
7302<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7303 When the IPK backend is in use and package management
7304 is enabled on the target, you can use this variable to
7305 set up <filename>opkg</filename> in the target image
7306 to point to package feeds on a nominated server.
7307 Once the feed is established, you can perform
7308 installations or upgrades using the package manager
7309 at runtime.
7310 </para>
7311 </glossdef>
7312 </glossentry>
7313
7314<!--
7315 <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
7316 <glossdef>
7317 <para>
7318 An environment variable that defines the directory where
7319 post installation hooks are installed for the
7320 post install environment.
7321 This variable is fixed as follows:
7322 <literallayout class='monospaced'>
7323 ${WORKDIR}/intercept_scripts
7324 </literallayout>
7325 </para>
7326
7327 <para>
7328 After installation of a target's root filesystem,
7329 post installation scripts, which are essentially bash scripts,
7330 are all executed just a single time.
7331 Limiting execution of these scripts minimizes installation
7332 time that would be lengthened due to certain packages
7333 triggering redundant operations.
7334 For example, consider the installation of font packages
7335 as a common example.
7336 Without limiting the execution of post installation scripts,
7337 all font directories would be rescanned to create the
7338 cache after each individual font package was installed.
7339 </para>
7340
7341 <para>
7342 Do not edit the <filename>INTERCEPT_DIR</filename>
7343 variable.
7344 </para>
7345 </glossdef>
7346 </glossentry>
7347-->
7348
7349 </glossdiv>
7350
7351<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
7352<!-- </glossdiv>-->
7353
7354 <glossdiv id='var-glossary-k'><title>K</title>
7355
7356 <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
7357 <info>
7358 KARCH[doc] = "Defines the kernel architecture used when assembling the configuration. You define the KARCH variable in the BSP Descriptions."
7359 </info>
7360 <glossdef>
7361 <para role="glossdeffirst">
7362<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7363 Defines the kernel architecture used when assembling
7364 the configuration.
7365 Architectures supported for this release are:
7366 <literallayout class='monospaced'>
7367 powerpc
7368 i386
7369 x86_64
7370 arm
7371 qemu
7372 mips
7373 </literallayout>
7374 </para>
7375
7376 <para>
7377 You define the <filename>KARCH</filename> variable in the
7378 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
7379 </para>
7380 </glossdef>
7381 </glossentry>
7382
7383 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
7384 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04007385 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 -05007386 </info>
7387 <glossdef>
7388 <para role="glossdeffirst">
7389<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7390 A regular expression used by the build process to explicitly
7391 identify the kernel branch that is validated, patched,
7392 and configured during a build.
7393 You must set this variable to ensure the exact kernel
7394 branch you want is being used by the build process.
7395 </para>
7396
7397 <para>
7398 Values for this variable are set in the kernel's recipe
7399 file and the kernel's append file.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007400 For example, if you are using the
7401 <filename>linux-yocto_4.12</filename> kernel, the kernel
7402 recipe file is the
7403 <filename>meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007404 file.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007405 <filename>KBRANCH</filename> is set as follows in that
7406 kernel recipe file:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007407 <literallayout class='monospaced'>
7408 KBRANCH ?= "standard/base"
7409 </literallayout>
7410 </para>
7411
7412 <para>
7413 This variable is also used from the kernel's append file
7414 to identify the kernel branch specific to a particular
7415 machine or target hardware.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007416 Continuing with the previous kernel example, the kernel's
7417 append file (i.e.
7418 <filename>linux-yocto_4.12.bbappend</filename>) is located
7419 in the BSP layer for a given machine.
7420 For example, the append file for the Beaglebone,
7421 EdgeRouter, and generic versions of both 32 and 64-bit IA
7422 machines (<filename>meta-yocto-bsp</filename>) is named
7423 <filename>meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend</filename>.
7424 Here are the related statements from that append file:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007425 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007426 KBRANCH_genericx86 = "standard/base"
7427 KBRANCH_genericx86-64 = "standard/base"
7428 KBRANCH_edgerouter = "standard/edgerouter"
7429 KBRANCH_beaglebone = "standard/beaglebone"
7430 KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007431 </literallayout>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007432 The <filename>KBRANCH</filename> statements identify
7433 the kernel branch to use when building for each
7434 supported BSP.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007435 </para>
7436 </glossdef>
7437 </glossentry>
7438
7439 <glossentry id='var-KBUILD_DEFCONFIG'><glossterm>KBUILD_DEFCONFIG</glossterm>
7440 <info>
7441 KBUILD_DEFCONFIG[doc] = "Specifies an "in-tree" kernel configuration file for use during a kernel build."
7442 </info>
7443 <glossdef>
7444 <para role="glossdeffirst">
7445<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7446 When used with the
7447 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
7448 class, specifies an "in-tree" kernel configuration file
7449 for use during a kernel build.
7450 </para>
7451
7452 <para>
7453 Typically, when using a <filename>defconfig</filename> to
7454 configure a kernel during a build, you place the
7455 file in your layer in the same manner as you would
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007456 place patch files and configuration fragment files (i.e.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007457 "out-of-tree").
7458 However, if you want to use a <filename>defconfig</filename>
7459 file that is part of the kernel tree (i.e. "in-tree"),
7460 you can use the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007461 <filename>KBUILD_DEFCONFIG</filename> variable and append
7462 the
7463 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
7464 variable to point to the <filename>defconfig</filename>
7465 file.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007466 </para>
7467
7468 <para>
7469 To use the variable, set it in the append file for your
7470 kernel recipe using the following form:
7471 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007472 KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007473 </literallayout>
7474 Here is an example from a "raspberrypi2"
7475 <filename>KMACHINE</filename> build that uses a
7476 <filename>defconfig</filename> file named
7477 "bcm2709_defconfig":
7478 <literallayout class='monospaced'>
7479 KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig"
7480 </literallayout>
7481 As an alternative, you can use the following within your
7482 append file:
7483 <literallayout class='monospaced'>
7484 KBUILD_DEFCONFIG_pn-linux-yocto ?= <replaceable>defconfig_file</replaceable>
7485 </literallayout>
7486 For more information on how to use the
7487 <filename>KBUILD_DEFCONFIG</filename> variable, see the
7488 "<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 -04007489 section in the Yocto Project Linux Kernel Development
7490 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007491 </para>
7492 </glossdef>
7493 </glossentry>
7494
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007495 <glossentry id='var-KERNEL_ALT_IMAGETYPE'><glossterm>KERNEL_ALT_IMAGETYPE</glossterm>
7496 <info>
7497 KERNEL_ALT_IMAGETYPE[doc] = "Specifies an alternate kernel image type for creation."
7498 </info>
7499 <glossdef>
7500 <para role="glossdeffirst">
7501<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7502 Specifies an alternate kernel image type for creation in
7503 addition to the kernel image type specified using the
7504 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
7505 variable.
7506 </para>
7507 </glossdef>
7508 </glossentry>
7509
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007510 <glossentry id='var-KERNEL_ARTIFACT_NAME'><glossterm>KERNEL_ARTIFACT_NAME</glossterm>
7511 <info>
7512 KERNEL_ARTIFACT_NAME[doc] = "Specifies the name of all of the build artifacts."
7513 </info>
7514 <glossdef>
7515 <para role="glossdeffirst">
7516<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7517 Specifies the name of all of the build artifacts.
7518 You can change the name of the artifacts by changing the
7519 <filename>KERNEL_ARTIFACT_NAME</filename> variable.
7520 </para>
7521
7522 <para>
7523 The value of <filename>KERNEL_ARTIFACT_NAME</filename>,
7524 which is set in the
7525 <filename> meta/classes/kernel-artifact-names.bbclass</filename>
7526 file, has the following default value:
7527 <literallayout class='monospaced'>
7528 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7529 </literallayout>
7530 </para>
7531
7532 <para>
7533 See the
7534 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
7535 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
7536 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
7537 and
7538 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7539 variables for additional information.
7540 <note>
7541 The <filename>IMAGE_VERSION_SUFFIX</filename> variable
7542 is set to
7543 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>.
7544 </note>
7545 </para>
7546 </glossdef>
7547 </glossentry>
7548
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007549 <glossentry id='var-KERNEL_CLASSES'><glossterm>KERNEL_CLASSES</glossterm>
7550 <info>
7551 KERNEL_CLASSES[doc] = "A list of classes defining kernel image types that kernel class should inherit."
7552 </info>
7553 <glossdef>
7554 <para role="glossdeffirst">
7555<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7556 A list of classes defining kernel image types that the
7557 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
7558 class should inherit.
7559 You typically append this variable to enable extended image
7560 types.
7561 An example is the "kernel-fitimage", which enables
7562 fitImage support and resides in
7563 <filename>meta/classes/kernel-fitimage.bbclass</filename>.
7564 You can register custom kernel image types with the
7565 <filename>kernel</filename> class using this variable.
7566 </para>
7567 </glossdef>
7568 </glossentry>
7569
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007570 <glossentry id='var-KERNEL_DEVICETREE'><glossterm>KERNEL_DEVICETREE</glossterm>
7571 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04007572 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 -05007573 </info>
7574 <glossdef>
7575 <para role="glossdeffirst">
7576<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7577 Specifies the name of the generated Linux kernel device tree
7578 (i.e. the <filename>.dtb</filename>) file.
7579 <note>
7580 Legacy support exists for specifying the full path
7581 to the device tree.
7582 However, providing just the <filename>.dtb</filename>
7583 file is preferred.
7584 </note>
Brad Bishop79641f22019-09-10 07:20:22 -04007585 In order to use this variable, the
7586 <link linkend='ref-classes-kernel-devicetree'><filename>kernel-devicetree</filename></link>
7587 class must be inherited.
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007588 </para>
7589 </glossdef>
7590 </glossentry>
7591
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007592 <glossentry id='var-KERNEL_DTB_LINK_NAME'><glossterm>KERNEL_DTB_LINK_NAME</glossterm>
7593 <info>
7594 KERNEL_DTB_LINK_NAME[doc] = "The link name of the kernel device tree binary (DTB)."
7595 </info>
7596 <glossdef>
7597 <para role="glossdeffirst">
7598<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7599 The link name of the kernel device tree binary (DTB).
7600 This variable is set in the
7601 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7602 file as follows:
7603 <literallayout class='monospaced'>
7604 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7605 </literallayout>
7606 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7607 variable, which is set in the same file, has the following
7608 value:
7609 <literallayout class='monospaced'>
7610 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7611 </literallayout>
7612 </para>
7613
7614 <para>
7615 See the
7616 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7617 variable for additional information.
7618 </para>
7619 </glossdef>
7620 </glossentry>
7621
7622 <glossentry id='var-KERNEL_DTB_NAME'><glossterm>KERNEL_DTB_NAME</glossterm>
7623 <info>
7624 KERNEL_DTB_NAME[doc] = "The base name of the kernel device tree binary (DTB)."
7625 </info>
7626 <glossdef>
7627 <para role="glossdeffirst">
7628<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7629 The base name of the kernel device tree binary (DTB).
7630 This variable is set in the
7631 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7632 file as follows:
7633 <literallayout class='monospaced'>
7634 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7635 </literallayout>
7636 The value of the
7637 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7638 variable, which is set in the same file, has the following
7639 value:
7640 <literallayout class='monospaced'>
7641 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7642 </literallayout>
7643 </para>
7644 </glossdef>
7645 </glossentry>
7646
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007647 <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
7648 <info>
7649 KERNEL_EXTRA_ARGS[doc] = "Specifies additional make command-line arguments the OpenEmbedded build system passes on when compiling the kernel."
7650 </info>
7651 <glossdef>
7652 <para role="glossdeffirst">
7653<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7654 Specifies additional <filename>make</filename>
7655 command-line arguments the OpenEmbedded build system
7656 passes on when compiling the kernel.
7657 </para>
7658 </glossdef>
7659 </glossentry>
7660
7661 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
7662 <info>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007663 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 -05007664 </info>
7665 <glossdef>
7666 <para role="glossdeffirst">
7667<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007668 Includes additional kernel metadata.
7669 In the OpenEmbedded build system, the default Board Support
7670 Packages (BSPs)
7671 <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007672 is provided through
7673 the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007674 and
7675 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>
7676 variables.
7677 You can use the <filename>KERNEL_FEATURES</filename>
7678 variable from within the kernel recipe or kernel append
7679 file to further add metadata for all BSPs or specific
7680 BSPs.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007681 </para>
7682
7683 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007684 The metadata you add through this variable includes config
7685 fragments and features descriptions,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007686 which usually includes patches as well as config fragments.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007687 You typically override the
7688 <filename>KERNEL_FEATURES</filename> variable for a
7689 specific machine.
7690 In this way, you can provide validated, but optional,
7691 sets of kernel configurations and features.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007692 </para>
7693
7694 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007695 For example, the following example from the
7696 <filename>linux-yocto-rt_4.12</filename> kernel recipe
7697 adds "netfilter" and "taskstats" features to all BSPs
7698 as well as "virtio" configurations to all QEMU machines.
7699 The last two statements add specific configurations to
7700 targeted machine types:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007701 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007702 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
7703 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007704 KERNEL_FEATURES_append_qemuall = " cfg/virtio.scc"
7705 KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"
7706 KERNEL_FEATURES_append_qemux86-64 = " cfg/sound.scc" </literallayout></para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007707 </glossdef>
7708 </glossentry>
7709
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007710 <glossentry id='var-KERNEL_FIT_LINK_NAME'><glossterm>KERNEL_FIT_LINK_NAME</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007711 <info>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007712 KERNEL_FIT_LINK_NAME[doc] = "The link name of the kernel flattened image tree (FIT) image."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007713 </info>
7714 <glossdef>
7715 <para role="glossdeffirst">
7716<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007717 The link name of the kernel flattened image tree (FIT) image.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007718 This variable is set in the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007719 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7720 file as follows:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007721 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007722 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7723 </literallayout>
7724 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7725 variable, which is set in the same file, has the following
7726 value:
7727 <literallayout class='monospaced'>
7728 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007729 </literallayout>
7730 </para>
7731
7732 <para>
7733 See the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007734 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7735 variable for additional information.
7736 </para>
7737 </glossdef>
7738 </glossentry>
7739
7740 <glossentry id='var-KERNEL_FIT_NAME'><glossterm>KERNEL_FIT_NAME</glossterm>
7741 <info>
7742 KERNEL_FIT_NAME[doc] = "The base name of the kernel flattened image tree (FIT) image."
7743 </info>
7744 <glossdef>
7745 <para role="glossdeffirst">
7746<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7747 The base name of the kernel flattened image tree (FIT) image.
7748 This variable is set in the
7749 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7750 file as follows:
7751 <literallayout class='monospaced'>
7752 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7753 </literallayout>
7754 The value of the
7755 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7756 variable, which is set in the same file, has the following
7757 value:
7758 <literallayout class='monospaced'>
7759 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7760 </literallayout>
7761 </para>
7762 </glossdef>
7763 </glossentry>
7764
7765 <glossentry id='var-KERNEL_IMAGE_LINK_NAME'><glossterm>KERNEL_IMAGE_LINK_NAME</glossterm>
7766 <info>
7767 KERNEL_IMAGE_LINK_NAME[doc] = "The link name for the kernel image."
7768 </info>
7769 <glossdef>
7770 <para role="glossdeffirst">
7771<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7772 The link name for the kernel image.
7773 This variable is set in the
7774 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7775 file as follows:
7776 <literallayout class='monospaced'>
7777 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7778 </literallayout>
7779 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7780 variable, which is set in the same file, has the following
7781 value:
7782 <literallayout class='monospaced'>
7783 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7784 </literallayout>
7785 </para>
7786
7787 <para>
7788 See the
7789 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7790 variable for additional information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007791 </para>
7792 </glossdef>
7793 </glossentry>
7794
7795 <glossentry id='var-KERNEL_IMAGE_MAXSIZE'><glossterm>KERNEL_IMAGE_MAXSIZE</glossterm>
7796 <info>
7797 KERNEL_IMAGE_MAXSIZE[doc] = "The maximum allowable size in kilobytes of the kernel image file."
7798 </info>
7799 <glossdef>
7800 <para role="glossdeffirst">
7801<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7802 Specifies the maximum size of the kernel image file in
7803 kilobytes.
7804 If <filename>KERNEL_IMAGE_MAXSIZE</filename> is set,
7805 the size of the kernel image file is checked against
7806 the set value during the
7807 <link linkend='ref-tasks-sizecheck'><filename>do_sizecheck</filename></link>
7808 task.
7809 The task fails if the kernel image file is larger than
7810 the setting.
7811 </para>
7812
7813 <para>
7814 <filename>KERNEL_IMAGE_MAXSIZE</filename> is useful for
7815 target devices that have a limited amount of space in
7816 which the kernel image must be stored.
7817 </para>
7818
7819 <para>
7820 By default, this variable is not set, which means the
7821 size of the kernel image is not checked.
7822 </para>
7823 </glossdef>
7824 </glossentry>
7825
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007826 <glossentry id='var-KERNEL_IMAGE_NAME'><glossterm>KERNEL_IMAGE_NAME</glossterm>
7827 <info>
7828 KERNEL_IMAGE_NAME[doc] = "The base name of the kernel image."
7829 </info>
7830 <glossdef>
7831 <para role="glossdeffirst">
7832<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7833 The base name of the kernel image.
7834 This variable is set in the
7835 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7836 file as follows:
7837 <literallayout class='monospaced'>
7838 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7839 </literallayout>
7840 The value of the
7841 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7842 variable, which is set in the same file, has the following
7843 value:
7844 <literallayout class='monospaced'>
7845 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7846 </literallayout>
7847 </para>
7848 </glossdef>
7849 </glossentry>
7850
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007851 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
7852 <info>
7853 KERNEL_IMAGETYPE[doc] = "The type of kernel to build for a device, usually set by the machine configuration files and defaults to 'zImage'."
7854 </info>
7855 <glossdef>
7856 <para role="glossdeffirst">
7857<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7858 The type of kernel to build for a device, usually set by the
7859 machine configuration files and defaults to "zImage".
7860 This variable is used
7861 when building the kernel and is passed to <filename>make</filename> as the target to
7862 build.
7863 </para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007864
7865 <para>
7866 If you want to build an alternate kernel image type, use the
7867 <link linkend='var-KERNEL_ALT_IMAGETYPE'><filename>KERNEL_ALT_IMAGETYPE</filename></link>
7868 variable.
7869 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007870 </glossdef>
7871 </glossentry>
7872
7873 <glossentry id='var-KERNEL_MODULE_AUTOLOAD'><glossterm>KERNEL_MODULE_AUTOLOAD</glossterm>
7874 <info>
7875 KERNEL_MODULE_AUTOLOAD[doc] = "Lists kernel modules that need to be auto-loaded during boot"
7876 </info>
7877 <glossdef>
7878 <para role="glossdeffirst">
7879<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7880 Lists kernel modules that need to be auto-loaded during
7881 boot.
7882 <note>
7883 This variable replaces the deprecated
7884 <link linkend='var-module_autoload'><filename>module_autoload</filename></link>
7885 variable.
7886 </note>
7887 </para>
7888
7889 <para>
7890 You can use the <filename>KERNEL_MODULE_AUTOLOAD</filename>
7891 variable anywhere that it can be
7892 recognized by the kernel recipe or by an out-of-tree kernel
7893 module recipe (e.g. a machine configuration file, a
7894 distribution configuration file, an append file for the
7895 recipe, or the recipe itself).
7896 </para>
7897
7898 <para>
7899 Specify it as follows:
7900 <literallayout class='monospaced'>
7901 KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name1</replaceable> <replaceable>module_name2</replaceable> <replaceable>module_name3</replaceable>"
7902 </literallayout>
7903 </para>
7904
7905 <para>
7906 Including <filename>KERNEL_MODULE_AUTOLOAD</filename> causes
7907 the OpenEmbedded build system to populate the
7908 <filename>/etc/modules-load.d/modname.conf</filename>
7909 file with the list of modules to be auto-loaded on boot.
7910 The modules appear one-per-line in the file.
7911 Here is an example of the most common use case:
7912 <literallayout class='monospaced'>
7913 KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name</replaceable>"
7914 </literallayout>
7915 </para>
7916
7917 <para>
7918 For information on how to populate the
7919 <filename>modname.conf</filename> file with
7920 <filename>modprobe.d</filename> syntax lines, see the
7921 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
7922 variable.
7923 </para>
7924 </glossdef>
7925 </glossentry>
7926
7927 <glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm>KERNEL_MODULE_PROBECONF</glossterm>
7928 <info>
7929 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."
7930 </info>
7931 <glossdef>
7932 <para role="glossdeffirst">
7933<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7934 Provides a list of modules for which the OpenEmbedded
7935 build system expects to find
7936 <filename>module_conf_</filename><replaceable>modname</replaceable>
7937 values that specify configuration for each of the modules.
7938 For information on how to provide those module
7939 configurations, see the
7940 <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
7941 variable.
7942 </para>
7943 </glossdef>
7944 </glossentry>
7945
7946 <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
7947 <info>
7948 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)."
7949 </info>
7950 <glossdef>
7951 <para role="glossdeffirst">
7952<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7953 The location of the kernel sources.
7954 This variable is set to the value of the
7955 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
7956 within the
7957 <link linkend='ref-classes-module'><filename>module</filename></link>
7958 class.
7959 For information on how this variable is used, see the
7960 "<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 -04007961 section in the Yocto Project Linux Kernel Development
7962 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007963 </para>
7964
7965 <para>
7966 To help maximize compatibility with out-of-tree drivers
7967 used to build modules, the OpenEmbedded build system also
7968 recognizes and uses the
7969 <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
7970 variable, which is identical to the
7971 <filename>KERNEL_PATH</filename> variable.
7972 Both variables are common variables used by external
7973 Makefiles to point to the kernel source directory.
7974 </para>
7975 </glossdef>
7976 </glossentry>
7977
7978 <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
7979 <info>
7980 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)."
7981 </info>
7982 <glossdef>
7983 <para role="glossdeffirst">
7984<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7985 The location of the kernel sources.
7986 This variable is set to the value of the
7987 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
7988 within the
7989 <link linkend='ref-classes-module'><filename>module</filename></link>
7990 class.
7991 For information on how this variable is used, see the
7992 "<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 -04007993 section in the Yocto Project Linux Kernel Development
7994 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007995 </para>
7996
7997 <para>
7998 To help maximize compatibility with out-of-tree drivers
7999 used to build modules, the OpenEmbedded build system also
8000 recognizes and uses the
8001 <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
8002 variable, which is identical to the
8003 <filename>KERNEL_SRC</filename> variable.
8004 Both variables are common variables used by external
8005 Makefiles to point to the kernel source directory.
8006 </para>
8007 </glossdef>
8008 </glossentry>
8009
Patrick Williamsf1e5d692016-03-30 15:21:19 -05008010 <glossentry id='var-KERNEL_VERSION'><glossterm>KERNEL_VERSION</glossterm>
8011 <info>
8012 KERNEL_VERSION[doc] = "Specifies the version of the kernel as extracted from version.h or utsrelease.h within the kernel sources."
8013 </info>
8014 <glossdef>
8015 <para role="glossdeffirst">
8016<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8017 Specifies the version of the kernel as extracted from
8018 <filename>version.h</filename> or
8019 <filename>utsrelease.h</filename> within the kernel sources.
8020 Effects of setting this variable do not take affect until
8021 the kernel has been configured.
8022 Consequently, attempting to refer to this variable in
8023 contexts prior to configuration will not work.
8024 </para>
8025 </glossdef>
8026 </glossentry>
8027
8028 <glossentry id='var-KERNELDEPMODDEPEND'><glossterm>KERNELDEPMODDEPEND</glossterm>
8029 <info>
8030 KERNELDEPMODDEPEND[doc] = "Specifies whether or not to use the data referenced through the PKGDATA_DIR directory."
8031 </info>
8032 <glossdef>
8033 <para role="glossdeffirst">
8034<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8035 Specifies whether the data referenced through
8036 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
8037 is needed or not.
8038 The <filename>KERNELDEPMODDEPEND</filename> does not
8039 control whether or not that data exists,
8040 but simply whether or not it is used.
8041 If you do not need to use the data, set the
8042 <filename>KERNELDEPMODDEPEND</filename> variable in your
8043 <filename>initramfs</filename> recipe.
8044 Setting the variable there when the data is not needed
8045 avoids a potential dependency loop.
8046 </para>
8047 </glossdef>
8048 </glossentry>
8049
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008050 <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
8051 <info>
8052 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."
8053 </info>
8054 <glossdef>
8055 <para role="glossdeffirst">
8056<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8057 Provides a short description of a configuration fragment.
8058 You use this variable in the <filename>.scc</filename>
8059 file that describes a configuration fragment file.
8060 Here is the variable used in a file named
8061 <filename>smp.scc</filename> to describe SMP being
8062 enabled:
8063 <literallayout class='monospaced'>
8064 define KFEATURE_DESCRIPTION "Enable SMP"
8065 </literallayout>
8066 </para>
8067 </glossdef>
8068 </glossentry>
8069
8070 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
8071 <info>
8072 KMACHINE[doc] = "The machine as known by the kernel."
8073 </info>
8074 <glossdef>
8075 <para role="glossdeffirst">
8076<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8077 The machine as known by the kernel.
8078 Sometimes the machine name used by the kernel does not
8079 match the machine name used by the OpenEmbedded build
8080 system.
8081 For example, the machine name that the OpenEmbedded build
8082 system understands as
8083 <filename>core2-32-intel-common</filename> goes by a
8084 different name in the Linux Yocto kernel.
8085 The kernel understands that machine as
8086 <filename>intel-core2-32</filename>.
8087 For cases like these, the <filename>KMACHINE</filename>
8088 variable maps the kernel machine name to the OpenEmbedded
8089 build system machine name.
8090 </para>
8091
8092 <para>
8093 These mappings between different names occur in the
8094 Yocto Linux Kernel's <filename>meta</filename> branch.
8095 As an example take a look in the
8096 <filename>common/recipes-kernel/linux/linux-yocto_3.19.bbappend</filename>
8097 file:
8098 <literallayout class='monospaced'>
8099 LINUX_VERSION_core2-32-intel-common = "3.19.0"
8100 COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}"
8101 SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"
8102 SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
8103 KMACHINE_core2-32-intel-common = "intel-core2-32"
8104 KBRANCH_core2-32-intel-common = "standard/base"
8105 KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"
8106 </literallayout>
8107 The <filename>KMACHINE</filename> statement says that
8108 the kernel understands the machine name as
8109 "intel-core2-32".
8110 However, the OpenEmbedded build system understands the
8111 machine as "core2-32-intel-common".
8112 </para>
8113
8114 </glossdef>
8115 </glossentry>
8116
8117 <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
8118 <info>
8119 KTYPE[doc] = "Defines the kernel type to be used in assembling the configuration."
8120 </info>
8121 <glossdef>
8122 <para role="glossdeffirst">
8123<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8124 Defines the kernel type to be used in assembling the
8125 configuration.
8126 The linux-yocto recipes define "standard", "tiny",
8127 and "preempt-rt" kernel types.
8128 See the
8129 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
8130 section in the Yocto Project Linux Kernel Development
8131 Manual for more information on kernel types.
8132 </para>
8133
8134 <para>
8135 You define the <filename>KTYPE</filename> variable in the
8136 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
8137 The value you use must match the value used for the
8138 <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
8139 value used by the kernel recipe.
8140 </para>
8141 </glossdef>
8142 </glossentry>
8143 </glossdiv>
8144
8145 <glossdiv id='var-glossary-l'><title>L</title>
8146
8147 <glossentry id='var-LABELS'><glossterm>LABELS</glossterm>
8148 <info>
8149 LABELS[doc] = "Provides a list of targets for automatic configuration."
8150 </info>
8151 <glossdef>
8152 <para role="glossdeffirst">
8153<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8154 Provides a list of targets for automatic configuration.
8155 </para>
8156
8157 <para>
8158 See the
8159 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
8160 class for more information on how this variable is used.
8161 </para>
8162 </glossdef>
8163 </glossentry>
8164
8165 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
8166 <info>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05008167 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 -05008168 </info>
8169 <glossdef>
8170 <para role="glossdeffirst">
8171<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop6e60e8b2018-02-01 10:27:11 -05008172 Lists the layers, separated by spaces, on which this
8173 recipe depends.
8174 Optionally, you can specify a specific layer version for a
8175 dependency by adding it to the end of the layer name.
8176 Here is an example:
8177 <literallayout class='monospaced'>
8178 LAYERDEPENDS_mylayer = "anotherlayer (=3)"
8179 </literallayout>
8180 In this previous example, version 3 of "anotherlayer"
8181 is compared against
8182 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>.
8183 </para>
8184
8185 <para>
8186 An error is produced if any dependency is missing or
8187 the version numbers (if specified) do not match exactly.
8188 This variable is used in the
8189 <filename>conf/layer.conf</filename> file and must be
8190 suffixed with the name of the specific layer (e.g.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008191 <filename>LAYERDEPENDS_mylayer</filename>).
8192 </para>
8193 </glossdef>
8194 </glossentry>
8195
8196 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
8197 <info>
8198 LAYERDIR[doc] = "When used inside the layer.conf configuration file, this variable provides the path of the current layer."
8199 </info>
8200 <glossdef>
8201 <para role="glossdeffirst">
8202<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8203 When used inside the <filename>layer.conf</filename> configuration
8204 file, this variable provides the path of the current layer.
8205 This variable is not available outside of <filename>layer.conf</filename>
8206 and references are expanded immediately when parsing of the file completes.
8207 </para>
8208 </glossdef>
8209 </glossentry>
8210
Brad Bishop6e60e8b2018-02-01 10:27:11 -05008211 <glossentry id='var-LAYERRECOMMENDS'><glossterm>LAYERRECOMMENDS</glossterm>
8212 <info>
8213 LAYERRECOMMENDS[doc] = "Lists the layers, separated by spaces, recommended for use with this layer."
8214 </info>
8215 <glossdef>
8216 <para role="glossdeffirst">
8217<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8218 Lists the layers, separated by spaces, recommended for
8219 use with this layer.
8220 </para>
8221
8222 <para>
8223 Optionally, you can specify a specific layer version for a
8224 recommendation by adding the version to the end of the
8225 layer name.
8226 Here is an example:
8227 <literallayout class='monospaced'>
8228 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"
8229 </literallayout>
8230 In this previous example, version 3 of "anotherlayer" is
8231 compared against
8232 <filename>LAYERVERSION_anotherlayer</filename>.
8233 </para>
8234
8235 <para>
8236 This variable is used in the
8237 <filename>conf/layer.conf</filename> file and must be
8238 suffixed with the name of the specific layer (e.g.
8239 <filename>LAYERRECOMMENDS_mylayer</filename>).
8240 </para>
8241 </glossdef>
8242 </glossentry>
8243
Brad Bishop316dfdd2018-06-25 12:45:53 -04008244 <glossentry id='var-LAYERSERIES_COMPAT'><glossterm>LAYERSERIES_COMPAT</glossterm>
8245 <info>
8246 LAYERSERIES_COMPAT[doc] = "Lists the OpenEmbedded-Core versions for which a layer is compatible."
8247 </info>
8248 <glossdef>
8249 <para role="glossdeffirst">
8250<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8251 Lists the versions of the
8252 <link linkend='oe-core'>OpenEmbedded-Core</link> for which
8253 a layer is compatible.
8254 Using the <filename>LAYERSERIES_COMPAT</filename> variable
8255 allows the layer maintainer to indicate which combinations
8256 of the layer and OE-Core can be expected to work.
8257 The variable gives the system a way to detect when a layer
8258 has not been tested with new releases of OE-Core (e.g.
8259 the layer is not maintained).
8260 </para>
8261
8262 <para>
8263 To specify the OE-Core versions for which a layer is
8264 compatible, use this variable in your layer's
8265 <filename>conf/layer.conf</filename> configuration file.
8266 For the list, use the Yocto Project
8267 <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Release Name</ulink>
8268 (e.g. &DISTRO_NAME_NO_CAP;).
8269 To specify multiple OE-Core versions for the layer,
8270 use a space-separated list:
8271 <literallayout class='monospaced'>
8272 LAYERSERIES_COMPAT_<replaceable>layer_root_name</replaceable> = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;"
8273 </literallayout>
8274 <note>
8275 Setting <filename>LAYERSERIES_COMPAT</filename> is
8276 required by the Yocto Project Compatible version 2
8277 standard.
8278 The OpenEmbedded build system produces a warning if
8279 the variable is not set for any given layer.
8280 </note>
8281 </para>
8282
8283 <para>
8284 See the
8285 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-layer'>Creating Your Own Layer</ulink>"
8286 section in the Yocto Project Development Tasks Manual.
8287 </para>
8288 </glossdef>
8289 </glossentry>
8290
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008291 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
8292 <info>
8293 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."
8294 </info>
8295 <glossdef>
8296 <para role="glossdeffirst">
8297<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8298 Optionally specifies the version of a layer as a single number.
8299 You can use this within
8300 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
8301 for another layer in order to depend on a specific version
8302 of the layer.
8303 This variable is used in the <filename>conf/layer.conf</filename> file
8304 and must be suffixed with the name of the specific layer (e.g.
8305 <filename>LAYERVERSION_mylayer</filename>).
8306 </para>
8307 </glossdef>
8308 </glossentry>
8309
8310 <glossentry id='var-LD'><glossterm>LD</glossterm>
8311 <info>
8312 LD[doc] = "Minimal command and arguments to run the linker."
8313 </info>
8314 <glossdef>
8315 <para role="glossdeffirst">
8316<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8317 The minimal command and arguments used to run the
8318 linker.
8319 </para>
8320 </glossdef>
8321 </glossentry>
8322
8323 <glossentry id='var-LDFLAGS'><glossterm>LDFLAGS</glossterm>
8324 <info>
8325 LDFLAGS[doc] = "Specifies the flags to pass to the linker."
8326 </info>
8327 <glossdef>
8328 <para role="glossdeffirst">
8329<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8330 Specifies the flags to pass to the linker.
8331 This variable is exported to an environment
8332 variable and thus made visible to the software being
8333 built during the compilation step.
8334 </para>
8335
8336 <para>
8337 Default initialization for <filename>LDFLAGS</filename>
8338 varies depending on what is being built:
8339 <itemizedlist>
8340 <listitem><para>
8341 <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link>
8342 when building for the target
8343 </para></listitem>
8344 <listitem><para>
8345 <link linkend='var-BUILD_LDFLAGS'><filename>BUILD_LDFLAGS</filename></link>
8346 when building for the build host (i.e.
8347 <filename>-native</filename>)
8348 </para></listitem>
8349 <listitem><para>
8350 <link linkend='var-BUILDSDK_LDFLAGS'><filename>BUILDSDK_LDFLAGS</filename></link>
8351 when building for an SDK (i.e.
8352 <filename>nativesdk-</filename>)
8353 </para></listitem>
8354 </itemizedlist>
8355 </para>
8356 </glossdef>
8357 </glossentry>
8358
8359 <glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>
8360 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04008361 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 -05008362 </info>
8363 <glossdef>
8364 <para role="glossdeffirst">
8365<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8366 Specifies the lead (or primary) compiled library file
Brad Bishop316dfdd2018-06-25 12:45:53 -04008367 (i.e. <filename>.so</filename>) that the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008368 <link linkend='ref-classes-debian'><filename>debian</filename></link>
8369 class applies its naming policy to given a recipe that
8370 packages multiple libraries.
8371 </para>
8372
8373 <para>
8374 This variable works in conjunction with the
8375 <filename>debian</filename> class.
8376 </para>
8377 </glossdef>
8378 </glossentry>
8379
8380 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
8381 <info>
8382 LIC_FILES_CHKSUM[doc] = "Checksums of the license text in the recipe source code."
8383 </info>
8384 <glossdef>
8385 <para role="glossdeffirst">
8386<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8387 Checksums of the license text in the recipe source code.
8388 </para>
8389
8390 <para>
8391 This variable tracks changes in license text of the source
8392 code files.
8393 If the license text is changed, it will trigger a build
8394 failure, which gives the developer an opportunity to review any
8395 license change.
8396 </para>
8397
8398 <para>
8399 This variable must be defined for all recipes (unless
8400 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8401 is set to "CLOSED").</para>
8402 <para>For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04008403 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
8404 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008405 </para>
8406 </glossdef>
8407 </glossentry>
8408
8409 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
8410 <info>
8411 LICENSE[doc] = "The list of source licenses for the recipe. The logical operators &amp;, '|', and parentheses can be used."
8412 </info>
8413 <glossdef>
8414 <para role="glossdeffirst">
8415<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8416 The list of source licenses for the recipe.
8417 Follow these rules:
8418 <itemizedlist>
8419 <listitem><para>Do not use spaces within individual
8420 license names.</para></listitem>
8421 <listitem><para>Separate license names using
8422 | (pipe) when there is a choice between licenses.
8423 </para></listitem>
8424 <listitem><para>Separate license names using
8425 &amp; (ampersand) when multiple licenses exist
8426 that cover different parts of the source.
8427 </para></listitem>
8428 <listitem><para>You can use spaces between license
8429 names.</para></listitem>
8430 <listitem><para>For standard licenses, use the names
8431 of the files in
8432 <filename>meta/files/common-licenses/</filename>
8433 or the
8434 <link linkend='var-SPDXLICENSEMAP'><filename>SPDXLICENSEMAP</filename></link>
8435 flag names defined in
8436 <filename>meta/conf/licenses.conf</filename>.
8437 </para></listitem>
8438 </itemizedlist>
8439 </para>
8440
8441 <para>
8442 Here are some examples:
8443 <literallayout class='monospaced'>
8444 LICENSE = "LGPLv2.1 | GPLv3"
8445 LICENSE = "MPL-1 &amp; LGPLv2.1"
8446 LICENSE = "GPLv2+"
8447 </literallayout>
8448 The first example is from the recipes for Qt, which the user
8449 may choose to distribute under either the LGPL version
8450 2.1 or GPL version 3.
8451 The second example is from Cairo where two licenses cover
8452 different parts of the source code.
8453 The final example is from <filename>sysstat</filename>,
8454 which presents a single license.
8455 </para>
8456
8457 <para>
8458 You can also specify licenses on a per-package basis to
8459 handle situations where components of the output have
8460 different licenses.
8461 For example, a piece of software whose code is
8462 licensed under GPLv2 but has accompanying documentation
8463 licensed under the GNU Free Documentation License 1.2 could
8464 be specified as follows:
8465 <literallayout class='monospaced'>
8466 LICENSE = "GFDL-1.2 &amp; GPLv2"
8467 LICENSE_${PN} = "GPLv2"
8468 LICENSE_${PN}-doc = "GFDL-1.2"
8469 </literallayout>
8470 </para>
8471 </glossdef>
8472 </glossentry>
8473
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05008474 <glossentry id='var-LICENSE_CREATE_PACKAGE'><glossterm>LICENSE_CREATE_PACKAGE</glossterm>
8475 <info>
8476 LICENSE_CREATE_PACKAGE[doc] = "Creates an extra package (i.e. ${PN}-lic) for each recipe and adds that package to the RRECOMMENDS+${PN}."
8477 </info>
8478 <glossdef>
8479 <para role="glossdeffirst">
8480<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8481 Setting <filename>LICENSE_CREATE_PACKAGE</filename>
8482 to "1" causes the OpenEmbedded build system to create
8483 an extra package (i.e.
8484 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-lic</filename>)
8485 for each recipe and to add those packages to the
8486 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link><filename>_${PN}</filename>.
8487 </para>
8488
8489 <para>
8490 The <filename>${PN}-lic</filename> package installs a
8491 directory in <filename>/usr/share/licenses</filename>
8492 named <filename>${PN}</filename>, which is the recipe's
8493 base name, and installs files in that directory that
8494 contain license and copyright information (i.e. copies of
8495 the appropriate license files from
8496 <filename>meta/common-licenses</filename> that match the
8497 licenses specified in the
8498 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8499 variable of the recipe metadata and copies of files marked
8500 in
8501 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
8502 as containing license text).
8503 </para>
8504
8505 <para>
8506 For related information on providing license text, see the
8507 <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
8508 variable, the
8509 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
8510 variable, and the
8511 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008512 section in the Yocto Project Development Tasks Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05008513 </para>
8514 </glossdef>
8515 </glossentry>
8516
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008517 <glossentry id='var-LICENSE_FLAGS'><glossterm>LICENSE_FLAGS</glossterm>
8518 <info>
8519 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."
8520 </info>
8521 <glossdef>
8522 <para role="glossdeffirst">
8523<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8524 Specifies additional flags for a recipe you must
8525 whitelist through
8526 <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
8527 in order to allow the recipe to be built.
8528 When providing multiple flags, separate them with
8529 spaces.
8530 </para>
8531
8532 <para>
8533 This value is independent of
8534 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8535 and is typically used to mark recipes that might
8536 require additional licenses in order to be used in a
8537 commercial product.
8538 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04008539 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8540 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008541 </para>
8542 </glossdef>
8543 </glossentry>
8544
8545 <glossentry id='var-LICENSE_FLAGS_WHITELIST'><glossterm>LICENSE_FLAGS_WHITELIST</glossterm>
8546 <info>
8547 LICENSE_FLAGS_WHITELIST[doc] = "Lists license flags that when specified in LICENSE_FLAGS within a recipe should not prevent that recipe from being built."
8548 </info>
8549 <glossdef>
8550 <para role="glossdeffirst">
8551<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8552 Lists license flags that when specified in
8553 <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
8554 within a recipe should not prevent that recipe from being
8555 built.
8556 This practice is otherwise known as "whitelisting"
8557 license flags.
8558 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04008559 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8560 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008561 </para>
8562 </glossdef>
8563 </glossentry>
8564
8565 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
8566 <info>
8567 LICENSE_PATH[doc] = "Path to additional licenses used during the build."
8568 </info>
8569 <glossdef>
8570 <para role="glossdeffirst">
8571<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8572 Path to additional licenses used during the build.
8573 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
8574 to define the directory that holds common license text used during the build.
8575 The <filename>LICENSE_PATH</filename> variable allows you to extend that
8576 location to other areas that have additional licenses:
8577 <literallayout class='monospaced'>
8578 LICENSE_PATH += "<replaceable>path-to-additional-common-licenses</replaceable>"
8579 </literallayout>
8580 </para>
8581 </glossdef>
8582 </glossentry>
8583
8584 <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
8585 <info>
8586 LINUX_KERNEL_TYPE[doc] = "Defines the kernel type to be used in assembling the configuration."
8587 </info>
8588 <glossdef>
8589 <para role="glossdeffirst">
8590<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8591 Defines the kernel type to be used in assembling the
8592 configuration.
8593 The linux-yocto recipes define "standard", "tiny", and
8594 "preempt-rt" kernel types.
8595 See the
8596 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
8597 section in the Yocto Project Linux Kernel Development
8598 Manual for more information on kernel types.
8599 </para>
8600
8601 <para>
8602 If you do not specify a
8603 <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
8604 "standard".
8605 Together with
8606 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
8607 the <filename>LINUX_KERNEL_TYPE</filename> variable
8608 defines the search
8609 arguments used by the kernel tools to find the appropriate
8610 description within the kernel
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008611 <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008612 with which to build out the sources and configuration.
8613 </para>
8614 </glossdef>
8615 </glossentry>
8616
8617 <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
8618 <info>
8619 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."
8620 </info>
8621 <glossdef>
8622 <para role="glossdeffirst">
8623<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8624 The Linux version from <filename>kernel.org</filename>
8625 on which the Linux kernel image being built using the
8626 OpenEmbedded build system is based.
8627 You define this variable in the kernel recipe.
8628 For example, the <filename>linux-yocto-3.4.bb</filename>
8629 kernel recipe found in
8630 <filename>meta/recipes-kernel/linux</filename>
8631 defines the variables as follows:
8632 <literallayout class='monospaced'>
8633 LINUX_VERSION ?= "3.4.24"
8634 </literallayout>
8635 </para>
8636
8637 <para>
8638 The <filename>LINUX_VERSION</filename> variable is used to
8639 define <link linkend='var-PV'><filename>PV</filename></link>
8640 for the recipe:
8641 <literallayout class='monospaced'>
8642 PV = "${LINUX_VERSION}+git${SRCPV}"
8643 </literallayout>
8644 </para>
8645 </glossdef>
8646 </glossentry>
8647
8648 <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
8649 <info>
8650 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."
8651 </info>
8652 <glossdef>
8653 <para role="glossdeffirst">
8654<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8655 A string extension compiled into the version
8656 string of the Linux kernel built with the OpenEmbedded
8657 build system.
8658 You define this variable in the kernel recipe.
8659 For example, the linux-yocto kernel recipes all define
8660 the variable as follows:
8661 <literallayout class='monospaced'>
8662 LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
8663 </literallayout>
8664 </para>
8665
8666 <para>
8667 Defining this variable essentially sets the
8668 Linux kernel configuration item
8669 <filename>CONFIG_LOCALVERSION</filename>, which is visible
8670 through the <filename>uname</filename> command.
8671 Here is an example that shows the extension assuming it
8672 was set as previously shown:
8673 <literallayout class='monospaced'>
8674 $ uname -r
8675 3.7.0-rc8-custom
8676 </literallayout>
8677 </para>
8678 </glossdef>
8679 </glossentry>
8680
8681 <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
8682 <info>
8683 LOG_DIR[doc] = "Specifies the directory to which the OpenEmbedded build system writes overall log files. The default directory is ${TMPDIR}/log"
8684 </info>
8685 <glossdef>
8686 <para role="glossdeffirst">
8687<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8688 Specifies the directory to which the OpenEmbedded build
8689 system writes overall log files.
8690 The default directory is <filename>${TMPDIR}/log</filename>.
8691 </para>
8692
8693 <para>
8694 For the directory containing logs specific to each task,
8695 see the <link linkend='var-T'><filename>T</filename></link>
8696 variable.
8697 </para>
8698 </glossdef>
8699 </glossentry>
8700
8701 </glossdiv>
8702
8703 <glossdiv id='var-glossary-m'><title>M</title>
8704
8705 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
8706 <info>
8707 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."
8708 </info>
8709 <glossdef>
8710 <para role="glossdeffirst">
8711<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8712 Specifies the target device for which the image is built.
8713 You define <filename>MACHINE</filename> in the
8714 <filename>local.conf</filename> file found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008715 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008716 By default, <filename>MACHINE</filename> is set to
8717 "qemux86", which is an x86-based architecture machine to
8718 be emulated using QEMU:
8719 <literallayout class='monospaced'>
8720 MACHINE ?= "qemux86"
8721 </literallayout>
8722 </para>
8723
8724 <para>
8725 The variable corresponds to a machine configuration file of the
8726 same name, through which machine-specific configurations are set.
8727 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
8728 exists the corresponding <filename>qemux86.conf</filename> machine
8729 configuration file, which can be found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008730 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008731 in <filename>meta/conf/machine</filename>.
8732 </para>
8733
8734 <para>
8735 The list of machines supported by the Yocto Project as
8736 shipped include the following:
8737 <literallayout class='monospaced'>
8738 MACHINE ?= "qemuarm"
8739 MACHINE ?= "qemuarm64"
8740 MACHINE ?= "qemumips"
8741 MACHINE ?= "qemumips64"
8742 MACHINE ?= "qemuppc"
8743 MACHINE ?= "qemux86"
8744 MACHINE ?= "qemux86-64"
8745 MACHINE ?= "genericx86"
8746 MACHINE ?= "genericx86-64"
8747 MACHINE ?= "beaglebone"
8748 MACHINE ?= "mpc8315e-rdb"
8749 MACHINE ?= "edgerouter"
8750 </literallayout>
8751 The last five are Yocto Project reference hardware boards, which
8752 are provided in the <filename>meta-yocto-bsp</filename> layer.
8753 <note>Adding additional Board Support Package (BSP) layers
8754 to your configuration adds new possible settings for
8755 <filename>MACHINE</filename>.
8756 </note>
8757 </para>
8758 </glossdef>
8759 </glossentry>
8760
8761 <glossentry id='var-MACHINE_ARCH'><glossterm>MACHINE_ARCH</glossterm>
8762 <info>
8763 MACHINE_ARCH[doc] = "Specifies the name of the machine-specific architecture. This variable is set automatically from MACHINE or TUNE_PKGARCH."
8764 </info>
8765 <glossdef>
8766 <para role="glossdeffirst">
8767<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8768 Specifies the name of the machine-specific architecture.
8769 This variable is set automatically from
8770 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
8771 or
8772 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>.
8773 You should not hand-edit the
8774 <filename>MACHINE_ARCH</filename> variable.
8775 </para>
8776 </glossdef>
8777 </glossentry>
8778
8779 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
8780 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04008781 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 -05008782 </info>
8783 <glossdef>
8784 <para role="glossdeffirst">
8785<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8786 A list of required machine-specific packages to install as part of
8787 the image being built.
8788 The build process depends on these packages being present.
Brad Bishop316dfdd2018-06-25 12:45:53 -04008789 Furthermore, because this is a "machine-essential" variable, the list of
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008790 packages are essential for the machine to boot.
8791 The impact of this variable affects images based on
8792 <filename>packagegroup-core-boot</filename>,
8793 including the <filename>core-image-minimal</filename> image.
8794 </para>
8795
8796 <para>
8797 This variable is similar to the
8798 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
8799 variable with the exception that the image being built has a build
8800 dependency on the variable's list of packages.
8801 In other words, the image will not build if a file in this list is not found.
8802 </para>
8803
8804 <para>
8805 As an example, suppose the machine for which you are building requires
8806 <filename>example-init</filename> to be run during boot to initialize the hardware.
8807 In this case, you would use the following in the machine's
8808 <filename>.conf</filename> configuration file:
8809 <literallayout class='monospaced'>
8810 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
8811 </literallayout>
8812 </para>
8813 </glossdef>
8814 </glossentry>
8815
8816 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
8817 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04008818 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 -05008819 </info>
8820 <glossdef>
8821 <para role="glossdeffirst">
8822<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8823 A list of recommended machine-specific packages to install as part of
8824 the image being built.
8825 The build process does not depend on these packages being present.
Brad Bishop316dfdd2018-06-25 12:45:53 -04008826 However, because this is a "machine-essential" variable, the list of
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008827 packages are essential for the machine to boot.
8828 The impact of this variable affects images based on
8829 <filename>packagegroup-core-boot</filename>,
8830 including the <filename>core-image-minimal</filename> image.
8831 </para>
8832
8833 <para>
8834 This variable is similar to the
8835 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
8836 variable with the exception that the image being built does not have a build
8837 dependency on the variable's list of packages.
8838 In other words, the image will still build if a package in this list is not found.
8839 Typically, this variable is used to handle essential kernel modules, whose
8840 functionality may be selected to be built into the kernel rather than as a module,
8841 in which case a package will not be produced.
8842 </para>
8843
8844 <para>
8845 Consider an example where you have a custom kernel where a specific touchscreen
8846 driver is required for the machine to be usable.
8847 However, the driver can be built as a module or
8848 into the kernel depending on the kernel configuration.
8849 If the driver is built as a module, you want it to be installed.
8850 But, when the driver is built into the kernel, you still want the
8851 build to succeed.
8852 This variable sets up a "recommends" relationship so that in the latter case,
8853 the build will not fail due to the missing package.
8854 To accomplish this, assuming the package for the module was called
8855 <filename>kernel-module-ab123</filename>, you would use the
8856 following in the machine's <filename>.conf</filename> configuration
8857 file:
8858 <literallayout class='monospaced'>
8859 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
8860 </literallayout>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05008861 <note>
8862 In this example, the
8863 <filename>kernel-module-ab123</filename> recipe
8864 needs to explicitly set its
8865 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
8866 variable to ensure that BitBake does not use the
8867 kernel recipe's
8868 <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link>
8869 variable to satisfy the dependency.
8870 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008871 </para>
8872
8873 <para>
8874 Some examples of these machine essentials are flash, screen, keyboard, mouse,
8875 or touchscreen drivers (depending on the machine).
8876 </para>
8877 </glossdef>
8878 </glossentry>
8879
8880 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
8881 <info>
8882 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."
8883 </info>
8884 <glossdef>
8885 <para role="glossdeffirst">
8886<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8887 A list of machine-specific packages to install as part of the
8888 image being built that are not essential for the machine to boot.
8889 However, the build process for more fully-featured images
8890 depends on the packages being present.
8891 </para>
8892
8893 <para>
8894 This variable affects all images based on
8895 <filename>packagegroup-base</filename>, which does not include the
8896 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
8897 images.
8898 </para>
8899
8900 <para>
8901 The variable is similar to the
8902 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
8903 variable with the exception that the image being built has a build
8904 dependency on the variable's list of packages.
8905 In other words, the image will not build if a file in this list is not found.
8906 </para>
8907
8908 <para>
8909 An example is a machine that has WiFi capability but is not
8910 essential for the machine to boot the image.
8911 However, if you are building a more fully-featured image, you want to enable
8912 the WiFi.
8913 The package containing the firmware for the WiFi hardware is always
8914 expected to exist, so it is acceptable for the build process to depend upon
8915 finding the package.
8916 In this case, assuming the package for the firmware was called
8917 <filename>wifidriver-firmware</filename>, you would use the following in the
8918 <filename>.conf</filename> file for the machine:
8919 <literallayout class='monospaced'>
8920 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
8921 </literallayout>
8922 </para>
8923 </glossdef>
8924 </glossentry>
8925
8926 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
8927 <info>
8928 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."
8929 </info>
8930 <glossdef>
8931 <para role="glossdeffirst">
8932<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8933 A list of machine-specific packages to install as part of the
8934 image being built that are not essential for booting the machine.
8935 The image being built has no build dependency on this list of packages.
8936 </para>
8937
8938 <para>
8939 This variable affects only images based on
8940 <filename>packagegroup-base</filename>, which does not include the
8941 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
8942 images.
8943 </para>
8944
8945 <para>
8946 This variable is similar to the
8947 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
8948 variable with the exception that the image being built does not have a build
8949 dependency on the variable's list of packages.
8950 In other words, the image will build if a file in this list is not found.
8951 </para>
8952
8953 <para>
8954 An example is a machine that has WiFi capability but is not essential
8955 For the machine to boot the image.
8956 However, if you are building a more fully-featured image, you want to enable
8957 WiFi.
8958 In this case, the package containing the WiFi kernel module will not be produced
8959 if the WiFi driver is built into the kernel, in which case you still want the
8960 build to succeed instead of failing as a result of the package not being found.
8961 To accomplish this, assuming the package for the module was called
8962 <filename>kernel-module-examplewifi</filename>, you would use the
8963 following in the <filename>.conf</filename> file for the machine:
8964 <literallayout class='monospaced'>
8965 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
8966 </literallayout>
8967 </para>
8968 </glossdef>
8969 </glossentry>
8970
8971 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
8972 <info>
8973 MACHINE_FEATURES[doc] = "Specifies the list of hardware features the MACHINE supports."
8974 </info>
8975 <glossdef>
8976 <para role="glossdeffirst">
8977<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8978 Specifies the list of hardware features the
8979 <link linkend='var-MACHINE'><filename>MACHINE</filename></link> is capable
8980 of supporting.
8981 For related information on enabling features, see the
8982 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>,
8983 <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>,
8984 and
8985 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
8986 variables.
8987 </para>
8988
8989 <para>
8990 For a list of hardware features supported by the Yocto
8991 Project as shipped, see the
8992 "<link linkend='ref-features-machine'>Machine Features</link>"
8993 section.
8994 </para>
8995 </glossdef>
8996 </glossentry>
8997
8998 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
8999 <info>
9000 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."
9001 </info>
9002 <glossdef>
9003 <para role="glossdeffirst">
9004<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9005 Features to be added to
9006 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
9007 if not also present in
9008 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
9009 </para>
9010
9011 <para>
9012 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
9013 It is not intended to be user-configurable.
9014 It is best to just reference the variable to see which machine features are
9015 being backfilled for all machine configurations.
Brad Bishop316dfdd2018-06-25 12:45:53 -04009016 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009017 more information.
9018 </para>
9019 </glossdef>
9020 </glossentry>
9021
9022 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
9023 <info>
9024 MACHINE_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from MACHINE_FEATURES_BACKFILL that should not be backfilled (i.e. added to MACHINE_FEATURES) during the build."
9025 </info>
9026 <glossdef>
9027 <para role="glossdeffirst">
9028<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9029 Features from
9030 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
9031 that should not be backfilled (i.e. added to
9032 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
9033 during the build.
Brad Bishop316dfdd2018-06-25 12:45:53 -04009034 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009035 more information.
9036 </para>
9037 </glossdef>
9038 </glossentry>
9039
9040 <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
9041 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009042 MACHINEOVERRIDES[doc] = "A colon-separated list of overrides that apply to the current machine."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009043 </info>
9044 <glossdef>
9045 <para role="glossdeffirst">
9046<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009047 A colon-separated list of overrides that apply to the
9048 current machine.
9049 By default, this list includes the value of
9050 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009051 </para>
9052
9053 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009054 You can extend <filename>MACHINEOVERRIDES</filename>
9055 to add extra overrides that should apply to a machine.
9056 For example, all machines emulated in QEMU (e.g.
9057 <filename>qemuarm</filename>, <filename>qemux86</filename>,
9058 and so forth) include a file named
9059 <filename>meta/conf/machine/include/qemu.inc</filename>
9060 that prepends the following override to
9061 <filename>MACHINEOVERRIDES</filename>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009062 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009063 MACHINEOVERRIDES =. "qemuall:"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009064 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009065 This override allows variables to be overriden for all
9066 machines emulated in QEMU, like in the following example
9067 from the <filename>connman-conf</filename> recipe:
9068 <literallayout class='monospaced'>
9069 SRC_URI_append_qemuall = "file://wired.config \
9070 file://wired-setup \
9071 "
9072 </literallayout>
9073 The underlying mechanism behind
9074 <filename>MACHINEOVERRIDES</filename> is simply that it is
9075 included in the default value of
9076 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009077 </para>
9078 </glossdef>
9079 </glossentry>
9080
9081 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
9082 <info>
9083 MAINTAINER[doc] = "The email address of the distribution maintainer."
9084 </info>
9085 <glossdef>
9086 <para role="glossdeffirst">
9087<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9088 The email address of the distribution maintainer.
9089 </para>
9090 </glossdef>
9091 </glossentry>
9092
9093 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
9094 <info>
9095 MIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."
9096 </info>
9097 <glossdef>
9098 <para role="glossdeffirst">
9099<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9100 Specifies additional paths from which the OpenEmbedded
9101 build system gets source code.
9102 When the build system searches for source code, it first
9103 tries the local download directory.
9104 If that location fails, the build system tries locations
9105 defined by
9106 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
9107 the upstream source, and then locations specified by
9108 <filename>MIRRORS</filename> in that order.
9109 </para>
9110
9111 <para>
9112 Assuming your distribution
9113 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
9114 is "poky", the default value for
9115 <filename>MIRRORS</filename> is defined in the
9116 <filename>conf/distro/poky.conf</filename> file in the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05009117 <filename>meta-poky</filename> Git repository.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009118 </para>
9119 </glossdef>
9120 </glossentry>
9121
9122 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
9123 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04009124 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 -05009125 </info>
9126 <glossdef>
9127 <para role="glossdeffirst">
9128<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9129 Specifies a prefix has been added to
9130 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
Brad Bishop316dfdd2018-06-25 12:45:53 -04009131 of a recipe or package (i.e. a Multilib version).
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009132 The variable is used in places where the prefix needs to be
9133 added to or removed from a the name (e.g. the
9134 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
9135 <filename>MLPREFIX</filename> gets set when a prefix has been
9136 added to <filename>PN</filename>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009137 <note>
9138 The "ML" in <filename>MLPREFIX</filename> stands for
9139 "MultiLib".
9140 This representation is historical and comes from
9141 a time when <filename>nativesdk</filename> was a suffix
9142 rather than a prefix on the recipe name.
9143 When <filename>nativesdk</filename> was turned into a
9144 prefix, it made sense to set
9145 <filename>MLPREFIX</filename> for it as well.
9146 </note>
9147 </para>
9148
9149 <para>
9150 To help understand when <filename>MLPREFIX</filename>
9151 might be needed, consider when
9152 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
9153 is used to provide a <filename>nativesdk</filename> version
9154 of a recipe in addition to the target version.
9155 If that recipe declares build-time dependencies on tasks in
9156 other recipes by using
9157 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>,
9158 then a dependency on "foo" will automatically get rewritten
9159 to a dependency on "nativesdk-foo".
9160 However, dependencies like the following will not get
9161 rewritten automatically:
9162 <literallayout class='monospaced'>
9163 do_foo[depends] += "<replaceable>recipe</replaceable>:do_foo"
9164 </literallayout>
9165 If you want such a dependency to also get transformed,
9166 you can do the following:
9167 <literallayout class='monospaced'>
9168 do_foo[depends] += "${MLPREFIX}<replaceable>recipe</replaceable>:do_foo"
9169 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009170 </para>
9171 </glossdef>
9172 </glossentry>
9173
9174 <glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm>
9175 <info>
9176 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."
9177 </info>
9178 <glossdef>
9179 <para role="glossdeffirst">
9180<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9181 This variable has been replaced by the
9182 <filename>KERNEL_MODULE_AUTOLOAD</filename> variable.
9183 You should replace all occurrences of
9184 <filename>module_autoload</filename> with additions to
9185 <filename>KERNEL_MODULE_AUTOLOAD</filename>, for example:
9186 <literallayout class='monospaced'>
9187 module_autoload_rfcomm = "rfcomm"
9188 </literallayout>
9189 </para>
9190
9191 <para>
9192 should now be replaced with:
9193 <literallayout class='monospaced'>
9194 KERNEL_MODULE_AUTOLOAD += "rfcomm"
9195 </literallayout>
9196 See the
9197 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
9198 variable for more information.
9199 </para>
9200 </glossdef>
9201 </glossentry>
9202
9203 <glossentry id='var-module_conf'><glossterm>module_conf</glossterm>
9204 <info>
9205 module_conf[doc] = "Specifies modprobe.d syntax lines for inclusion in the /etc/modprobe.d/modname.conf file."
9206 </info>
9207 <glossdef>
9208 <para role="glossdeffirst">
9209<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9210 Specifies
9211 <ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink>
9212 syntax lines for inclusion in the
9213 <filename>/etc/modprobe.d/modname.conf</filename> file.
9214 </para>
9215
9216 <para>
9217 You can use this variable anywhere that it can be
9218 recognized by the kernel recipe or out-of-tree kernel
9219 module recipe (e.g. a machine configuration file, a
9220 distribution configuration file, an append file for the
9221 recipe, or the recipe itself).
9222 If you use this variable, you must also be sure to list
9223 the module name in the
9224 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
9225 variable.
9226 </para>
9227
9228 <para>
9229 Here is the general syntax:
9230 <literallayout class='monospaced'>
9231 module_conf_<replaceable>module_name</replaceable> = "<replaceable>modprobe.d-syntax</replaceable>"
9232 </literallayout>
9233 You must use the kernel module name override.
9234 </para>
9235
9236 <para>
9237 Run <filename>man modprobe.d</filename> in the shell to
9238 find out more information on the exact syntax
9239 you want to provide with <filename>module_conf</filename>.
9240 </para>
9241
9242 <para>
9243 Including <filename>module_conf</filename> causes the
9244 OpenEmbedded build system to populate the
9245 <filename>/etc/modprobe.d/modname.conf</filename>
9246 file with <filename>modprobe.d</filename> syntax lines.
9247 Here is an example that adds the options
9248 <filename>arg1</filename> and <filename>arg2</filename>
9249 to a module named <filename>mymodule</filename>:
9250 <literallayout class='monospaced'>
9251 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
9252 </literallayout>
9253 </para>
9254
9255 <para>
9256 For information on how to specify kernel modules to
9257 auto-load on boot, see the
9258 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
9259 variable.
9260 </para>
9261 </glossdef>
9262 </glossentry>
9263
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009264 <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
9265 <info>
9266 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."
9267 </info>
9268 <glossdef>
9269 <para role="glossdeffirst">
9270<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9271 Controls creation of the <filename>modules-*.tgz</filename>
9272 file.
9273 Set this variable to "0" to disable creation of this
9274 file, which contains all of the kernel modules resulting
9275 from a kernel build.
9276 </para>
9277 </glossdef>
9278 </glossentry>
9279
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08009280 <glossentry id='var-MODULE_TARBALL_LINK_NAME'><glossterm>MODULE_TARBALL_LINK_NAME</glossterm>
9281 <info>
9282 MODULE_TARBALL_LINK_NAME[doc] = "The link name of the kernel module tarball."
9283 </info>
9284 <glossdef>
9285 <para role="glossdeffirst">
9286<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9287 The link name of the kernel module tarball.
9288 This variable is set in the
9289 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
9290 file as follows:
9291 <literallayout class='monospaced'>
9292 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
9293 </literallayout>
9294 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
9295 variable, which is set in the same file, has the following
9296 value:
9297 <literallayout class='monospaced'>
9298 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
9299 </literallayout>
9300 </para>
9301
9302 <para>
9303 See the
9304 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
9305 variable for additional information.
9306 </para>
9307 </glossdef>
9308 </glossentry>
9309
9310 <glossentry id='var-MODULE_TARBALL_NAME'><glossterm>MODULE_TARBALL_NAME</glossterm>
9311 <info>
9312 MODULE_TARBALL_NAME[doc] = "The base name of the kernel module tarball."
9313 </info>
9314 <glossdef>
9315 <para role="glossdeffirst">
9316<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9317 The base name of the kernel module tarball.
9318 This variable is set in the
9319 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
9320 file as follows:
9321 <literallayout class='monospaced'>
9322 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"
9323 </literallayout>
9324 The value of the
9325 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
9326 variable, which is set in the same file, has the following
9327 value:
9328 <literallayout class='monospaced'>
9329 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
9330 </literallayout>
9331 </para>
9332 </glossdef>
9333 </glossentry>
9334
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009335<!--
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009336 <glossentry id='var-MULTIMACH_HOST_SYS'><glossterm>MULTIMACH_HOST_SYS</glossterm>
9337 <info>
9338 MULTIMACH_HOST_SYS[doc] = "Separates files for different machines such that you can build for multiple host machines using the same output directories."
9339 </info>
9340 <glossdef>
9341 <para role="glossdeffirst">
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009342-->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009343<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009344<!--
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009345 Serves the same purpose as
9346 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
9347 but for the "HOST" system, in situations that involve a
9348 "HOST" and a "TARGET" system.
9349 See the
9350 <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link>
9351 variable for more information.
9352 </para>
9353
9354 <para>
9355 The default value of this variable is:
9356 <literallayout class='monospaced'>
9357 ${PACKAGE_ARCH}${HOST_VENDOR}-${HOST_OS}
9358 </literallayout>
9359 </para>
9360 </glossdef>
9361 </glossentry>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009362-->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009363
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009364 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
9365 <info>
9366 MULTIMACH_TARGET_SYS[doc] = "Separates files for different machines such that you can build for multiple target machines using the same output directories."
9367 </info>
9368 <glossdef>
9369 <para role="glossdeffirst">
9370<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009371 Uniquely identifies the type of the target system for
9372 which packages are being built.
9373 This variable allows output for different types of target
9374 systems to be put into different subdirectories of the same
9375 output directory.
9376 </para>
9377
9378 <para>
9379 The default value of this variable is:
9380 <literallayout class='monospaced'>
9381 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}
9382 </literallayout>
9383 Some classes (e.g.
9384 <link linkend='ref-classes-cross-canadian'><filename>cross-canadian</filename></link>)
9385 modify the <filename>MULTIMACH_TARGET_SYS</filename> value.
9386 </para>
9387
9388 <para>
9389 See the
9390 <link linkend='var-STAMP'><filename>STAMP</filename></link>
9391 variable for an example.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009392 See the
9393 <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link>
9394 variable for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009395 </para>
9396 </glossdef>
9397 </glossentry>
9398
9399 </glossdiv>
9400
9401 <glossdiv id='var-glossary-n'><title>N</title>
9402
9403 <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
9404 <info>
9405 NATIVELSBSTRING[doc] = "A string identifying the host distribution."
9406 </info>
9407 <glossdef>
9408 <para role="glossdeffirst">
9409<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9410 A string identifying the host distribution.
9411 Strings consist of the host distributor ID
9412 followed by the release, as reported by the
9413 <filename>lsb_release</filename> tool
9414 or as read from <filename>/etc/lsb-release</filename>.
9415 For example, when running a build on Ubuntu 12.10, the value
9416 is "Ubuntu-12.10".
9417 If this information is unable to be determined, the value
9418 resolves to "Unknown".
9419 </para>
9420
9421 <para>
9422 This variable is used by default to isolate native shared
9423 state packages for different distributions (e.g. to avoid
9424 problems with <filename>glibc</filename> version
9425 incompatibilities).
9426 Additionally, the variable is checked against
9427 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
9428 if that variable is set.
9429 </para>
9430 </glossdef>
9431 </glossentry>
9432
9433 <glossentry id='var-NM'><glossterm>NM</glossterm>
9434 <info>
9435 NM[doc] = "Minimal command and arguments to run 'nm'."
9436 </info>
9437 <glossdef>
9438 <para role="glossdeffirst">
9439<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9440 The minimal command and arguments to run
9441 <filename>nm</filename>.
9442 </para>
9443 </glossdef>
9444 </glossentry>
9445
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08009446 <glossentry id='var-NO_GENERIC_LICENSE'><glossterm>NO_GENERIC_LICENSE</glossterm>
9447 <info>
9448 NO_GENERIC_LICENSE[doc] = "Used to allow copying a license that does not exist in common licenses."
9449 </info>
9450 <glossdef>
9451 <para role="glossdeffirst">
9452<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9453 Avoids QA errors when you use a non-common, non-CLOSED
9454 license in a recipe.
9455 Packages exist, such as the linux-firmware package, with
9456 many licenses that are not in any way common.
9457 Also, new licenses are added occasionally to avoid
9458 introducing a lot of common license files, which are only
9459 applicable to a specific package.
9460 <filename>NO_GENERIC_LICENSE</filename> is used to allow
9461 copying a license that does not exist in common licenses.
9462 </para>
9463
9464 <para>
9465 The following example shows how to add
9466 <filename>NO_GENERIC_LICENSE</filename> to a recipe:
9467 <literallayout class='monospaced'>
9468 NO_GENERIC_LICENSE[<replaceable>license_name</replaceable>] = "<replaceable>license_file_in_fetched_source</replaceable>"
9469 </literallayout>
9470 The following is an example that uses the
9471 <filename>LICENSE.Abilis.txt</filename> file as the license
9472 from the fetched source:
9473 <literallayout class='monospaced'>
9474 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
9475 </literallayout>
9476 </para>
9477 </glossdef>
9478 </glossentry>
9479
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009480 <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
9481 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04009482 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 -05009483 </info>
9484 <glossdef>
9485 <para role="glossdeffirst">
9486<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9487 Prevents installation of all "recommended-only" packages.
9488 Recommended-only packages are packages installed only
9489 through the
9490 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
9491 variable).
9492 Setting the <filename>NO_RECOMMENDATIONS</filename> variable
9493 to "1" turns this feature on:
9494 <literallayout class='monospaced'>
9495 NO_RECOMMENDATIONS = "1"
9496 </literallayout>
9497 </para>
9498
9499 <para>
9500 You can set this variable globally in your
9501 <filename>local.conf</filename> file or you can attach it to
9502 a specific image recipe by using the recipe name override:
9503 <literallayout class='monospaced'>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009504 NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "1"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009505 </literallayout>
9506 </para>
9507
9508 <para>
9509 It is important to realize that if you choose to not install
9510 packages using this variable and some other packages are
9511 dependent on them (i.e. listed in a recipe's
9512 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
9513 variable), the OpenEmbedded build system ignores your
9514 request and will install the packages to avoid dependency
9515 errors.
9516 <note>
9517 Some recommended packages might be required for certain
9518 system functionality, such as kernel modules.
9519 It is up to you to add packages with the
9520 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
9521 variable.
9522 </note>
9523 </para>
9524
9525 <para>
9526 Support for this variable exists only when using the
9527 IPK and RPM packaging backend.
9528 Support does not exist for DEB.
9529 </para>
9530
9531 <para>
9532 See the
9533 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
9534 and the
9535 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
9536 variables for related information.
9537 </para>
9538 </glossdef>
9539 </glossentry>
9540
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009541 <glossentry id='var-NOAUTOPACKAGEDEBUG'><glossterm>NOAUTOPACKAGEDEBUG</glossterm>
9542 <info>
9543 NOAUTOPACKAGEDEBUG[doc] = "Disables auto package from splitting .debug files."
9544 </info>
9545 <glossdef>
9546 <para role="glossdeffirst">
9547<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9548 Disables auto package from splitting
9549 <filename>.debug</filename> files. If a recipe requires
9550 <filename>FILES_${PN}-dbg</filename> to be set manually,
9551 the <filename>NOAUTOPACKAGEDEBUG</filename> can be defined
9552 allowing you to define the content of the debug package.
9553 For example:
9554 <literallayout class='monospaced'>
9555 NOAUTOPACKAGEDEBUG = "1"
9556 FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
9557 FILES_${PN}-dbg = "/usr/src/debug/"
9558 FILES_${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"
9559 </literallayout>
9560 </para>
9561 </glossdef>
9562 </glossentry>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009563 </glossdiv>
9564
9565 <glossdiv id='var-glossary-o'><title>O</title>
9566
9567 <glossentry id='var-OBJCOPY'><glossterm>OBJCOPY</glossterm>
9568 <info>
9569 OBJCOPY[doc] = "Minimal command and arguments to run 'objcopy'."
9570 </info>
9571 <glossdef>
9572 <para role="glossdeffirst">
9573<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9574 The minimal command and arguments to run
9575 <filename>objcopy</filename>.
9576 </para>
9577 </glossdef>
9578 </glossentry>
9579
9580 <glossentry id='var-OBJDUMP'><glossterm>OBJDUMP</glossterm>
9581 <info>
9582 OBJDUMP[doc] = "Minimal command and arguments to run 'objdump'."
9583 </info>
9584 <glossdef>
9585 <para role="glossdeffirst">
9586<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9587 The minimal command and arguments to run
9588 <filename>objdump</filename>.
9589 </para>
9590 </glossdef>
9591 </glossentry>
9592
9593 <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
9594 <info>
9595 OE_BINCONFIG_EXTRA_MANGLE[doc] = "When a recipe inherits the binconfig.bbclass class, this variable specifies additional arguments passed to the "sed" command."
9596 </info>
9597 <glossdef>
9598 <para role="glossdeffirst">
9599<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9600 When inheriting the
9601 <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
9602 class, this variable
9603 specifies additional arguments passed to the "sed" command.
9604 The sed command alters any paths in configuration scripts
9605 that have been set up during compilation.
9606 Inheriting this class results in all paths in these scripts
9607 being changed to point into the
9608 <filename>sysroots/</filename> directory so that all builds
9609 that use the script will use the correct directories
9610 for the cross compiling layout.
9611 </para>
9612
9613 <para>
9614 See the <filename>meta/classes/binconfig.bbclass</filename>
9615 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009616 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009617 for details on how this class applies these additional
9618 sed command arguments.
9619 For general information on the
Brad Bishop316dfdd2018-06-25 12:45:53 -04009620 <filename>binconfig</filename> class, see the
9621 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009622 section.
9623 </para>
9624 </glossdef>
9625 </glossentry>
9626
9627 <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
9628 <info>
9629 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."
9630 </info>
9631 <glossdef>
9632 <para role="glossdeffirst">
9633<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9634 An internal variable used to tell the OpenEmbedded build
9635 system what Python modules to import for every Python
9636 function run by the system.
9637 </para>
9638
9639 <note>
9640 Do not set this variable.
9641 It is for internal use only.
9642 </note>
9643 </glossdef>
9644 </glossentry>
9645
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05009646 <glossentry id='var-OE_INIT_ENV_SCRIPT'><glossterm>OE_INIT_ENV_SCRIPT</glossterm>
9647 <info>
9648 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."
9649 </info>
9650 <glossdef>
9651 <para role="glossdeffirst">
9652<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9653 The name of the build environment setup script for the
9654 purposes of setting up the environment within the
9655 extensible SDK.
9656 The default value is "oe-init-build-env".
9657 </para>
9658
9659 <para>
9660 If you use a custom script to set up your build
9661 environment, set the
9662 <filename>OE_INIT_ENV_SCRIPT</filename> variable to its
9663 name.
9664 </para>
9665 </glossdef>
9666 </glossentry>
9667
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009668 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
9669 <info>
9670 OE_TERMINAL[doc] = "Controls how the OpenEmbedded build system spawns interactive terminals on the host development system."
9671 </info>
9672 <glossdef>
9673 <para role="glossdeffirst">
9674<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9675 Controls how the OpenEmbedded build system spawns
9676 interactive terminals on the host development system
9677 (e.g. using the BitBake command with the
9678 <filename>-c devshell</filename> command-line option).
9679 For more information, see the
9680 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009681 in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009682 </para>
9683
9684 <para>
9685 You can use the following values for the
9686 <filename>OE_TERMINAL</filename> variable:
9687 <literallayout class='monospaced'>
9688 auto
9689 gnome
9690 xfce
9691 rxvt
9692 screen
9693 konsole
9694 none
9695 </literallayout>
9696 </para>
9697 </glossdef>
9698 </glossentry>
9699
9700 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
9701 <info>
9702 OEROOT[doc] = "The directory from which the top-level build environment setup script is sourced."
9703 </info>
9704 <glossdef>
9705 <para role="glossdeffirst">
9706<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9707 The directory from which the top-level build environment
9708 setup script is sourced.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009709 The Yocto Project provides a top-level build environment
9710 setup script:
9711 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
9712 When you run this script, the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009713 <filename>OEROOT</filename> variable resolves to the
9714 directory that contains the script.
9715 </para>
9716
9717 <para>
9718 For additional information on how this variable is used,
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009719 see the initialization script.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009720 </para>
9721 </glossdef>
9722 </glossentry>
9723
9724 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
9725 <info>
9726 OLDEST_KERNEL[doc] = "Declares the oldest version of the Linux kernel that the produced binaries must support."
9727 </info>
9728 <glossdef>
9729 <para role="glossdeffirst">
9730<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9731 Declares the oldest version of the Linux kernel that the
9732 produced binaries must support.
9733 This variable is passed into the build of the Embedded
9734 GNU C Library (<filename>glibc</filename>).
9735 </para>
9736
9737 <para>
9738 The default for this variable comes from the
9739 <filename>meta/conf/bitbake.conf</filename> configuration
9740 file.
9741 You can override this default by setting the variable
9742 in a custom distribution configuration file.
9743 </para>
9744 </glossdef>
9745 </glossentry>
9746
9747 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
9748 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009749 OVERRIDES[doc] = "A colon-separated list of overrides that currently apply."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009750 </info>
9751 <glossdef>
9752 <para role="glossdeffirst">
9753<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009754 A colon-separated list of overrides that currently apply.
9755 Overrides are a BitBake mechanism that allows variables to
9756 be selectively overridden at the end of parsing.
9757 The set of overrides in <filename>OVERRIDES</filename>
9758 represents the "state" during building, which includes
9759 the current recipe being built, the machine for which
9760 it is being built, and so forth.
9761 </para>
9762
9763 <para>
9764 As an example, if the string "an-override" appears as an
9765 element in the colon-separated list in
9766 <filename>OVERRIDES</filename>, then the following
9767 assignment will override <filename>FOO</filename> with the
9768 value "overridden" at the end of parsing:
9769 <literallayout class='monospaced'>
9770 FOO_an-override = "overridden"
9771 </literallayout>
9772 See the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009773 "<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009774 section in the BitBake User Manual for more information on
9775 the overrides mechanism.
9776 </para>
9777
9778 <para>
9779 The default value of <filename>OVERRIDES</filename>
9780 includes the values of the
9781 <link linkend='var-CLASSOVERRIDE'><filename>CLASSOVERRIDE</filename></link>,
9782 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>,
9783 and
9784 <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
9785 variables.
9786 Another important override included by default is
9787 <filename>pn-${PN}</filename>.
9788 This override allows variables to be set for a single
9789 recipe within configuration (<filename>.conf</filename>)
9790 files.
9791 Here is an example:
9792 <literallayout class='monospaced'>
9793 FOO_pn-myrecipe = "myrecipe-specific value"
9794 </literallayout>
9795 <note><title>Tip</title>
9796 An easy way to see what overrides apply is to search for
9797 <filename>OVERRIDES</filename> in the output of the
9798 <filename>bitbake -e</filename> command.
9799 See the
Brad Bishop316dfdd2018-06-25 12:45:53 -04009800 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-debugging-viewing-variable-values'>Viewing Variable Values</ulink>"
9801 section in the Yocto Project Development Tasks
9802 Manual for more information.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009803 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009804 </para>
9805 </glossdef>
9806 </glossentry>
9807 </glossdiv>
9808
9809 <glossdiv id='var-glossary-p'><title>P</title>
9810
9811 <glossentry id='var-P'><glossterm>P</glossterm>
9812 <info>
9813 P[doc] = "The recipe name and version. P is comprised of ${PN}-${PV}."
9814 </info>
9815 <glossdef>
9816 <para role="glossdeffirst">
9817<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9818 The recipe name and version.
9819 <filename>P</filename> is comprised of the following:
9820 <literallayout class='monospaced'>
9821 ${PN}-${PV}
9822 </literallayout>
9823 </para>
9824 </glossdef>
9825 </glossentry>
9826
9827 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
9828 <info>
9829 PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages."
9830 </info>
9831 <glossdef>
9832 <para role="glossdeffirst">
9833<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9834 The architecture of the resulting package or packages.
9835 </para>
9836
9837 <para>
9838 By default, the value of this variable is set to
9839 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
9840 when building for the target,
Brad Bishop316dfdd2018-06-25 12:45:53 -04009841 <link linkend='var-BUILD_ARCH'><filename>BUILD_ARCH</filename></link>
9842 when building for the
9843 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009844 for the SDK.
Brad Bishop316dfdd2018-06-25 12:45:53 -04009845 <note>
9846 See
9847 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>
9848 for more information.
9849 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009850 However, if your recipe's output packages are built
Brad Bishop316dfdd2018-06-25 12:45:53 -04009851 specific to the target machine rather than generally for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009852 the architecture of the machine, you should set
9853 <filename>PACKAGE_ARCH</filename> to the value of
9854 <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>
9855 in the recipe as follows:
9856 <literallayout class='monospaced'>
9857 PACKAGE_ARCH = "${MACHINE_ARCH}"
9858 </literallayout>
9859 </para>
9860 </glossdef>
9861 </glossentry>
9862
9863 <glossentry id='var-PACKAGE_ARCHS'><glossterm>PACKAGE_ARCHS</glossterm>
9864 <info>
9865 PACKAGE_ARCHS[doc] = "A list of architectures compatible with the given target in order of priority."
9866 </info>
9867 <glossdef>
9868 <para role="glossdeffirst">
9869<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9870 Specifies a list of architectures compatible with
9871 the target machine.
9872 This variable is set automatically and should not
9873 normally be hand-edited.
9874 Entries are separated using spaces and listed in order
9875 of priority.
9876 The default value for
9877 <filename>PACKAGE_ARCHS</filename> is "all any noarch
9878 ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
9879 </para>
9880 </glossdef>
9881 </glossentry>
9882
9883 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
9884 <info>
9885 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."
9886 </info>
9887 <glossdef>
9888 <para role="glossdeffirst">
9889<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9890 Enables easily adding packages to
9891 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
9892 before <filename>${<link linkend='var-PN'>PN</link>}</filename>
9893 so that those added packages can pick up files that would normally be
9894 included in the default package.
9895 </para>
9896 </glossdef>
9897 </glossentry>
9898
9899 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
9900 <info>
9901 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."
9902 </info>
9903 <glossdef>
9904 <para role="glossdeffirst">
9905<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9906 This variable, which is set in the
9907 <filename>local.conf</filename> configuration file found in
9908 the <filename>conf</filename> folder of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009909 <link linkend='build-directory'>Build Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009910 specifies the package manager the OpenEmbedded build system
9911 uses when packaging data.
9912 </para>
9913
9914 <para>
9915 You can provide one or more of the following arguments for
9916 the variable:
9917 <literallayout class='monospaced'>
9918 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"
9919 </literallayout>
9920 <note><title>Warning</title>
9921 While it is a legal option, the
Brad Bishop316dfdd2018-06-25 12:45:53 -04009922 <filename>package_tar</filename> class has limited
9923 functionality due to no support for package
9924 dependencies by that backend.
9925 Therefore, it is recommended that you do not use it.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009926 </note>
9927 The build system uses only the first argument in the list
9928 as the package manager when creating your image or SDK.
9929 However, packages will be created using any additional
9930 packaging classes you specify.
9931 For example, if you use the following in your
9932 <filename>local.conf</filename> file:
9933 <literallayout class='monospaced'>
9934 PACKAGE_CLASSES ?= "package_ipk"
9935 </literallayout>
9936 The OpenEmbedded build system uses the IPK package manager
9937 to create your image or SDK.
9938 </para>
9939
9940 <para>
9941 For information on packaging and build performance effects
9942 as a result of the package manager in use, see the
9943 "<link linkend='ref-classes-package'><filename>package.bbclass</filename></link>"
9944 section.
9945 </para>
9946 </glossdef>
9947 </glossentry>
9948
9949 <glossentry id='var-PACKAGE_DEBUG_SPLIT_STYLE'><glossterm>PACKAGE_DEBUG_SPLIT_STYLE</glossterm>
9950 <info>
9951 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)."
9952 </info>
9953 <glossdef>
9954 <para role="glossdeffirst">
9955<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9956 Determines how to split up the binary and debug information
9957 when creating <filename>*-dbg</filename> packages to be
9958 used with the GNU Project Debugger (GDB).
9959 </para>
9960
9961 <para>
9962 With the
9963 <filename>PACKAGE_DEBUG_SPLIT_STYLE</filename> variable,
9964 you can control where debug information, which can include
9965 or exclude source files, is stored:
9966 <itemizedlist>
9967 <listitem><para>
9968 ".debug": Debug symbol files are placed next
9969 to the binary in a <filename>.debug</filename>
9970 directory on the target.
9971 For example, if a binary is installed into
9972 <filename>/bin</filename>, the corresponding debug
9973 symbol files are installed in
9974 <filename>/bin/.debug</filename>.
9975 Source files are placed in
9976 <filename>/usr/src/debug</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009977 </para></listitem>
9978 <listitem><para>
9979 "debug-file-directory": Debug symbol files are
9980 placed under <filename>/usr/lib/debug</filename>
9981 on the target, and separated by the path from where
9982 the binary is installed.
9983 For example, if a binary is installed in
9984 <filename>/bin</filename>, the corresponding debug
9985 symbols are installed in
9986 <filename>/usr/lib/debug/bin</filename>.
9987 Source files are placed in
9988 <filename>/usr/src/debug</filename>.
9989 </para></listitem>
9990 <listitem><para>
9991 "debug-without-src": The same behavior as
9992 ".debug" previously described with the exception
9993 that no source files are installed.
9994 </para></listitem>.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08009995 <listitem><para>
9996 "debug-with-srcpkg": The same behavior as
9997 ".debug" previously described with the exception
9998 that all source files are placed in a separate
9999 <filename>*-src</filename> pkg.
Brad Bishop19323692019-04-05 15:28:33 -040010000 This is the default behavior.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010001 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010002 </itemizedlist>
10003 </para>
10004
10005 <para>
10006 You can find out more about debugging using GDB by reading
10007 the
10008 "<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 -050010009 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010010 </para>
10011 </glossdef>
10012 </glossentry>
10013
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010014 <glossentry id='var-PACKAGE_EXCLUDE_COMPLEMENTARY'><glossterm>PACKAGE_EXCLUDE_COMPLEMENTARY</glossterm>
10015 <info>
10016 PACKAGE_EXCLUDE_COMPLEMENTARY[doc] = "Prevents specific packages from being installed when you are installing complementary packages."
10017 </info>
10018 <glossdef>
10019 <para role="glossdeffirst">
10020<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10021 Prevents specific packages from being installed when
10022 you are installing complementary packages.
10023 </para>
10024
10025 <para>
10026 You might find that you want to prevent installing certain
10027 packages when you are installing complementary packages.
10028 For example, if you are using
10029 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
10030 to install <filename>dev-pkgs</filename>, you might not want
10031 to install all packages from a particular multilib.
10032 If you find yourself in this situation, you can use the
10033 <filename>PACKAGE_EXCLUDE_COMPLEMENTARY</filename> variable
10034 to specify regular expressions to match the packages you
10035 want to exclude.
10036 </para>
10037 </glossdef>
10038 </glossentry>
10039
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010040 <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
10041 <info>
10042 PACKAGE_EXCLUDE[doc] = "Packages to exclude from the installation. If a listed package is required, an error is generated."
10043 </info>
10044 <glossdef>
10045 <para role="glossdeffirst">
10046<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10047 Lists packages that should not be installed into an image.
10048 For example:
10049 <literallayout class='monospaced'>
10050 PACKAGE_EXCLUDE = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."
10051 </literallayout>
10052 </para>
10053
10054 <para>
10055 You can set this variable globally in your
10056 <filename>local.conf</filename> file or you can attach it to
10057 a specific image recipe by using the recipe name override:
10058 <literallayout class='monospaced'>
10059 PACKAGE_EXCLUDE_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"
10060 </literallayout>
10061 </para>
10062
10063 <para>
10064 If you choose to not install
10065 a package using this variable and some other package is
10066 dependent on it (i.e. listed in a recipe's
10067 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
10068 variable), the OpenEmbedded build system generates a fatal
10069 installation error.
10070 Because the build system halts the process with a fatal
10071 error, you can use the variable with an iterative
10072 development process to remove specific components from a
10073 system.
10074 </para>
10075
10076 <para>
10077 Support for this variable exists only when using the
10078 IPK and RPM packaging backend.
10079 Support does not exist for DEB.
10080 </para>
10081
10082 <para>
10083 See the
10084 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
10085 and the
10086 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
10087 variables for related information.
10088 </para>
10089 </glossdef>
10090 </glossentry>
10091
10092 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
10093 <info>
10094 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."
10095 </info>
10096 <glossdef>
10097 <para role="glossdeffirst">
10098<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10099 Specifies the list of architectures compatible with the device CPU.
10100 This variable is useful when you build for several different devices that use
10101 miscellaneous processors such as XScale and ARM926-EJS.
10102 </para>
10103 </glossdef>
10104 </glossentry>
10105
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010106 <glossentry id='var-PACKAGE_FEED_ARCHS'><glossterm>PACKAGE_FEED_ARCHS</glossterm>
10107 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040010108 PACKAGE_FEED_ARCHS[doc] = "Optionally specifies user-defined package architectures when constructing package feed URIs."
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010109 </info>
10110 <glossdef>
10111 <para role="glossdeffirst">
10112<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040010113 Optionally specifies the package architectures used as
10114 part of the package feed URIs during the build.
10115 When used, the <filename>PACKAGE_FEED_ARCHS</filename>
10116 variable is appended to the final package feed URI, which
10117 is constructed using the
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010118 <link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
10119 and
10120 <link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>
10121 variables.
Brad Bishop316dfdd2018-06-25 12:45:53 -040010122 <note><title>Tip</title>
10123 You can use the <filename>PACKAGE_FEEDS_ARCHS</filename>
10124 variable to whitelist specific package architectures.
10125 If you do not need to whitelist specific architectures,
10126 which is a common case, you can omit this variable.
10127 Omitting the variable results in all available
10128 architectures for the current machine being included
10129 into remote package feeds.
10130 </note>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010131 </para>
10132
10133 <para>
10134 Consider the following example where the
10135 <filename>PACKAGE_FEED_URIS</filename>,
10136 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
10137 <filename>PACKAGE_FEED_ARCHS</filename> variables are
10138 defined in your <filename>local.conf</filename> file:
10139 <literallayout class='monospaced'>
10140 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
10141 https://example.com/packagerepos/updates"
10142 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
10143 PACKAGE_FEED_ARCHS = "all core2-64"
10144 </literallayout>
10145 Given these settings, the resulting package feeds are
10146 as follows:
10147 <literallayout class='monospaced'>
10148 https://example.com/packagerepos/release/rpm/all
10149 https://example.com/packagerepos/release/rpm/core2-64
10150 https://example.com/packagerepos/release/rpm-dev/all
10151 https://example.com/packagerepos/release/rpm-dev/core2-64
10152 https://example.com/packagerepos/updates/rpm/all
10153 https://example.com/packagerepos/updates/rpm/core2-64
10154 https://example.com/packagerepos/updates/rpm-dev/all
10155 https://example.com/packagerepos/updates/rpm-dev/core2-64
10156 </literallayout>
10157 </para>
10158 </glossdef>
10159 </glossentry>
10160
10161 <glossentry id='var-PACKAGE_FEED_BASE_PATHS'><glossterm>PACKAGE_FEED_BASE_PATHS</glossterm>
10162 <info>
10163 PACKAGE_FEED_BASE_PATHS[doc] = "Specifies base path used when constructing package feed URIs."
10164 </info>
10165 <glossdef>
10166 <para role="glossdeffirst">
10167<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10168 Specifies the base path used when constructing package feed
10169 URIs.
10170 The <filename>PACKAGE_FEED_BASE_PATHS</filename> variable
10171 makes up the middle portion of a package feed URI used
10172 by the OpenEmbedded build system.
10173 The base path lies between the
10174 <link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
10175 and
10176 <link linkend='var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></link>
10177 variables.
10178 </para>
10179
10180 <para>
10181 Consider the following example where the
10182 <filename>PACKAGE_FEED_URIS</filename>,
10183 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
10184 <filename>PACKAGE_FEED_ARCHS</filename> variables are
10185 defined in your <filename>local.conf</filename> file:
10186 <literallayout class='monospaced'>
10187 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
10188 https://example.com/packagerepos/updates"
10189 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
10190 PACKAGE_FEED_ARCHS = "all core2-64"
10191 </literallayout>
10192 Given these settings, the resulting package feeds are
10193 as follows:
10194 <literallayout class='monospaced'>
10195 https://example.com/packagerepos/release/rpm/all
10196 https://example.com/packagerepos/release/rpm/core2-64
10197 https://example.com/packagerepos/release/rpm-dev/all
10198 https://example.com/packagerepos/release/rpm-dev/core2-64
10199 https://example.com/packagerepos/updates/rpm/all
10200 https://example.com/packagerepos/updates/rpm/core2-64
10201 https://example.com/packagerepos/updates/rpm-dev/all
10202 https://example.com/packagerepos/updates/rpm-dev/core2-64
10203 </literallayout>
10204 </para>
10205 </glossdef>
10206 </glossentry>
10207
10208 <glossentry id='var-PACKAGE_FEED_URIS'><glossterm>PACKAGE_FEED_URIS</glossterm>
10209 <info>
10210 PACKAGE_FEED_URIS[doc] = "Specifies the front portion of the package feed URI used by the OpenEmbedded build system."
10211 </info>
10212 <glossdef>
10213 <para role="glossdeffirst">
10214<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10215 Specifies the front portion of the package feed URI
10216 used by the OpenEmbedded build system.
10217 Each final package feed URI is comprised of
10218 <filename>PACKAGE_FEED_URIS</filename>,
10219 <link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>,
10220 and
10221 <link linkend='var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></link>
10222 variables.
10223 </para>
10224
10225 <para>
10226 Consider the following example where the
10227 <filename>PACKAGE_FEED_URIS</filename>,
10228 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
10229 <filename>PACKAGE_FEED_ARCHS</filename> variables are
10230 defined in your <filename>local.conf</filename> file:
10231 <literallayout class='monospaced'>
10232 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
10233 https://example.com/packagerepos/updates"
10234 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
10235 PACKAGE_FEED_ARCHS = "all core2-64"
10236 </literallayout>
10237 Given these settings, the resulting package feeds are
10238 as follows:
10239 <literallayout class='monospaced'>
10240 https://example.com/packagerepos/release/rpm/all
10241 https://example.com/packagerepos/release/rpm/core2-64
10242 https://example.com/packagerepos/release/rpm-dev/all
10243 https://example.com/packagerepos/release/rpm-dev/core2-64
10244 https://example.com/packagerepos/updates/rpm/all
10245 https://example.com/packagerepos/updates/rpm/core2-64
10246 https://example.com/packagerepos/updates/rpm-dev/all
10247 https://example.com/packagerepos/updates/rpm-dev/core2-64
10248 </literallayout>
10249 </para>
10250 </glossdef>
10251 </glossentry>
10252
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010253 <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
10254 <info>
10255 PACKAGE_GROUP[doc] = "Defines one or more packages to include in an image when a specific item is included in IMAGE_FEATURES."
10256 </info>
10257 <glossdef>
10258 <para role="glossdeffirst">
10259<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10260 The <filename>PACKAGE_GROUP</filename> variable has been
10261 renamed to
10262 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>.
10263 See the variable description for
10264 <filename>FEATURE_PACKAGES</filename> for information.
10265 </para>
10266
10267 <para>
10268 If if you use the <filename>PACKAGE_GROUP</filename>
10269 variable, the OpenEmbedded build system issues a warning
10270 message.
10271 </para>
10272 </glossdef>
10273 </glossentry>
10274
10275 <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
10276 <info>
10277 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."
10278 </info>
10279 <glossdef>
10280 <para role="glossdeffirst">
10281<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10282 The final list of packages passed to the package manager
10283 for installation into the image.
10284 </para>
10285
10286 <para>
10287 Because the package manager controls actual installation
10288 of all packages, the list of packages passed using
10289 <filename>PACKAGE_INSTALL</filename> is not the final list
10290 of packages that are actually installed.
10291 This variable is internal to the image construction
10292 code.
10293 Consequently, in general, you should use the
10294 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
10295 variable to specify packages for installation.
10296 The exception to this is when working with
10297 the
10298 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
10299 image.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050010300 When working with an initial RAM filesystem (initramfs)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010301 image, use the <filename>PACKAGE_INSTALL</filename>
10302 variable.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050010303 For information on creating an initramfs, see the
10304 "<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 -050010305 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010306 </para>
10307 </glossdef>
10308 </glossentry>
10309
10310 <glossentry id='var-PACKAGE_INSTALL_ATTEMPTONLY'><glossterm>PACKAGE_INSTALL_ATTEMPTONLY</glossterm>
10311 <info>
10312 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."
10313 </info>
10314 <glossdef>
10315 <para role="glossdeffirst">
10316<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10317 Specifies a list of packages the OpenEmbedded build
10318 system attempts to install when creating an image.
10319 If a listed package fails to install, the build system
10320 does not generate an error.
10321 This variable is generally not user-defined.
10322 </para>
10323 </glossdef>
10324 </glossentry>
10325
10326 <glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm>PACKAGE_PREPROCESS_FUNCS</glossterm>
10327 <info>
10328 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."
10329 </info>
10330 <glossdef>
10331 <para role="glossdeffirst">
10332<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10333 Specifies a list of functions run to pre-process the
10334 <link linkend='var-PKGD'><filename>PKGD</filename></link>
10335 directory prior to splitting the files out to individual
10336 packages.
10337 </para>
10338 </glossdef>
10339 </glossentry>
10340
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010341 <glossentry id='var-PACKAGE_WRITE_DEPS'><glossterm>PACKAGE_WRITE_DEPS</glossterm>
10342 <info>
10343 PACKAGE_WRITE_DEPS[doc] = "Specifies post-installation and pre-installation script dependencies on native/cross tools."
10344 </info>
10345 <glossdef>
10346 <para role="glossdeffirst">
10347<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10348 Specifies a list of dependencies for post-installation and
10349 pre-installation scripts on native/cross tools.
10350 If your post-installation or pre-installation script can
10351 execute at rootfs creation time rather than on the
10352 target but depends on a native tool in order to execute,
10353 you need to list the tools in
Brad Bishopd5ae7d92018-06-14 09:52:03 -070010354 <filename>PACKAGE_WRITE_DEPS</filename>.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010355 </para>
10356
10357 <para>
10358 For information on running post-installation scripts, see
10359 the
10360 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010361 section in the Yocto Project Development Tasks Manual.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010362 </para>
10363 </glossdef>
10364 </glossentry>
10365
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010366 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
10367 <info>
10368 PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis."
10369 </info>
10370 <glossdef>
10371 <para role="glossdeffirst">
10372<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10373 This variable provides a means of enabling or disabling
10374 features of a recipe on a per-recipe basis.
10375 <filename>PACKAGECONFIG</filename> blocks are defined
10376 in recipes when you specify features and then arguments
10377 that define feature behaviors.
10378 Here is the basic block structure:
10379 <literallayout class='monospaced'>
10380 PACKAGECONFIG ??= "f1 f2 f3 ..."
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010381 PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1,rt-recs-f1"
10382 PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2,rt-recs-f2"
10383 PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3,rt-recs-f3"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010384 </literallayout>
10385 </para>
10386
10387 <para>
10388 The <filename>PACKAGECONFIG</filename>
10389 variable itself specifies a space-separated list of the
10390 features to enable.
10391 Following the features, you can determine the behavior of
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010392 each feature by providing up to five order-dependent
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010393 arguments, which are separated by commas.
10394 You can omit any argument you like but must retain the
10395 separating commas.
10396 The order is important and specifies the following:
10397 <orderedlist>
10398 <listitem><para>Extra arguments
10399 that should be added to the configure script
10400 argument list
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010401 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
10402 or
10403 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010404 if the feature is enabled.</para></listitem>
10405 <listitem><para>Extra arguments
10406 that should be added to <filename>EXTRA_OECONF</filename>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010407 or <filename>PACKAGECONFIG_CONFARGS</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010408 if the feature is disabled.
10409 </para></listitem>
10410 <listitem><para>Additional build dependencies
10411 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
10412 that should be added if the feature is enabled.
10413 </para></listitem>
10414 <listitem><para>Additional runtime dependencies
10415 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
10416 that should be added if the feature is enabled.
10417 </para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010418 <listitem><para>Additional runtime recommendations
10419 (<link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)
10420 that should be added if the feature is enabled.
10421 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010422 </orderedlist>
10423 </para>
10424
10425 <para>
10426 Consider the following
10427 <filename>PACKAGECONFIG</filename> block taken from the
10428 <filename>librsvg</filename> recipe.
10429 In this example the feature is <filename>croco</filename>,
10430 which has three arguments that determine the feature's
10431 behavior.
10432 <literallayout class='monospaced'>
10433 PACKAGECONFIG ??= "croco"
10434 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
10435 </literallayout>
10436 The <filename>--with-croco</filename> and
10437 <filename>libcroco</filename> arguments apply only if
10438 the feature is enabled.
10439 In this case, <filename>--with-croco</filename> is
10440 added to the configure script argument list and
10441 <filename>libcroco</filename> is added to
Brad Bishop316dfdd2018-06-25 12:45:53 -040010442 <filename>DEPENDS</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010443 On the other hand, if the feature is disabled say through
10444 a <filename>.bbappend</filename> file in another layer, then
10445 the second argument <filename>--without-croco</filename> is
10446 added to the configure script rather than
10447 <filename>--with-croco</filename>.
10448 </para>
10449
10450 <para>
10451 The basic <filename>PACKAGECONFIG</filename> structure
10452 previously described holds true regardless of whether you
10453 are creating a block or changing a block.
10454 When creating a block, use the structure inside your
10455 recipe.
10456 </para>
10457
10458 <para>
10459 If you want to change an existing
10460 <filename>PACKAGECONFIG</filename> block, you can do so
10461 one of two ways:
10462 <itemizedlist>
10463 <listitem><para><emphasis>Append file:</emphasis>
10464 Create an append file named
10465 <replaceable>recipename</replaceable><filename>.bbappend</filename>
10466 in your layer and override the value of
10467 <filename>PACKAGECONFIG</filename>.
10468 You can either completely override the variable:
10469 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010470 PACKAGECONFIG = "f4 f5"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010471 </literallayout>
10472 Or, you can just append the variable:
10473 <literallayout class='monospaced'>
10474 PACKAGECONFIG_append = " f4"
10475 </literallayout></para></listitem>
10476 <listitem><para><emphasis>Configuration file:</emphasis>
10477 This method is identical to changing the block
10478 through an append file except you edit your
10479 <filename>local.conf</filename> or
10480 <filename><replaceable>mydistro</replaceable>.conf</filename> file.
10481 As with append files previously described,
10482 you can either completely override the variable:
10483 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010484 PACKAGECONFIG_pn-<replaceable>recipename</replaceable> = "f4 f5"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010485 </literallayout>
10486 Or, you can just amend the variable:
10487 <literallayout class='monospaced'>
10488 PACKAGECONFIG_append_pn-<replaceable>recipename</replaceable> = " f4"
10489 </literallayout></para></listitem>
10490 </itemizedlist>
10491 </para>
10492 </glossdef>
10493 </glossentry>
10494
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010495 <glossentry id='var-PACKAGECONFIG_CONFARGS'><glossterm>PACKAGECONFIG_CONFARGS</glossterm>
10496 <info>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010497 PACKAGECONFIG_CONFARGS[doc] = "A space-separated list of configuration options generated from the PACKAGECONFIG setting."
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010498 </info>
10499 <glossdef>
10500 <para role="glossdeffirst">
10501<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10502 A space-separated list of configuration options generated
10503 from the
10504 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
10505 setting.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010506 </para>
10507
10508 <para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010509 Classes such as
10510 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
10511 and
10512 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
10513 use <filename>PACKAGECONFIG_CONFARGS</filename> to pass
Brad Bishop316dfdd2018-06-25 12:45:53 -040010514 <filename>PACKAGECONFIG</filename> options to
10515 <filename>configure</filename> and
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010516 <filename>cmake</filename>, respectively.
10517 If you are using
10518 <filename>PACKAGECONFIG</filename> but not a class that
10519 handles the <filename>do_configure</filename> task, then
10520 you need to use
10521 <filename>PACKAGECONFIG_CONFARGS</filename> appropriately.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010522 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010523 </glossdef>
10524 </glossentry>
10525
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010526 <glossentry id='var-PACKAGEGROUP_DISABLE_COMPLEMENTARY'><glossterm>PACKAGEGROUP_DISABLE_COMPLEMENTARY</glossterm>
10527 <info>
10528 PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents automatic creation of the normal complementary packages such as -dev and -dbg in a packagegroup recipe."
10529 </info>
10530 <glossdef>
10531 <para role="glossdeffirst">
10532<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10533 For recipes inheriting the
10534 <link linkend='ref-classes-packagegroup'><filename>packagegroup</filename></link>
10535 class, setting
10536 <filename>PACKAGEGROUP_DISABLE_COMPLEMENTARY</filename> to
10537 "1" specifies that the normal complementary packages
10538 (i.e. <filename>-dev</filename>,
10539 <filename>-dbg</filename>, and so forth) should not be
10540 automatically created by the
10541 <filename>packagegroup</filename> recipe, which is the
10542 default behavior.
10543 </para>
10544 </glossdef>
10545 </glossentry>
10546
10547 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
10548 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040010549 PACKAGES[doc] = "The list of packages the recipe creates."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010550 </info>
10551 <glossdef>
10552 <para role="glossdeffirst">
10553<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040010554 The list of packages the recipe creates.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010555 The default value is the following:
10556 <literallayout class='monospaced'>
10557 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
10558 </literallayout>
10559 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010560
10561 <para>
10562 During packaging, the
10563 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
10564 task goes through <filename>PACKAGES</filename> and uses
10565 the
10566 <link linkend='var-FILES'><filename>FILES</filename></link>
10567 variable corresponding to each package to assign files to
10568 the package.
10569 If a file matches the <filename>FILES</filename> variable
10570 for more than one package in <filename>PACKAGES</filename>,
10571 it will be assigned to the earliest (leftmost) package.
10572 </para>
10573
10574 <para>
10575 Packages in the variable's list that are empty (i.e. where
10576 none of the patterns in
10577 <filename>FILES_</filename><replaceable>pkg</replaceable>
10578 match any files installed by the
10579 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
10580 task) are not generated, unless generation is forced through
10581 the
10582 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>
10583 variable.
10584 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010585 </glossdef>
10586 </glossentry>
10587
10588 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
10589 <info>
10590 PACKAGES_DYNAMIC[doc] = "A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes."
10591 </info>
10592 <glossdef>
10593 <para role="glossdeffirst">
10594<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10595 A promise that your recipe satisfies runtime dependencies
10596 for optional modules that are found in other recipes.
10597 <filename>PACKAGES_DYNAMIC</filename>
10598 does not actually satisfy the dependencies, it only states that
10599 they should be satisfied.
10600 For example, if a hard, runtime dependency
10601 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
10602 of another package is satisfied
10603 at build time through the <filename>PACKAGES_DYNAMIC</filename>
10604 variable, but a package with the module name is never actually
10605 produced, then the other package will be broken.
10606 Thus, if you attempt to include that package in an image,
10607 you will get a dependency failure from the packaging system
10608 during the
10609 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
10610 task.
10611 </para>
10612
10613 <para>
10614 Typically, if there is a chance that such a situation can
10615 occur and the package that is not created is valid
10616 without the dependency being satisfied, then you should use
10617 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
10618 (a soft runtime dependency) instead of
10619 <filename>RDEPENDS</filename>.
10620 </para>
10621
10622 <para>
10623 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
10624 variable when you are splitting packages, see the
10625 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010626 in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010627 </para>
10628 </glossdef>
10629 </glossentry>
10630
10631 <glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm>
10632 <info>
10633 PACKAGESPLITFUNCS[doc] = "Specifies a list of functions run to perform additional splitting of files into individual packages."
10634 </info>
10635 <glossdef>
10636 <para role="glossdeffirst">
10637<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10638 Specifies a list of functions run to perform additional
10639 splitting of files into individual packages.
10640 Recipes can either prepend to this variable or prepend
10641 to the <filename>populate_packages</filename> function
10642 in order to perform additional package splitting.
10643 In either case, the function should set
10644 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>,
10645 <link linkend='var-FILES'><filename>FILES</filename></link>,
10646 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
10647 and other packaging variables appropriately in order to
10648 perform the desired splitting.
10649 </para>
10650 </glossdef>
10651 </glossentry>
10652
10653 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
10654 <info>
10655 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."
10656 </info>
10657 <glossdef>
10658 <para role="glossdeffirst">
10659<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10660 Extra options passed to the <filename>make</filename>
10661 command during the
10662 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
10663 task in order to specify parallel compilation on the local
10664 build host.
10665 This variable is usually in the form "-j <replaceable>x</replaceable>",
10666 where <replaceable>x</replaceable> represents the maximum
10667 number of parallel threads <filename>make</filename> can
10668 run.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010669 <note><title>Caution</title>
10670 In order for <filename>PARALLEL_MAKE</filename> to be
10671 effective, <filename>make</filename> must be called
10672 with
10673 <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.
10674 An easy way to ensure this is to use the
10675 <filename>oe_runmake</filename> function.
10676 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010677 </para>
10678
10679 <para>
10680 By default, the OpenEmbedded build system automatically
10681 sets this variable to be equal to the number of cores the
10682 build system uses.
10683 <note>
10684 If the software being built experiences dependency
10685 issues during the <filename>do_compile</filename>
10686 task that result in race conditions, you can clear
10687 the <filename>PARALLEL_MAKE</filename> variable within
10688 the recipe as a workaround.
10689 For information on addressing race conditions, see the
10690 "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010691 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010692 </note>
10693 For single socket systems (i.e. one CPU), you should not
10694 have to override this variable to gain optimal parallelism
10695 during builds.
10696 However, if you have very large systems that employ
10697 multiple physical CPUs, you might want to make sure the
10698 <filename>PARALLEL_MAKE</filename> variable is not
10699 set higher than "-j 20".
10700 </para>
10701
10702 <para>
10703 For more information on speeding up builds, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040010704 "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"
10705 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010706 </para>
10707 </glossdef>
10708 </glossentry>
10709
10710 <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
10711 <info>
10712 PARALLEL_MAKEINST[doc] = "Extra options passed to the make install command during the do_install task in order to specify parallel installation."
10713 </info>
10714 <glossdef>
10715 <para role="glossdeffirst">
10716<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10717 Extra options passed to the
10718 <filename>make install</filename> command during the
10719 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
10720 task in order to specify parallel installation.
10721 This variable defaults to the value of
10722 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010723 <note><title>Notes and Cautions</title>
10724 <para>In order for <filename>PARALLEL_MAKEINST</filename>
10725 to be
10726 effective, <filename>make</filename> must be called
10727 with
10728 <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.
10729 An easy way to ensure this is to use the
10730 <filename>oe_runmake</filename> function.</para>
10731
10732 <para>If the software being built experiences
10733 dependency issues during the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010734 <filename>do_install</filename> task that result in
10735 race conditions, you can clear the
10736 <filename>PARALLEL_MAKEINST</filename> variable within
10737 the recipe as a workaround.
10738 For information on addressing race conditions, see the
10739 "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010740 section in the Yocto Project Development Tasks Manual.
10741 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010742 </note>
10743 </para>
10744 </glossdef>
10745 </glossentry>
10746
10747 <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
10748 <info>
10749 PATCHRESOLVE[doc] = "Enable or disable interactive patch resolution."
10750 </info>
10751 <glossdef>
10752 <para role="glossdeffirst">
10753<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10754 Determines the action to take when a patch fails.
10755 You can set this variable to one of two values: "noop" and
10756 "user".
10757 </para>
10758
10759 <para>
10760 The default value of "noop" causes the build to simply fail
10761 when the OpenEmbedded build system cannot successfully
10762 apply a patch.
10763 Setting the value to "user" causes the build system to
10764 launch a shell and places you in the right location so that
10765 you can manually resolve the conflicts.
10766 </para>
10767
10768 <para>
10769 Set this variable in your
10770 <filename>local.conf</filename> file.
10771 </para>
10772 </glossdef>
10773 </glossentry>
10774
10775 <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
10776 <info>
10777 PATCHTOOL[doc] = "Specifies the utility used to apply patches for a recipe during do_patch."
10778 </info>
10779 <glossdef>
10780 <para role="glossdeffirst">
10781<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10782 Specifies the utility used to apply patches for a recipe
10783 during the
10784 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
10785 task.
10786 You can specify one of three utilities: "patch", "quilt", or
10787 "git".
10788 The default utility used is "quilt" except for the
10789 quilt-native recipe itself.
10790 Because the quilt tool is not available at the
10791 time quilt-native is being patched, it uses "patch".
10792 </para>
10793
10794 <para>
10795 If you wish to use an alternative patching tool, set the
10796 variable in the recipe using one of the following:
10797 <literallayout class='monospaced'>
10798 PATCHTOOL = "patch"
10799 PATCHTOOL = "quilt"
10800 PATCHTOOL = "git"
10801 </literallayout>
10802 </para>
10803 </glossdef>
10804 </glossentry>
10805
10806 <glossentry id='var-PE'><glossterm>PE</glossterm>
10807 <info>
10808 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."
10809 </info>
10810 <glossdef>
10811 <para role="glossdeffirst">
10812<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10813 The epoch of the recipe.
10814 By default, this variable is unset.
10815 The variable is used to make upgrades possible when the
10816 versioning scheme changes in some backwards incompatible
10817 way.
10818 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010819
10820 <para>
10821 <filename>PE</filename> is the default value of the
10822 <link linkend='var-PKGE'><filename>PKGE</filename></link>
10823 variable.
10824 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010825 </glossdef>
10826 </glossentry>
10827
10828 <glossentry id='var-PF'><glossterm>PF</glossterm>
10829 <info>
10830 PF[doc] = "Specifies the recipe or package name and includes all version and revision numbers. This variable is comprised of ${PN}-${EXTENDPE}${PV}-${PR}."
10831 </info>
10832 <glossdef>
10833 <para role="glossdeffirst">
10834<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10835 Specifies the recipe or package name and includes all version and revision
10836 numbers (i.e. <filename>glibc-2.13-r20+svnr15508/</filename> and
10837 <filename>bash-4.2-r1/</filename>).
10838 This variable is comprised of the following:
10839 <literallayout class='monospaced'>
10840 ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
10841 </literallayout>
10842 </para>
10843 </glossdef>
10844 </glossentry>
10845
10846 <glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm>
10847 <info>
10848 PIXBUF_PACKAGES[doc] = "When a recipe inherits the pixbufcache class, this variable identifies packages that contain the pixbuf loaders used with gdk-pixbuf."
10849 </info>
10850 <glossdef>
10851 <para role="glossdeffirst">
10852<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10853 When inheriting the
10854 <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link>
10855 class, this variable identifies packages that contain
10856 the pixbuf loaders used with
10857 <filename>gdk-pixbuf</filename>.
10858 By default, the <filename>pixbufcache</filename> class
10859 assumes that the loaders are in the recipe's main package
10860 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
10861 Use this variable if the loaders you need are in a package
10862 other than that main package.
10863 </para>
10864 </glossdef>
10865 </glossentry>
10866
10867 <glossentry id='var-PKG'><glossterm>PKG</glossterm>
10868 <info>
10869 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."
10870 </info>
10871 <glossdef>
10872 <para role="glossdeffirst">
10873<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10874 The name of the resulting package created by the
10875 OpenEmbedded build system.
10876 <note>
10877 When using the <filename>PKG</filename> variable, you
10878 must use a package name override.
10879 </note>
10880 </para>
10881
10882 <para>
10883 For example, when the
10884 <link linkend='ref-classes-debian'><filename>debian</filename></link>
10885 class renames the output package, it does so by setting
10886 <filename>PKG_<replaceable>packagename</replaceable></filename>.
10887 </para>
10888 </glossdef>
10889 </glossentry>
10890
10891 <glossentry id='var-PKG_CONFIG_PATH'><glossterm>PKG_CONFIG_PATH</glossterm>
10892 <info>
10893 PKG_CONFIG_PATH[doc] = "Path to pkg-config files for the current build context."
10894 </info>
10895 <glossdef>
10896 <para role="glossdeffirst">
10897<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10898 The path to <filename>pkg-config</filename> files for the
10899 current build context.
10900 <filename>pkg-config</filename> reads this variable
10901 from the environment.
10902 </para>
10903 </glossdef>
10904 </glossentry>
10905
10906 <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
10907 <info>
10908 PKGD[doc] = "Points to the destination directory for files to be packaged before they are split into individual packages."
10909 </info>
10910 <glossdef>
10911 <para role="glossdeffirst">
10912<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10913 Points to the destination directory for files to be
10914 packaged before they are split into individual packages.
10915 This directory defaults to the following:
10916 <literallayout class='monospaced'>
10917 ${WORKDIR}/package
10918 </literallayout>
10919 </para>
10920
10921 <para>
10922 Do not change this default.
10923 </para>
10924 </glossdef>
10925 </glossentry>
10926
10927 <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
10928 <info>
10929 PKGDATA_DIR[doc] = "Points to a shared, global-state directory that holds data generated during the packaging process."
10930 </info>
10931 <glossdef>
10932 <para role="glossdeffirst">
10933<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10934 Points to a shared, global-state directory that holds data
10935 generated during the packaging process.
10936 During the packaging process, the
10937 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
10938 task packages data for each recipe and installs it into
10939 this temporary, shared area.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010940 This directory defaults to the following, which you should
10941 not change:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010942 <literallayout class='monospaced'>
10943 ${STAGING_DIR_HOST}/pkgdata
10944 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010945 For examples of how this data is used, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040010946 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
10947 section in the Yocto Project Overview and Concepts Manual
10948 and the
10949 "<ulink url='&YOCTO_DOCS_DEV_URL;#viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></ulink>"
10950 section in the Yocto Project Development Tasks Manual.
10951 For more information on the shared, global-state directory,
10952 see
10953 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010954 </para>
10955 </glossdef>
10956 </glossentry>
10957
10958 <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
10959 <info>
10960 PKGDEST[doc] = "Points to the parent directory for files to be packaged after they have been split into individual packages."
10961 </info>
10962 <glossdef>
10963 <para role="glossdeffirst">
10964<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10965 Points to the parent directory for files to be packaged
10966 after they have been split into individual packages.
10967 This directory defaults to the following:
10968 <literallayout class='monospaced'>
10969 ${WORKDIR}/packages-split
10970 </literallayout>
10971 </para>
10972
10973 <para>
10974 Under this directory, the build system creates
10975 directories for each package specified in
10976 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
10977 Do not change this default.
10978 </para>
10979 </glossdef>
10980 </glossentry>
10981
10982 <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
10983 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010984 PKGDESTWORK[doc] = "Points to a temporary work area where the do_package task saves package metadata."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010985 </info>
10986 <glossdef>
10987 <para role="glossdeffirst">
10988<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010989 Points to a temporary work area where the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010990 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010991 task saves package metadata.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010992 The <filename>PKGDESTWORK</filename> location defaults to
10993 the following:
10994 <literallayout class='monospaced'>
10995 ${WORKDIR}/pkgdata
10996 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010997 Do not change this default.
10998 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010999
11000 <para>
11001 The
11002 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
11003 task copies the package metadata from
11004 <filename>PKGDESTWORK</filename> to
11005 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
11006 to make it available globally.
11007 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011008 </glossdef>
11009 </glossentry>
11010
11011 <glossentry id='var-PKGE'><glossterm>PKGE</glossterm>
11012 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011013 PKGE[doc] = "The epoch of the package(s) built by the recipe."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011014 </info>
11015 <glossdef>
11016 <para role="glossdeffirst">
11017<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011018 The epoch of the package(s) built by the recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011019 By default, <filename>PKGE</filename> is set to
11020 <link linkend='var-PE'><filename>PE</filename></link>.
11021 </para>
11022 </glossdef>
11023 </glossentry>
11024
11025 <glossentry id='var-PKGR'><glossterm>PKGR</glossterm>
11026 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011027 PKGR[doc] = "The revision of the package(s) built by the recipe."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011028 </info>
11029 <glossdef>
11030 <para role="glossdeffirst">
11031<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011032 The revision of the package(s) built by the recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011033 By default, <filename>PKGR</filename> is set to
11034 <link linkend='var-PR'><filename>PR</filename></link>.
11035 </para>
11036 </glossdef>
11037 </glossentry>
11038
11039 <glossentry id='var-PKGV'><glossterm>PKGV</glossterm>
11040 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011041 PKGV[doc] = "The version of the package(s) built by the recipe."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011042 </info>
11043 <glossdef>
11044 <para role="glossdeffirst">
11045<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011046 The version of the package(s) built by the
11047 recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011048 By default, <filename>PKGV</filename> is set to
11049 <link linkend='var-PV'><filename>PV</filename></link>.
11050 </para>
11051 </glossdef>
11052 </glossentry>
11053
11054 <glossentry id='var-PN'><glossterm>PN</glossterm>
11055 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011056 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 -050011057 </info>
11058 <glossdef>
11059 <para role="glossdeffirst">
11060<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11061 This variable can have two separate functions depending on the context: a recipe
11062 name or a resulting package name.
11063 </para>
11064
11065 <para>
11066 <filename>PN</filename> refers to a recipe name in the context of a file used
11067 by the OpenEmbedded build system as input to create a package.
11068 The name is normally extracted from the recipe file name.
11069 For example, if the recipe is named
11070 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
11071 will be "expat".
11072 </para>
11073
11074 <para>
11075 The variable refers to a package name in the context of a file created or produced by the
11076 OpenEmbedded build system.
11077 </para>
11078
11079 <para>
11080 If applicable, the <filename>PN</filename> variable also contains any special
11081 suffix or prefix.
11082 For example, using <filename>bash</filename> to build packages for the native
11083 machine, <filename>PN</filename> is <filename>bash-native</filename>.
11084 Using <filename>bash</filename> to build packages for the target and for Multilib,
11085 <filename>PN</filename> would be <filename>bash</filename> and
11086 <filename>lib64-bash</filename>, respectively.
11087 </para>
11088 </glossdef>
11089 </glossentry>
11090
11091 <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>
11092 <info>
11093 PNBLACKLIST[doc] = "Lists recipes you do not want the OpenEmbedded build system to build."
11094 </info>
11095 <glossdef>
11096 <para role="glossdeffirst">
11097<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11098 Lists recipes you do not want the OpenEmbedded build system
11099 to build.
11100 This variable works in conjunction with the
11101 <link linkend='ref-classes-blacklist'><filename>blacklist</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011102 class, which is inherited globally.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011103 </para>
11104
11105 <para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011106 To prevent a recipe from being built, use the
11107 <filename>PNBLACKLIST</filename> variable in your
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011108 <filename>local.conf</filename> file.
11109 Here is an example that prevents
11110 <filename>myrecipe</filename> from being built:
11111 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011112 PNBLACKLIST[myrecipe] = "Not supported by our organization."
11113 </literallayout>
11114 </para>
11115 </glossdef>
11116 </glossentry>
11117
11118 <glossentry id='var-POPULATE_SDK_POST_HOST_COMMAND'><glossterm>POPULATE_SDK_POST_HOST_COMMAND</glossterm>
11119 <info>
11120 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."
11121 </info>
11122 <glossdef>
11123 <para role="glossdeffirst">
11124<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11125 Specifies a list of functions to call once the
11126 OpenEmbedded build system has created the host part of
11127 the SDK.
11128 You can specify functions separated by semicolons:
11129 <literallayout class='monospaced'>
11130 POPULATE_SDK_POST_HOST_COMMAND += "<replaceable>function</replaceable>; ... "
11131 </literallayout>
11132 </para>
11133
11134 <para>
11135 If you need to pass the SDK path to a command
11136 within a function, you can use
11137 <filename>${SDK_DIR}</filename>, which points to
11138 the parent directory used by the OpenEmbedded build
11139 system when creating SDK output.
11140 See the
11141 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
11142 variable for more information.
11143 </para>
11144 </glossdef>
11145 </glossentry>
11146
11147 <glossentry id='var-POPULATE_SDK_POST_TARGET_COMMAND'><glossterm>POPULATE_SDK_POST_TARGET_COMMAND</glossterm>
11148 <info>
11149 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."
11150 </info>
11151 <glossdef>
11152 <para role="glossdeffirst">
11153<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11154 Specifies a list of functions to call once the
11155 OpenEmbedded build system has created the target part of
11156 the SDK.
11157 You can specify functions separated by semicolons:
11158 <literallayout class='monospaced'>
11159 POPULATE_SDK_POST_TARGET_COMMAND += "<replaceable>function</replaceable>; ... "
11160 </literallayout>
11161 </para>
11162
11163 <para>
11164 If you need to pass the SDK path to a command
11165 within a function, you can use
11166 <filename>${SDK_DIR}</filename>, which points to
11167 the parent directory used by the OpenEmbedded build
11168 system when creating SDK output.
11169 See the
11170 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
11171 variable for more information.
11172 </para>
11173 </glossdef>
11174 </glossentry>
11175
11176 <glossentry id='var-PR'><glossterm>PR</glossterm>
11177 <info>
11178 PR[doc] = "The revision of the recipe. The default value for this variable is 'r0'."
11179 </info>
11180 <glossdef>
11181 <para role="glossdeffirst">
11182<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011183 The revision of the recipe. The default value for this
11184 variable is "r0".
11185 Subsequent revisions of the recipe conventionally have the
11186 values "r1", "r2", and so forth.
11187 When
11188 <link linkend='var-PV'><filename>PV</filename></link>
11189 increases, <filename>PR</filename> is conventionally reset
11190 to "r0".
11191 <note>
11192 The OpenEmbedded build system does not need the aid of
11193 <filename>PR</filename> to know when to rebuild a
11194 recipe.
11195 The build system uses the task
Brad Bishop316dfdd2018-06-25 12:45:53 -040011196 <ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>input checksums</ulink>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011197 along with the
11198 <link linkend='structure-build-tmp-stamps'>stamp</link>
11199 and
Brad Bishop316dfdd2018-06-25 12:45:53 -040011200 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state cache</ulink>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011201 mechanisms.
11202 </note>
11203 The <filename>PR</filename> variable primarily becomes
11204 significant when a package manager dynamically installs
11205 packages on an already built image.
11206 In this case, <filename>PR</filename>, which is the default
11207 value of
11208 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
11209 helps the package manager distinguish which package is the
11210 most recent one in cases where many packages have the same
11211 <filename>PV</filename> (i.e. <filename>PKGV</filename>).
11212 A component having many packages with the same
11213 <filename>PV</filename> usually means that the packages all
11214 install the same upstream version, but with later
11215 (<filename>PR</filename>) version packages including
11216 packaging fixes.
11217 <note>
11218 <filename>PR</filename> does not need to be increased
11219 for changes that do not change the package contents or
11220 metadata.
11221 </note>
11222 Because manually managing <filename>PR</filename> can be
11223 cumbersome and error-prone, an automated solution exists.
11224 See the
11225 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011226 section in the Yocto Project Development Tasks Manual
11227 for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011228 </para>
11229 </glossdef>
11230 </glossentry>
11231
11232 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
11233 <info>
11234 PREFERRED_PROVIDER[doc] = "If multiple recipes provide an item, this variable determines which recipe should be given preference."
11235 </info>
11236 <glossdef>
11237 <para role="glossdeffirst">
11238<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040011239 If multiple recipes provide the same item, this variable
11240 determines which recipe is preferred and thus provides
11241 the item (i.e. the preferred provider).
11242 You should always suffix this variable with the name of the
11243 provided item.
11244 And, you should define the variable using the preferred
11245 recipe's name
11246 (<link linkend='var-PN'><filename>PN</filename></link>).
11247 Here is a common example:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011248 <literallayout class='monospaced'>
11249 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
Brad Bishop316dfdd2018-06-25 12:45:53 -040011250 </literallayout>
11251 In the previous example, multiple recipes are providing
11252 "virtual/kernel".
11253 The <filename>PREFERRED_PROVIDER</filename> variable is
11254 set with the name (<filename>PN</filename>) of the recipe
11255 you prefer to provide "virtual/kernel".
11256 </para>
11257
11258 <para>
11259 Following are more examples:
11260 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011261 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
11262 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
11263 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011264 For more information, see the
11265 "<ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>Using Virtual Providers</ulink>"
11266 section in the Yocto Project Development Tasks Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011267 <note>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011268 If you use a <filename>virtual/*</filename> item
11269 with <filename>PREFERRED_PROVIDER</filename>, then any
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011270 recipe that
11271 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011272 that item but is not selected (defined) by
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011273 <filename>PREFERRED_PROVIDER</filename> is prevented
11274 from building, which is usually desirable since this
11275 mechanism is designed to select between mutually
11276 exclusive alternative providers.
11277 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011278 </para>
11279 </glossdef>
11280 </glossentry>
11281
11282 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
11283 <info>
11284 PREFERRED_VERSION[doc] = "If there are multiple versions of recipes available, this variable determines which recipe should be given preference."
11285 </info>
11286 <glossdef>
11287 <para role="glossdeffirst">
11288<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011289 If multiple versions of recipes exist, this
11290 variable determines which version is given preference.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011291 You must always suffix the variable with the
11292 <link linkend='var-PN'><filename>PN</filename></link>
11293 you want to select, and you should set the
11294 <link linkend='var-PV'><filename>PV</filename></link>
11295 accordingly for precedence.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011296 </para>
11297
11298 <para>
11299 The <filename>PREFERRED_VERSION</filename> variable
11300 supports limited wildcard use through the
11301 "<filename>%</filename>" character.
11302 You can use the character to match any number of
11303 characters, which can be useful when specifying versions
11304 that contain long revision numbers that potentially change.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011305 Here are two examples:
11306 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011307 PREFERRED_VERSION_python = "3.4.0"
Brad Bishopc342db32019-05-15 21:57:59 -040011308 PREFERRED_VERSION_linux-yocto = "5.0%"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011309 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011310 <note><title>Important</title>
11311 The use of the "<filename>%</filename>" character
11312 is limited in that it only works at the end of the
11313 string.
11314 You cannot use the wildcard character in any other
11315 location of the string.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011316 </note>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011317 </para>
11318
11319 <para>
11320 The specified version is matched against
11321 <link linkend='var-PV'><filename>PV</filename></link>,
11322 which does not necessarily match the version part of
11323 the recipe's filename.
11324 For example, consider two recipes
11325 <filename>foo_1.2.bb</filename> and
11326 <filename>foo_git.bb</filename> where
11327 <filename>foo_git.bb</filename> contains the following
11328 assignment:
11329 <literallayout class='monospaced'>
11330 PV = "1.1+git${SRCPV}"
11331 </literallayout>
11332 In this case, the correct way to select
11333 <filename>foo_git.bb</filename> is by using an
11334 assignment such as the following:
11335 <literallayout class='monospaced'>
11336 PREFERRED_VERSION_foo = "1.1+git%"
11337 </literallayout>
11338 Compare that previous example against the following
11339 incorrect example, which does not work:
11340 <literallayout class='monospaced'>
11341 PREFERRED_VERSION_foo = "git"
11342 </literallayout>
11343 </para>
11344
11345 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011346 Sometimes the <filename>PREFERRED_VERSION</filename>
11347 variable can be set by configuration files in a way that
11348 is hard to change.
11349 You can use
11350 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
11351 to set a machine-specific override.
11352 Here is an example:
11353 <literallayout class='monospaced'>
Brad Bishopc342db32019-05-15 21:57:59 -040011354 PREFERRED_VERSION_linux-yocto_qemux86 = "5.0%"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011355 </literallayout>
11356 Although not recommended, worst case, you can also use the
11357 "forcevariable" override, which is the strongest override
11358 possible.
11359 Here is an example:
11360 <literallayout class='monospaced'>
Brad Bishopc342db32019-05-15 21:57:59 -040011361 PREFERRED_VERSION_linux-yocto_forcevariable = "5.0%"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011362 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011363 <note>
11364 The <filename>_forcevariable</filename> override is
11365 not handled specially.
11366 This override only works because the default value of
Brad Bishop316dfdd2018-06-25 12:45:53 -040011367 <filename>OVERRIDES</filename> includes
11368 "forcevariable".
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011369 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011370 </para>
11371 </glossdef>
11372 </glossentry>
11373
11374 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
11375 <info>
11376 PREMIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."
11377 </info>
11378 <glossdef>
11379 <para role="glossdeffirst">
11380<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11381 Specifies additional paths from which the OpenEmbedded
11382 build system gets source code.
11383 When the build system searches for source code, it first
11384 tries the local download directory.
11385 If that location fails, the build system tries locations
11386 defined by <filename>PREMIRRORS</filename>, the upstream
11387 source, and then locations specified by
11388 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
11389 in that order.
11390 </para>
11391
11392 <para>
11393 Assuming your distribution
11394 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
11395 is "poky", the default value for
11396 <filename>PREMIRRORS</filename> is defined in the
11397 <filename>conf/distro/poky.conf</filename> file in the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011398 <filename>meta-poky</filename> Git repository.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011399 </para>
11400
11401 <para>
11402 Typically, you could add a specific server for the
11403 build system to attempt before any others by adding
11404 something like the following to the
11405 <filename>local.conf</filename> configuration file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011406 <link linkend='build-directory'>Build Directory</link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011407 <literallayout class='monospaced'>
11408 PREMIRRORS_prepend = "\
11409 git://.*/.* http://www.yoctoproject.org/sources/ \n \
11410 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
11411 http://.*/.* http://www.yoctoproject.org/sources/ \n \
11412 https://.*/.* http://www.yoctoproject.org/sources/ \n"
11413 </literallayout>
11414 These changes cause the build system to intercept
11415 Git, FTP, HTTP, and HTTPS requests and direct them to
11416 the <filename>http://</filename> sources mirror.
11417 You can use <filename>file://</filename> URLs to point
11418 to local directories or network shares as well.
11419 </para>
11420 </glossdef>
11421 </glossentry>
11422
11423 <glossentry id='var-PRIORITY'><glossterm>PRIORITY</glossterm>
11424 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011425 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 -050011426 </info>
11427 <glossdef>
11428 <para role="glossdeffirst">
11429<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11430 Indicates the importance of a package.
11431 </para>
11432
11433 <para>
11434 <filename>PRIORITY</filename> is considered to be part of
11435 the distribution policy because the importance of any given
11436 recipe depends on the purpose for which the distribution
11437 is being produced.
11438 Thus, <filename>PRIORITY</filename> is not normally set
11439 within recipes.
11440 </para>
11441
11442 <para>
11443 You can set <filename>PRIORITY</filename> to "required",
11444 "standard", "extra", and "optional", which is the default.
11445 </para>
11446 </glossdef>
11447 </glossentry>
11448
11449 <glossentry id='var-PRIVATE_LIBS'><glossterm>PRIVATE_LIBS</glossterm>
11450 <info>
11451 PRIVATE_LIBS[doc] = "Specifies libraries installed within a recipe that should be ignored by the OpenEmbedded build system's shared library resolver."
11452 </info>
11453 <glossdef>
11454 <para role="glossdeffirst">
11455<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11456 Specifies libraries installed within a recipe that
11457 should be ignored by the OpenEmbedded build system's
11458 shared library resolver.
11459 This variable is typically used when software being
11460 built by a recipe has its own private versions of a
11461 library normally provided by another recipe.
11462 In this case, you would not want the package containing
11463 the private libraries to be set as a dependency on other
11464 unrelated packages that should instead depend on the
11465 package providing the standard version of the library.
11466 </para>
11467
11468 <para>
11469 Libraries specified in this variable should be specified
11470 by their file name.
11471 For example, from the Firefox recipe in meta-browser:
11472 <literallayout class='monospaced'>
11473 PRIVATE_LIBS = "libmozjs.so \
11474 libxpcom.so \
11475 libnspr4.so \
11476 libxul.so \
11477 libmozalloc.so \
11478 libplc4.so \
11479 libplds4.so"
11480 </literallayout>
11481 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011482
11483 <para>
11484 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040011485 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
11486 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011487 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011488 </glossdef>
11489 </glossentry>
11490
11491 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
11492 <info>
11493 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."
11494 </info>
11495 <glossdef>
11496 <para role="glossdeffirst">
11497<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11498 A list of aliases by which a particular recipe can be
11499 known.
11500 By default, a recipe's own
11501 <filename><link linkend='var-PN'>PN</link></filename>
11502 is implicitly already in its <filename>PROVIDES</filename>
11503 list.
11504 If a recipe uses <filename>PROVIDES</filename>, the
11505 additional aliases are synonyms for the recipe and can
11506 be useful satisfying dependencies of other recipes during
11507 the build as specified by
11508 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
11509 </para>
11510
11511 <para>
11512 Consider the following example
11513 <filename>PROVIDES</filename> statement from a recipe
11514 file <filename>libav_0.8.11.bb</filename>:
11515 <literallayout class='monospaced'>
11516 PROVIDES += "libpostproc"
11517 </literallayout>
11518 The <filename>PROVIDES</filename> statement results in
11519 the "libav" recipe also being known as "libpostproc".
11520 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011521
11522 <para>
11523 In addition to providing recipes under alternate names,
11524 the <filename>PROVIDES</filename> mechanism is also used
11525 to implement virtual targets.
11526 A virtual target is a name that corresponds to some
11527 particular functionality (e.g. a Linux kernel).
11528 Recipes that provide the functionality in question list the
11529 virtual target in <filename>PROVIDES</filename>.
11530 Recipes that depend on the functionality in question can
Brad Bishop316dfdd2018-06-25 12:45:53 -040011531 include the virtual target in <filename>DEPENDS</filename>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011532 to leave the choice of provider open.
11533 </para>
11534
11535 <para>
11536 Conventionally, virtual targets have names on the form
11537 "virtual/function" (e.g. "virtual/kernel").
11538 The slash is simply part of the name and has no
11539 syntactical significance.
11540 </para>
11541
11542 <para>
11543 The
11544 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
11545 variable is used to select which particular recipe
11546 provides a virtual target.
11547 <note>
11548 <para>A corresponding mechanism for virtual runtime
11549 dependencies (packages) exists.
11550 However, the mechanism does not depend on any special
11551 functionality beyond ordinary variable assignments.
11552 For example,
11553 <filename>VIRTUAL-RUNTIME_dev_manager</filename>
11554 refers to the package of the component that manages
11555 the <filename>/dev</filename> directory.</para>
11556
11557 <para>Setting the "preferred provider" for runtime
11558 dependencies is as simple as using the following
11559 assignment in a configuration file:</para>
11560 <literallayout class='monospaced'>
11561 VIRTUAL-RUNTIME_dev_manager = "udev"
11562 </literallayout>
11563 </note>
11564 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011565 </glossdef>
11566 </glossentry>
11567
11568 <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
11569 <info>
11570 PRSERV_HOST[doc] = "The network based PR service host and port."
11571 </info>
11572 <glossdef>
11573 <para role="glossdeffirst">
11574<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11575 The network based
11576 <link linkend='var-PR'><filename>PR</filename></link>
11577 service host and port.
11578 </para>
11579
11580 <para>
11581 The <filename>conf/local.conf.sample.extended</filename>
11582 configuration file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011583 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011584 shows how the <filename>PRSERV_HOST</filename> variable is
11585 set:
11586 <literallayout class='monospaced'>
11587 PRSERV_HOST = "localhost:0"
11588 </literallayout>
11589 You must set the variable if you want to automatically
11590 start a local
11591 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.
11592 You can set <filename>PRSERV_HOST</filename> to other
11593 values to use a remote PR service.
11594 </para>
11595 </glossdef>
11596 </glossentry>
11597
11598 <glossentry id='var-PTEST_ENABLED'><glossterm>PTEST_ENABLED</glossterm>
11599 <info>
11600 PRSERV_HOST[doc] = "Specifies whether or not Package Test (ptest) functionality is enabled when building a recipe."
11601 </info>
11602 <glossdef>
11603 <para role="glossdeffirst">
11604<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11605 Specifies whether or not
11606 <ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Package Test</ulink>
11607 (ptest) functionality is enabled when building a recipe.
11608 You should not set this variable directly.
11609 Enabling and disabling building Package Tests
11610 at build time should be done by adding "ptest" to (or
11611 removing it from)
11612 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
11613 </para>
11614 </glossdef>
11615 </glossentry>
11616
11617 <glossentry id='var-PV'><glossterm>PV</glossterm>
11618 <info>
11619 PV[doc] = "The version of the recipe. The version is normally extracted from the recipe filename."
11620 </info>
11621 <glossdef>
11622 <para role="glossdeffirst">
11623<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11624 The version of the recipe.
11625 The version is normally extracted from the recipe filename.
11626 For example, if the recipe is named
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011627 <filename>expat_2.0.1.bb</filename>, then the default value
11628 of <filename>PV</filename> will be "2.0.1".
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011629 <filename>PV</filename> is generally not overridden within
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011630 a recipe unless it is building an unstable (i.e.
11631 development) version from a source code repository
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011632 (e.g. Git or Subversion).
11633 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011634
11635 <para>
11636 <filename>PV</filename> is the default value of the
11637 <link linkend='var-PKGV'><filename>PKGV</filename></link>
11638 variable.
11639 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011640 </glossdef>
11641 </glossentry>
11642
11643 <glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>
11644 <info>
11645 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."
11646 </info>
11647 <glossdef>
11648 <para role="glossdeffirst">
11649<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11650 When used by recipes that inherit the
11651 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
11652 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
11653 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
11654 or
11655 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
11656 classes, denotes the Application Binary Interface (ABI)
11657 currently in use for Python.
11658 By default, the ABI is "m".
11659 You do not have to set this variable as the OpenEmbedded
11660 build system sets it for you.
11661 </para>
11662
11663 <para>
11664 The OpenEmbedded build system uses the ABI to construct
11665 directory names used when installing the Python headers
11666 and libraries in sysroot
11667 (e.g. <filename>.../python3.3m/...</filename>).
11668 </para>
11669
11670 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011671 Recipes that inherit the <filename>distutils</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011672 class during cross-builds also use this variable to
11673 locate the headers and libraries of the appropriate Python
11674 that the extension is targeting.
11675 </para>
11676 </glossdef>
11677 </glossentry>
11678
11679 <glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>
11680 <info>
11681 PYTHON_PN[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, specifies the major Python version being built."
11682 </info>
11683 <glossdef>
11684 <para role="glossdeffirst">
11685<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11686 When used by recipes that inherit the
11687 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
11688 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
11689 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
11690 or
11691 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
11692 classes, specifies the major Python version being built.
Brad Bishop96ff1982019-08-19 13:50:42 -040011693 For Python 3.x, <filename>PYTHON_PN</filename> would be
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011694 "python3".
11695 You do not have to set this variable as the
11696 OpenEmbedded build system automatically sets it for you.
11697 </para>
11698
11699 <para>
11700 The variable allows recipes to use common infrastructure
11701 such as the following:
11702 <literallayout class='monospaced'>
11703 DEPENDS += "${PYTHON_PN}-native"
11704 </literallayout>
11705 In the previous example, the version of the dependency
11706 is <filename>PYTHON_PN</filename>.
11707 </para>
11708 </glossdef>
11709 </glossentry>
11710
11711 </glossdiv>
11712
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011713 <glossdiv id='var-glossary-r'><title>R</title>
11714
11715 <glossentry id='var-RANLIB'><glossterm>RANLIB</glossterm>
11716 <info>
11717 RANLIB[doc] = "Minimal command and arguments to run 'ranlib'."
11718 </info>
11719 <glossdef>
11720 <para role="glossdeffirst">
11721<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11722 The minimal command and arguments to run
11723 <filename>ranlib</filename>.
11724 </para>
11725 </glossdef>
11726 </glossentry>
11727
11728 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
11729 <info>
11730 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."
11731 </info>
11732 <glossdef>
11733 <para role="glossdeffirst">
11734<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11735 The list of packages that conflict with packages.
11736 Note that packages will not be installed if conflicting
11737 packages are not first removed.
11738 </para>
11739
11740 <para>
11741 Like all package-controlling variables, you must always use
11742 them in conjunction with a package name override.
11743 Here is an example:
11744 <literallayout class='monospaced'>
11745 RCONFLICTS_${PN} = "<replaceable>another_conflicting_package_name</replaceable>"
11746 </literallayout>
11747 </para>
11748
11749 <para>
11750 BitBake, which the OpenEmbedded build system uses, supports
11751 specifying versioned dependencies.
11752 Although the syntax varies depending on the packaging
11753 format, BitBake hides these differences from you.
11754 Here is the general syntax to specify versions with
11755 the <filename>RCONFLICTS</filename> variable:
11756 <literallayout class='monospaced'>
11757 RCONFLICTS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
11758 </literallayout>
11759 For <filename>operator</filename>, you can specify the
11760 following:
11761 <literallayout class='monospaced'>
11762 =
11763 &lt;
11764 &gt;
11765 &lt;=
11766 &gt;=
11767 </literallayout>
11768 For example, the following sets up a dependency on version
11769 1.2 or greater of the package <filename>foo</filename>:
11770 <literallayout class='monospaced'>
11771 RCONFLICTS_${PN} = "foo (>= 1.2)"
11772 </literallayout>
11773 </para>
11774 </glossdef>
11775 </glossentry>
11776
11777 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
11778 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011779 RDEPENDS[doc] = "Lists runtime dependencies of a package."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011780 </info>
11781 <glossdef>
11782 <para role="glossdeffirst">
11783<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011784 Lists runtime dependencies of a package.
11785 These dependencies are other packages that must be
11786 installed in order for the package to function correctly.
11787 As an example, the following assignment declares that the
11788 package <filename>foo</filename> needs the packages
11789 <filename>bar</filename> and <filename>baz</filename> to
11790 be installed:
11791 <literallayout class='monospaced'>
11792 RDEPENDS_foo = "bar baz"
11793 </literallayout>
11794 The most common types of package runtime dependencies are
11795 automatically detected and added.
11796 Therefore, most recipes do not need to set
11797 <filename>RDEPENDS</filename>.
11798 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040011799 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
11800 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011801 </para>
11802
11803 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011804 The practical effect of the above
11805 <filename>RDEPENDS</filename> assignment is that
11806 <filename>bar</filename> and <filename>baz</filename>
11807 will be declared as dependencies inside the package
11808 <filename>foo</filename> when it is written out by one of
11809 the
11810 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>
11811 tasks.
11812 Exactly how this is done depends on which package format
11813 is used, which is determined by
11814 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>.
11815 When the corresponding package manager installs the
11816 package, it will know to also install the packages on
11817 which it depends.
11818 </para>
11819
11820 <para>
11821 To ensure that the packages <filename>bar</filename> and
11822 <filename>baz</filename> get built, the previous
11823 <filename>RDEPENDS</filename> assignment also causes a task
11824 dependency to be added.
11825 This dependency is from the recipe's
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011826 <link linkend='ref-tasks-build'><filename>do_build</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011827 (not to be confused with
11828 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>)
11829 task to the <filename>do_package_write_*</filename>
11830 task of the recipes that build <filename>bar</filename> and
11831 <filename>baz</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011832 </para>
11833
11834 <para>
11835 The names of the packages you list within
11836 <filename>RDEPENDS</filename> must be the names of other
11837 packages - they cannot be recipe names.
11838 Although package names and recipe names usually match,
11839 the important point here is that you are
11840 providing package names within the
11841 <filename>RDEPENDS</filename> variable.
11842 For an example of the default list of packages created from
11843 a recipe, see the
11844 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
11845 variable.
11846 </para>
11847
11848 <para>
11849 Because the <filename>RDEPENDS</filename> variable applies
11850 to packages being built, you should always use the variable
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011851 in a form with an attached package name (remember that a
11852 single recipe can build multiple packages).
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011853 For example, suppose you are building a development package
11854 that depends on the <filename>perl</filename> package.
11855 In this case, you would use the following
11856 <filename>RDEPENDS</filename> statement:
11857 <literallayout class='monospaced'>
11858 RDEPENDS_${PN}-dev += "perl"
11859 </literallayout>
11860 In the example, the development package depends on
11861 the <filename>perl</filename> package.
11862 Thus, the <filename>RDEPENDS</filename> variable has the
11863 <filename>${PN}-dev</filename> package name as part of the
11864 variable.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011865 <note>
11866 <title>Caution</title>
11867 <filename>RDEPENDS_${PN}-dev</filename> includes
11868 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>
11869 by default.
11870 This default is set in the BitBake configuration file
11871 (<filename>meta/conf/bitbake.conf</filename>).
11872 Be careful not to accidentally remove
11873 <filename>${PN}</filename> when modifying
11874 <filename>RDEPENDS_${PN}-dev</filename>.
11875 Use the "+=" operator rather than the "=" operator.
11876 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011877 </para>
11878
11879 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011880 The package names you use with
11881 <filename>RDEPENDS</filename> must appear as they would in
11882 the <filename>PACKAGES</filename> variable.
11883 The
11884 <link linkend='var-PKG'><filename>PKG</filename></link>
11885 variable allows a different name to be used for
11886 the final package (e.g. the
11887 <link linkend='ref-classes-debian'><filename>debian</filename></link>
11888 class uses this to rename packages), but this final package
11889 name cannot be used with <filename>RDEPENDS</filename>,
11890 which makes sense as <filename>RDEPENDS</filename> is meant
11891 to be independent of the package format used.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011892 </para>
11893
11894 <para>
11895 BitBake, which the OpenEmbedded build system uses, supports
11896 specifying versioned dependencies.
11897 Although the syntax varies depending on the packaging
11898 format, BitBake hides these differences from you.
11899 Here is the general syntax to specify versions with
11900 the <filename>RDEPENDS</filename> variable:
11901 <literallayout class='monospaced'>
11902 RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
11903 </literallayout>
Brad Bishop37a0e4d2017-12-04 01:01:44 -050011904 For <replaceable>operator</replaceable>, you can specify the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011905 following:
11906 <literallayout class='monospaced'>
11907 =
11908 &lt;
11909 &gt;
11910 &lt;=
11911 &gt;=
11912 </literallayout>
Brad Bishop37a0e4d2017-12-04 01:01:44 -050011913 For <replaceable>version</replaceable>, provide the version
11914 number.
11915 <note><title>Tip</title>
11916 You can use
11917 <link linkend='var-EXTENDPKGV'><filename>EXTENDPKGV</filename></link>
11918 to provide a full package version specification.
11919 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011920 For example, the following sets up a dependency on version
11921 1.2 or greater of the package <filename>foo</filename>:
11922 <literallayout class='monospaced'>
11923 RDEPENDS_${PN} = "foo (>= 1.2)"
11924 </literallayout>
11925 </para>
11926
11927 <para>
11928 For information on build-time dependencies, see the
11929 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
11930 variable.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011931 You can also see the
11932 "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
11933 "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
11934 sections in the BitBake User Manual for additional
11935 information on tasks and dependencies.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011936 </para>
11937 </glossdef>
11938 </glossentry>
11939
11940 <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm>
11941 <info>
11942 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."
11943 </info>
11944 <glossdef>
11945 <para role="glossdeffirst">
11946<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11947 When inheriting the
11948 <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link>
11949 class, this
11950 variable identifies distribution features that must
11951 exist in the current configuration in order for the
11952 OpenEmbedded build system to build the recipe.
11953 In other words, if the
11954 <filename>REQUIRED_DISTRO_FEATURES</filename> variable
11955 lists a feature that does not appear in
11956 <filename>DISTRO_FEATURES</filename> within the
11957 current configuration, an error occurs and the
11958 build stops.
11959 </para>
11960 </glossdef>
11961 </glossentry>
11962
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011963 <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
11964 <info>
11965 RM_WORK_EXCLUDE[doc] = "With rm_work enabled, this variable specifies a list of packages whose work directories should not be removed."
11966 </info>
11967 <glossdef>
11968 <para role="glossdeffirst">
11969<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11970 With <filename>rm_work</filename> enabled, this
11971 variable specifies a list of recipes whose work directories
11972 should not be removed.
11973 See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
11974 section for more details.
11975 </para>
11976 </glossdef>
11977 </glossentry>
11978
11979 <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm>
11980 <info>
11981 ROOT_HOME[doc] = "Defines the root home directory."
11982 </info>
11983 <glossdef>
11984 <para role="glossdeffirst">
11985<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11986 Defines the root home directory.
11987 By default, this directory is set as follows in the
11988 BitBake configuration file:
11989 <literallayout class='monospaced'>
11990 ROOT_HOME ??= "/home/root"
11991 </literallayout>
11992 <note>
11993 This default value is likely used because some
11994 embedded solutions prefer to have a read-only root
11995 filesystem and prefer to keep writeable data in one
11996 place.
11997 </note>
11998 </para>
11999
12000 <para>
12001 You can override the default by setting the variable
12002 in any layer or in the <filename>local.conf</filename> file.
12003 Because the default is set using a "weak" assignment
12004 (i.e. "??="), you can use either of the following forms
12005 to define your override:
12006 <literallayout class='monospaced'>
12007 ROOT_HOME = "/root"
12008 ROOT_HOME ?= "/root"
12009 </literallayout>
12010 These override examples use <filename>/root</filename>,
12011 which is probably the most commonly used override.
12012 </para>
12013 </glossdef>
12014 </glossentry>
12015
12016 <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>
12017 <info>
12018 ROOTFS[doc] = "Indicates a filesystem image to include as the root filesystem."
12019 </info>
12020 <glossdef>
12021 <para role="glossdeffirst">
12022<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12023 Indicates a filesystem image to include as the root
12024 filesystem.
12025 </para>
12026
12027 <para>
12028 The <filename>ROOTFS</filename> variable is an optional
12029 variable used with the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012030 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012031 class.
12032 </para>
12033 </glossdef>
12034 </glossentry>
12035
12036 <glossentry id='var-ROOTFS_POSTINSTALL_COMMAND'><glossterm>ROOTFS_POSTINSTALL_COMMAND</glossterm>
12037 <info>
12038 ROOTFS_POSTINSTALL_COMMAND[doc] = "Specifies a list of functions to call after installing packages."
12039 </info>
12040 <glossdef>
12041 <para role="glossdeffirst">
12042<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12043 Specifies a list of functions to call after the
12044 OpenEmbedded build system has installed packages.
12045 You can specify functions separated by semicolons:
12046 <literallayout class='monospaced'>
12047 ROOTFS_POSTINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
12048 </literallayout>
12049 </para>
12050
12051 <para>
12052 If you need to pass the root filesystem path to a command
12053 within a function, you can use
12054 <filename>${IMAGE_ROOTFS}</filename>, which points to
12055 the directory that becomes the root filesystem image.
12056 See the
12057 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12058 variable for more information.
12059 </para>
12060 </glossdef>
12061 </glossentry>
12062
12063 <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
12064 <info>
12065 ROOTFS_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the root filesystem."
12066 </info>
12067 <glossdef>
12068 <para role="glossdeffirst">
12069<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12070 Specifies a list of functions to call once the
12071 OpenEmbedded build system has created the root filesystem.
12072 You can specify functions separated by semicolons:
12073 <literallayout class='monospaced'>
12074 ROOTFS_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
12075 </literallayout>
12076 </para>
12077
12078 <para>
12079 If you need to pass the root filesystem path to a command
12080 within a function, you can use
12081 <filename>${IMAGE_ROOTFS}</filename>, which points to
12082 the directory that becomes the root filesystem image.
12083 See the
12084 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12085 variable for more information.
12086 </para>
12087 </glossdef>
12088 </glossentry>
12089
12090 <glossentry id='var-ROOTFS_POSTUNINSTALL_COMMAND'><glossterm>ROOTFS_POSTUNINSTALL_COMMAND</glossterm>
12091 <info>
12092 ROOTFS_POSTUNINSTALL_COMMAND[doc] = "Specifies a list of functions to call after removal of unneeded packages."
12093 </info>
12094 <glossdef>
12095 <para role="glossdeffirst">
12096<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12097 Specifies a list of functions to call after the
12098 OpenEmbedded build system has removed unnecessary
12099 packages.
12100 When runtime package management is disabled in the
12101 image, several packages are removed including
12102 <filename>base-passwd</filename>,
12103 <filename>shadow</filename>, and
12104 <filename>update-alternatives</filename>.
12105 You can specify functions separated by semicolons:
12106 <literallayout class='monospaced'>
12107 ROOTFS_POSTUNINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
12108 </literallayout>
12109 </para>
12110
12111 <para>
12112 If you need to pass the root filesystem path to a command
12113 within a function, you can use
12114 <filename>${IMAGE_ROOTFS}</filename>, which points to
12115 the directory that becomes the root filesystem image.
12116 See the
12117 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12118 variable for more information.
12119 </para>
12120 </glossdef>
12121 </glossentry>
12122
12123 <glossentry id='var-ROOTFS_PREPROCESS_COMMAND'><glossterm>ROOTFS_PREPROCESS_COMMAND</glossterm>
12124 <info>
12125 ROOTFS_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the root filesystem."
12126 </info>
12127 <glossdef>
12128 <para role="glossdeffirst">
12129<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12130 Specifies a list of functions to call before the
12131 OpenEmbedded build system has created the root filesystem.
12132 You can specify functions separated by semicolons:
12133 <literallayout class='monospaced'>
12134 ROOTFS_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
12135 </literallayout>
12136 </para>
12137
12138 <para>
12139 If you need to pass the root filesystem path to a command
12140 within a function, you can use
12141 <filename>${IMAGE_ROOTFS}</filename>, which points to
12142 the directory that becomes the root filesystem image.
12143 See the
12144 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12145 variable for more information.
12146 </para>
12147 </glossdef>
12148 </glossentry>
12149
12150 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
12151 <info>
12152 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."
12153 </info>
12154 <glossdef>
12155 <para role="glossdeffirst">
12156<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12157 A list of package name aliases that a package also provides.
12158 These aliases are useful for satisfying runtime dependencies
12159 of other packages both during the build and on the target
12160 (as specified by
12161 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
12162 <note>
12163 A package's own name is implicitly already in its
12164 <filename>RPROVIDES</filename> list.
12165 </note>
12166 </para>
12167
12168 <para>
12169 As with all package-controlling variables, you must always
12170 use the variable in conjunction with a package name override.
12171 Here is an example:
12172 <literallayout class='monospaced'>
12173 RPROVIDES_${PN} = "widget-abi-2"
12174 </literallayout>
12175 </para>
12176 </glossdef>
12177 </glossentry>
12178
12179 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
12180 <info>
12181 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."
12182 </info>
12183 <glossdef>
12184 <para role="glossdeffirst">
12185<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12186 A list of packages that extends the usability of a package
12187 being built.
12188 The package being built does not depend on this list of
12189 packages in order to successfully build, but rather
12190 uses them for extended usability.
12191 To specify runtime dependencies for packages, see the
12192 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
12193 variable.
12194 </para>
12195
12196 <para>
12197 The package manager will automatically install the
12198 <filename>RRECOMMENDS</filename> list of packages when
12199 installing the built package.
12200 However, you can prevent listed packages from being
12201 installed by using the
12202 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
12203 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
12204 and
12205 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
12206 variables.
12207 </para>
12208
12209 <para>
12210 Packages specified in
12211 <filename>RRECOMMENDS</filename> need not actually be
12212 produced.
12213 However, a recipe must exist that provides each package,
12214 either through the
12215 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
12216 or
12217 <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link>
12218 variables or the
12219 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>
12220 variable, or an error will occur during the build.
12221 If such a recipe does exist and the package is not produced,
12222 the build continues without error.
12223 </para>
12224
12225 <para>
12226 Because the <filename>RRECOMMENDS</filename> variable
12227 applies to packages being built, you should always attach
12228 an override to the variable to specify the particular
12229 package whose usability is being extended.
12230 For example, suppose you are building a development package
12231 that is extended to support wireless functionality.
12232 In this case, you would use the following:
12233 <literallayout class='monospaced'>
12234 RRECOMMENDS_${PN}-dev += "<replaceable>wireless_package_name</replaceable>"
12235 </literallayout>
12236 In the example, the package name
12237 (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
12238 must appear as it would in the
Brad Bishop316dfdd2018-06-25 12:45:53 -040012239 <filename>PACKAGES</filename> namespace before any renaming
12240 of the output package by classes such as
12241 <filename>debian.bbclass</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012242 </para>
12243
12244 <para>
12245 BitBake, which the OpenEmbedded build system uses, supports
12246 specifying versioned recommends.
12247 Although the syntax varies depending on the packaging
12248 format, BitBake hides these differences from you.
12249 Here is the general syntax to specify versions with
12250 the <filename>RRECOMMENDS</filename> variable:
12251 <literallayout class='monospaced'>
12252 RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
12253 </literallayout>
12254 For <filename>operator</filename>, you can specify the
12255 following:
12256 <literallayout class='monospaced'>
12257 =
12258 &lt;
12259 &gt;
12260 &lt;=
12261 &gt;=
12262 </literallayout>
12263 For example, the following sets up a recommend on version
12264 1.2 or greater of the package <filename>foo</filename>:
12265 <literallayout class='monospaced'>
12266 RRECOMMENDS_${PN} = "foo (>= 1.2)"
12267 </literallayout>
12268 </para>
12269 </glossdef>
12270 </glossentry>
12271
12272 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
12273 <info>
12274 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."
12275 </info>
12276 <glossdef>
12277 <para role="glossdeffirst">
12278<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12279 A list of packages replaced by a package.
12280 The package manager uses this variable to determine which
12281 package should be installed to replace other package(s)
12282 during an upgrade.
12283 In order to also have the other package(s) removed at the
12284 same time, you must add the name of the other
12285 package to the
12286 <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
12287 </para>
12288
12289 <para>
12290 As with all package-controlling variables, you must use
12291 this variable in conjunction with a package name
12292 override.
12293 Here is an example:
12294 <literallayout class='monospaced'>
12295 RREPLACES_${PN} = "<replaceable>other_package_being_replaced</replaceable>"
12296 </literallayout>
12297 </para>
12298
12299 <para>
12300 BitBake, which the OpenEmbedded build system uses, supports
12301 specifying versioned replacements.
12302 Although the syntax varies depending on the packaging
12303 format, BitBake hides these differences from you.
12304 Here is the general syntax to specify versions with
12305 the <filename>RREPLACES</filename> variable:
12306 <literallayout class='monospaced'>
12307 RREPLACES_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
12308 </literallayout>
12309 For <filename>operator</filename>, you can specify the
12310 following:
12311 <literallayout class='monospaced'>
12312 =
12313 &lt;
12314 &gt;
12315 &lt;=
12316 &gt;=
12317 </literallayout>
12318 For example, the following sets up a replacement using
12319 version 1.2 or greater of the package
12320 <filename>foo</filename>:
12321 <literallayout class='monospaced'>
12322 RREPLACES_${PN} = "foo (>= 1.2)"
12323 </literallayout>
12324 </para>
12325 </glossdef>
12326 </glossentry>
12327
12328 <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
12329 <info>
12330 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."
12331 </info>
12332 <glossdef>
12333 <para role="glossdeffirst">
12334<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12335 A list of additional packages that you can suggest for
12336 installation by the package manager at the time a package
12337 is installed.
12338 Not all package managers support this functionality.
12339 </para>
12340
12341 <para>
12342 As with all package-controlling variables, you must always
12343 use this variable in conjunction with a package name
12344 override.
12345 Here is an example:
12346 <literallayout class='monospaced'>
12347 RSUGGESTS_${PN} = "<replaceable>useful_package</replaceable> <replaceable>another_package</replaceable>"
12348 </literallayout>
12349 </para>
12350 </glossdef>
12351 </glossentry>
12352
12353 </glossdiv>
12354
12355 <glossdiv id='var-glossary-s'><title>S</title>
12356
12357 <glossentry id='var-S'><glossterm>S</glossterm>
12358 <info>
12359 S[doc] = "The location in the Build Directory where unpacked package source code resides."
12360 </info>
12361 <glossdef>
12362 <para role="glossdeffirst">
12363<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12364 The location in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050012365 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012366 where unpacked recipe source code resides.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012367 By default, this directory is
12368 <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>,
12369 where <filename>${BPN}</filename> is the base recipe name
12370 and <filename>${PV}</filename> is the recipe version.
12371 If the source tarball extracts the code to a directory
12372 named anything other than <filename>${BPN}-${PV}</filename>,
Brad Bishopd7bf8c12018-02-25 22:55:05 -050012373 or if the source code is fetched from an SCM such as
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012374 Git or Subversion, then you must set <filename>S</filename>
12375 in the recipe so that the OpenEmbedded build system
12376 knows where to find the unpacked source.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012377 </para>
12378
12379 <para>
12380 As an example, assume a
Brad Bishopd7bf8c12018-02-25 22:55:05 -050012381 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012382 top-level folder named <filename>poky</filename> and a
12383 default Build Directory at <filename>poky/build</filename>.
12384 In this case, the work directory the build system uses
12385 to keep the unpacked recipe for <filename>db</filename>
12386 is the following:
12387 <literallayout class='monospaced'>
12388 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
12389 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012390 The unpacked source code resides in the
12391 <filename>db-5.1.19</filename> folder.
12392 </para>
12393
12394 <para>
12395 This next example assumes a Git repository.
12396 By default, Git repositories are cloned to
12397 <filename>${WORKDIR}/git</filename> during
12398 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>.
12399 Since this path is different from the default value of
12400 <filename>S</filename>, you must set it specifically
12401 so the source can be located:
12402 <literallayout class='monospaced'>
12403 SRC_URI = "git://path/to/repo.git"
12404 S = "${WORKDIR}/git"
12405 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012406 </para>
12407 </glossdef>
12408 </glossentry>
12409
12410 <glossentry id='var-SANITY_REQUIRED_UTILITIES'><glossterm>SANITY_REQUIRED_UTILITIES</glossterm>
12411 <info>
12412 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."
12413 </info>
12414 <glossdef>
12415 <para role="glossdeffirst">
12416<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12417 Specifies a list of command-line utilities that should be
12418 checked for during the initial sanity checking process when
12419 running BitBake.
12420 If any of the utilities are not installed on the build host,
12421 then BitBake immediately exits with an error.
12422 </para>
12423 </glossdef>
12424 </glossentry>
12425
12426 <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
12427 <info>
12428 SANITY_TESTED_DISTROS[doc] = "A list of the host distribution identifiers that the build system has been tested against."
12429 </info>
12430 <glossdef>
12431 <para role="glossdeffirst">
12432<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12433 A list of the host distribution identifiers that the
12434 build system has been tested against.
12435 Identifiers consist of the host distributor ID
12436 followed by the release,
12437 as reported by the <filename>lsb_release</filename> tool
12438 or as read from <filename>/etc/lsb-release</filename>.
12439 Separate the list items with explicit newline
12440 characters (<filename>\n</filename>).
12441 If <filename>SANITY_TESTED_DISTROS</filename> is not empty
12442 and the current value of
12443 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
12444 does not appear in the list, then the build system reports
12445 a warning that indicates the current host distribution has
12446 not been tested as a build host.
12447 </para>
12448 </glossdef>
12449 </glossentry>
12450
12451 <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
12452 <info>
12453 SDK_ARCH[doc] = "The target architecture for the SDK."
12454 </info>
12455 <glossdef>
12456 <para role="glossdeffirst">
12457<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12458 The target architecture for the SDK.
12459 Typically, you do not directly set this variable.
12460 Instead, use
12461 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
12462 </para>
12463 </glossdef>
12464 </glossentry>
12465
12466 <glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>
12467 <info>
12468 SDK_DEPLOY[doc] = "The directory set up and used by the populate_sdk_base to which the SDK is deployed."
12469 </info>
12470 <glossdef>
12471 <para role="glossdeffirst">
12472<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12473 The directory set up and used by the
12474 <link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012475 class to which the SDK is deployed.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012476 The <filename>populate_sdk_base</filename> class defines
12477 <filename>SDK_DEPLOY</filename> as follows:
12478 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012479 SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012480 </literallayout>
12481 </para>
12482 </glossdef>
12483 </glossentry>
12484
12485 <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm>
12486 <info>
12487 SDK_DIR[doc] = "The parent directory used by the OpenEmbedded build system when creating SDK output."
12488 </info>
12489 <glossdef>
12490 <para role="glossdeffirst">
12491<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12492 The parent directory used by the OpenEmbedded build system
12493 when creating SDK output.
12494 The
12495 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12496 class defines the variable as follows:
12497 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012498 SDK_DIR = "${WORKDIR}/sdk"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012499 </literallayout>
12500 <note>
12501 The <filename>SDK_DIR</filename> directory is a
12502 temporary directory as it is part of
12503 <filename>WORKDIR</filename>.
12504 The final output directory is
12505 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
12506 </note>
12507 </para>
12508 </glossdef>
12509 </glossentry>
12510
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012511 <glossentry id='var-SDK_EXT_TYPE'><glossterm>SDK_EXT_TYPE</glossterm>
12512 <info>
12513 SDK_EXT_TYPE[doc] = "Controls whether or not shared state artifacts are copied into the extensible SDK."
12514 </info>
12515 <glossdef>
12516 <para role="glossdeffirst">
12517<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12518 Controls whether or not shared state artifacts are copied
12519 into the extensible SDK.
12520 The default value of "full" copies all of the required
12521 shared state artifacts into the extensible SDK.
12522 The value "minimal" leaves these artifacts out of the
12523 SDK.
12524 <note>
12525 If you set the variable to "minimal", you need to
12526 ensure
12527 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
12528 is set in the SDK's configuration to enable the
12529 artifacts to be fetched as needed.
12530 </note>
12531 </para>
12532 </glossdef>
12533 </glossentry>
12534
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012535 <glossentry id='var-SDK_HOST_MANIFEST'><glossterm>SDK_HOST_MANIFEST</glossterm>
12536 <info>
12537 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."
12538 </info>
12539 <glossdef>
12540 <para role="glossdeffirst">
12541<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12542 The manifest file for the host part of the SDK.
12543 This file lists all the installed packages that make up
Brad Bishop316dfdd2018-06-25 12:45:53 -040012544 the host part of the SDK.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012545 The file contains package information on a line-per-package
12546 basis as follows:
12547 <literallayout class='monospaced'>
12548 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
12549 </literallayout>
12550 </para>
12551
12552 <para>
12553 The
12554 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12555 class defines the manifest file as follows:
12556 <literallayout class='monospaced'>
12557 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"
12558 </literallayout>
12559 The location is derived using the
12560 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>
12561 and
12562 <link linkend='var-TOOLCHAIN_OUTPUTNAME'><filename>TOOLCHAIN_OUTPUTNAME</filename></link>
12563 variables.
12564 </para>
12565 </glossdef>
12566 </glossentry>
12567
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012568 <glossentry id='var-SDK_INCLUDE_PKGDATA'><glossterm>SDK_INCLUDE_PKGDATA</glossterm>
12569 <info>
12570 SDK_INCLUDE_PKGDATA[doc] = "When set to "1", specifies to include the packagedata for all recipes in the "world" target in the extensible SDK."
12571 </info>
12572 <glossdef>
12573 <para role="glossdeffirst">
12574<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12575 When set to "1", specifies to include the packagedata for
12576 all recipes in the "world" target in the extensible SDK.
12577 Including this data allows the
12578 <filename>devtool search</filename> command to find these
12579 recipes in search results, as well as allows the
12580 <filename>devtool add</filename> command to map
12581 dependencies more effectively.
12582 <note>
12583 Enabling the <filename>SDK_INCLUDE_PKGDATA</filename>
12584 variable significantly increases build time because
12585 all of world needs to be built.
12586 Enabling the variable also slightly increases the size
12587 of the extensible SDK.
12588 </note>
12589 </para>
12590 </glossdef>
12591 </glossentry>
12592
Patrick Williamsc0f7c042017-02-23 20:41:17 -060012593 <glossentry id='var-SDK_INCLUDE_TOOLCHAIN'><glossterm>SDK_INCLUDE_TOOLCHAIN</glossterm>
12594 <info>
12595 SDK_INCLUDE_TOOLCHAIN[doc] = "When set to "1", specifies to include the toolchain in the extensible SDK."
12596 </info>
12597 <glossdef>
12598 <para role="glossdeffirst">
12599<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12600 When set to "1", specifies to include the toolchain in the
12601 extensible SDK.
12602 Including the toolchain is useful particularly when
12603 <link linkend='var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></link>
12604 is set to "minimal" to keep the SDK reasonably small
12605 but you still want to provide a usable toolchain.
12606 For example, suppose you want to use the toolchain from an
Brad Bishopc342db32019-05-15 21:57:59 -040012607 IDE or from other tools and you do not
Patrick Williamsc0f7c042017-02-23 20:41:17 -060012608 want to perform additional steps to install the toolchain.
12609 </para>
12610
12611 <para>
12612 The <filename>SDK_INCLUDE_TOOLCHAIN</filename> variable
12613 defaults to "0" if <filename>SDK_EXT_TYPE</filename>
12614 is set to "minimal", and defaults to "1" if
12615 <filename>SDK_EXT_TYPE</filename> is set to "full".
12616 </para>
12617 </glossdef>
12618 </glossentry>
12619
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012620 <glossentry id='var-SDK_INHERIT_BLACKLIST'><glossterm>SDK_INHERIT_BLACKLIST</glossterm>
12621 <info>
12622 SDK_INHERIT_BLACKLIST[doc] = "A list of classes to remove from the INHERIT value globally within the extensible SDK configuration."
12623 </info>
12624 <glossdef>
12625 <para role="glossdeffirst">
12626<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12627 A list of classes to remove from the
12628 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
12629 value globally within the extensible SDK configuration.
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012630 The
12631 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12632 class sets the default value:
12633 <literallayout class='monospaced'>
12634 SDK_INHERIT_BLACKLIST ?= "buildhistory icecc"
12635 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012636 </para>
12637
12638 <para>
12639 Some classes are not generally applicable within
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012640 the extensible SDK context.
12641 You can use this variable to disable those classes.
12642 </para>
12643
12644 <para>
12645 For additional information on how to customize the
12646 extensible SDK's configuration, see the
12647 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12648 section in the Yocto Project Application Development and
12649 the Extensible Software Development Kit (eSDK) manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012650 </para>
12651 </glossdef>
12652 </glossentry>
12653
12654 <glossentry id='var-SDK_LOCAL_CONF_BLACKLIST'><glossterm>SDK_LOCAL_CONF_BLACKLIST</glossterm>
12655 <info>
12656 SDK_LOCAL_CONF_BLACKLIST[doc] = "A list of variables not allowed through from the build system configuration into the extensible SDK configuration."
12657 </info>
12658 <glossdef>
12659 <para role="glossdeffirst">
12660<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012661 A list of variables not allowed through from the
12662 OpenEmbedded build system configuration into the extensible
12663 SDK configuration.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012664 Usually, these are variables that are specific to the
12665 machine on which the build system is running and thus
12666 would be potentially problematic within the extensible SDK.
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012667 </para>
12668
12669 <para>By default,
12670 <filename>SDK_LOCAL_CONF_BLACKLIST</filename> is set in the
12671 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12672 class and excludes the following variables:
12673 <literallayout class='monospaced'>
12674 <link linkend='var-CONF_VERSION'>CONF_VERSION</link>
12675 <link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link>
12676 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'>BB_NUMBER_PARSE_THREADS</ulink>
12677 <link linkend='var-PARALLEL_MAKE'>PARALLEL_MAKE</link>
12678 <link linkend='var-PRSERV_HOST'>PRSERV_HOST</link>
12679 <link linkend='var-SSTATE_MIRRORS'>SSTATE_MIRRORS</link>
12680 <link linkend='var-DL_DIR'>DL_DIR</link>
12681 <link linkend='var-SSTATE_DIR'>SSTATE_DIR</link>
12682 <link linkend='var-TMPDIR'>TMPDIR</link>
12683 <link linkend='var-BB_SERVER_TIMEOUT'>BB_SERVER_TIMEOUT</link>
12684 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012685 </para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012686
12687 <para>
12688 For additional information on how to customize the
12689 extensible SDK's configuration, see the
12690 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12691 section in the Yocto Project Application Development and
12692 the Extensible Software Development Kit (eSDK) manual.
12693 </para>
12694
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012695 </glossdef>
12696 </glossentry>
12697
12698 <glossentry id='var-SDK_LOCAL_CONF_WHITELIST'><glossterm>SDK_LOCAL_CONF_WHITELIST</glossterm>
12699 <info>
12700 SDK_LOCAL_CONF_WHITELIST[doc] = "A list of variables allowed through from the build system configuration into the extensible SDK configuration."
12701 </info>
12702 <glossdef>
12703 <para role="glossdeffirst">
12704<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012705 A list of variables allowed through from the OpenEmbedded
12706 build system configuration into the extensible SDK
12707 configuration.
12708 By default, the list of variables is empty and is set in
12709 the
12710 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12711 class.
12712 </para>
12713
12714 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012715 This list overrides the variables specified using the
12716 <link linkend='var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></link>
12717 variable as well as any variables identified by automatic
12718 blacklisting due to the "/" character being found at the
12719 start of the value, which is usually indicative of being a
12720 path and thus might not be valid on the system where the
12721 SDK is installed.
12722 </para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012723
12724 <para>
12725 For additional information on how to customize the
12726 extensible SDK's configuration, see the
12727 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12728 section in the Yocto Project Application Development and
12729 the Extensible Software Development Kit (eSDK) manual.
12730 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012731 </glossdef>
12732 </glossentry>
12733
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012734 <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
12735 <info>
12736 SDK_NAME[doc] = "The base name for SDK output files."
12737 </info>
12738 <glossdef>
12739 <para role="glossdeffirst">
12740<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12741 The base name for SDK output files.
12742 The name is derived from the
12743 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
12744 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
12745 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
12746 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
12747 and
12748 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
12749 variables:
12750 <literallayout class='monospaced'>
12751 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
12752 </literallayout>
12753 </para>
12754 </glossdef>
12755 </glossentry>
12756
12757 <glossentry id='var-SDK_OS'><glossterm>SDK_OS</glossterm>
12758 <info>
12759 SDK_OS[doc] = "The operating system for which the SDK will be built."
12760 </info>
12761 <glossdef>
12762 <para role="glossdeffirst">
12763<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12764 Specifies the operating system for which the SDK
12765 will be built.
12766 The default value is the value of
12767 <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>.
12768 </para>
12769 </glossdef>
12770 </glossentry>
12771
12772 <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>
12773 <info>
12774 SDK_OUTPUT[doc] = "The location used by the OpenEmbedded build system when creating SDK output."
12775 </info>
12776 <glossdef>
12777 <para role="glossdeffirst">
12778<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12779 The location used by the OpenEmbedded build system when
12780 creating SDK output.
12781 The
12782 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12783 class defines the variable as follows:
12784 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012785 SDK_DIR = "${WORKDIR}/sdk"
12786 SDK_OUTPUT = "${SDK_DIR}/image"
12787 SDK_DEPLOY = "${DEPLOY_DIR}/sdk"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012788 </literallayout>
12789 <note>
12790 The <filename>SDK_OUTPUT</filename> directory is a
12791 temporary directory as it is part of
Brad Bishop316dfdd2018-06-25 12:45:53 -040012792 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
12793 by way of
12794 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012795 The final output directory is
12796 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
12797 </note>
12798 </para>
12799 </glossdef>
12800 </glossentry>
12801
12802 <glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm>
12803 <info>
12804 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."
12805 </info>
12806 <glossdef>
12807 <para role="glossdeffirst">
12808<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12809 Specifies a list of architectures compatible with
12810 the SDK machine.
12811 This variable is set automatically and should not
12812 normally be hand-edited.
12813 Entries are separated using spaces and listed in order
12814 of priority.
12815 The default value for
12816 <filename>SDK_PACKAGE_ARCHS</filename> is "all any noarch
12817 ${SDK_ARCH}-${SDKPKGSUFFIX}".
12818 </para>
12819 </glossdef>
12820 </glossentry>
12821
12822 <glossentry id='var-SDK_POSTPROCESS_COMMAND'><glossterm>SDK_POSTPROCESS_COMMAND</glossterm>
12823 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012824 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 -050012825 </info>
12826 <glossdef>
12827 <para role="glossdeffirst">
12828<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12829 Specifies a list of functions to call once the
Brad Bishop316dfdd2018-06-25 12:45:53 -040012830 OpenEmbedded build system creates the SDK.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012831 You can specify functions separated by semicolons:
12832 <literallayout class='monospaced'>
12833 SDK_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
12834 </literallayout>
12835 </para>
12836
12837 <para>
12838 If you need to pass an SDK path to a command within a
12839 function, you can use
12840 <filename>${SDK_DIR}</filename>, which points to
12841 the parent directory used by the OpenEmbedded build system
12842 when creating SDK output.
12843 See the
12844 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
12845 variable for more information.
12846 </para>
12847 </glossdef>
12848 </glossentry>
12849
12850 <glossentry id='var-SDK_PREFIX'><glossterm>SDK_PREFIX</glossterm>
12851 <info>
12852 SDK_PREFIX[doc] = "The toolchain binary prefix used for nativesdk recipes."
12853 </info>
12854 <glossdef>
12855 <para role="glossdeffirst">
12856<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012857 The toolchain binary prefix used for
12858 <filename>nativesdk</filename> recipes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012859 The OpenEmbedded build system uses the
12860 <filename>SDK_PREFIX</filename> value to set the
12861 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
12862 when building <filename>nativesdk</filename> recipes.
12863 The default value is "${SDK_SYS}-".
12864 </para>
12865 </glossdef>
12866 </glossentry>
12867
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012868 <glossentry id='var-SDK_RECRDEP_TASKS'><glossterm>SDK_RECRDEP_TASKS</glossterm>
12869 <info>
12870 SDK_RECRDEP_TASKS[doc] = "A list of shared state tasks added to the extensible SDK."
12871 </info>
12872 <glossdef>
12873 <para role="glossdeffirst">
12874<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12875 A list of shared state tasks added to the extensible SDK.
12876 By default, the following tasks are added:
12877 <literallayout class='monospaced'>
12878 do_populate_lic
12879 do_package_qa
12880 do_populate_sysroot
12881 do_deploy
12882 </literallayout>
12883 Despite the default value of "" for the
12884 <filename>SDK_RECRDEP_TASKS</filename> variable, the
12885 above four tasks are always added to the SDK.
12886 To specify tasks beyond these four, you need to use
12887 the <filename>SDK_RECRDEP_TASKS</filename> variable (e.g.
12888 you are defining additional tasks that are needed in
12889 order to build
12890 <link linkend='var-SDK_TARGETS'><filename>SDK_TARGETS</filename></link>).
12891 </para>
12892 </glossdef>
12893 </glossentry>
12894
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012895 <glossentry id='var-SDK_SYS'><glossterm>SDK_SYS</glossterm>
12896 <info>
12897 SDK_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the SDK will be built."
12898 </info>
12899 <glossdef>
12900 <para role="glossdeffirst">
12901<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12902 Specifies the system, including the architecture and the
12903 operating system, for which the SDK will be built.
12904 </para>
12905
12906 <para>
12907 The OpenEmbedded build system automatically sets this
12908 variable based on
12909 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
12910 <link linkend='var-SDK_VENDOR'><filename>SDK_VENDOR</filename></link>,
12911 and
12912 <link linkend='var-SDK_OS'><filename>SDK_OS</filename></link>.
12913 You do not need to set the <filename>SDK_SYS</filename>
12914 variable yourself.
12915 </para>
12916 </glossdef>
12917 </glossentry>
12918
12919 <glossentry id='var-SDK_TARGET_MANIFEST'><glossterm>SDK_TARGET_MANIFEST</glossterm>
12920 <info>
12921 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."
12922 </info>
12923 <glossdef>
12924 <para role="glossdeffirst">
12925<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12926 The manifest file for the target part of the SDK.
12927 This file lists all the installed packages that make up
12928 the target part of the SDK.
12929 The file contains package information on a line-per-package
12930 basis as follows:
12931 <literallayout class='monospaced'>
12932 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
12933 </literallayout>
12934 </para>
12935
12936 <para>
12937 The
12938 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12939 class defines the manifest file as follows:
12940 <literallayout class='monospaced'>
12941 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"
12942 </literallayout>
12943 The location is derived using the
12944 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>
12945 and
12946 <link linkend='var-TOOLCHAIN_OUTPUTNAME'><filename>TOOLCHAIN_OUTPUTNAME</filename></link>
12947 variables.
12948 </para>
12949 </glossdef>
12950 </glossentry>
12951
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012952 <glossentry id='var-SDK_TARGETS'><glossterm>SDK_TARGETS</glossterm>
12953 <info>
12954 SDK_TARGETS[doc] = "A list of targets to install from shared state as part of the standard or extensible SDK installation."
12955 </info>
12956 <glossdef>
12957 <para role="glossdeffirst">
12958<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12959 A list of targets to install from shared state as part of
12960 the standard or extensible SDK installation.
12961 The default value is "${PN}" (i.e. the image from which
12962 the SDK is built).
12963 </para>
12964
12965 <para>
12966 The <filename>SDK_TARGETS</filename> variable is an
12967 internal variable and typically would not be changed.
12968 </para>
12969 </glossdef>
12970 </glossentry>
12971
12972 <glossentry id='var-SDK_TITLE'><glossterm>SDK_TITLE</glossterm>
12973 <info>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080012974 SDK_TITLE[doc] = "The title to be printed when running the SDK installer."
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012975 </info>
12976 <glossdef>
12977 <para role="glossdeffirst">
12978<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080012979 The title to be printed when running the SDK installer.
12980 By default, this title is based on the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012981 <link linkend='var-DISTRO_NAME'><filename>DISTRO_NAME</filename></link>
12982 or
12983 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080012984 variable and is set in the
12985 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12986 class as follows:
12987 <literallayout class='monospaced'>
12988 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
12989 </literallayout>
12990 For the default distribution "poky",
12991 <filename>SDK_TITLE</filename> is set to
12992 "Poky (Yocto Project Reference Distro)".
12993 </para>
12994
12995 <para>
12996 For information on how to change this default title,
12997 see the
12998 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-changing-the-sdk-installer-title'>Changing the Extensible SDK Installer Title</ulink>"
12999 section in the Yocto Project Application Development and
13000 the Extensible Software Development Kit (eSDK) manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013001 </para>
13002 </glossdef>
13003 </glossentry>
13004
13005 <glossentry id='var-SDK_UPDATE_URL'><glossterm>SDK_UPDATE_URL</glossterm>
13006 <info>
13007 SDK_UPDATE_URL[doc] = "An optional URL for an update server for the extensible SDK."
13008 </info>
13009 <glossdef>
13010 <para role="glossdeffirst">
13011<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13012 An optional URL for an update server for the extensible
13013 SDK.
13014 If set, the value is used as the default update server when
13015 running <filename>devtool sdk-update</filename> within the
13016 extensible SDK.
13017 </para>
13018 </glossdef>
13019 </glossentry>
13020
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013021 <glossentry id='var-SDK_VENDOR'><glossterm>SDK_VENDOR</glossterm>
13022 <info>
13023 SDK_VENDOR[doc] = "Specifies the name of the SDK vendor."
13024 </info>
13025 <glossdef>
13026 <para role="glossdeffirst">
13027<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13028 Specifies the name of the SDK vendor.
13029 </para>
13030 </glossdef>
13031 </glossentry>
13032
13033 <glossentry id='var-SDK_VERSION'><glossterm>SDK_VERSION</glossterm>
13034 <info>
13035 SDK_VERSION[doc] = "Specifies the version for the SDK."
13036 </info>
13037 <glossdef>
13038 <para role="glossdeffirst">
13039<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13040 Specifies the version of the SDK.
13041 The distribution configuration file (e.g.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013042 <filename>/meta-poky/conf/distro/poky.conf</filename>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013043 defines the <filename>SDK_VERSION</filename> as follows:
13044 <literallayout class='monospaced'>
Brad Bishop19323692019-04-05 15:28:33 -040013045 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013046 </literallayout>
13047 </para>
13048
13049 <para>
13050 For additional information, see the
13051 <link linkend='var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></link>
13052 and
13053 <link linkend='var-DATE'><filename>DATE</filename></link>
13054 variables.
13055 </para>
13056 </glossdef>
13057 </glossentry>
13058
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080013059 <glossentry id='var-SDKEXTPATH'><glossterm>SDKEXTPATH</glossterm>
13060 <info>
13061 SDKEXTPATH[doc] = "The default installation directory for the extensible SDK."
13062 </info>
13063 <glossdef>
13064 <para role="glossdeffirst">
13065<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13066 The default installation directory for the Extensible SDK.
13067 By default, this directory is based on the
13068 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
13069 variable and is set in the
13070 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
13071 class as follows:
13072 <literallayout class='monospaced'>
13073 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
13074 </literallayout>
13075 For the default distribution "poky", the
13076 <filename>SDKEXTPATH</filename> is set to "poky_sdk".
13077 </para>
13078
13079 <para>
13080 For information on how to change this default directory,
13081 see the
13082 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-changing-the-default-sdk-installation-directory'>Changing the Default SDK Installation Directory</ulink>"
13083 section in the Yocto Project Application Development and
13084 the Extensible Software Development Kit (eSDK) manual.
13085 </para>
13086 </glossdef>
13087 </glossentry>
13088
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013089 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
13090 <info>
13091 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'."
13092 </info>
13093 <glossdef>
13094 <para role="glossdeffirst">
13095<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13096 Equivalent to
13097 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
13098 However, this variable applies to the SDK generated from an
13099 image using the following command:
13100 <literallayout class='monospaced'>
13101 $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
13102 </literallayout>
13103 </para>
13104 </glossdef>
13105 </glossentry>
13106
13107 <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
13108 <info>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013109 SDKMACHINE[doc] = "Specifies the architecture (i.e. i686 or x86_64) for which to build SDK items."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013110 </info>
13111 <glossdef>
13112 <para role="glossdeffirst">
13113<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013114 The machine for which the SDK is built.
13115 In other words, the SDK is built such that it
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013116 runs on the target you specify with the
13117 <filename>SDKMACHINE</filename> value.
13118 The value points to a corresponding
13119 <filename>.conf</filename> file under
13120 <filename>conf/machine-sdk/</filename>.
13121 </para>
13122
13123 <para>
13124 You can use "i686" and "x86_64" as possible values
13125 for this variable. The variable defaults to "i686"
13126 and is set in the local.conf file in the Build Directory.
13127 <literallayout class='monospaced'>
13128 SDKMACHINE ?= "i686"
13129 </literallayout>
13130 <note>
13131 You cannot set the <filename>SDKMACHINE</filename>
13132 variable in your distribution configuration file.
13133 If you do, the configuration will not take affect.
13134 </note>
13135 </para>
13136 </glossdef>
13137 </glossentry>
13138
13139 <glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>
13140 <info>
13141 SDKPATH[doc] = "Defines the path offered to the user for installation of the SDK that is generated by the OpenEmbedded build system."
13142 </info>
13143 <glossdef>
13144 <para role="glossdeffirst">
13145<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13146 Defines the path offered to the user for installation
13147 of the SDK that is generated by the OpenEmbedded build
13148 system.
13149 The path appears as the default location for installing
13150 the SDK when you run the SDK's installation script.
13151 You can override the offered path when you run the
13152 script.
13153 </para>
13154 </glossdef>
13155 </glossentry>
13156
13157 <glossentry id='var-SDKTARGETSYSROOT'><glossterm>SDKTARGETSYSROOT</glossterm>
13158 <info>
13159 SDKTARGETSYSROOT[doc] = "Full path to the sysroot used for cross-compilation within an SDK as it will be when installed into the default SDKPATH."
13160 </info>
13161 <glossdef>
13162 <para role="glossdeffirst">
13163<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13164 The full path to the sysroot used for cross-compilation
13165 within an SDK as it will be when installed into the
13166 default
13167 <link linkend='var-SDKPATH'><filename>SDKPATH</filename></link>.
13168 </para>
13169 </glossdef>
13170 </glossentry>
13171
13172 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
13173 <info>
13174 SECTION[doc] = "The section in which packages should be categorized. Package management utilities can make use of this variable."
13175 </info>
13176 <glossdef>
13177 <para role="glossdeffirst">
13178<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13179 The section in which packages should be categorized.
13180 Package management utilities can make use of this variable.
13181 </para>
13182 </glossdef>
13183 </glossentry>
13184
13185 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
13186 <info>
13187 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."
13188 </info>
13189 <glossdef>
13190 <para role="glossdeffirst">
13191<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13192 Specifies the optimization flags passed to the C compiler
13193 when building for the target.
13194 The flags are passed through the default value of the
13195 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
13196 variable.
13197 </para>
13198
13199 <para>
13200 The <filename>SELECTED_OPTIMIZATION</filename> variable
13201 takes the value of
13202 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
13203 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
13204 If that is the case, the value of
13205 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
13206 </para>
13207 </glossdef>
13208 </glossentry>
13209
13210 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
13211 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013212 SERIAL_CONSOLE[doc] = "Defines the serial consoles (TTYs) to enable using getty."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013213 </info>
13214 <glossdef>
13215 <para role="glossdeffirst">
13216<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040013217 Defines a serial console (TTY) to enable using
13218 <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013219 Provide a value that specifies the baud rate followed by
13220 the TTY device name separated by a space.
13221 You cannot specify more than one TTY device:
13222 <literallayout class='monospaced'>
13223 SERIAL_CONSOLE = "115200 ttyS0"
13224 </literallayout>
13225 <note>
13226 The <filename>SERIAL_CONSOLE</filename> variable
13227 is deprecated.
13228 Please use the
13229 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
13230 variable.
13231 </note>
13232 </para>
13233 </glossdef>
13234 </glossentry>
13235
13236 <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
13237 <info>
13238 SERIAL_CONSOLES[doc] = "Defines the serial consoles (TTYs) to enable using getty."
13239 </info>
13240 <glossdef>
13241 <para role="glossdeffirst">
13242<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040013243 Defines a serial console (TTY) to enable using
13244 <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013245 Provide a value that specifies the baud rate followed by
13246 the TTY device name separated by a semicolon.
13247 Use spaces to separate multiple devices:
13248 <literallayout class='monospaced'>
13249 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
13250 </literallayout>
13251 </para>
13252 </glossdef>
13253 </glossentry>
13254
13255 <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
13256 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060013257 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 -050013258 </info>
13259 <glossdef>
13260 <para role="glossdeffirst">
13261<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060013262 Specifies serial consoles, which must be listed in
13263 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>,
13264 to check against <filename>/proc/console</filename>
13265 before enabling them using getty.
13266 This variable allows aliasing in the format:
13267 &lt;device&gt;:&lt;alias&gt;.
13268 If a device was listed as "sclp_line0"
13269 in <filename>/dev/</filename> and "ttyS0" was listed
13270 in <filename>/proc/console</filename>, you would do the
13271 following:
13272 <literallayout class='monospaced'>
13273 SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0"
13274 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013275 This variable is currently only supported with SysVinit
13276 (i.e. not with systemd).
13277 </para>
13278 </glossdef>
13279 </glossentry>
13280
13281 <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
13282 <info>
13283 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."
13284 </info>
13285 <glossdef>
13286 <para role="glossdeffirst">
13287<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13288 A list of recipe dependencies that should not be used to
13289 determine signatures of tasks from one recipe when they
13290 depend on tasks from another recipe.
13291 For example:
13292 <literallayout class='monospaced'>
13293 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
13294 </literallayout>
13295 </para>
13296
13297 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013298 In the previous example, <filename>intone</filename>
13299 depends on <filename>mplayer2</filename>.
13300 </para>
13301
13302 <para>
13303 You can use the special token <filename>"*"</filename> on
13304 the left-hand side of the dependency to match all
13305 recipes except the one on the right-hand side.
13306 Here is an example:
13307 <literallayout class='monospaced'>
13308 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
13309 </literallayout>
13310 </para>
13311
13312 <para>
13313 In the previous example, all recipes except
13314 <filename>quilt-native</filename> ignore task
13315 signatures from the <filename>quilt-native</filename>
13316 recipe when determining their task signatures.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013317 </para>
13318
13319 <para>
13320 Use of this variable is one mechanism to remove dependencies
13321 that affect task signatures and thus force rebuilds when a
13322 recipe changes.
13323 <note><title>Caution</title>
13324 If you add an inappropriate dependency for a recipe
13325 relationship, the software might break during
13326 runtime if the interface of the second recipe was
13327 changed after the first recipe had been built.
13328 </note>
13329 </para>
13330 </glossdef>
13331 </glossentry>
13332
13333 <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
13334 <info>
13335 SIGGEN_EXCLUDERECIPES_ABISAFE[doc] = "A list of recipes that are completely stable and will never change."
13336 </info>
13337 <glossdef>
13338 <para role="glossdeffirst">
13339<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13340 A list of recipes that are completely stable and will
13341 never change.
13342 The ABI for the recipes in the list are presented by
13343 output from the tasks run to build the recipe.
13344 Use of this variable is one way to remove dependencies from
13345 one recipe on another that affect task signatures and
13346 thus force rebuilds when the recipe changes.
13347 <note><title>Caution</title>
13348 If you add an inappropriate variable to this list,
13349 the software might break at runtime if the
13350 interface of the recipe was changed after the other
13351 had been built.
13352 </note>
13353 </para>
13354 </glossdef>
13355 </glossentry>
13356
13357 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
13358 <info>
13359 SITEINFO_BITS[doc] = "Specifies the number of bits for the target system CPU."
13360 </info>
13361 <glossdef>
13362 <para role="glossdeffirst">
13363<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13364 Specifies the number of bits for the target system CPU.
13365 The value should be either "32" or "64".
13366 </para>
13367 </glossdef>
13368 </glossentry>
13369
13370 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
13371 <info>
13372 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'."
13373 </info>
13374 <glossdef>
13375 <para role="glossdeffirst">
13376<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13377 Specifies the endian byte order of the target system.
13378 The value should be either "le" for little-endian or "be" for big-endian.
13379 </para>
13380 </glossdef>
13381 </glossentry>
13382
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013383 <glossentry id='var-SKIP_FILEDEPS'><glossterm>SKIP_FILEDEPS</glossterm>
13384 <info>
13385 SKIP_FILEDEPS[doc] = "Enables you to remove all files from
13386 the "Provides" section of an RPM package."
13387 </info>
13388 <glossdef>
13389 <para role="glossdeffirst">
13390<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13391 Enables removal of all files from the "Provides" section of
13392 an RPM package.
13393 Removal of these files is required for packages containing
13394 prebuilt binaries and libraries such as
13395 <filename>libstdc++</filename> and
13396 <filename>glibc</filename>.
13397 </para>
13398
13399 <para>
13400 To enable file removal, set the variable to "1" in your
13401 <filename>conf/local.conf</filename> configuration file
13402 in your:
Brad Bishopd7bf8c12018-02-25 22:55:05 -050013403 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013404 <literallayout class='monospaced'>
13405 SKIP_FILEDEPS = "1"
13406 </literallayout>
13407 </para>
13408 </glossdef>
13409 </glossentry>
13410
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013411 <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
13412 <info>
13413 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."
13414 </info>
13415 <glossdef>
13416 <para role="glossdeffirst">
13417<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13418 Groups together machines based upon the same family
13419 of SOC (System On Chip).
13420 You typically set this variable in a common
13421 <filename>.inc</filename> file that you include in the
13422 configuration files of all the machines.
13423 <note>
13424 You must include
13425 <filename>conf/machine/include/soc-family.inc</filename>
13426 for this variable to appear in
13427 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
13428 </note>
13429 </para>
13430 </glossdef>
13431 </glossentry>
13432
13433 <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
13434 <info>
13435 SOLIBS[doc] = "Defines the suffix for shared libraries used on the target platform."
13436 </info>
13437 <glossdef>
13438 <para role="glossdeffirst">
13439<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13440 Defines the suffix for shared libraries used on the
13441 target platform.
13442 By default, this suffix is ".so.*" for all Linux-based
13443 systems and is defined in the
13444 <filename>meta/conf/bitbake.conf</filename> configuration
13445 file.
13446 </para>
13447
13448 <para>
13449 You will see this variable referenced in the default values
13450 of <filename>FILES_${PN}</filename>.
13451 </para>
13452 </glossdef>
13453 </glossentry>
13454
13455 <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
13456 <info>
13457 SOLIBSDEV[doc] = "Defines the suffix for the development symbolic link (symlink) for shared libraries on the target platform."
13458 </info>
13459 <glossdef>
13460 <para role="glossdeffirst">
13461<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13462 Defines the suffix for the development symbolic link
13463 (symlink) for shared libraries on the target platform.
13464 By default, this suffix is ".so" for Linux-based
13465 systems and is defined in the
13466 <filename>meta/conf/bitbake.conf</filename> configuration
13467 file.
13468 </para>
13469
13470 <para>
13471 You will see this variable referenced in the default values
13472 of <filename>FILES_${PN}-dev</filename>.
13473 </para>
13474 </glossdef>
13475 </glossentry>
13476
13477 <glossentry id='var-SOURCE_MIRROR_FETCH'><glossterm>SOURCE_MIRROR_FETCH</glossterm>
13478 <info>
13479 SOURCE_MIRROR_FETCH[doc] = "Set as part of a source mirror generation script to skip COMPATIBLE_MACHINE and COMPATIBLE_HOST checks."
13480 </info>
13481 <glossdef>
13482 <para role="glossdeffirst">
13483<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13484 When you are fetching files to create a mirror of sources
13485 (i.e. creating a source mirror), setting
13486 <filename>SOURCE_MIRROR_FETCH</filename> to "1" in your
13487 <filename>local.conf</filename> configuration file ensures
13488 the source for all recipes are fetched regardless of
13489 whether or not a recipe is compatible with the
13490 configuration.
13491 A recipe is considered incompatible with the currently
13492 configured machine when either or both the
13493 <link linkend='var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></link>
13494 variable and
13495 <link linkend='var-COMPATIBLE_HOST'><filename>COMPATIBLE_HOST</filename></link>
13496 variables specify compatibility with a machine other
13497 than that of the current machine or host.
13498 <note><title>Warning</title>
13499 Do not set the
13500 <filename>SOURCE_MIRROR_FETCH</filename> variable
13501 unless you are creating a source mirror.
13502 In other words, do not set the variable during a
13503 normal build.
13504 </note>
13505 </para>
13506 </glossdef>
13507 </glossentry>
13508
13509 <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm>
13510 <info>
13511 SOURCE_MIRROR_URL[doc] = "URL to source mirror that will be used before fetching from original SRC_URI."
13512 </info>
13513 <glossdef>
13514 <para role="glossdeffirst">
13515<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13516 Defines your own
13517 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
13518 from which to first fetch source before attempting to fetch
13519 from the upstream specified in
13520 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
13521 </para>
13522
13523 <para>
13524 To use this variable, you must globally inherit the
13525 <link linkend='ref-classes-own-mirrors'><filename>own-mirrors</filename></link>
13526 class and then provide the URL to your mirrors.
13527 Here is the general syntax:
13528 <literallayout class='monospaced'>
13529 INHERIT += "own-mirrors"
13530 SOURCE_MIRROR_URL = "http://<replaceable>example</replaceable>.com/<replaceable>my_source_mirror</replaceable>"
13531 </literallayout>
13532 <note>
13533 You can specify only a single URL in
13534 <filename>SOURCE_MIRROR_URL</filename>.
13535 </note>
13536 </para>
13537 </glossdef>
13538 </glossentry>
13539
13540 <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>
13541 <info>
13542 SPDXLICENSEMAP[doc] = "Maps commonly used license names to their SPDX counterparts found in meta/files/common-licenses/."
13543 </info>
13544 <glossdef>
13545 <para role="glossdeffirst">
13546<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13547 Maps commonly used license names to their SPDX counterparts
13548 found in <filename>meta/files/common-licenses/</filename>.
13549 For the default <filename>SPDXLICENSEMAP</filename>
13550 mappings, see the
13551 <filename>meta/conf/licenses.conf</filename> file.
13552 </para>
13553
13554 <para>
13555 For additional information, see the
13556 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
13557 variable.
13558 </para>
13559 </glossdef>
13560 </glossentry>
13561
13562 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
13563 <info>
13564 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."
13565 </info>
13566 <glossdef>
13567 <para role="glossdeffirst">
13568<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13569 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
13570 OpenEmbedded build system to create variants of recipes or packages.
13571 The list specifies the prefixes to strip off during certain circumstances
13572 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
13573 </para>
13574 </glossdef>
13575 </glossentry>
13576
Brad Bishop316dfdd2018-06-25 12:45:53 -040013577 <glossentry id='var-SPL_BINARY'><glossterm>SPL_BINARY</glossterm>
13578 <info>
13579 SPL_BINARY[doc] = "The file type of the Secondary Program Loader (SPL)."
13580 </info>
13581 <glossdef>
13582 <para role="glossdeffirst">
13583<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13584 The file type for the Secondary Program Loader (SPL).
13585 Some devices use an SPL from which to boot (e.g. the
13586 BeagleBone development board).
13587 For such cases, you can declare the file type of the
13588 SPL binary in the <filename>u-boot.inc</filename> include
13589 file, which is used in the U-Boot recipe.
13590 </para>
13591
13592 <para>
13593 The SPL file type is set to "null" by default in the
13594 <filename>u-boot.inc</filename> file as follows:
13595 <literallayout class='monospaced'>
13596 # Some versions of u-boot build an SPL (Second Program Loader) image that
13597 # should be packaged along with the u-boot binary as well as placed in the
13598 # deploy directory. For those versions they can set the following variables
13599 # to allow packaging the SPL.
13600 SPL_BINARY ?= ""
13601 SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"
13602 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
13603 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"
13604 </literallayout>
13605 The <filename>SPL_BINARY</filename> variable helps form
13606 various <filename>SPL_*</filename> variables used by
13607 the OpenEmbedded build system.
13608 </para>
13609
13610 <para>
13611 See the BeagleBone machine configuration example in the
13612 "<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>"
13613 section in the Yocto Project Board Support Package
13614 Developer's Guide for additional information.
13615 </para>
13616 </glossdef>
13617 </glossentry>
13618
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013619 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
13620 <info>
13621 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."
13622 </info>
13623 <glossdef>
13624 <para role="glossdeffirst">
13625<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13626 The list of source files - local or remote.
13627 This variable tells the OpenEmbedded build system which bits
13628 to pull in for the build and how to pull them in.
13629 For example, if the recipe or append file only needs to
13630 fetch a tarball from the Internet, the recipe or
13631 append file uses a single <filename>SRC_URI</filename>
13632 entry.
13633 On the other hand, if the recipe or append file needs to
13634 fetch a tarball, apply two patches, and include a custom
13635 file, the recipe or append file would include four
13636 instances of the variable.
13637 </para>
13638
13639 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013640 The following list explains the available URI protocols.
13641 URI protocols are highly dependent on particular BitBake
13642 Fetcher submodules.
13643 Depending on the fetcher BitBake uses, various URL
13644 parameters are employed.
13645 For specifics on the supported Fetchers, see the
13646 "<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"
13647 section in the BitBake User Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013648 <itemizedlist>
13649 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
13650 Fetches files, which are usually files shipped with
13651 the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050013652 <link linkend='metadata'>Metadata</link>,
Brad Bishop316dfdd2018-06-25 12:45:53 -040013653 from the local machine (e.g.
13654 <ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>patch</ulink>
13655 files).
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013656 The path is relative to the
13657 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
13658 variable.
13659 Thus, the build system searches, in order, from the
13660 following directories, which are assumed to be a
13661 subdirectories of the directory in which the
13662 recipe file (<filename>.bb</filename>) or
13663 append file (<filename>.bbappend</filename>)
13664 resides:
13665 <itemizedlist>
13666 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
13667 The base recipe name without any special
13668 suffix or version numbers.
13669 </para></listitem>
13670 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
13671 <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
13672 The base recipe name and version but without
13673 any special package name suffix.
13674 </para></listitem>
13675 <listitem><para><emphasis>files -</emphasis>
13676 Files within a directory, which is named
13677 <filename>files</filename> and is also
13678 alongside the recipe or append file.
13679 </para></listitem>
13680 </itemizedlist>
13681 <note>
13682 If you want the build system to pick up files
13683 specified through a
13684 <filename>SRC_URI</filename>
13685 statement from your append file, you need to be
13686 sure to extend the
13687 <filename>FILESPATH</filename>
13688 variable by also using the
13689 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
13690 variable from within your append file.
13691 </note>
13692 </para></listitem>
13693 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
13694 Bazaar revision control repository.</para></listitem>
13695 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
13696 Git revision control repository.</para></listitem>
13697 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
13698 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
13699 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
13700 a repo (Git) repository.</para></listitem>
13701 <listitem><para><emphasis><filename>ccrc://</filename> -</emphasis>
13702 Fetches files from a ClearCase repository.
13703 </para></listitem>
13704 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
13705 the Internet using <filename>http</filename>.</para></listitem>
13706 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
13707 from the Internet using <filename>https</filename>.</para></listitem>
13708 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
13709 from the Internet using <filename>ftp</filename>.</para></listitem>
13710 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
13711 a CVS revision control repository.</para></listitem>
13712 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
13713 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
13714 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
13715 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
13716 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
13717 a secure shell.</para></listitem>
13718 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
13719 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
Brad Bishopc342db32019-05-15 21:57:59 -040013720 <listitem><para><emphasis><filename>npm://</filename> -</emphasis> Fetches JavaScript
13721 modules from a registry.
13722 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013723 </itemizedlist>
13724 </para>
13725
13726 <para>
13727 Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
13728 Here are standard options:
13729 <itemizedlist>
13730 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
13731 the patch or not.
13732 The default action is to apply the patch.</para></listitem>
13733 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
13734 striplevel to use when applying the patch.
13735 The default level is 1.</para></listitem>
13736 <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
13737 the directory in which the patch should be applied.
13738 The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
13739 </para></listitem>
13740 </itemizedlist>
13741 </para>
13742
13743 <para>
13744 Here are options specific to recipes building code from a revision control system:
13745 <itemizedlist>
13746 <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
13747 Apply the patch only if
13748 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
13749 is equal to or greater than <filename>mindate</filename>.
13750 </para></listitem>
13751 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
13752 Apply the patch only if <filename>SRCDATE</filename>
Andrew Geissler5fa08482019-03-20 15:58:14 -050013753 is not later than <filename>maxdate</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013754 </para></listitem>
13755 <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
13756 Apply the patch only if <filename>SRCREV</filename>
13757 is equal to or greater than <filename>minrev</filename>.
13758 </para></listitem>
13759 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
13760 Apply the patch only if <filename>SRCREV</filename>
13761 is not later than <filename>maxrev</filename>.
13762 </para></listitem>
13763 <listitem><para><emphasis><filename>rev</filename> -</emphasis>
13764 Apply the patch only if <filename>SRCREV</filename>
13765 is equal to <filename>rev</filename>.
13766 </para></listitem>
13767 <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
13768 Apply the patch only if <filename>SRCREV</filename>
13769 is not equal to <filename>rev</filename>.
13770 </para></listitem>
13771 </itemizedlist>
13772 </para>
13773
13774 <para>
13775 Here are some additional options worth mentioning:
13776 <itemizedlist>
13777 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
13778 whether or not to unpack the file if it is an archive.
13779 The default action is to unpack the file.</para></listitem>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013780 <listitem><para><emphasis><filename>destsuffix</filename> -</emphasis> Places the file
13781 (or extracts its contents) into the specified
13782 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
13783 when the Git fetcher is used.
13784 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013785 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
13786 (or extracts its contents) into the specified
Brad Bishop316dfdd2018-06-25 12:45:53 -040013787 subdirectory of <filename>WORKDIR</filename>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013788 when the local (<filename>file://</filename>)
13789 fetcher is used.
13790 </para></listitem>
13791 <listitem><para><emphasis><filename>localdir</filename> -</emphasis> Places the file
13792 (or extracts its contents) into the specified
Brad Bishop316dfdd2018-06-25 12:45:53 -040013793 subdirectory of <filename>WORKDIR</filename> when
13794 the CVS fetcher is used.
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013795 </para></listitem>
13796 <listitem><para><emphasis><filename>subpath</filename> -</emphasis>
13797 Limits the checkout to a specific subpath of the
13798 tree when using the Git fetcher is used.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013799 </para></listitem>
13800 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
13801 name to be used for association with <filename>SRC_URI</filename> checksums
13802 when you have more than one file specified in <filename>SRC_URI</filename>.
13803 </para></listitem>
13804 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
13805 the filename used when storing the downloaded file.</para></listitem>
13806 </itemizedlist>
13807 </para>
13808 </glossdef>
13809 </glossentry>
13810
13811 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
13812 <info>
13813 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."
13814 </info>
13815 <glossdef>
13816 <para role="glossdeffirst">
13817<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13818 By default, the OpenEmbedded build system automatically detects whether
13819 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
13820 contains files that are machine-specific.
13821 If so, the build system automatically changes
13822 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
13823 Setting this variable to "0" disables this behavior.
13824 </para>
13825 </glossdef>
13826 </glossentry>
13827
13828 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
13829 <info>
13830 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)."
13831 </info>
13832 <glossdef>
13833 <para role="glossdeffirst">
13834<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13835 The date of the source code used to build the package.
13836 This variable applies only if the source was fetched from a Source Code Manager (SCM).
13837 </para>
13838 </glossdef>
13839 </glossentry>
13840
13841 <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
13842 <info>
13843 SRCPV[doc] = "Returns the version string of the current package. This string is used to help define the value of PV."
13844 </info>
13845 <glossdef>
13846 <para role="glossdeffirst">
13847<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13848 Returns the version string of the current package.
13849 This string is used to help define the value of
13850 <link linkend='var-PV'><filename>PV</filename></link>.
13851 </para>
13852
13853 <para>
13854 The <filename>SRCPV</filename> variable is defined in the
13855 <filename>meta/conf/bitbake.conf</filename> configuration
13856 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050013857 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013858 as follows:
13859 <literallayout class='monospaced'>
13860 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
13861 </literallayout>
13862 </para>
13863
13864 <para>
13865 Recipes that need to define <filename>PV</filename> do so
13866 with the help of the <filename>SRCPV</filename>.
13867 For example, the <filename>ofono</filename> recipe
13868 (<filename>ofono_git.bb</filename>) located in
13869 <filename>meta/recipes-connectivity</filename> in the
13870 Source Directory defines <filename>PV</filename> as
13871 follows:
13872 <literallayout class='monospaced'>
13873 PV = "0.12-git${SRCPV}"
13874 </literallayout>
13875 </para>
13876 </glossdef>
13877 </glossentry>
13878
13879 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
13880 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013881 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 -050013882 </info>
13883 <glossdef>
13884 <para role="glossdeffirst">
13885<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13886 The revision of the source code used to build the package.
Brad Bishop316dfdd2018-06-25 12:45:53 -040013887 This variable applies to Subversion, Git, Mercurial, and
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013888 Bazaar only.
13889 Note that if you want to build a fixed revision and you
13890 want to avoid performing a query on the remote repository
13891 every time BitBake parses your recipe, you should specify
13892 a <filename>SRCREV</filename> that is a
13893 full revision identifier and not just a tag.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050013894 <note>
13895 For information on limitations when inheriting the
13896 latest revision of software using
13897 <filename>SRCREV</filename>, see the
13898 <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link>
13899 variable description and the
13900 "<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 -050013901 section, which is in the Yocto Project Development
13902 Tasks Manual.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050013903 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013904 </para>
13905
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013906 </glossdef>
13907 </glossentry>
13908
13909 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
13910 <info>
13911 SSTATE_DIR[doc] = "The directory for the shared state cache."
13912 </info>
13913 <glossdef>
13914 <para role="glossdeffirst">
13915<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13916 The directory for the shared state cache.
13917 </para>
13918 </glossdef>
13919 </glossentry>
13920
13921 <glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm>
13922 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013923 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 -050013924 </info>
13925 <glossdef>
13926 <para role="glossdeffirst">
13927<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13928 If set to "1", allows fetches from
13929 mirrors that are specified in
13930 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013931 to work even when fetching from the network is
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013932 disabled by setting <filename>BB_NO_NETWORK</filename>
13933 to "1".
13934 Using the
13935 <filename>SSTATE_MIRROR_ALLOW_NETWORK</filename>
13936 variable is useful if you have set
13937 <filename>SSTATE_MIRRORS</filename> to point to an
13938 internal server for your shared state cache, but
13939 you want to disable any other fetching from the network.
13940 </para>
13941 </glossdef>
13942 </glossentry>
13943
13944 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
13945 <info>
13946 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."
13947 </info>
13948 <glossdef>
13949 <para role="glossdeffirst">
13950<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13951 Configures the OpenEmbedded build system to search other
13952 mirror locations for prebuilt cache data objects before
13953 building out the data.
13954 This variable works like fetcher
13955 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
13956 and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
13957 and points to the cache locations to check for the shared
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080013958 state (sstate) objects.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013959 </para>
13960
13961 <para>
13962 You can specify a filesystem directory or a remote URL such
13963 as HTTP or FTP.
13964 The locations you specify need to contain the shared state
13965 cache (sstate-cache) results from previous builds.
13966 The sstate-cache you point to can also be from builds on
13967 other machines.
13968 </para>
13969
13970 <para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080013971 When pointing to sstate build artifacts on another machine
13972 that uses a different GCC version for native builds,
13973 you must configure <filename>SSTATE_MIRROR</filename>
13974 with a regular expression that maps local search paths
13975 to server paths.
13976 The paths need to take into account
13977 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
13978 set by the
13979 <link linkend='ref-classes-uninative'><filename>uninative</filename></link>
13980 class.
13981 For example, the following maps the local search path
13982 <filename>universal-4.9</filename> to the server-provided
13983 path <replaceable>server_url_sstate_path</replaceable>:
13984 <literallayout class='monospaced'>
13985 SSTATE_MIRRORS ?= file://universal-4.9/(.*) http://<replaceable>server_url_sstate_path</replaceable>/universal-4.8/\1 \n
13986 </literallayout>
13987 </para>
13988
13989 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013990 If a mirror uses the same structure as
13991 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
13992 you need to add
13993 "PATH" at the end as shown in the examples below.
13994 The build system substitutes the correct path within the
13995 directory structure.
13996 <literallayout class='monospaced'>
13997 SSTATE_MIRRORS ?= "\
Patrick Williamsc0f7c042017-02-23 20:41:17 -060013998 file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH;downloadfilename=PATH \n \
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013999 file://.* file:///<replaceable>some-local-dir</replaceable>/sstate/PATH"
14000 </literallayout>
14001 </para>
14002 </glossdef>
14003 </glossentry>
14004
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014005 <glossentry id='var-SSTATE_SCAN_FILES'><glossterm>SSTATE_SCAN_FILES</glossterm>
14006 <info>
14007 SSTATE_SCAN_FILES[doc] = "Controls the list of files the OpenEmbedded build system scans for hardcoded installation paths."
14008 </info>
14009 <glossdef>
14010 <para role="glossdeffirst">
14011<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14012 Controls the list of files the OpenEmbedded build system
14013 scans for hardcoded installation paths. The variable uses a
14014 space-separated list of filenames (not paths) with standard
14015 wildcard characters allowed.
14016 </para>
14017
14018 <para>
14019 During a build, the OpenEmbedded build system creates a
14020 shared state (sstate) object during the first stage of
14021 preparing the sysroots. That object is scanned for
14022 hardcoded paths for original installation locations.
14023 The list of files that are scanned for paths is controlled
14024 by the <filename>SSTATE_SCAN_FILES</filename> variable.
14025 Typically, recipes add files they want to be scanned to the
14026 value of <filename>SSTATE_SCAN_FILES</filename> rather than
14027 the variable being comprehensively set. The
14028 <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
14029 class specifies the default list of files.
14030 </para>
14031
14032 <para>
14033 For details on the process, see the
14034 <link linkend='ref-classes-staging'><filename>staging</filename></link>
14035 class.
14036 </para>
14037 </glossdef>
14038 </glossentry>
14039
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014040 <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm>
14041 <info>
14042 STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host."
14043 </info>
14044 <glossdef>
14045 <para role="glossdeffirst">
14046<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14047 Specifies the path to the <filename>/lib</filename>
14048 subdirectory of the sysroot directory for the
14049 build host.
14050 </para>
14051 </glossdef>
14052 </glossentry>
14053
14054 <glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm>
14055 <info>
14056 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)."
14057 </info>
14058 <glossdef>
14059 <para role="glossdeffirst">
14060<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14061 Specifies the path to the <filename>/lib</filename>
14062 subdirectory of the sysroot directory for the target
14063 for which the current recipe is being built
14064 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14065 </para>
14066 </glossdef>
14067 </glossentry>
14068
14069 <glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm>
14070 <info>
14071 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)."
14072 </info>
14073 <glossdef>
14074 <para role="glossdeffirst">
14075<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14076 Specifies the path to the
14077 <filename>/usr/bin</filename> subdirectory of the
14078 sysroot directory for the target for which the current
14079 recipe is being built
14080 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14081 </para>
14082 </glossdef>
14083 </glossentry>
14084
14085 <glossentry id='var-STAGING_BINDIR_CROSS'><glossterm>STAGING_BINDIR_CROSS</glossterm>
14086 <info>
14087 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."
14088 </info>
14089 <glossdef>
14090 <para role="glossdeffirst">
14091<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14092 Specifies the path to the directory containing binary
14093 configuration scripts.
14094 These scripts provide configuration information for
14095 other software that wants to make use of libraries or
14096 include files provided by the software associated with
14097 the script.
14098 <note>
14099 This style of build configuration has been largely
14100 replaced by <filename>pkg-config</filename>.
14101 Consequently, if <filename>pkg-config</filename>
14102 is supported by the library to which you are linking,
14103 it is recommended you use
14104 <filename>pkg-config</filename> instead of a
14105 provided configuration script.
14106 </note>
14107 </para>
14108 </glossdef>
14109 </glossentry>
14110
14111 <glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm>
14112 <info>
14113 STAGING_BINDIR_NATIVE[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the build host."
14114 </info>
14115 <glossdef>
14116 <para role="glossdeffirst">
14117<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14118 Specifies the path to the
14119 <filename>/usr/bin</filename> subdirectory of the
14120 sysroot directory for the build host.
14121 </para>
14122 </glossdef>
14123 </glossentry>
14124
14125 <glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm>
14126 <info>
14127 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)."
14128 </info>
14129 <glossdef>
14130 <para role="glossdeffirst">
14131<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14132 Specifies the path to the <filename>/usr/share</filename>
14133 subdirectory of the sysroot directory for the target
14134 for which the current recipe is being built
14135 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14136 </para>
14137 </glossdef>
14138 </glossentry>
14139
14140 <glossentry id='var-STAGING_DATADIR_NATIVE'><glossterm>STAGING_DATADIR_NATIVE</glossterm>
14141 <info>
14142 STAGING_DATADIR_NATIVE[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the build host."
14143 </info>
14144 <glossdef>
14145 <para role="glossdeffirst">
14146<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14147 Specifies the path to the <filename>/usr/share</filename>
14148 subdirectory of the sysroot directory for the build host.
14149 </para>
14150 </glossdef>
14151 </glossentry>
14152
14153 <glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm>
14154 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014155 STAGING_DIR[doc] = "Helps construct the recipe-sysroots directory, which is used during packaging."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014156 </info>
14157 <glossdef>
14158 <para role="glossdeffirst">
14159<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040014160 Helps construct the <filename>recipe-sysroots</filename>
14161 directory, which is used during packaging.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014162 </para>
14163
14164 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014165 For information on how staging for recipe-specific
14166 sysroots occurs, see the
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014167 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014168 task, the
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014169 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-sharing-files-between-recipes'>Sharing Files Between Recipes</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -040014170 section in the Yocto Project Development Tasks Manual, the
14171 "<ulink url='&YOCTO_DOCS_OM_URL;#configuration-compilation-and-staging-dev-environment'>Configuration, Compilation, and Staging</ulink>"
14172 section in the Yocto Project Overview and Concepts Manual,
14173 and the
14174 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
14175 variable.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014176 <note>
14177 Recipes should never write files directly under
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014178 the <filename>STAGING_DIR</filename> directory because
14179 the OpenEmbedded build system
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014180 manages the directory automatically.
14181 Instead, files should be installed to
14182 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
14183 within your recipe's
14184 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
14185 task and then the OpenEmbedded build system will
14186 stage a subset of those files into the sysroot.
14187 </note>
14188 </para>
14189 </glossdef>
14190 </glossentry>
14191
14192 <glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm>
14193 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014194 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 -050014195 </info>
14196 <glossdef>
14197 <para role="glossdeffirst">
14198<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014199 Specifies the path to the sysroot directory for the system
Brad Bishop316dfdd2018-06-25 12:45:53 -040014200 on which the component is built to run (the system that
14201 hosts the component).
14202 For most recipes, this sysroot is the one in which that
14203 recipe's
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014204 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014205 task copies files.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014206 Exceptions include <filename>-native</filename> recipes,
14207 where the <filename>do_populate_sysroot</filename> task
14208 instead uses
14209 <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>.
14210 Depending on the type of recipe and the build target,
14211 <filename>STAGING_DIR_HOST</filename> can have the
14212 following values:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014213 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014214 <listitem><para>
14215 For recipes building for the target machine, the
14216 value is
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014217 "${<link linkend='var-STAGING_DIR'>STAGING_DIR</link>}/${<link linkend='var-MACHINE'>MACHINE</link>}".
14218 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014219 <listitem><para>
14220 For native recipes building for the build host, the
14221 value is empty given the assumption that when
14222 building for the build host, the build host's own
14223 directories should be used.
14224 <note>
14225 <para><filename>-native</filename> recipes are
14226 not installed into host paths like such as
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014227 <filename>/usr</filename>.
14228 Rather, these recipes are installed into
14229 <filename>STAGING_DIR_NATIVE</filename>.
14230 When compiling <filename>-native</filename>
14231 recipes, standard build environment variables
14232 such as
14233 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
14234 and
14235 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
14236 are set up so that both host paths and
14237 <filename>STAGING_DIR_NATIVE</filename> are
14238 searched for libraries and headers using, for
14239 example, GCC's <filename>-isystem</filename>
14240 option.</para>
14241
Brad Bishop316dfdd2018-06-25 12:45:53 -040014242 <para>Thus, the emphasis is that the
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014243 <filename>STAGING_DIR*</filename> variables
14244 should be viewed as input variables by tasks
14245 such as
14246 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>,
14247 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
14248 and
14249 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
14250 Having the real system root correspond to
14251 <filename>STAGING_DIR_HOST</filename> makes
14252 conceptual sense for
14253 <filename>-native</filename> recipes, as
14254 they make use of host headers and libraries.
14255 </para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014256 </note>
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014257 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014258 </itemizedlist>
14259 </para>
14260 </glossdef>
14261 </glossentry>
14262
14263 <glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm>
14264 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014265 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 -050014266 </info>
14267 <glossdef>
14268 <para role="glossdeffirst">
14269<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014270 Specifies the path to the sysroot directory used when
14271 building components that run on the build host itself.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014272 </para>
14273 </glossdef>
14274 </glossentry>
14275
14276 <glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm>
14277 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014278 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 -050014279 </info>
14280 <glossdef>
14281 <para role="glossdeffirst">
14282<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014283 Specifies the path to the sysroot used for the system for
14284 which the component generates code.
14285 For components that do not generate code, which is the
14286 majority, <filename>STAGING_DIR_TARGET</filename> is set
14287 to match
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014288 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
14289 </para>
14290
14291 <para>
14292 Some recipes build binaries that can run on the target
14293 system but those binaries in turn generate code for
14294 another different system (e.g. cross-canadian recipes).
14295 Using terminology from GNU, the primary system is referred
14296 to as the "HOST" and the secondary, or different, system is
14297 referred to as the "TARGET".
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014298 Thus, the binaries run on the "HOST" system
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014299 and generate binaries for the "TARGET" system.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014300 The <filename>STAGING_DIR_HOST</filename> variable points
14301 to the sysroot used for the "HOST" system, while
14302 <filename>STAGING_DIR_TARGET</filename>
14303 points to the sysroot used for the "TARGET" system.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014304 </para>
14305 </glossdef>
14306 </glossentry>
14307
14308 <glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm>STAGING_ETCDIR_NATIVE</glossterm>
14309 <info>
14310 STAGING_ETCDIR_NATIVE[doc] = "Specifies the path to the /etc subdirectory of the sysroot directory for the build host."
14311 </info>
14312 <glossdef>
14313 <para role="glossdeffirst">
14314<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14315 Specifies the path to the <filename>/etc</filename>
14316 subdirectory of the sysroot directory for the
14317 build host.
14318 </para>
14319 </glossdef>
14320 </glossentry>
14321
14322 <glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm>
14323 <info>
14324 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)."
14325 </info>
14326 <glossdef>
14327 <para role="glossdeffirst">
14328<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14329 Specifies the path to the <filename>/usr</filename>
14330 subdirectory of the sysroot directory for the target
14331 for which the current recipe is being built
14332 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14333 </para>
14334 </glossdef>
14335 </glossentry>
14336
14337 <glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm>
14338 <info>
14339 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)."
14340 </info>
14341 <glossdef>
14342 <para role="glossdeffirst">
14343<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14344 Specifies the path to the
14345 <filename>/usr/include</filename> subdirectory of the
14346 sysroot directory for the target for which the current
14347 recipe being built
14348 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14349 </para>
14350 </glossdef>
14351 </glossentry>
14352
14353 <glossentry id='var-STAGING_INCDIR_NATIVE'><glossterm>STAGING_INCDIR_NATIVE</glossterm>
14354 <info>
14355 STAGING_INCDIR_NATIVE[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the build host."
14356 </info>
14357 <glossdef>
14358 <para role="glossdeffirst">
14359<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14360 Specifies the path to the <filename>/usr/include</filename>
14361 subdirectory of the sysroot directory for the build host.
14362 </para>
14363 </glossdef>
14364 </glossentry>
14365
Patrick Williamsf1e5d692016-03-30 15:21:19 -050014366 <glossentry id='var-STAGING_KERNEL_BUILDDIR'><glossterm>STAGING_KERNEL_BUILDDIR</glossterm>
14367 <info>
14368 STAGING_KERNEL_BUILDDIR[doc] = "Points to the directory containing the kernel build artifacts."
14369 </info>
14370 <glossdef>
14371 <para role="glossdeffirst">
14372<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14373 Points to the directory containing the kernel build
14374 artifacts.
14375 Recipes building software that needs to access kernel
14376 build artifacts
14377 (e.g. <filename>systemtap-uprobes</filename>) can look in
14378 the directory specified with the
14379 <filename>STAGING_KERNEL_BUILDDIR</filename> variable to
14380 find these artifacts after the kernel has been built.
14381 </para>
14382 </glossdef>
14383 </glossentry>
14384
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014385 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
14386 <info>
14387 STAGING_KERNEL_DIR[doc] = "The directory with kernel headers that are required to build out-of-tree modules."
14388 </info>
14389 <glossdef>
14390 <para role="glossdeffirst">
14391<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14392 The directory with kernel headers that are required to build out-of-tree
14393 modules.
14394 </para>
14395 </glossdef>
14396 </glossentry>
14397
14398 <glossentry id='var-STAGING_LIBDIR'><glossterm>STAGING_LIBDIR</glossterm>
14399 <info>
14400 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)."
14401 </info>
14402 <glossdef>
14403 <para role="glossdeffirst">
14404<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14405 Specifies the path to the <filename>/usr/lib</filename>
14406 subdirectory of the sysroot directory for the target for
14407 which the current recipe is being built
14408 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14409 </para>
14410 </glossdef>
14411 </glossentry>
14412
14413 <glossentry id='var-STAGING_LIBDIR_NATIVE'><glossterm>STAGING_LIBDIR_NATIVE</glossterm>
14414 <info>
14415 STAGING_LIBDIR_NATIVE[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the build host."
14416 </info>
14417 <glossdef>
14418 <para role="glossdeffirst">
14419<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14420 Specifies the path to the <filename>/usr/lib</filename>
14421 subdirectory of the sysroot directory for the build host.
14422 </para>
14423 </glossdef>
14424 </glossentry>
14425
14426 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
14427 <info>
14428 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."
14429 </info>
14430 <glossdef>
14431 <para role="glossdeffirst">
14432<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14433 Specifies the base path used to create recipe stamp files.
14434 The path to an actual stamp file is constructed by evaluating this
14435 string and then appending additional information.
14436 Currently, the default assignment for <filename>STAMP</filename>
14437 as set in the <filename>meta/conf/bitbake.conf</filename> file
14438 is:
14439 <literallayout class='monospaced'>
14440 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
14441 </literallayout>
14442 </para>
14443
14444 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014445 For information on how BitBake uses stamp files to determine
14446 if a task should be rerun, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040014447 "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
14448 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014449 </para>
14450
14451 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014452 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
14453 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
14454 <link linkend='var-PN'><filename>PN</filename></link>,
14455 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
14456 <link linkend='var-PV'><filename>PV</filename></link>, and
14457 <link linkend='var-PR'><filename>PR</filename></link> for related variable
14458 information.
14459 </para>
14460 </glossdef>
14461 </glossentry>
14462
14463 <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
14464 <info>
14465 STAMPS_DIR[doc] = "Specifies the base directory in which the OpenEmbedded build system places stamps."
14466 </info>
14467 <glossdef>
14468 <para role="glossdeffirst">
14469<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14470 Specifies the base directory in which the OpenEmbedded
14471 build system places stamps.
14472 The default directory is
14473 <filename>${TMPDIR}/stamps</filename>.
14474 </para>
14475 </glossdef>
14476 </glossentry>
14477
14478 <glossentry id='var-STRIP'><glossterm>STRIP</glossterm>
14479 <info>
14480 STRIP[doc] = "Minimal command and arguments to run 'strip' (strip symbols)."
14481 </info>
14482 <glossdef>
14483 <para role="glossdeffirst">
14484<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14485 The minimal command and arguments to run
14486 <filename>strip</filename>, which is used to strip
14487 symbols.
14488 </para>
14489 </glossdef>
14490 </glossentry>
14491
14492 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
14493 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014494 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 -050014495 </info>
14496 <glossdef>
14497 <para role="glossdeffirst">
14498<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14499 The short (72 characters or less) summary of the binary package for packaging
Brad Bishop316dfdd2018-06-25 12:45:53 -040014500 systems such as <filename>opkg</filename>, <filename>rpm</filename>, or
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014501 <filename>dpkg</filename>.
14502 By default, <filename>SUMMARY</filename> is used to define
14503 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
14504 variable if <filename>DESCRIPTION</filename> is not set
14505 in the recipe.
14506 </para>
14507 </glossdef>
14508 </glossentry>
14509
14510 <glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm>
14511 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014512 SVNDIR[doc] = "The directory where Subversion checkouts are stored."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014513 </info>
14514 <glossdef>
14515 <para role="glossdeffirst">
14516<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14517 The directory in which files checked out of a Subversion
14518 system are stored.
14519 </para>
14520 </glossdef>
14521 </glossentry>
14522
14523 <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm>
14524 <info>
14525 SYSLINUX_DEFAULT_CONSOLE[doc] = "Specifies the kernel boot default console."
14526 </info>
14527 <glossdef>
14528 <para role="glossdeffirst">
14529<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14530 Specifies the kernel boot default console.
14531 If you want to use a console other than the default,
14532 set this variable in your recipe as follows where "X" is
14533 the console number you want to use:
14534 <literallayout class='monospaced'>
14535 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
14536 </literallayout>
14537 </para>
14538
14539 <para>
14540 The
14541 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14542 class initially sets this variable to null but then checks
14543 for a value later.
14544 </para>
14545 </glossdef>
14546 </glossentry>
14547
14548 <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm>
14549 <info>
14550 SYSLINUX_OPTS[doc] = "Lists additional options to add to the syslinux file."
14551 </info>
14552 <glossdef>
14553 <para role="glossdeffirst">
14554<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14555 Lists additional options to add to the syslinux file.
14556 You need to set this variable in your recipe.
14557 If you want to list multiple options, separate the options
14558 with a semicolon character (<filename>;</filename>).
14559 </para>
14560
14561 <para>
14562 The
14563 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14564 class uses this variable to create a set of options.
14565 </para>
14566 </glossdef>
14567 </glossentry>
14568
14569 <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm>
14570 <info>
14571 SYSLINUX_SERIAL[doc] = "Specifies the alternate serial port or turns it off."
14572 </info>
14573 <glossdef>
14574 <para role="glossdeffirst">
14575<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14576 Specifies the alternate serial port or turns it off.
14577 To turn off serial, set this variable to an empty string
14578 in your recipe.
14579 The variable's default value is set in the
14580 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014581 class as follows:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014582 <literallayout class='monospaced'>
14583 SYSLINUX_SERIAL ?= "0 115200"
14584 </literallayout>
14585 </para>
14586
14587 <para>
14588 The class checks for and uses the variable as needed.
14589 </para>
14590 </glossdef>
14591 </glossentry>
14592
14593 <glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm>
14594 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014595 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 -050014596 </info>
14597 <glossdef>
14598 <para role="glossdeffirst">
14599<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14600 An <filename>.LSS</filename> file used as the background
Brad Bishop316dfdd2018-06-25 12:45:53 -040014601 for the VGA boot menu when you use the boot menu.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014602 You need to set this variable in your recipe.
14603 </para>
14604
14605 <para>
14606 The
14607 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14608 class checks for this variable and if found, the
14609 OpenEmbedded build system installs the splash screen.
14610 </para>
14611 </glossdef>
14612 </glossentry>
14613
14614 <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>
14615 <info>
14616 SYSLINUX_SERIAL_TTY[doc] = "Specifies the alternate console=tty... kernel boot argument."
14617 </info>
14618 <glossdef>
14619 <para role="glossdeffirst">
14620<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14621 Specifies the alternate console=tty... kernel boot argument.
14622 The variable's default value is set in the
14623 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014624 class as follows:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014625 <literallayout class='monospaced'>
14626 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
14627 </literallayout>
14628 </para>
14629
14630 <para>
14631 The class checks for and uses the variable as needed.
14632 </para>
14633 </glossdef>
14634 </glossentry>
14635
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014636 <glossentry id='var-SYSROOT_DESTDIR'><glossterm>SYSROOT_DESTDIR</glossterm>
14637 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014638 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 -050014639 </info>
14640 <glossdef>
14641 <para role="glossdeffirst">
14642<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14643 Points to the temporary directory under the work directory
14644 (default
Brad Bishopd7bf8c12018-02-25 22:55:05 -050014645 "<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/sysroot-destdir</filename>")
Brad Bishop316dfdd2018-06-25 12:45:53 -040014646 where the files populated into the sysroot are assembled
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014647 during the
14648 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14649 task.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014650 </para>
14651 </glossdef>
14652 </glossentry>
14653
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014654 <glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm>
14655 <info>
14656 SYSROOT_DIRS[doc] = "Directories that are staged into the sysroot by the do_populate_sysroot task."
14657 </info>
14658 <glossdef>
14659 <para role="glossdeffirst">
14660<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14661 Directories that are staged into the sysroot by the
14662 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14663 task.
14664 By default, the following directories are staged:
14665 <literallayout class='monospaced'>
14666 SYSROOT_DIRS = " \
14667 ${includedir} \
14668 ${libdir} \
14669 ${base_libdir} \
14670 ${nonarch_base_libdir} \
14671 ${datadir} \
14672 "
14673 </literallayout>
14674 </para>
14675 </glossdef>
14676 </glossentry>
14677
14678 <glossentry id='var-SYSROOT_DIRS_BLACKLIST'><glossterm>SYSROOT_DIRS_BLACKLIST</glossterm>
14679 <info>
14680 SYSROOT_DIRS_BLACKLIST[doc] = "Directories that are not staged into the sysroot by the do_populate_sysroot task."
14681 </info>
14682 <glossdef>
14683 <para role="glossdeffirst">
14684<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14685 Directories that are not staged into the sysroot by the
14686 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14687 task.
14688 You can use this variable to exclude certain subdirectories
14689 of directories listed in
14690 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
14691 from staging.
14692 By default, the following directories are not staged:
14693 <literallayout class='monospaced'>
14694 SYSROOT_DIRS_BLACKLIST = " \
14695 ${mandir} \
14696 ${docdir} \
14697 ${infodir} \
14698 ${datadir}/locale \
14699 ${datadir}/applications \
14700 ${datadir}/fonts \
14701 ${datadir}/pixmaps \
14702 "
14703 </literallayout>
14704 </para>
14705 </glossdef>
14706 </glossentry>
14707
14708 <glossentry id='var-SYSROOT_DIRS_NATIVE'><glossterm>SYSROOT_DIRS_NATIVE</glossterm>
14709 <info>
14710 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."
14711 </info>
14712 <glossdef>
14713 <para role="glossdeffirst">
14714<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14715 Extra directories staged into the sysroot by the
14716 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14717 task for <filename>-native</filename> recipes, in addition
14718 to those specified in
14719 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>.
14720 By default, the following extra directories are staged:
14721 <literallayout class='monospaced'>
14722 SYSROOT_DIRS_NATIVE = " \
14723 ${bindir} \
14724 ${sbindir} \
14725 ${base_bindir} \
14726 ${base_sbindir} \
14727 ${libexecdir} \
14728 ${sysconfdir} \
14729 ${localstatedir} \
14730 "
14731 </literallayout>
14732 <note>
14733 Programs built by <filename>-native</filename> recipes
14734 run directly from the sysroot
14735 (<link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>),
14736 which is why additional directories containing program
14737 executables and supporting files need to be staged.
14738 </note>
14739 </para>
14740 </glossdef>
14741 </glossentry>
14742
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014743 <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
14744 <info>
14745 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."
14746 </info>
14747 <glossdef>
14748 <para role="glossdeffirst">
14749<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14750 A list of functions to execute after files are staged into
14751 the sysroot.
14752 These functions are usually used to apply additional
14753 processing on the staged files, or to stage additional
14754 files.
14755 </para>
14756 </glossdef>
14757 </glossentry>
14758
14759 <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>
14760 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014761 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 -050014762 </info>
14763 <glossdef>
14764 <para role="glossdeffirst">
14765<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14766 When inheriting the
14767 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014768 class, this variable specifies whether the specified service
14769 in
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014770 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014771 should start automatically or not.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014772 By default, the service is enabled to automatically start
14773 at boot time.
14774 The default setting is in the
14775 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14776 class as follows:
14777 <literallayout class='monospaced'>
14778 SYSTEMD_AUTO_ENABLE ??= "enable"
14779 </literallayout>
14780 </para>
14781
14782 <para>
14783 You can disable the service by setting the variable to
14784 "disable".
14785 </para>
14786 </glossdef>
14787 </glossentry>
14788
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014789 <glossentry id='var-SYSTEMD_BOOT_CFG'><glossterm>SYSTEMD_BOOT_CFG</glossterm>
14790 <info>
14791 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."
14792 </info>
14793 <glossdef>
14794 <para role="glossdeffirst">
14795<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14796 When
14797 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14798 is set to "systemd-boot", the
14799 <filename>SYSTEMD_BOOT_CFG</filename> variable specifies the
14800 configuration file that should be used.
14801 By default, the
14802 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14803 class sets the <filename>SYSTEMD_BOOT_CFG</filename> as
14804 follows:
14805 <literallayout class='monospaced'>
14806 SYSTEMD_BOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf"
14807 </literallayout>
14808 </para>
14809
14810 <para>
14811 For information on Systemd-boot, see the
14812 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14813 </para>
14814 </glossdef>
14815 </glossentry>
14816
14817 <glossentry id='var-SYSTEMD_BOOT_ENTRIES'><glossterm>SYSTEMD_BOOT_ENTRIES</glossterm>
14818 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014819 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 -060014820 </info>
14821 <glossdef>
14822 <para role="glossdeffirst">
14823<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14824 When
14825 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14826 is set to "systemd-boot", the
14827 <filename>SYSTEMD_BOOT_ENTRIES</filename> variable specifies
14828 a list of entry files
Brad Bishop316dfdd2018-06-25 12:45:53 -040014829 (<filename>*.conf</filename>) to install that contain
14830 one boot entry per file.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014831 By default, the
14832 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14833 class sets the <filename>SYSTEMD_BOOT_ENTRIES</filename> as
14834 follows:
14835 <literallayout class='monospaced'>
14836 SYSTEMD_BOOT_ENTRIES ?= ""
14837 </literallayout>
14838 </para>
14839
14840 <para>
14841 For information on Systemd-boot, see the
14842 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14843 </para>
14844 </glossdef>
14845 </glossentry>
14846
14847 <glossentry id='var-SYSTEMD_BOOT_TIMEOUT'><glossterm>SYSTEMD_BOOT_TIMEOUT</glossterm>
14848 <info>
14849 SYSTEMD_BOOT_TIMEOUT[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_TIMEOUT variable specifies the boot menu timeout in seconds."
14850 </info>
14851 <glossdef>
14852 <para role="glossdeffirst">
14853<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14854 When
14855 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14856 is set to "systemd-boot", the
14857 <filename>SYSTEMD_BOOT_TIMEOUT</filename> variable specifies
14858 the boot menu timeout in seconds.
14859 By default, the
14860 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14861 class sets the <filename>SYSTEMD_BOOT_TIMEOUT</filename> as
14862 follows:
14863 <literallayout class='monospaced'>
14864 SYSTEMD_BOOT_TIMEOUT ?= "10"
14865 </literallayout>
14866 </para>
14867
14868 <para>
14869 For information on Systemd-boot, see the
14870 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14871 </para>
14872 </glossdef>
14873 </glossentry>
14874
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014875 <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>
14876 <info>
14877 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."
14878 </info>
14879 <glossdef>
14880 <para role="glossdeffirst">
14881<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14882 When inheriting the
14883 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14884 class, this variable locates the systemd unit files when
14885 they are not found in the main recipe's package.
14886 By default, the
14887 <filename>SYSTEMD_PACKAGES</filename> variable is set
14888 such that the systemd unit files are assumed to reside in
14889 the recipes main package:
14890 <literallayout class='monospaced'>
14891 SYSTEMD_PACKAGES ?= "${PN}"
14892 </literallayout>
14893 </para>
14894
14895 <para>
14896 If these unit files are not in this recipe's main
14897 package, you need to use
14898 <filename>SYSTEMD_PACKAGES</filename> to list the package
14899 or packages in which the build system can find the systemd
14900 unit files.
14901 </para>
14902 </glossdef>
14903 </glossentry>
14904
14905 <glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm>
14906 <info>
14907 SYSTEMD_SERVICE[doc] = "For recipes that inherit the systemd class, this variable specifies the systemd service name for a package."
14908 </info>
14909 <glossdef>
14910 <para role="glossdeffirst">
14911<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14912 When inheriting the
14913 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14914 class, this variable specifies the systemd service name for
14915 a package.
14916 </para>
14917
14918 <para>
14919 When you specify this file in your recipe, use a package
14920 name override to indicate the package to which the value
14921 applies.
14922 Here is an example from the connman recipe:
14923 <literallayout class='monospaced'>
14924 SYSTEMD_SERVICE_${PN} = "connman.service"
14925 </literallayout>
14926 </para>
14927 </glossdef>
14928 </glossentry>
14929
14930 <glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>SYSVINIT_ENABLED_GETTYS</glossterm>
14931 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014932 SYSVINIT_ENABLED_GETTYS[doc] = "Specifies which virtual terminals should run a getty, the default is '1'."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014933 </info>
14934 <glossdef>
14935 <para role="glossdeffirst">
14936<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14937 When using
14938 <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
14939 specifies a space-separated list of the virtual terminals
Brad Bishop316dfdd2018-06-25 12:45:53 -040014940 that should run a
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014941 <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
14942 (allowing login), assuming
14943 <link linkend='var-USE_VT'><filename>USE_VT</filename></link>
14944 is not set to "0".
14945 </para>
14946
14947 <para>
14948 The default value for
14949 <filename>SYSVINIT_ENABLED_GETTYS</filename> is "1"
14950 (i.e. only run a getty on the first virtual terminal).
14951 </para>
14952 </glossdef>
14953 </glossentry>
14954
14955 </glossdiv>
14956
14957 <glossdiv id='var-glossary-t'><title>T</title>
14958
14959 <glossentry id='var-T'><glossterm>T</glossterm>
14960 <info>
14961 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."
14962 </info>
14963 <glossdef>
14964 <para role="glossdeffirst">
14965<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14966 This variable points to a directory were BitBake places
14967 temporary files, which consist mostly of task logs and
14968 scripts, when building a particular recipe.
14969 The variable is typically set as follows:
14970 <literallayout class='monospaced'>
14971 T = "${WORKDIR}/temp"
14972 </literallayout>
14973 </para>
14974
14975 <para>
14976 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
14977 is the directory into which BitBake unpacks and builds the
14978 recipe.
14979 The default <filename>bitbake.conf</filename> file sets this variable.</para>
14980 <para>The <filename>T</filename> variable is not to be confused with
14981 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
14982 which points to the root of the directory tree where BitBake
14983 places the output of an entire build.
14984 </para>
14985 </glossdef>
14986 </glossentry>
14987
14988 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
14989 <info>
14990 TARGET_ARCH[doc] = "The architecture of the device being built. The OpenEmbedded build system supports the following architectures: arm, mips, ppc, x86, x86-64."
14991 </info>
14992 <glossdef>
14993 <para role="glossdeffirst">
14994<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14995 The target machine's architecture.
14996 The OpenEmbedded build system supports many
14997 architectures.
14998 Here is an example list of architectures supported.
14999 This list is by no means complete as the architecture
15000 is configurable:
15001 <literallayout class='monospaced'>
15002 arm
15003 i586
15004 x86_64
15005 powerpc
15006 powerpc64
15007 mips
15008 mipsel
15009 </literallayout>
15010 </para>
15011
15012 <para>
15013 For additional information on machine architectures, see
15014 the
15015 <link linkend='var-TUNE_ARCH'><filename>TUNE_ARCH</filename></link>
15016 variable.
15017 </para>
15018 </glossdef>
15019 </glossentry>
15020
15021 <glossentry id='var-TARGET_AS_ARCH'><glossterm>TARGET_AS_ARCH</glossterm>
15022 <info>
15023 TARGET_AS_ARCH[doc] = "Specifies architecture-specific assembler flags for the target system."
15024 </info>
15025 <glossdef>
15026 <para role="glossdeffirst">
15027<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15028 Specifies architecture-specific assembler flags for the
15029 target system.
15030 <filename>TARGET_AS_ARCH</filename> is initialized from
15031 <link linkend='var-TUNE_ASARGS'><filename>TUNE_ASARGS</filename></link>
15032 by default in the BitBake configuration file
15033 (<filename>meta/conf/bitbake.conf</filename>):
15034 <literallayout class='monospaced'>
15035 TARGET_AS_ARCH = "${TUNE_ASARGS}"
15036 </literallayout>
15037 </para>
15038 </glossdef>
15039 </glossentry>
15040
15041 <glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm>
15042 <info>
15043 TARGET_CC_ARCH[doc] = "Specifies architecture-specific C compiler flags for the target system."
15044 </info>
15045 <glossdef>
15046 <para role="glossdeffirst">
15047<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15048 Specifies architecture-specific C compiler flags for the
15049 target system.
15050 <filename>TARGET_CC_ARCH</filename> is initialized from
15051 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
15052 by default.
15053 <note>
15054 It is a common workaround to append
15055 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
15056 to <filename>TARGET_CC_ARCH</filename>
15057 in recipes that build software for the target that
15058 would not otherwise respect the exported
15059 <filename>LDFLAGS</filename> variable.
15060 </note>
15061 </para>
15062 </glossdef>
15063 </glossentry>
15064
15065 <glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm>
15066 <info>
15067 TARGET_CC_KERNEL_ARCH[doc] = "This is a specific kernel compiler flag for a CPU or Application Binary Interface (ABI) tune."
15068 </info>
15069 <glossdef>
15070 <para role="glossdeffirst">
15071<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15072 This is a specific kernel compiler flag for a CPU or
15073 Application Binary Interface (ABI) tune.
15074 The flag is used rarely and only for cases where a
15075 userspace
15076 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
15077 is not compatible with the kernel compilation.
15078 The <filename>TARGET_CC_KERNEL_ARCH</filename> variable
15079 allows the kernel (and associated modules) to use a
15080 different configuration.
15081 See the
15082 <filename>meta/conf/machine/include/arm/feature-arm-thumb.inc</filename>
15083 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015084 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015085 for an example.
15086 </para>
15087 </glossdef>
15088 </glossentry>
15089
15090 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
15091 <info>
15092 TARGET_CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as CFLAGS."
15093 </info>
15094 <glossdef>
15095 <para role="glossdeffirst">
15096<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15097 Specifies the flags to pass to the C compiler when building
15098 for the target.
15099 When building in the target context,
15100 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
15101 is set to the value of this variable by default.
15102 </para>
15103
15104 <para>
15105 Additionally, the SDK's environment setup script sets
Brad Bishop316dfdd2018-06-25 12:45:53 -040015106 the <filename>CFLAGS</filename> variable in the environment
15107 to the <filename>TARGET_CFLAGS</filename> value so that
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015108 executables built using the SDK also have the flags
15109 applied.
15110 </para>
15111 </glossdef>
15112 </glossentry>
15113
15114 <glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm>
15115 <info>
15116 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."
15117 </info>
15118 <glossdef>
15119 <para role="glossdeffirst">
15120<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15121 Specifies the flags to pass to the C pre-processor
15122 (i.e. to both the C and the C++ compilers) when building
15123 for the target.
15124 When building in the target context,
15125 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
15126 is set to the value of this variable by default.
15127 </para>
15128
15129 <para>
15130 Additionally, the SDK's environment setup script sets
Brad Bishop316dfdd2018-06-25 12:45:53 -040015131 the <filename>CPPFLAGS</filename> variable in the
15132 environment to the <filename>TARGET_CPPFLAGS</filename>
15133 value so that executables built using the SDK also have
15134 the flags applied.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015135 </para>
15136 </glossdef>
15137 </glossentry>
15138
15139 <glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm>
15140 <info>
15141 TARGET_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the target."
15142 </info>
15143 <glossdef>
15144 <para role="glossdeffirst">
15145<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15146 Specifies the flags to pass to the C++ compiler when
15147 building for the target.
15148 When building in the target context,
15149 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
15150 is set to the value of this variable by default.
15151 </para>
15152
15153 <para>
15154 Additionally, the SDK's environment setup script sets
Brad Bishop316dfdd2018-06-25 12:45:53 -040015155 the <filename>CXXFLAGS</filename> variable in the
15156 environment to the <filename>TARGET_CXXFLAGS</filename>
15157 value so that executables built using the SDK also have
15158 the flags applied.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015159 </para>
15160 </glossdef>
15161 </glossentry>
15162
15163 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
15164 <info>
15165 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."
15166 </info>
15167 <glossdef>
15168 <para role="glossdeffirst">
15169<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15170 Specifies the method for handling FPU code.
15171 For FPU-less targets, which include most ARM CPUs, the variable must be
15172 set to "soft".
15173 If not, the kernel emulation gets used, which results in a performance penalty.
15174 </para>
15175 </glossdef>
15176 </glossentry>
15177
15178 <glossentry id='var-TARGET_LD_ARCH'><glossterm>TARGET_LD_ARCH</glossterm>
15179 <info>
15180 TARGET_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the target system."
15181 </info>
15182 <glossdef>
15183 <para role="glossdeffirst">
15184<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15185 Specifies architecture-specific linker flags for the
15186 target system.
15187 <filename>TARGET_LD_ARCH</filename> is initialized from
15188 <link linkend='var-TUNE_LDARGS'><filename>TUNE_LDARGS</filename></link>
15189 by default in the BitBake configuration file
15190 (<filename>meta/conf/bitbake.conf</filename>):
15191 <literallayout class='monospaced'>
15192 TARGET_LD_ARCH = "${TUNE_LDARGS}"
15193 </literallayout>
15194 </para>
15195 </glossdef>
15196 </glossentry>
15197
15198 <glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm>
15199 <info>
15200 TARGET_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the target."
15201 </info>
15202 <glossdef>
15203 <para role="glossdeffirst">
15204<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15205 Specifies the flags to pass to the linker when building
15206 for the target.
15207 When building in the target context,
15208 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
15209 is set to the value of this variable by default.
15210 </para>
15211
15212 <para>
15213 Additionally, the SDK's environment setup script sets
15214 the
15215 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
15216 variable in the environment to the
15217 <filename>TARGET_LDFLAGS</filename> value so that
15218 executables built using the SDK also have the flags
15219 applied.
15220 </para>
15221 </glossdef>
15222 </glossentry>
15223
15224 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
15225 <info>
15226 TARGET_OS[doc] = "Specifies the target's operating system."
15227 </info>
15228 <glossdef>
15229 <para role="glossdeffirst">
15230<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15231 Specifies the target's operating system.
Brad Bishop316dfdd2018-06-25 12:45:53 -040015232 The variable can be set to "linux" for glibc-based systems
15233 (GNU C Library) and to "linux-musl" for musl libc.
15234 For ARM/EABI targets, "linux-gnueabi" and "linux-musleabi"
15235 possible values exist.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015236 </para>
15237 </glossdef>
15238 </glossentry>
15239
15240 <glossentry id='var-TARGET_PREFIX'><glossterm>TARGET_PREFIX</glossterm>
15241 <info>
15242 TARGET_PREFIX[doc] = "The prefix used for the toolchain binary target tools."
15243 </info>
15244 <glossdef>
15245 <para role="glossdeffirst">
15246<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15247 Specifies the prefix used for the toolchain binary target
15248 tools.
15249 </para>
15250
15251 <para>
15252 Depending on the type of recipe and the build target,
15253 <filename>TARGET_PREFIX</filename> is set as follows:
15254 <itemizedlist>
15255 <listitem><para>
15256 For recipes building for the target machine,
15257 the value is
15258 "${<link linkend='var-TARGET_SYS'>TARGET_SYS</link>}-".
15259 </para></listitem>
15260 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015261 For native recipes, the build system sets the
15262 variable to the value of
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015263 <filename>BUILD_PREFIX</filename>.
15264 </para></listitem>
15265 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015266 For native SDK recipes
15267 (<filename>nativesdk</filename>), the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015268 build system sets the variable to the value of
15269 <filename>SDK_PREFIX</filename>.
15270 </para></listitem>
15271 </itemizedlist>
15272 </para>
15273 </glossdef>
15274 </glossentry>
15275
15276 <glossentry id='var-TARGET_SYS'><glossterm>TARGET_SYS</glossterm>
15277 <info>
15278 TARGET_SYS[doc] = "The target system is comprised of TARGET_ARCH,TARGET_VENDOR and TARGET_OS."
15279 </info>
15280 <glossdef>
15281 <para role="glossdeffirst">
15282<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15283 Specifies the system, including the architecture and the
15284 operating system, for which the build is occurring in
15285 the context of the current recipe.
15286 </para>
15287
15288 <para>
15289 The OpenEmbedded build system automatically sets this
15290 variable based on
15291 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
15292 <link linkend='var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></link>,
15293 and
15294 <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>
15295 variables.
15296 <note>
15297 You do not need to set the
15298 <filename>TARGET_SYS</filename> variable yourself.
15299 </note>
15300 </para>
15301
15302 <para>
15303 Consider these two examples:
15304 <itemizedlist>
15305 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015306 Given a native recipe on a 32-bit, x86 machine
15307 running Linux, the value is "i686-linux".
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015308 </para></listitem>
15309 <listitem><para>
15310 Given a recipe being built for a little-endian,
15311 MIPS target running Linux, the value might be
15312 "mipsel-linux".
15313 </para></listitem>
15314 </itemizedlist>
15315 </para>
15316 </glossdef>
15317 </glossentry>
15318
15319 <glossentry id='var-TARGET_VENDOR'><glossterm>TARGET_VENDOR</glossterm>
15320 <info>
15321 TARGET_VENDOR[doc] = "The name of the target vendor."
15322 </info>
15323 <glossdef>
15324 <para role="glossdeffirst">
15325<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15326 Specifies the name of the target vendor.
15327 </para>
15328 </glossdef>
15329 </glossentry>
15330
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015331 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
15332 <info>
15333 TCLIBC[doc] = "Specifies GNU standard C library (libc) variant to use during the build process. You can select 'glibc', 'musl' or "newlib."
15334 </info>
15335 <glossdef>
15336 <para role="glossdeffirst">
15337<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15338 Specifies the GNU standard C library
15339 (<filename>libc</filename>) variant to use during the
15340 build process.
15341 This variable replaces <filename>POKYLIBC</filename>,
15342 which is no longer supported.
15343 </para>
15344
15345 <para>
15346 You can select "glibc", "musl", "newlib", or "baremetal"
15347 </para>
15348 </glossdef>
15349 </glossentry>
15350
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015351 <glossentry id='var-TCLIBCAPPEND'><glossterm>TCLIBCAPPEND</glossterm>
15352 <info>
15353 TCLIBCAPPEND[doc] = "Specifies a suffix appended to TMPDIR that identifies the libc variant for the build."
15354 </info>
15355 <glossdef>
15356 <para role="glossdeffirst">
15357<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15358 Specifies a suffix to be appended onto the
15359 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
15360 value.
15361 The suffix identifies the <filename>libc</filename> variant
15362 for building.
15363 When you are building for multiple variants with the same
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015364 <link linkend='build-directory'>Build Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015365 this mechanism ensures that output for different
15366 <filename>libc</filename> variants is kept separate to
15367 avoid potential conflicts.
15368 </para>
15369
15370 <para>
15371 In the <filename>defaultsetup.conf</filename> file, the
15372 default value of <filename>TCLIBCAPPEND</filename> is
15373 "-${TCLIBC}".
15374 However, distros such as poky, which normally only support
15375 one <filename>libc</filename> variant, set
15376 <filename>TCLIBCAPPEND</filename> to "" in their distro
15377 configuration file resulting in no suffix being applied.
15378 </para>
15379 </glossdef>
15380 </glossentry>
15381
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015382 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
15383 <info>
15384 TCMODE[doc] = "Enables an external toolchain (where provided by an additional layer) if set to a value other than 'default'."
15385 </info>
15386 <glossdef>
15387 <para role="glossdeffirst">
15388<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15389 Specifies the toolchain selector.
15390 <filename>TCMODE</filename> controls the characteristics
15391 of the generated packages and images by telling the
15392 OpenEmbedded build system which toolchain profile to use.
15393 By default, the OpenEmbedded build system builds its own
15394 internal toolchain.
15395 The variable's default value is "default", which uses
15396 that internal toolchain.
15397 <note>
15398 If <filename>TCMODE</filename> is set to a value
15399 other than "default", then it is your responsibility
15400 to ensure that the toolchain is compatible with the
15401 default toolchain.
15402 Using older or newer versions of these components
15403 might cause build problems.
Brad Bishop316dfdd2018-06-25 12:45:53 -040015404 See the Release Notes for the Yocto Project release
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015405 for the specific components with which the toolchain
15406 must be compatible.
Brad Bishop316dfdd2018-06-25 12:45:53 -040015407 To access the Release Notes, go to the
15408 <ulink url='&YOCTO_HOME_URL;/software-overview/downloads/'>Downloads</ulink>
15409 page on the Yocto Project website and click on the
15410 "RELEASE INFORMATION" link for the appropriate
15411 release.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015412 </note>
15413 </para>
15414
15415 <para>
15416 The <filename>TCMODE</filename> variable is similar to
15417 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
15418 which controls the variant of the GNU standard C library
15419 (<filename>libc</filename>) used during the build process:
Brad Bishop37a0e4d2017-12-04 01:01:44 -050015420 <filename>glibc</filename> or <filename>musl</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015421 </para>
15422
15423 <para>
15424 With additional layers, it is possible to use a pre-compiled
15425 external toolchain.
15426 One example is the Sourcery G++ Toolchain.
15427 The support for this toolchain resides in the separate
15428 <trademark class='registered'>Mentor Graphics</trademark>
15429 <filename>meta-sourcery</filename> layer at
15430 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
15431 </para>
15432
15433 <para>
15434 The layer's <filename>README</filename> file contains
15435 information on how to use the Sourcery G++ Toolchain as
15436 an external toolchain.
15437 In summary, you must be sure to add the layer to your
15438 <filename>bblayers.conf</filename> file in front of the
15439 <filename>meta</filename> layer and then set the
15440 <filename>EXTERNAL_TOOLCHAIN</filename>
15441 variable in your <filename>local.conf</filename> file
15442 to the location in which you installed the toolchain.
15443 </para>
15444
15445 <para>
15446 The fundamentals used for this example apply to any
15447 external toolchain.
15448 You can use <filename>meta-sourcery</filename> as a
15449 template for adding support for other external toolchains.
15450 </para>
15451 </glossdef>
15452 </glossentry>
15453
15454 <glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>
15455 <info>
15456 TEST_EXPORT_DIR[doc] = "The location the OpenEmbedded build system uses to export tests when the TEST_EXPORT_ONLY variable is set to "1"."
15457 </info>
15458 <glossdef>
15459 <para role="glossdeffirst">
15460<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15461 The location the OpenEmbedded build system uses to export
15462 tests when the
15463 <link linkend='var-TEST_EXPORT_ONLY'><filename>TEST_EXPORT_ONLY</filename></link>
15464 variable is set to "1".
15465 </para>
15466
15467 <para>
15468 The <filename>TEST_EXPORT_DIR</filename> variable defaults
15469 to <filename>"${TMPDIR}/testimage/${PN}"</filename>.
15470 </para>
15471 </glossdef>
15472 </glossentry>
15473
15474 <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>
15475 <info>
15476 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."
15477 </info>
15478 <glossdef>
15479 <para role="glossdeffirst">
15480<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15481 Specifies to export the tests only.
15482 Set this variable to "1" if you do not want to run the
15483 tests but you want them to be exported in a manner that
15484 you to run them outside of the build system.
15485 </para>
15486 </glossdef>
15487 </glossentry>
15488
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015489 <glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm>
15490 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040015491 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 -050015492 </info>
15493 <glossdef>
15494 <para role="glossdeffirst">
15495<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15496 Holds the SSH log and the boot log for QEMU machines.
15497 The <filename>TEST_LOG_DIR</filename> variable defaults
15498 to <filename>"${WORKDIR}/testimage"</filename>.
15499 <note>
15500 Actual test results reside in the task log
15501 (<filename>log.do_testimage</filename>), which is in
15502 the <filename>${WORKDIR}/temp/</filename> directory.
15503 </note>
15504 </para>
15505 </glossdef>
15506 </glossentry>
15507
15508 <glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm>TEST_POWERCONTROL_CMD</glossterm>
15509 <info>
15510 TEST_POWERCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to control the power of the target machine under test"
15511 </info>
15512 <glossdef>
15513 <para role="glossdeffirst">
15514<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15515 For automated hardware testing, specifies the command to
15516 use to control the power of the target machine under test.
15517 Typically, this command would point to a script that
15518 performs the appropriate action (e.g. interacting
15519 with a web-enabled power strip).
15520 The specified command should expect to receive as the last
15521 argument "off", "on" or "cycle" specifying to power off,
15522 on, or cycle (power off and then power on) the device,
15523 respectively.
15524 </para>
15525 </glossdef>
15526 </glossentry>
15527
15528 <glossentry id='var-TEST_POWERCONTROL_EXTRA_ARGS'><glossterm>TEST_POWERCONTROL_EXTRA_ARGS</glossterm>
15529 <info>
15530 TEST_POWERCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_POWERCONTROL_CMD"
15531 </info>
15532 <glossdef>
15533 <para role="glossdeffirst">
15534<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15535 For automated hardware testing, specifies additional
15536 arguments to pass through to the command specified in
15537 <link linkend='var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></link>.
15538 Setting <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
15539 is optional.
15540 You can use it if you wish, for example, to separate the
15541 machine-specific and non-machine-specific parts of the
15542 arguments.
15543 </para>
15544 </glossdef>
15545 </glossentry>
15546
15547 <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
15548 <info>
15549 TEST_QEMUBOOT_TIMEOUT[doc] = "The time in seconds allowed for an image to boot before automated runtime tests begin to run against an image."
15550 </info>
15551 <glossdef>
15552 <para role="glossdeffirst">
15553<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15554 The time in seconds allowed for an image to boot before
15555 automated runtime tests begin to run against an
15556 image.
15557 The default timeout period to allow the boot process to
15558 reach the login prompt is 500 seconds.
15559 You can specify a different value in the
15560 <filename>local.conf</filename> file.
15561 </para>
15562
15563 <para>
15564 For more information on testing images, see the
15565 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015566 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015567 </para>
15568 </glossdef>
15569 </glossentry>
15570
15571 <glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm>TEST_SERIALCONTROL_CMD</glossterm>
15572 <info>
15573 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."
15574 </info>
15575 <glossdef>
15576 <para role="glossdeffirst">
15577<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15578 For automated hardware testing, specifies the command
15579 to use to connect to the serial console of the target
15580 machine under test.
15581 This command simply needs to connect to the serial console
15582 and forward that connection to standard input and output
15583 as any normal terminal program does.
15584 </para>
15585
15586 <para>
15587 For example, to use the Picocom terminal program on
15588 serial device <filename>/dev/ttyUSB0</filename> at
15589 115200bps, you would set the variable as follows:
15590 <literallayout class='monospaced'>
15591 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
15592 </literallayout>
15593 </para>
15594 </glossdef>
15595 </glossentry>
15596
15597 <glossentry id='var-TEST_SERIALCONTROL_EXTRA_ARGS'><glossterm>TEST_SERIALCONTROL_EXTRA_ARGS</glossterm>
15598 <info>
15599 TEST_SERIALCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_SERIALCONTROL_CMD."
15600 </info>
15601 <glossdef>
15602 <para role="glossdeffirst">
15603<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15604 For automated hardware testing, specifies additional
15605 arguments to pass through to the command specified in
15606 <link linkend='var-TEST_SERIALCONTROL_CMD'><filename>TEST_SERIALCONTROL_CMD</filename></link>.
15607 Setting <filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename>
15608 is optional.
15609 You can use it if you wish, for example, to separate the
15610 machine-specific and non-machine-specific parts of the
15611 command.
15612 </para>
15613 </glossdef>
15614 </glossentry>
15615
15616 <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>
15617 <info>
15618 TEST_SERVER_IP[doc] = "The IP address of the build machine (host machine). This IP address is usually automatically detected."
15619 </info>
15620 <glossdef>
15621 <para role="glossdeffirst">
15622<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15623 The IP address of the build machine (host machine).
15624 This IP address is usually automatically detected.
15625 However, if detection fails, this variable needs to be set
15626 to the IP address of the build machine (i.e. where
15627 the build is taking place).
15628 <note>
15629 The <filename>TEST_SERVER_IP</filename> variable
15630 is only used for a small number of tests such as
Brad Bishop6e60e8b2018-02-01 10:27:11 -050015631 the "dnf" test suite, which needs to download
15632 packages from
15633 <filename>WORKDIR/oe-rootfs-repo</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015634 </note>
15635 </para>
15636 </glossdef>
15637 </glossentry>
15638
15639 <glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>
15640 <info>
15641 TEST_TARGET[doc] = "For automated runtime testing, specifies the method of deploying the image and running tests on the target machine."
15642 </info>
15643 <glossdef>
15644 <para role="glossdeffirst">
15645<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15646 Specifies the target controller to use when running tests
15647 against a test image.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015648 The default controller to use is "QemuTarget":
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015649 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015650 TEST_TARGET = "QemuTarget"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015651 </literallayout>
15652 </para>
15653
15654 <para>
15655 A target controller is a class that defines how an
15656 image gets deployed on a target and how a target is started.
15657 A layer can extend the controllers by adding a module
15658 in the layer's <filename>/lib/oeqa/controllers</filename>
15659 directory and by inheriting the
15660 <filename>BaseTarget</filename> class, which is an abstract
15661 class that cannot be used as a value of
15662 <filename>TEST_TARGET</filename>.
15663 </para>
15664
15665 <para>
15666 You can provide the following arguments with
15667 <filename>TEST_TARGET</filename>:
15668 <itemizedlist>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015669 <listitem><para><emphasis>"QemuTarget":</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015670 Boots a QEMU image and runs the tests.
15671 See the
15672 "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015673 section in the Yocto Project Development Tasks
15674 Manual for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015675 </para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015676 <listitem><para><emphasis>"SimpleRemoteTarget":</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015677 Runs the tests on target hardware that is already
15678 up and running.
15679 The hardware can be on the network or it can be
15680 a device running an image on QEMU.
15681 You must also set
15682 <link linkend='var-TEST_TARGET_IP'><filename>TEST_TARGET_IP</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015683 when you use "SimpleRemoteTarget".
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015684 <note>
15685 This argument is defined in
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015686 <filename>meta/lib/oeqa/controllers/simpleremote.py</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015687 </note>
15688 </para></listitem>
15689 </itemizedlist>
15690 </para>
15691
15692 <para>
15693 For information on running tests on hardware, see the
15694 "<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015695 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015696 </para>
15697 </glossdef>
15698 </glossentry>
15699
15700 <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>
15701 <info>
15702 TEST_TARGET_IP[doc] = "The IP address of your hardware under test."
15703 </info>
15704 <glossdef>
15705 <para role="glossdeffirst">
15706<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15707 The IP address of your hardware under test.
15708 The <filename>TEST_TARGET_IP</filename> variable has no
15709 effect when
15710 <link linkend='var-TEST_TARGET'><filename>TEST_TARGET</filename></link>
15711 is set to "qemu".
15712 </para>
15713
15714 <para>
15715 When you specify the IP address, you can also include a
15716 port.
15717 Here is an example:
15718 <literallayout class='monospaced'>
15719 TEST_TARGET_IP = "192.168.1.4:2201"
15720 </literallayout>
15721 Specifying a port is useful when SSH is started on a
15722 non-standard port or in cases when your hardware under test
15723 is behind a firewall or network that is not directly
15724 accessible from your host and you need to do port address
15725 translation.
15726 </para>
15727 </glossdef>
15728 </glossentry>
15729
15730 <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
15731 <info>
15732 TEST_SUITES[doc] = "An ordered list of tests (modules) to run against an image when performing automated runtime testing."
15733 </info>
15734 <glossdef>
15735 <para role="glossdeffirst">
15736<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15737 An ordered list of tests (modules) to run against
15738 an image when performing automated runtime testing.
15739 </para>
15740
15741 <para>
15742 The OpenEmbedded build system provides a core set of tests
15743 that can be used against images.
15744 <note>
15745 Currently, there is only support for running these tests
15746 under QEMU.
15747 </note>
15748 Tests include <filename>ping</filename>,
15749 <filename>ssh</filename>, <filename>df</filename> among
15750 others.
15751 You can add your own tests to the list of tests by
15752 appending <filename>TEST_SUITES</filename> as follows:
15753 <literallayout class='monospaced'>
15754 TEST_SUITES_append = " <replaceable>mytest</replaceable>"
15755 </literallayout>
15756 Alternatively, you can provide the "auto" option to
15757 have all applicable tests run against the image.
15758 <literallayout class='monospaced'>
15759 TEST_SUITES_append = " auto"
15760 </literallayout>
15761 Using this option causes the build system to automatically
15762 run tests that are applicable to the image.
15763 Tests that are not applicable are skipped.
15764 </para>
15765
15766 <para>
15767 The order in which tests are run is important.
15768 Tests that depend on another test must appear later in the
15769 list than the test on which they depend.
15770 For example, if you append the list of tests with two
15771 tests (<filename>test_A</filename> and
15772 <filename>test_B</filename>) where
15773 <filename>test_B</filename> is dependent on
15774 <filename>test_A</filename>, then you must order the tests
15775 as follows:
15776 <literallayout class='monospaced'>
15777 TEST_SUITES = " test_A test_B"
15778 </literallayout>
15779 </para>
15780
15781 <para>
15782 For more information on testing images, see the
15783 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015784 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015785 </para>
15786 </glossdef>
15787 </glossentry>
15788
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015789 <glossentry id='var-TESTIMAGE_AUTO'><glossterm>TESTIMAGE_AUTO</glossterm>
15790 <info>
15791 TESTIMAGE_AUTO[doc] = "Enables automatic testing of an image once it is built."
15792 </info>
15793 <glossdef>
15794 <para role="glossdeffirst">
15795<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15796 Automatically runs the series of automated tests for
15797 images when an image is successfully built.
15798 Setting <filename>TESTIMAGE_AUTO</filename> to "1"
15799 causes any image that successfully builds to automatically
15800 boot under QEMU.
15801 Using the variable also adds in dependencies so that any
15802 SDK for which testing is requested is automatically built
15803 first.
15804 </para>
15805
15806 <para>
15807 These tests are written in Python making use of the
15808 <filename>unittest</filename> module, and the majority of
15809 them run commands on the target system over
15810 <filename>ssh</filename>.
15811 You can set this variable to "1" in your
15812 <filename>local.conf</filename> file in the
15813 <link linkend='build-directory'>Build Directory</link>
15814 to have the OpenEmbedded build system automatically run
15815 these tests after an image successfully builds:
15816 <literallayout class='monospaced'>
15817 TESTIMAGE_AUTO = "1"
15818 </literallayout>
15819 For more information on enabling, running, and writing
15820 these tests, see the
15821 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
15822 section in the Yocto Project Development Tasks Manual and
15823 the
15824 "<link linkend='ref-classes-testimage*'><filename>testimage*.bbclass</filename></link>"
15825 section.
15826 </para>
15827 </glossdef>
15828 </glossentry>
15829
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015830 <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
15831 <info>
15832 THISDIR[doc] = "The directory in which the file BitBake is currently parsing is located."
15833 </info>
15834 <glossdef>
15835 <para role="glossdeffirst">
15836<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15837 The directory in which the file BitBake is currently
15838 parsing is located.
15839 Do not manually set this variable.
15840 </para>
15841 </glossdef>
15842 </glossentry>
15843
15844 <glossentry id='var-TIME'><glossterm>TIME</glossterm>
15845 <info>
15846 TIME[doc] = "The time the build was started using HMS format."
15847 </info>
15848 <glossdef>
15849 <para role="glossdeffirst">
15850<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15851 The time the build was started.
15852 Times appear using the hour, minute, and second (HMS)
15853 format (e.g. "140159" for one minute and fifty-nine
15854 seconds past 1400 hours).
15855 </para>
15856 </glossdef>
15857 </glossentry>
15858
15859 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
15860 <info>
15861 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."
15862 </info>
15863 <glossdef>
15864 <para role="glossdeffirst">
15865<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15866 This variable is the base directory the OpenEmbedded
15867 build system uses for all build output and intermediate
15868 files (other than the shared state cache).
15869 By default, the <filename>TMPDIR</filename> variable points
15870 to <filename>tmp</filename> within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015871 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015872 </para>
15873
15874 <para>
15875 If you want to establish this directory in a location other
15876 than the default, you can uncomment and edit the following
15877 statement in the
15878 <filename>conf/local.conf</filename> file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015879 <link linkend='source-directory'>Source Directory</link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015880 <literallayout class='monospaced'>
15881 #TMPDIR = "${TOPDIR}/tmp"
15882 </literallayout>
15883 An example use for this scenario is to set
15884 <filename>TMPDIR</filename> to a local disk, which does
15885 not use NFS, while having the Build Directory use NFS.
15886 </para>
15887
15888 <para>
15889 The filesystem used by <filename>TMPDIR</filename> must
15890 have standard filesystem semantics (i.e. mixed-case files
15891 are unique, POSIX file locking, and persistent inodes).
15892 Due to various issues with NFS and bugs in some
15893 implementations, NFS does not meet this minimum
15894 requirement.
15895 Consequently, <filename>TMPDIR</filename> cannot be on
15896 NFS.
15897 </para>
15898 </glossdef>
15899 </glossentry>
15900
15901 <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
15902 <info>
15903 TOOLCHAIN_HOST_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when building an SDK, which contains a cross-development environment."
15904 </info>
15905 <glossdef>
15906 <para role="glossdeffirst">
15907<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15908 This variable lists packages the OpenEmbedded build system
15909 uses when building an SDK, which contains a
15910 cross-development environment.
15911 The packages specified by this variable are part of the
15912 toolchain set that runs on the
15913 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
15914 and each package should usually have the prefix
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015915 <filename>nativesdk-</filename>.
15916 For example, consider the following command when
15917 building an SDK:
15918 <literallayout class='monospaced'>
15919 $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
15920 </literallayout>
15921 In this case, a default list of packages is set in this
15922 variable, but you can add additional packages to the list.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050015923 See the
15924 "<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 -050015925 section in the Yocto Project Application Development and
15926 the Extensible Software Development Kit (eSDK) manual
15927 for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015928 </para>
15929
15930 <para>
15931 For background information on cross-development toolchains
15932 in the Yocto Project development environment, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040015933 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
15934 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015935 For information on setting up a cross-development
15936 environment, see the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015937 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
15938 manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015939 </para>
15940 </glossdef>
15941 </glossentry>
15942
15943 <glossentry id='var-TOOLCHAIN_OUTPUTNAME'><glossterm>TOOLCHAIN_OUTPUTNAME</glossterm>
15944 <info>
15945 TOOLCHAIN_OUTPUTNAME[doc] = "Defines the name used for the toolchain output."
15946 </info>
15947 <glossdef>
15948 <para role="glossdeffirst">
15949<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15950 This variable defines the name used for the toolchain
15951 output.
15952 The
15953 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
15954 class sets the
15955 <filename>TOOLCHAIN_OUTPUTNAME</filename> variable as
15956 follows:
15957 <literallayout class='monospaced'>
15958 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"
15959 </literallayout>
15960 See the
15961 <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
15962 and
15963 <link linkend='var-SDK_VERSION'><filename>SDK_VERSION</filename></link>
15964 variables for additional information.
15965 </para>
15966 </glossdef>
15967 </glossentry>
15968
15969 <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
15970 <info>
15971 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."
15972 </info>
15973 <glossdef>
15974 <para role="glossdeffirst">
15975<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15976 This variable lists packages the OpenEmbedded build system
15977 uses when it creates the target part of an SDK
15978 (i.e. the part built for the target hardware), which
15979 includes libraries and headers.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050015980 Use this variable to add individual packages to the
15981 part of the SDK that runs on the target.
15982 See the
15983 "<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 -050015984 section in the Yocto Project Application Development and
15985 the Extensible Software Development Kit (eSDK) manual for
15986 more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015987 </para>
15988
15989 <para>
15990 For background information on cross-development toolchains
15991 in the Yocto Project development environment, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040015992 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
15993 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015994 For information on setting up a cross-development
15995 environment, see the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015996 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
15997 manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015998 </para>
15999 </glossdef>
16000 </glossentry>
16001
16002 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
16003 <info>
16004 TOPDIR[doc] = "The Build Directory. BitBake automatically sets this variable. The OpenEmbedded build system uses the Build Directory when building images."
16005 </info>
16006 <glossdef>
16007 <para role="glossdeffirst">
16008<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16009 The top-level
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016010 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016011 BitBake automatically sets this variable when you
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016012 initialize your build environment using
16013 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016014 </para>
16015 </glossdef>
16016 </glossentry>
16017
16018 <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
16019 <info>
16020 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."
16021 </info>
16022 <glossdef>
16023 <para role="glossdeffirst">
16024<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16025 A sanitized version of
16026 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
16027 This variable is used where the architecture is needed in
16028 a value where underscores are not allowed, for example
16029 within package filenames.
16030 In this case, dash characters replace any underscore
Brad Bishop316dfdd2018-06-25 12:45:53 -040016031 characters used in <filename>TARGET_ARCH</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016032 </para>
16033
16034 <para>
16035 Do not edit this variable.
16036 </para>
16037 </glossdef>
16038 </glossentry>
16039
16040 <glossentry id='var-TUNE_ARCH'><glossterm>TUNE_ARCH</glossterm>
16041 <info>
16042 TUNE_ARCH[doc] = "The GNU canonical architecture for a specific architecture (i.e. arm, armeb, mips, mips64, and so forth)."
16043 </info>
16044 <glossdef>
16045 <para role="glossdeffirst">
16046<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16047 The GNU canonical architecture for a specific architecture
16048 (i.e. <filename>arm</filename>,
16049 <filename>armeb</filename>,
16050 <filename>mips</filename>,
16051 <filename>mips64</filename>, and so forth).
16052 BitBake uses this value to setup configuration.
16053 </para>
16054
16055 <para>
16056 <filename>TUNE_ARCH</filename> definitions are specific to
16057 a given architecture.
16058 The definitions can be a single static definition, or
16059 can be dynamically adjusted.
16060 You can see details for a given CPU family by looking at
16061 the architecture's <filename>README</filename> file.
16062 For example, the
16063 <filename>meta/conf/machine/include/mips/README</filename>
16064 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016065 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016066 provides information for <filename>TUNE_ARCH</filename>
16067 specific to the <filename>mips</filename> architecture.
16068 </para>
16069
16070 <para>
16071 <filename>TUNE_ARCH</filename> is tied closely to
16072 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
16073 which defines the target machine's architecture.
16074 The BitBake configuration file
16075 (<filename>meta/conf/bitbake.conf</filename>) sets
16076 <filename>TARGET_ARCH</filename> as follows:
16077 <literallayout class='monospaced'>
16078 TARGET_ARCH = "${TUNE_ARCH}"
16079 </literallayout>
16080 </para>
16081
16082 <para>
16083 The following list, which is by no means complete since
16084 architectures are configurable, shows supported machine
16085 architectures:
16086 <literallayout class='monospaced'>
16087 arm
16088 i586
16089 x86_64
16090 powerpc
16091 powerpc64
16092 mips
16093 mipsel
16094 </literallayout>
16095 </para>
16096 </glossdef>
16097 </glossentry>
16098
16099 <glossentry id='var-TUNE_ASARGS'><glossterm>TUNE_ASARGS</glossterm>
16100 <info>
16101 TUNE_ASARGS[doc] = "Specifies architecture-specific assembler flags for the target system."
16102 </info>
16103 <glossdef>
16104 <para role="glossdeffirst">
16105<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16106 Specifies architecture-specific assembler flags for
16107 the target system.
16108 The set of flags is based on the selected tune features.
16109 <filename>TUNE_ASARGS</filename> is set using
16110 the tune include files, which are typically under
16111 <filename>meta/conf/machine/include/</filename> and are
16112 influenced through
16113 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
16114 For example, the
16115 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
16116 file defines the flags for the x86 architecture as follows:
16117 <literallayout class='monospaced'>
16118 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
16119 </literallayout>
16120 <note>
16121 Board Support Packages (BSPs) select the tune.
16122 The selected tune, in turn, affects the tune variables
16123 themselves (i.e. the tune can supply its own
16124 set of flags).
16125 </note>
16126 </para>
16127 </glossdef>
16128 </glossentry>
16129
16130 <glossentry id='var-TUNE_CCARGS'><glossterm>TUNE_CCARGS</glossterm>
16131 <info>
16132 TUNE_CCARGS[doc] = "Specifies architecture-specific C compiler flags for the target system."
16133 </info>
16134 <glossdef>
16135 <para role="glossdeffirst">
16136<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16137 Specifies architecture-specific C compiler flags for
16138 the target system.
16139 The set of flags is based on the selected tune features.
16140 <filename>TUNE_CCARGS</filename> is set using
16141 the tune include files, which are typically under
16142 <filename>meta/conf/machine/include/</filename> and are
16143 influenced through
16144 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
16145 <note>
16146 Board Support Packages (BSPs) select the tune.
16147 The selected tune, in turn, affects the tune variables
16148 themselves (i.e. the tune can supply its own
16149 set of flags).
16150 </note>
16151 </para>
16152 </glossdef>
16153 </glossentry>
16154
16155 <glossentry id='var-TUNE_LDARGS'><glossterm>TUNE_LDARGS</glossterm>
16156 <info>
16157 TUNE_LDARGS[doc] = "Specifies architecture-specific linker flags for the target system."
16158 </info>
16159 <glossdef>
16160 <para role="glossdeffirst">
16161<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16162 Specifies architecture-specific linker flags for
16163 the target system.
16164 The set of flags is based on the selected tune features.
16165 <filename>TUNE_LDARGS</filename> is set using
16166 the tune include files, which are typically under
16167 <filename>meta/conf/machine/include/</filename> and are
16168 influenced through
16169 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
16170 For example, the
16171 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
16172 file defines the flags for the x86 architecture as follows:
16173 <literallayout class='monospaced'>
16174 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
16175 </literallayout>
16176 <note>
16177 Board Support Packages (BSPs) select the tune.
16178 The selected tune, in turn, affects the tune variables
16179 themselves (i.e. the tune can supply its own
16180 set of flags).
16181 </note>
16182 </para>
16183 </glossdef>
16184 </glossentry>
16185
16186 <glossentry id='var-TUNE_FEATURES'><glossterm>TUNE_FEATURES</glossterm>
16187 <info>
16188 TUNE_FEATURES[doc] = "Features used to "tune" a compiler for optimal use given a specific processor."
16189 </info>
16190 <glossdef>
16191 <para role="glossdeffirst">
16192<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16193 Features used to "tune" a compiler for optimal use
16194 given a specific processor.
16195 The features are defined within the tune files and allow
16196 arguments (i.e. <filename>TUNE_*ARGS</filename>) to be
16197 dynamically generated based on the features.
16198 </para>
16199
16200 <para>
16201 The OpenEmbedded build system verifies the features
16202 to be sure they are not conflicting and that they are
16203 supported.
16204 </para>
16205
16206 <para>
16207 The BitBake configuration file
16208 (<filename>meta/conf/bitbake.conf</filename>) defines
16209 <filename>TUNE_FEATURES</filename> as follows:
16210 <literallayout class='monospaced'>
16211 TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}"
16212 </literallayout>
16213 See the
16214 <link linkend='var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></link>
16215 variable for more information.
16216 </para>
16217 </glossdef>
16218 </glossentry>
16219
16220 <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
16221 <info>
16222 TUNE_PKGARCH[doc] = "The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages."
16223 </info>
16224 <glossdef>
16225 <para role="glossdeffirst">
16226<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16227 The package architecture understood by the packaging
16228 system to define the architecture, ABI, and tuning of
16229 output packages.
16230 The specific tune is defined using the "_tune" override
16231 as follows:
16232 <literallayout class='monospaced'>
16233 TUNE_PKGARCH_tune-<replaceable>tune</replaceable> = "<replaceable>tune</replaceable>"
16234 </literallayout>
16235 </para>
16236
16237 <para>
16238 These tune-specific package architectures are defined in
16239 the machine include files.
16240 Here is an example of the "core2-32" tuning as used
16241 in the
16242 <filename>meta/conf/machine/include/tune-core2.inc</filename>
16243 file:
16244 <literallayout class='monospaced'>
16245 TUNE_PKGARCH_tune-core2-32 = "core2-32"
16246 </literallayout>
16247 </para>
16248 </glossdef>
16249 </glossentry>
16250
16251 <glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm>
16252 <info>
16253 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."
16254 </info>
16255 <glossdef>
16256 <para role="glossdeffirst">
16257<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16258 An underlying Application Binary Interface (ABI) used by
16259 a particular tuning in a given toolchain layer.
16260 Providers that use prebuilt libraries can use the
16261 <filename>TUNEABI</filename>,
16262 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
16263 and
16264 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
16265 variables to check compatibility of tunings against their
16266 selection of libraries.
16267 </para>
16268
16269 <para>
16270 If <filename>TUNEABI</filename> is undefined, then every
16271 tuning is allowed.
16272 See the
16273 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
16274 class to see how the variable is used.
16275 </para>
16276 </glossdef>
16277 </glossentry>
16278
16279 <glossentry id='var-TUNEABI_OVERRIDE'><glossterm>TUNEABI_OVERRIDE</glossterm>
16280 <info>
16281 TUNEABI_OVERRIDE[doc] = "If set, ignores TUNEABI_WHITELIST."
16282 </info>
16283 <glossdef>
16284 <para role="glossdeffirst">
16285<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16286 If set, the OpenEmbedded system ignores the
16287 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
16288 variable.
16289 Providers that use prebuilt libraries can use the
16290 <filename>TUNEABI_OVERRIDE</filename>,
16291 <filename>TUNEABI_WHITELIST</filename>,
16292 and
16293 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
16294 variables to check compatibility of a tuning against their
16295 selection of libraries.
16296 </para>
16297
16298 <para>
16299 See the
16300 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
16301 class to see how the variable is used.
16302 </para>
16303 </glossdef>
16304 </glossentry>
16305
16306 <glossentry id='var-TUNEABI_WHITELIST'><glossterm>TUNEABI_WHITELIST</glossterm>
16307 <info>
16308 TUNEABI_WHITELIST[doc] = "A whitelist of permissible TUNEABI values. If the variable is not set, all values are allowed."
16309 </info>
16310 <glossdef>
16311 <para role="glossdeffirst">
16312<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16313 A whitelist of permissible
16314 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
16315 values.
16316 If <filename>TUNEABI_WHITELIST</filename> is not set,
16317 all tunes are allowed.
16318 Providers that use prebuilt libraries can use the
16319 <filename>TUNEABI_WHITELIST</filename>,
16320 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
16321 and <filename>TUNEABI</filename> variables to check
16322 compatibility of a tuning against their selection of
16323 libraries.
16324 </para>
16325
16326 <para>
16327 See the
16328 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
16329 class to see how the variable is used.
16330 </para>
16331 </glossdef>
16332 </glossentry>
16333
16334 <glossentry id='var-TUNECONFLICTS'><glossterm>TUNECONFLICTS[<replaceable>feature</replaceable>]</glossterm>
16335 <info>
16336 TUNECONFLICTS[doc] = "Specifies CPU or Application Binary Interface (ABI) tuning features that conflict with specified feature."
16337 </info>
16338 <glossdef>
16339 <para role="glossdeffirst">
16340<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16341 Specifies CPU or Application Binary Interface (ABI)
16342 tuning features that conflict with <replaceable>feature</replaceable>.
16343 </para>
16344
16345 <para>
16346 Known tuning conflicts are specified in the machine include
16347 files in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016348 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016349 Here is an example from the
16350 <filename>meta/conf/machine/include/mips/arch-mips.inc</filename>
16351 include file that lists the "o32" and "n64" features as
16352 conflicting with the "n32" feature:
16353 <literallayout class='monospaced'>
16354 TUNECONFLICTS[n32] = "o32 n64"
16355 </literallayout>
16356 </para>
16357 </glossdef>
16358 </glossentry>
16359
16360 <glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[<replaceable>feature</replaceable>]</glossterm>
16361 <info>
16362 TUNEVALID[doc] = "Descriptions, stored as flags, of valid tuning features."
16363 </info>
16364 <glossdef>
16365 <para role="glossdeffirst">
16366<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16367 Specifies a valid CPU or Application Binary Interface (ABI)
16368 tuning feature.
16369 The specified feature is stored as a flag.
16370 Valid features are specified in the machine include files
16371 (e.g. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>).
16372 Here is an example from that file:
16373 <literallayout class='monospaced'>
16374 TUNEVALID[bigendian] = "Enable big-endian mode."
16375 </literallayout>
16376 </para>
16377
16378 <para>
16379 See the machine include files in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016380 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016381 for these features.
16382 </para>
16383 </glossdef>
16384 </glossentry>
16385
16386 </glossdiv>
16387
16388 <glossdiv id='var-glossary-u'><title>U</title>
16389
16390 <glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm>
16391 <info>
16392 UBOOT_CONFIG[doc] = "Configures the UBOOT_MACHINE and can also define IMAGE_FSTYPES for individual cases."
16393 </info>
16394 <glossdef>
16395 <para role="glossdeffirst">
16396<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16397 Configures the
16398 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
16399 and can also define
16400 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
16401 for individual cases.
16402 </para>
16403
16404 <para>
16405 Following is an example from the
16406 <filename>meta-fsl-arm</filename> layer.
16407 <literallayout class='monospaced'>
16408 UBOOT_CONFIG ??= "sd"
16409 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
16410 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
16411 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
16412 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
16413 </literallayout>
16414 In this example, "sd" is selected as the configuration
16415 of the possible four for the
16416 <filename>UBOOT_MACHINE</filename>.
16417 The "sd" configuration defines "mx6qsabreauto_config"
16418 as the value for <filename>UBOOT_MACHINE</filename>, while
16419 the "sdcard" specifies the
16420 <filename>IMAGE_FSTYPES</filename> to use for the U-boot
16421 image.
16422 </para>
16423
16424 <para>
16425 For more information on how the
16426 <filename>UBOOT_CONFIG</filename> is handled, see the
16427 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass'><filename>uboot-config</filename></ulink>
16428 class.
16429 </para>
16430 </glossdef>
16431 </glossentry>
16432
16433 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
16434 <info>
16435 UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image."
16436 </info>
16437 <glossdef>
16438 <para role="glossdeffirst">
16439<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16440 Specifies the entry point for the U-Boot image.
16441 During U-Boot image creation, the
16442 <filename>UBOOT_ENTRYPOINT</filename> variable is passed
16443 as a command-line parameter to the
16444 <filename>uboot-mkimage</filename> utility.
16445 </para>
16446 </glossdef>
16447 </glossentry>
16448
16449 <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
16450 <info>
16451 UBOOT_LOADADDRESS[doc] = "Specifies the load address for the U-Boot image."
16452 </info>
16453 <glossdef>
16454 <para role="glossdeffirst">
16455<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16456 Specifies the load address for the U-Boot image.
16457 During U-Boot image creation, the
16458 <filename>UBOOT_LOADADDRESS</filename> variable is passed
16459 as a command-line parameter to the
16460 <filename>uboot-mkimage</filename> utility.
16461 </para>
16462 </glossdef>
16463 </glossentry>
16464
16465 <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>
16466 <info>
16467 UBOOT_LOCALVERSION[doc] = "Appends a string to the name of the local version of the U-Boot image."
16468 </info>
16469 <glossdef>
16470 <para role="glossdeffirst">
16471<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16472 Appends a string to the name of the local version of the
16473 U-Boot image.
16474 For example, assuming the version of the U-Boot image
16475 built was "2013.10, the full version string reported by
16476 U-Boot would be "2013.10-yocto" given the following
16477 statement:
16478 <literallayout class='monospaced'>
16479 UBOOT_LOCALVERSION = "-yocto"
16480 </literallayout>
16481 </para>
16482 </glossdef>
16483 </glossentry>
16484
16485 <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
16486 <info>
16487 UBOOT_MACHINE[doc] = "Specifies the value passed on the make command line when building a U-Boot image."
16488 </info>
16489 <glossdef>
16490 <para role="glossdeffirst">
16491<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16492 Specifies the value passed on the
16493 <filename>make</filename> command line when building
16494 a U-Boot image.
16495 The value indicates the target platform configuration.
16496 You typically set this variable from the machine
16497 configuration file (i.e.
16498 <filename>conf/machine/<replaceable>machine_name</replaceable>.conf</filename>).
16499 </para>
16500
16501 <para>
16502 Please see the "Selection of Processor Architecture and
16503 Board Type" section in the U-Boot README for valid values
16504 for this variable.
16505 </para>
16506 </glossdef>
16507 </glossentry>
16508
16509 <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm>
16510 <info>
16511 UBOOT_MAKE_TARGET[doc] = "Specifies the target called in the Makefile."
16512 </info>
16513 <glossdef>
16514 <para role="glossdeffirst">
16515<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16516 Specifies the target called in the
16517 <filename>Makefile</filename>.
16518 The default target is "all".
16519 </para>
16520 </glossdef>
16521 </glossentry>
16522
16523 <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>
16524 <info>
16525 UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension."
16526 </info>
16527 <glossdef>
16528 <para role="glossdeffirst">
16529<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16530 Points to the generated U-Boot extension.
16531 For example, <filename>u-boot.sb</filename> has a
16532 <filename>.sb</filename> extension.
16533 </para>
16534
16535 <para>
16536 The default U-Boot extension is
16537 <filename>.bin</filename>
16538 </para>
16539 </glossdef>
16540 </glossentry>
16541
16542 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
16543 <info>
16544 UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot."
16545 </info>
16546 <glossdef>
16547 <para role="glossdeffirst">
16548<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16549 Specifies the target used for building U-Boot.
16550 The target is passed directly as part of the "make" command
16551 (e.g. SPL and AIS).
16552 If you do not specifically set this variable, the
16553 OpenEmbedded build process passes and uses "all" for the
16554 target during the U-Boot building process.
16555 </para>
16556 </glossdef>
16557 </glossentry>
16558
16559 <glossentry id='var-UNKNOWN_CONFIGURE_WHITELIST'><glossterm>UNKNOWN_CONFIGURE_WHITELIST</glossterm>
16560 <info>
16561 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."
16562 </info>
16563 <glossdef>
16564 <para role="glossdeffirst">
16565<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16566 Specifies a list of options that, if reported by the
16567 configure script as being invalid, should not generate a
16568 warning during the
16569 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
16570 task.
16571 Normally, invalid configure options are simply not passed
16572 to the configure script (e.g. should be removed from
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016573 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
16574 or
16575 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>).
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016576 However, common options, for example, exist that are passed
16577 to all configure scripts at a class level that might not
16578 be valid for some configure scripts.
16579 It follows that no benefit exists in seeing a warning about
16580 these options.
16581 For these cases, the options are added to
16582 <filename>UNKNOWN_CONFIGURE_WHITELIST</filename>.
16583 </para>
16584
16585 <para>
16586 The configure arguments check that uses
16587 <filename>UNKNOWN_CONFIGURE_WHITELIST</filename> is part
16588 of the
16589 <link linkend='ref-classes-insane'><filename>insane</filename></link>
16590 class and is only enabled if the recipe inherits the
16591 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
16592 class.
16593 </para>
16594 </glossdef>
16595 </glossentry>
16596
16597 <glossentry id='var-UPDATERCPN'><glossterm>UPDATERCPN</glossterm>
16598 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040016599 UPDATERCPN[doc] = "Specifies the package that contains the initscript that is enabled."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016600 </info>
16601 <glossdef>
16602 <para role="glossdeffirst">
16603<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16604 For recipes inheriting the
16605 <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
16606 class, <filename>UPDATERCPN</filename> specifies
Brad Bishop316dfdd2018-06-25 12:45:53 -040016607 the package that contains the initscript that is
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016608 enabled.
16609 </para>
16610
16611 <para>
16612 The default value is "${PN}".
16613 Given that almost all recipes that install initscripts
16614 package them in the main package for the recipe, you
16615 rarely need to set this variable in individual recipes.
16616 </para>
16617 </glossdef>
16618 </glossentry>
16619
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016620 <glossentry id='var-UPSTREAM_CHECK_GITTAGREGEX'><glossterm>UPSTREAM_CHECK_GITTAGREGEX</glossterm>
16621 <info>
16622 UPSTREAM_CHECK_GITTAGREGEX[doc] = "Filters relevant Git tags when fetching source from an upstream Git repository."
16623 </info>
16624 <glossdef>
16625 <para role="glossdeffirst">
16626<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop15ae2502019-06-18 21:44:24 -040016627 You can perform a per-recipe check for what the latest
16628 upstream source code version is by calling
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016629 <filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.
16630 If the recipe source code is provided from Git
16631 repositories, the OpenEmbedded build system determines the
16632 latest upstream version by picking the latest tag from the
16633 list of all repository tags.
Brad Bishop15ae2502019-06-18 21:44:24 -040016634 </para>
16635
16636 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016637 You can use the
16638 <filename>UPSTREAM_CHECK_GITTAGREGEX</filename>
16639 variable to provide a regular expression to filter only the
16640 relevant tags should the default filter not work
16641 correctly.
16642 <literallayout class='monospaced'>
16643 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"
16644 </literallayout>
16645 </para>
16646 </glossdef>
16647 </glossentry>
16648
16649 <glossentry id='var-UPSTREAM_CHECK_REGEX'><glossterm>UPSTREAM_CHECK_REGEX</glossterm>
16650 <info>
16651 UPSTREAM_CHECK_REGEX[doc] = "The regular expression the package checking system uses to parse the page pointed to by UPSTREAM_CHECK_URI."
16652 </info>
16653 <glossdef>
16654 <para role="glossdeffirst">
16655<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop15ae2502019-06-18 21:44:24 -040016656 Use the <filename>UPSTREAM_CHECK_REGEX</filename> variable
16657 to specify a different regular expression instead of the
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016658 default one when the package checking system is parsing
16659 the page found using
16660 <link linkend='var-UPSTREAM_CHECK_URI'><filename>UPSTREAM_CHECK_URI</filename></link>.
16661 <literallayout class='monospaced'>
16662 UPSTREAM_CHECK_REGEX = "package_regex"
16663 </literallayout>
16664 </para>
16665 </glossdef>
16666 </glossentry>
16667
16668 <glossentry id='var-UPSTREAM_CHECK_URI'><glossterm>UPSTREAM_CHECK_URI</glossterm>
16669 <info>
16670 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."
16671 </info>
16672 <glossdef>
16673 <para role="glossdeffirst">
16674<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop15ae2502019-06-18 21:44:24 -040016675 You can perform a per-recipe check for what the latest
16676 upstream source code version is by calling
16677 <filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016678 If the source code is provided from tarballs, the latest
16679 version is determined by fetching the directory listing
16680 where the tarball is and attempting to find a later tarball.
16681 When this approach does not work, you can use
16682 <filename>UPSTREAM_CHECK_URI</filename> to
16683 provide a different URI that contains the link to the
16684 latest tarball.
16685 <literallayout class='monospaced'>
16686 UPSTREAM_CHECK_URI = "recipe_url"
16687 </literallayout>
16688 </para>
16689 </glossdef>
16690 </glossentry>
16691
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016692 <glossentry id='var-USE_DEVFS'><glossterm>USE_DEVFS</glossterm>
16693 <info>
16694 USE_DEVFS[doc] = "Determines if devtmpfs is used for /dev population."
16695 </info>
16696 <glossdef>
16697 <para role="glossdeffirst">
16698<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16699 Determines if <filename>devtmpfs</filename> is used for
16700 <filename>/dev</filename> population.
16701 The default value used for <filename>USE_DEVFS</filename>
16702 is "1" when no value is specifically set.
16703 Typically, you would set <filename>USE_DEVFS</filename>
16704 to "0" for a statically populated <filename>/dev</filename>
16705 directory.
16706 </para>
16707
16708 <para>
16709 See the
16710 "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-dev-manager'>Selecting a Device Manager</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016711 section in the Yocto Project Development Tasks Manual for
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016712 information on how to use this variable.
16713 </para>
16714 </glossdef>
16715 </glossentry>
16716
16717 <glossentry id='var-USE_VT'><glossterm>USE_VT</glossterm>
16718 <info>
16719 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."
16720 </info>
16721 <glossdef>
16722 <para role="glossdeffirst">
16723<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16724 When using
16725 <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
16726 determines whether or not to run a
16727 <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
16728 on any virtual terminals in order to enable logging in
16729 through those terminals.
16730 </para>
16731
16732 <para>
16733 The default value used for <filename>USE_VT</filename>
16734 is "1" when no default value is specifically set.
16735 Typically, you would set <filename>USE_VT</filename>
16736 to "0" in the machine configuration file for machines
16737 that do not have a graphical display attached and
16738 therefore do not need virtual terminal functionality.
16739 </para>
16740 </glossdef>
16741 </glossentry>
16742
16743 <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
16744 <info>
16745 USER_CLASSES[doc] = "List of additional classes to use when building images that enable extra features."
16746 </info>
16747 <glossdef>
16748 <para role="glossdeffirst">
16749<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16750 A list of classes to globally inherit.
16751 These classes are used by the OpenEmbedded build system
16752 to enable extra features (e.g.
16753 <filename>buildstats</filename>,
16754 <filename>image-mklibs</filename>, and so forth).
16755 </para>
16756
16757 <para>
16758 The default list is set in your
16759 <filename>local.conf</filename> file:
16760 <literallayout class='monospaced'>
16761 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
16762 </literallayout>
16763 For more information, see
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050016764 <filename>meta-poky/conf/local.conf.sample</filename> in
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016765 the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016766 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016767 </para>
16768 </glossdef>
16769 </glossentry>
16770
16771 <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>
16772 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016773 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 -050016774 </info>
16775 <glossdef>
16776 <para role="glossdeffirst">
16777<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016778 If set to "error", forces the OpenEmbedded build system to
16779 produce an error if the user identification
16780 (<filename>uid</filename>) and group identification
16781 (<filename>gid</filename>) values are not defined
16782 in <filename>files/passwd</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016783 and <filename>files/group</filename> files.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016784 If set to "warn", a warning will be issued instead.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016785 </para>
16786
16787 <para>
16788 The default behavior for the build system is to dynamically
16789 apply <filename>uid</filename> and
16790 <filename>gid</filename> values.
16791 Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>
16792 variable is by default not set.
16793 If you plan on using statically assigned
16794 <filename>gid</filename> and <filename>uid</filename>
16795 values, you should set
16796 the <filename>USERADD_ERROR_DYNAMIC</filename> variable in
16797 your <filename>local.conf</filename> file as
16798 follows:
16799 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016800 USERADD_ERROR_DYNAMIC = "error"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016801 </literallayout>
16802 Overriding the default behavior implies you are going to
16803 also take steps to set static <filename>uid</filename> and
16804 <filename>gid</filename> values through use of the
16805 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
16806 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
16807 and
16808 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
16809 variables.
16810 </para>
16811 </glossdef>
16812 </glossentry>
16813
16814 <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>
16815 <info>
16816 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."
16817 </info>
16818 <glossdef>
16819 <para role="glossdeffirst">
16820<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16821 Specifies a password file to use for obtaining static
16822 group identification (<filename>gid</filename>) values
16823 when the OpenEmbedded build system adds a group to the
16824 system during package installation.
16825 </para>
16826
16827 <para>
16828 When applying static group identification
16829 (<filename>gid</filename>) values, the OpenEmbedded build
16830 system looks in
16831 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
16832 for a <filename>files/group</filename> file and then applies
16833 those <filename>uid</filename> values.
16834 Set the variable as follows in your
16835 <filename>local.conf</filename> file:
16836 <literallayout class='monospaced'>
16837 USERADD_GID_TABLES = "files/group"
16838 </literallayout>
16839 </para>
16840
16841 <note>
16842 Setting the
16843 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
16844 variable to "useradd-staticids" causes the build system
16845 to use static <filename>gid</filename> values.
16846 </note>
16847 </glossdef>
16848 </glossentry>
16849
16850 <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>
16851 <info>
16852 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."
16853 </info>
16854 <glossdef>
16855 <para role="glossdeffirst">
16856<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16857 When inheriting the
16858 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
16859 class, this variable
16860 specifies the individual packages within the recipe that
16861 require users and/or groups to be added.
16862 </para>
16863
16864 <para>
16865 You must set this variable if the recipe inherits the
16866 class.
16867 For example, the following enables adding a user for the
16868 main package in a recipe:
16869 <literallayout class='monospaced'>
16870 USERADD_PACKAGES = "${PN}"
16871 </literallayout>
16872 <note>
Andrew Geissler99467da2019-02-25 18:54:23 -060016873 It follows that if you are going to use the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016874 <filename>USERADD_PACKAGES</filename> variable,
16875 you need to set one or more of the
16876 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
16877 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
16878 or
16879 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
16880 variables.
16881 </note>
16882 </para>
16883
16884 </glossdef>
16885 </glossentry>
16886
16887 <glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>
16888 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040016889 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 -050016890 </info>
16891 <glossdef>
16892 <para role="glossdeffirst">
16893<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16894 When inheriting the
16895 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
16896 class, this variable
Brad Bishop316dfdd2018-06-25 12:45:53 -040016897 specifies for a package what parameters should pass
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016898 to the <filename>useradd</filename> command
Brad Bishop316dfdd2018-06-25 12:45:53 -040016899 if you add a user to the system when the package
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016900 is installed.
16901 </para>
16902
16903 <para>
16904 Here is an example from the <filename>dbus</filename>
16905 recipe:
16906 <literallayout class='monospaced'>
16907 USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \
16908 --no-create-home --shell /bin/false \
16909 --user-group messagebus"
16910 </literallayout>
16911 For information on the standard Linux shell command
16912 <filename>useradd</filename>, see
16913 <ulink url='http://linux.die.net/man/8/useradd'></ulink>.
16914 </para>
16915 </glossdef>
16916 </glossentry>
16917
16918 <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>
16919 <info>
16920 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."
16921 </info>
16922 <glossdef>
16923 <para role="glossdeffirst">
16924<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16925 Specifies a password file to use for obtaining static
16926 user identification (<filename>uid</filename>) values
16927 when the OpenEmbedded build system adds a user to the
16928 system during package installation.
16929 </para>
16930
16931 <para>
16932 When applying static user identification
16933 (<filename>uid</filename>) values, the OpenEmbedded build
16934 system looks in
16935 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
16936 for a <filename>files/passwd</filename> file and then applies
16937 those <filename>uid</filename> values.
16938 Set the variable as follows in your
16939 <filename>local.conf</filename> file:
16940 <literallayout class='monospaced'>
16941 USERADD_UID_TABLES = "files/passwd"
16942 </literallayout>
16943 </para>
16944
16945 <note>
16946 Setting the
16947 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
16948 variable to "useradd-staticids" causes the build system
16949 to use static <filename>uid</filename> values.
16950 </note>
16951 </glossdef>
16952 </glossentry>
16953
16954 <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>
16955 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016956 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 -050016957 </info>
16958 <glossdef>
16959 <para role="glossdeffirst">
16960<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16961 When set to "useradd-staticids", causes the
16962 OpenEmbedded build system to base all user and group
16963 additions on a static
16964 <filename>passwd</filename> and
16965 <filename>group</filename> files found in
16966 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
16967 </para>
16968
16969 <para>
16970 To use static user identification (<filename>uid</filename>)
16971 and group identification (<filename>gid</filename>)
16972 values, set the variable
16973 as follows in your <filename>local.conf</filename> file:
16974 <literallayout class='monospaced'>
16975 USERADDEXTENSION = "useradd-staticids"
16976 </literallayout>
16977 <note>
16978 Setting this variable to use static
16979 <filename>uid</filename> and <filename>gid</filename>
16980 values causes the OpenEmbedded build system to employ
16981 the
Patrick Williamsf1e5d692016-03-30 15:21:19 -050016982 <link linkend='ref-classes-useradd'><filename>useradd-staticids</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016983 class.
16984 </note>
16985 </para>
16986
16987 <para>
16988 If you use static <filename>uid</filename> and
16989 <filename>gid</filename> information, you must also
16990 specify the <filename>files/passwd</filename> and
16991 <filename>files/group</filename> files by setting the
16992 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
16993 and
16994 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
16995 variables.
16996 Additionally, you should also set the
16997 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
16998 variable.
16999 </para>
17000 </glossdef>
17001 </glossentry>
17002
17003 </glossdiv>
17004
Brad Bishop6e60e8b2018-02-01 10:27:11 -050017005 <glossdiv id='var-glossary-v'><title>V</title>
17006
17007 <glossentry id='var-VOLATILE_LOG_DIR'><glossterm>VOLATILE_LOG_DIR</glossterm>
17008 <info>
17009 VOLATILE_LOG_DIR[doc] = "Specifies the persistence of the target's /var/log directory, which is used to house postinstall target log files."
17010 </info>
17011 <glossdef>
17012 <para role="glossdeffirst">
17013<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17014 Specifies the persistence of the target's
17015 <filename>/var/log</filename> directory, which is used to
17016 house postinstall target log files.
17017 </para>
17018
17019 <para>
17020 By default, <filename>VOLATILE_LOG_DIR</filename> is set
17021 to "yes", which means the file is not persistent.
17022 You can override this setting by setting the
17023 variable to "no" to make the log directory persistent.
17024 </para>
17025 </glossdef>
17026 </glossentry>
17027
17028 </glossdiv>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017029
17030 <glossdiv id='var-glossary-w'><title>W</title>
17031
17032 <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
17033 <info>
17034 WARN_QA[doc] = "Specifies the quality assurance checks whose failures are reported as warnings by the OpenEmbedded build system."
17035 </info>
17036 <glossdef>
17037 <para role="glossdeffirst">
17038<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17039 Specifies the quality assurance checks whose failures are
17040 reported as warnings by the OpenEmbedded build system.
17041 You set this variable in your distribution configuration
17042 file.
17043 For a list of the checks you can control with this variable,
17044 see the
17045 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
17046 section.
17047 </para>
17048 </glossdef>
17049 </glossentry>
17050
Brad Bishop6e60e8b2018-02-01 10:27:11 -050017051 <glossentry id='var-WKS_FILE_DEPENDS'><glossterm>WKS_FILE_DEPENDS</glossterm>
17052 <info>
17053 WKS_FILE_DEPENDS[doc] = "Lists a recipe's build-time dependencies specific to Wic."
17054 </info>
17055 <glossdef>
17056 <para role="glossdeffirst">
17057 When placed in the recipe that builds your image, this
17058 variable lists build-time dependencies.
17059 The <filename>WKS_FILE_DEPENDS</filename> variable is only
17060 applicable when Wic images are active (i.e. when
17061 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
17062 contains entries related to Wic).
17063 If your recipe does not create Wic images, the variable
17064 has no effect.
17065 </para>
17066
17067 <para>
17068 The <filename>WKS_FILE_DEPENDS</filename> variable is
17069 similar to the
17070 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
17071 variable.
17072 When you use the variable in your recipe that builds the
17073 Wic image, dependencies you list in the
17074 <filename>WIC_FILE_DEPENDS</filename> variable are added to
17075 the <filename>DEPENDS</filename> variable.
17076 </para>
17077
17078 <para>
17079 With the <filename>WKS_FILE_DEPENDS</filename> variable,
17080 you have the possibility to specify a list of additional
17081 dependencies (e.g. native tools, bootloaders, and so forth),
17082 that are required to build Wic images.
17083 Following is an example:
17084 <literallayout class='monospaced'>
17085 WKS_FILE_DEPENDS = "<replaceable>some-native-tool</replaceable>"
17086 </literallayout>
17087 In the previous example,
17088 <replaceable>some-native-tool</replaceable> would be
17089 replaced with an actual native tool on which the build
17090 would depend.
17091 </para>
17092 </glossdef>
17093 </glossentry>
17094
Brad Bishop37a0e4d2017-12-04 01:01:44 -050017095 <glossentry id='var-WKS_FILE'><glossterm>WKS_FILE</glossterm>
17096 <info>
17097 WKS_FILE[doc] = "Specifies the name of the wic kickstart file."
17098 </info>
17099 <glossdef>
17100 <para role="glossdeffirst">
17101 Specifies the location of the Wic
17102 kickstart file that is used by the OpenEmbedded build
17103 system to create a partitioned image
17104 (<replaceable>image</replaceable><filename>.wic</filename>).
Brad Bishopd7bf8c12018-02-25 22:55:05 -050017105 For information on how to create a partitioned image, see
17106 the
17107 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
17108 section in the Yocto Project Development Tasks Manual.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050017109 For details on the kickstart file format, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040017110 "<link linkend='ref-kickstart'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</link>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050017111 Chapter.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050017112 </para>
17113 </glossdef>
17114 </glossentry>
17115
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017116 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
17117 <info>
17118 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."
17119 </info>
17120 <glossdef>
17121 <para role="glossdeffirst">
17122<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17123 The pathname of the work directory in which the OpenEmbedded
17124 build system builds a recipe.
17125 This directory is located within the
17126 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
17127 directory structure and is specific to the recipe being
17128 built and the system for which it is being built.
17129 </para>
17130
17131 <para>
17132 The <filename>WORKDIR</filename> directory is defined as
17133 follows:
17134 <literallayout class='monospaced'>
17135 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
17136 </literallayout>
17137 The actual directory depends on several things:
17138 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -040017139 <listitem><filename>TMPDIR</filename>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017140 The top-level build output directory</listitem>
17141 <listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>:
17142 The target system identifier</listitem>
17143 <listitem><link linkend='var-PN'><filename>PN</filename></link>:
17144 The recipe name</listitem>
17145 <listitem><link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>:
17146 The epoch - (if
17147 <link linkend='var-PE'><filename>PE</filename></link>
17148 is not specified, which is usually the case for most
17149 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
17150 <listitem><link linkend='var-PV'><filename>PV</filename></link>:
17151 The recipe version</listitem>
17152 <listitem><link linkend='var-PR'><filename>PR</filename></link>:
17153 The recipe revision</listitem>
17154 </itemizedlist>
17155 </para>
17156
17157 <para>
17158 As an example, assume a Source Directory top-level folder
17159 name <filename>poky</filename>, a default Build Directory at
17160 <filename>poky/build</filename>, and a
17161 <filename>qemux86-poky-linux</filename> machine target
17162 system.
17163 Furthermore, suppose your recipe is named
17164 <filename>foo_1.3.0-r0.bb</filename>.
17165 In this case, the work directory the build system uses to
17166 build the package would be as follows:
17167 <literallayout class='monospaced'>
17168 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
17169 </literallayout>
17170 </para>
17171 </glossdef>
17172 </glossentry>
17173
17174 </glossdiv>
17175
17176 <glossdiv id='var-glossary-x'><title>X</title>
17177
17178 <glossentry id='var-XSERVER'><glossterm>XSERVER</glossterm>
17179 <info>
17180 XSERVER[doc] = "Specifies the packages that should be installed
17181 to provide an X server and drivers for the current machine."
17182 </info>
17183 <glossdef>
17184 <para role="glossdeffirst">
17185<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17186 Specifies the packages that should be installed to
17187 provide an X server and drivers for the current machine,
17188 assuming your image directly includes
17189 <filename>packagegroup-core-x11-xserver</filename> or,
17190 perhaps indirectly, includes "x11-base" in
17191 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
17192 </para>
17193
17194 <para>
17195 The default value of <filename>XSERVER</filename>, if not
17196 specified in the machine configuration, is
17197 "xserver-xorg xf86-video-fbdev xf86-input-evdev".
17198 </para>
17199 </glossdef>
17200 </glossentry>
17201
17202 </glossdiv>
17203
17204<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
17205<!-- </glossdiv>-->
17206
17207<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
17208<!-- </glossdiv>-->
17209
17210</glossary>
17211</chapter>
17212<!--
17213vim: expandtab tw=80 ts=4
17214-->