blob: 9f6bc1adad2acb235b0c367c37f19cc79c57d13c [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<!-- Dummy chapter -->
6<chapter id='ref-variables-glos'>
7
8<title>Variables Glossary</title>
9
10<para>
11 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
12 of their function and contents.
13</para>
14
15<glossary id='ref-variables-glossary'>
16
17
18 <para>
19 <link linkend='var-ABIEXTENSION'>A</link>
20 <link linkend='var-B'>B</link>
21 <link linkend='var-CACHE'>C</link>
22 <link linkend='var-D'>D</link>
23 <link linkend='var-EFI_PROVIDER'>E</link>
24 <link linkend='var-FEATURE_PACKAGES'>F</link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040025 <link linkend='var-GCCPIE'>G</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050026 <link linkend='var-HOMEPAGE'>H</link>
27 <link linkend='var-ICECC_DISABLED'>I</link>
28<!-- <link linkend='var-glossary-j'>J</link> -->
29 <link linkend='var-KARCH'>K</link>
30 <link linkend='var-LABELS'>L</link>
31 <link linkend='var-MACHINE'>M</link>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050032 <link linkend='var-NATIVELSBSTRING'>N</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050033 <link linkend='var-OBJCOPY'>O</link>
34 <link linkend='var-P'>P</link>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050035<!-- <link linkend='var-glossary-q'>Q</link> -->
Patrick Williamsc124f4f2015-09-15 14:41:29 -050036 <link linkend='var-RANLIB'>R</link>
37 <link linkend='var-S'>S</link>
38 <link linkend='var-T'>T</link>
39 <link linkend='var-UBOOT_CONFIG'>U</link>
Brad Bishop6e60e8b2018-02-01 10:27:11 -050040 <link linkend='var-VOLATILE_LOG_DIR'>V</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050041 <link linkend='var-WARN_QA'>W</link>
42 <link linkend='var-XSERVER'>X</link>
43<!-- <link linkend='var-glossary-y'>Y</link> -->
44<!-- <link linkend='var-glossary-z'>Z</link>-->
45 </para>
46
47 <glossdiv id='var-glossary-a'><title>A</title>
48
49 <glossentry id='var-ABIEXTENSION'><glossterm>ABIEXTENSION</glossterm>
50 <info>
51 ABIEXTENSION[doc] = "Extension to the Application Binary Interface (ABI) field of the GNU canonical architecture name (e.g. "eabi")."
52 </info>
53 <glossdef>
54 <para role="glossdeffirst">
55<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
56 Extension to the Application Binary Interface (ABI)
57 field of the GNU canonical architecture name
58 (e.g. "eabi").
59 </para>
60
61 <para>
62 ABI extensions are set in the machine include files.
63 For example, the
64 <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>
65 file sets the following extension:
66 <literallayout class='monospaced'>
67 ABIEXTENSION = "eabi"
68 </literallayout>
69 </para>
70 </glossdef>
71 </glossentry>
72
73 <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
74 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040075 ALLOW_EMPTY[doc] = "Specifies whether to produce an output package even if it is empty."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050076 </info>
77 <glossdef>
78 <para role="glossdeffirst">
79<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040080 Specifies whether to produce an output package even if it is
81 empty.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050082 By default, BitBake does not produce empty packages.
83 This default behavior can cause issues when there is an
84 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
85 some other hard runtime requirement on the existence of the package.
86 </para>
87
88 <para>
89 Like all package-controlling variables, you must always use them in
90 conjunction with a package name override, as in:
91 <literallayout class='monospaced'>
92 ALLOW_EMPTY_${PN} = "1"
93 ALLOW_EMPTY_${PN}-dev = "1"
94 ALLOW_EMPTY_${PN}-staticdev = "1"
95 </literallayout>
96 </para>
97 </glossdef>
98 </glossentry>
99
100 <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
101 <info>
102 ALTERNATIVE[doc] = "Lists commands in a package that need an alternative binary naming scheme."
103 </info>
104 <glossdef>
105 <para role="glossdeffirst">
106<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
107 Lists commands in a package that need an alternative
108 binary naming scheme.
109 Sometimes the same command is provided in multiple packages.
110 When this occurs, the OpenEmbedded build system needs to
111 use the alternatives system to create a different binary
112 naming scheme so the commands can co-exist.
113 </para>
114
115 <para>
116 To use the variable, list out the package's commands
117 that also exist as part of another package.
118 For example, if the <filename>busybox</filename> package
119 has four commands that also exist as part of another
120 package, you identify them as follows:
121 <literallayout class='monospaced'>
122 ALTERNATIVE_busybox = "sh sed test bracket"
123 </literallayout>
124 For more information on the alternatives system, see the
125 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
126 section.
127 </para>
128 </glossdef>
129 </glossentry>
130
131 <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
132 <info>
133 ALTERNATIVE_LINK_NAME[doc] = "Used by the alternatives system to map duplicated commands to actual locations."
134 </info>
135 <glossdef>
136 <para role="glossdeffirst">
137<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
138 Used by the alternatives system to map duplicated commands
139 to actual locations.
140 For example, if the <filename>bracket</filename> command
141 provided by the <filename>busybox</filename> package is
142 duplicated through another package, you must use the
143 <filename>ALTERNATIVE_LINK_NAME</filename> variable to
144 specify the actual location:
145 <literallayout class='monospaced'>
146 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
147 </literallayout>
148 </para>
149
150 <para>
151 In this example, the binary for the
152 <filename>bracket</filename> command (i.e.
153 <filename>[</filename>) from the
154 <filename>busybox</filename> package resides in
155 <filename>/usr/bin/</filename>.
156 <note>
157 If <filename>ALTERNATIVE_LINK_NAME</filename> is not
158 defined, it defaults to
159 <filename>${bindir}/<replaceable>name</replaceable></filename>.
160 </note>
161 </para>
162
163 <para>
164 For more information on the alternatives system, see the
165 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
166 section.
167 </para>
168 </glossdef>
169 </glossentry>
170
171 <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
172 <info>
173 ALTERNATIVE_PRIORITY[doc] = "Used by the alternatives system to create default priorities for duplicated commands."
174 </info>
175 <glossdef>
176 <para role="glossdeffirst">
177<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
178 Used by the alternatives system to create default
179 priorities for duplicated commands.
180 You can use the variable to create a single default
181 regardless of the command name or package, a default for
182 specific duplicated commands regardless of the package, or
183 a default for specific commands tied to particular packages.
184 Here are the available syntax forms:
185 <literallayout class='monospaced'>
186 ALTERNATIVE_PRIORITY = "<replaceable>priority</replaceable>"
187 ALTERNATIVE_PRIORITY[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>"
188 ALTERNATIVE_PRIORITY_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>"
189 </literallayout>
190 </para>
191
192 <para>
193 For more information on the alternatives system, see the
194 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
195 section.
196 </para>
197 </glossdef>
198 </glossentry>
199
200 <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
201 <info>
202 ALTERNATIVE_TARGET[doc] = "Used by the alternatives system to create default link locations for duplicated commands."
203 </info>
204 <glossdef>
205 <para role="glossdeffirst">
206<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
207 Used by the alternatives system to create default link
208 locations for duplicated commands.
209 You can use the variable to create a single default
210 location for all duplicated commands regardless of the
211 command name or package, a default for
212 specific duplicated commands regardless of the package, or
213 a default for specific commands tied to particular packages.
214 Here are the available syntax forms:
215 <literallayout class='monospaced'>
216 ALTERNATIVE_TARGET = "<replaceable>target</replaceable>"
217 ALTERNATIVE_TARGET[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>"
218 ALTERNATIVE_TARGET_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>"
219 </literallayout>
220 <note>
221 <para>
222 If <filename>ALTERNATIVE_TARGET</filename> is not
223 defined, it inherits the value from the
224 <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
225 variable.
226 </para>
227
228 <para>
229 If <filename>ALTERNATIVE_LINK_NAME</filename> and
230 <filename>ALTERNATIVE_TARGET</filename> are the
231 same, the target for
232 <filename>ALTERNATIVE_TARGET</filename>
233 has "<filename>.{BPN}</filename>" appended to it.
234 </para>
235
236 <para>
237 Finally, if the file referenced has not been
238 renamed, the alternatives system will rename it to
239 avoid the need to rename alternative files in the
240 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
241 task while
242 retaining support for the command if necessary.
243 </para>
244 </note>
245 </para>
246
247 <para>
248 For more information on the alternatives system, see the
249 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
250 section.
251 </para>
252 </glossdef>
253 </glossentry>
254
255 <glossentry id='var-APPEND'><glossterm>APPEND</glossterm>
256 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400257 APPEND[doc] = "An override list of append strings for target specified using LABELS."
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500258 </info>
259 <glossdef>
260 <para role="glossdeffirst">
261<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -0400262 An override list of append strings for each target
263 specified with
264 <link linkend='var-LABELS'><filename>LABELS</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500265 </para>
266
267 <para>
268 See the
269 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
270 class for more information on how this variable is used.
271 </para>
272 </glossdef>
273 </glossentry>
274
275 <glossentry id='var-AR'><glossterm>AR</glossterm>
276 <info>
277 AR[doc] = "Minimal command and arguments to run 'ar'."
278 </info>
279 <glossdef>
280 <para role="glossdeffirst">
281<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
282 The minimal command and arguments used to run
283 <filename>ar</filename>.
284 </para>
285 </glossdef>
286 </glossentry>
287
288 <glossentry id='var-ARCHIVER_MODE'><glossterm>ARCHIVER_MODE</glossterm>
289 <info>
290 ARCHIVER_MODE[doc] = "Controls archive creation used when releasing source files."
291 </info>
292 <glossdef>
293 <para role="glossdeffirst">
294<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
295 When used with the
296 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
297 class, determines the type of information used to create
298 a released archive.
299 You can use this variable to create archives of patched
300 source, original source, configured source, and so forth
301 by employing the following variable flags (varflags):
302 <literallayout class='monospaced'>
303 ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source
304 # files.
305
306 ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is
307 # the default.
308
309 ARCHIVER_MODE[src] = "configured" # Uses configured source files.
310
311 ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and
312 # do_patch.
313
314 ARCHIVER_MODE[diff-exclude] ?= "<replaceable>file</replaceable> <replaceable>file</replaceable> ..." # Lists files and directories to
315 # exclude from diff.
316
317 ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
318
319 ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
320
321 ARCHIVER_MODE[srpm] = "1" # Uses RPM package files.
322 </literallayout>
323 For information on how the variable works, see the
324 <filename>meta/classes/archiver.bbclass</filename> file
325 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500326 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500327 </para>
328 </glossdef>
329 </glossentry>
330
331 <glossentry id='var-AS'><glossterm>AS</glossterm>
332 <info>
333 AS[doc] = "Minimal command and arguments to run the assembler."
334 </info>
335 <glossdef>
336 <para role="glossdeffirst">
337<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
338 The minimal command and arguments used to run the
339 assembler.
340 </para>
341 </glossdef>
342 </glossentry>
343
344 <glossentry id='var-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm>
345 <info>
346 ASSUME_PROVIDED[doc] = "Lists recipe names (PN values) BitBake does not attempt to build."
347 </info>
348 <glossdef>
349 <para role="glossdeffirst">
350<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
351 Lists recipe names
352 (<link linkend='var-PN'><filename>PN</filename></link>
353 values) BitBake does not attempt to build.
354 Instead, BitBake assumes these recipes have already been
355 built.
356 </para>
357
358 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400359 In OpenEmbedded-Core, <filename>ASSUME_PROVIDED</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500360 mostly specifies native tools that should not be built.
361 An example is <filename>git-native</filename>, which when
362 specified, allows for the Git binary from the host to be
363 used rather than building <filename>git-native</filename>.
364 </para>
365 </glossdef>
366 </glossentry>
367
368 <glossentry id='var-ASSUME_SHLIBS'><glossterm>ASSUME_SHLIBS</glossterm>
369 <info>
370 ASSUME_SHLIBS[doc] = Provides additional shlibs provider mapping information, which adds to or overwrites the information provided automatically by the system."
371 </info>
372 <glossdef>
373 <para role="glossdeffirst">
374<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
375 Provides additional <filename>shlibs</filename> provider
376 mapping information, which adds to or overwrites the
377 information provided automatically by the system.
378 Separate multiple entries using spaces.
379 </para>
380
381 <para>
382 As an example, use the following form to add an
383 <filename>shlib</filename> provider of
384 <replaceable>shlibname</replaceable> in
385 <replaceable>packagename</replaceable> with the optional
386 <replaceable>version</replaceable>:
387 <literallayout class='monospaced'>
388 <replaceable>shlibname:packagename</replaceable>[_<replaceable>version</replaceable>]
389 </literallayout>
390 </para>
391
392 <para>
393 Here is an example that adds a shared library named
394 <filename>libEGL.so.1</filename> as being provided by
395 the <filename>libegl-implementation</filename> package:
396 <literallayout class='monospaced'>
397 ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"
398 </literallayout>
399 </para>
400 </glossdef>
401 </glossentry>
402
403 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
404 <info>
405 AUTHOR[doc] = "Email address used to contact the original author or authors in order to send patches and forward bugs."
406 </info>
407 <glossdef>
408 <para role="glossdeffirst">
409<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
410 The email address used to contact the original author
411 or authors in order to send patches and forward bugs.
412 </para>
413 </glossdef>
414 </glossentry>
415
416 <glossentry id='var-AUTO_LIBNAME_PKGS'><glossterm>AUTO_LIBNAME_PKGS</glossterm>
417 <info>
418 AUTO_LIBNAME_PKGS[doc] = "Specifies which packages should be checked for libraries and renamed according to Debian library package naming."
419 </info>
420 <glossdef>
421 <para role="glossdeffirst">
422<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
423 When the
424 <link linkend='ref-classes-debian'><filename>debian</filename></link>
425 class is inherited, which is the default behavior,
426 <filename>AUTO_LIBNAME_PKGS</filename> specifies which
427 packages should be checked for libraries and renamed
428 according to Debian library package naming.
429 </para>
430
431 <para>
432 The default value is "${PACKAGES}", which causes the
433 debian class to act on all packages that are
434 explicitly generated by the recipe.
435 </para>
436 </glossdef>
437 </glossentry>
438
439 <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm>AUTO_SYSLINUXMENU</glossterm>
440 <info>
441 AUTO_SYSLINUXMENU[doc] = "Enables creating an automatic menu for the syslinux bootloader."
442 </info>
443 <glossdef>
444 <para role="glossdeffirst">
445<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
446 Enables creating an automatic menu for the syslinux
447 bootloader.
448 You must set this variable in your recipe.
449 The
450 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
451 class checks this variable.
452 </para>
453 </glossdef>
454 </glossentry>
455
456 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
457 <info>
458 AUTOREV[doc] = "When SRCREV is set to the value of this variable, it specifies to use the latest source revision in the repository."
459 </info>
460 <glossdef>
461 <para role="glossdeffirst">
462<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
463 When
464 <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
465 is set to the value of this variable, it specifies to use
466 the latest source revision in the repository.
467 Here is an example:
468 <literallayout class='monospaced'>
469 SRCREV = "${AUTOREV}"
470 </literallayout>
471 </para>
472
473 <para>
474 If you use the previous statement to retrieve the latest
475 version of software, you need to be sure
476 <link linkend='var-PV'><filename>PV</filename></link>
477 contains
478 <filename>${</filename><link linkend='var-SRCPV'><filename>SRCPV</filename></link><filename>}</filename>.
479 For example, suppose you have a kernel recipe that
480 inherits the
481 <link linkend='ref-classes-kernel'>kernel</link> class
482 and you use the previous statement.
483 In this example, <filename>${SRCPV}</filename> does not
484 automatically get into <filename>PV</filename>.
485 Consequently, you need to change <filename>PV</filename>
486 in your recipe so that it does contain
487 <filename>${SRCPV}</filename>.
488 </para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500489
490 <para>
491 For more information see the
492 "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500493 section in the Yocto Project Development Tasks Manual.
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500494 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500495 </glossdef>
496 </glossentry>
497
498 <glossentry id='var-AVAILTUNES'><glossterm>AVAILTUNES</glossterm>
499 <info>
500 AVAILTUNES[doc] = "The list of defined CPU and Application Binary Interface (ABI) tunings (i.e. "tunes") available for use by the OpenEmbedded build system."
501 </info>
502 <glossdef>
503 <para role="glossdeffirst">
504<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
505 The list of defined CPU and Application Binary Interface
506 (ABI) tunings (i.e. "tunes") available for use by the
507 OpenEmbedded build system.
508 </para>
509
510 <para>
511 The list simply presents the tunes that are available.
512 Not all tunes may be compatible with a particular
513 machine configuration, or with each other in a
514 <ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Multilib</ulink>
515 configuration.
516 </para>
517
518 <para>
519 To add a tune to the list, be sure to append it with
520 spaces using the "+=" BitBake operator.
521 Do not simply replace the list by using the "=" operator.
522 See the
523 "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>"
524 section in the BitBake User Manual for more information.
525 </para>
526 </glossdef>
527 </glossentry>
528
529 </glossdiv>
530
531 <glossdiv id='var-glossary-b'><title>B</title>
532
533 <glossentry id='var-B'><glossterm>B</glossterm>
534 <info>
535 B[doc] = "The Build Directory. The OpenEmbedded build system places generated objects into the Build Directory during a recipe's build process."
536 </info>
537 <glossdef>
538 <para role="glossdeffirst">
539<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
540 The directory within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500541 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500542 in which the OpenEmbedded build system places generated
543 objects during a recipe's build process.
544 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
545 directory, which is defined as:
546 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600547 S = "${WORKDIR}/${BP}"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500548 </literallayout>
549 </para>
550
551 <para>
552 You can separate the (<filename>S</filename>) directory
553 and the directory pointed to by the <filename>B</filename>
554 variable.
555 Most Autotools-based recipes support separating these
556 directories.
557 The build system defaults to using separate directories for
558 <filename>gcc</filename> and some kernel recipes.
559 </para>
560 </glossdef>
561 </glossentry>
562
563 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
564 <info>
565 BAD_RECOMMENDATIONS[doc] = "A list of packages not to install despite being recommended by a recipe. Support for this variable exists only when using the IPK packaging backend."
566 </info>
567 <glossdef>
568 <para role="glossdeffirst">
569<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
570 Lists "recommended-only" packages to not install.
571 Recommended-only packages are packages installed only
572 through the
573 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
574 variable.
575 You can prevent any of these "recommended" packages from
576 being installed by listing them with the
577 <filename>BAD_RECOMMENDATIONS</filename> variable:
578 <literallayout class='monospaced'>
579 BAD_RECOMMENDATIONS = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."
580 </literallayout>
581 </para>
582
583 <para>
584 You can set this variable globally in your
585 <filename>local.conf</filename> file or you can attach it to
586 a specific image recipe by using the recipe name override:
587 <literallayout class='monospaced'>
588 BAD_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"
589 </literallayout>
590 </para>
591
592 <para>
593 It is important to realize that if you choose to not install
594 packages using this variable and some other packages are
595 dependent on them (i.e. listed in a recipe's
596 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
597 variable), the OpenEmbedded build system ignores your
598 request and will install the packages to avoid dependency
599 errors.
600 </para>
601
602 <para>
603 Support for this variable exists only when using the
604 IPK and RPM packaging backend.
605 Support does not exist for DEB.
606 </para>
607
608 <para>
609 See the
610 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
611 and the
612 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
613 variables for related information.
614 </para>
615 </glossdef>
616 </glossentry>
617
618 <glossentry id='var-BASE_LIB'><glossterm>BASE_LIB</glossterm>
619 <info>
620 BASE_LIB[doc] = "The library directory name for the CPU or Application Binary Interface (ABI) tune."
621 </info>
622 <glossdef>
623 <para role="glossdeffirst">
624<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
625 The library directory name for the CPU or Application
626 Binary Interface (ABI) tune.
627 The <filename>BASE_LIB</filename> applies only in the
628 Multilib context.
629 See the
630 "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500631 section in the Yocto Project Development Tasks Manual for
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500632 information on Multilib.
633 </para>
634
635 <para>
636 The <filename>BASE_LIB</filename> variable is defined in
637 the machine include files in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500638 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500639 If Multilib is not being used, the value defaults to "lib".
640 </para>
641 </glossdef>
642 </glossentry>
643
644 <glossentry id='var-BASE_WORKDIR'><glossterm>BASE_WORKDIR</glossterm>
645 <info>
646 BASE_WORKDIR[doc] = "Points to the base of the work directory for all recipes."
647 </info>
648 <glossdef>
649 <para role="glossdeffirst">
650<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
651 Points to the base of the work directory for all recipes.
652 The default value is "${TMPDIR}/work".
653 </para>
654 </glossdef>
655 </glossentry>
656
657 <glossentry id='var-BB_ALLOWED_NETWORKS'><glossterm>BB_ALLOWED_NETWORKS</glossterm>
658 <info>
659 BB_ALLOWED_NETWORKS[doc] = "A list of hosts that the fetcher is allowed to use to obtain the required source code."
660 </info>
661 <glossdef>
662 <para>
663 Specifies a space-delimited list of hosts that the fetcher
664 is allowed to use to obtain the required source code.
665 Following are considerations surrounding this variable:
666 <itemizedlist>
667 <listitem><para>
668 This host list is only used if
669 <filename>BB_NO_NETWORK</filename> is either not
670 set or set to "0".
671 </para></listitem>
672 <listitem><para>
673 Limited support for wildcard matching against the
674 beginning of host names exists.
675 For example, the following setting matches
676 <filename>git.gnu.org</filename>,
677 <filename>ftp.gnu.org</filename>, and
678 <filename>foo.git.gnu.org</filename>.
679 <literallayout class='monospaced'>
680 BB_ALLOWED_NETWORKS = "*.gnu.org"
681 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800682 <note><title>Important</title>
683 <para>The use of the "<filename>*</filename>"
684 character only works at the beginning of
685 a host name and it must be isolated from
686 the remainder of the host name.
687 You cannot use the wildcard character in any
688 other location of the name or combined with
689 the front part of the name.</para>
690
691 <para>For example,
692 <filename>*.foo.bar</filename> is supported,
693 while <filename>*aa.foo.bar</filename> is not.
694 </para>
695 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500696 </para></listitem>
697 <listitem><para>
698 Mirrors not in the host list are skipped and
699 logged in debug.
700 </para></listitem>
701 <listitem><para>
702 Attempts to access networks not in the host list
703 cause a failure.
704 </para></listitem>
705 </itemizedlist>
706 Using <filename>BB_ALLOWED_NETWORKS</filename> in
707 conjunction with
708 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
709 is very useful.
710 Adding the host you want to use to
711 <filename>PREMIRRORS</filename> results in the source code
712 being fetched from an allowed location and avoids raising
713 an error when a host that is not allowed is in a
714 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
715 statement.
716 This is because the fetcher does not attempt to use the
717 host listed in <filename>SRC_URI</filename> after a
718 successful fetch from the
719 <filename>PREMIRRORS</filename> occurs.
720 </para>
721 </glossdef>
722 </glossentry>
723
724 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
725 <info>
726 BB_DANGLINGAPPENDS_WARNONLY[doc] = "Defines how BitBake handles situations where an append file (.bbappend) has no corresponding recipe file (.bb)."
727 </info>
728 <glossdef>
729 <para role="glossdeffirst">
730<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
731 Defines how BitBake handles situations where an append
732 file (<filename>.bbappend</filename>) has no
733 corresponding recipe file (<filename>.bb</filename>).
734 This condition often occurs when layers get out of sync
735 (e.g. <filename>oe-core</filename> bumps a
736 recipe version and the old recipe no longer exists and the
737 other layer has not been updated to the new version
738 of the recipe yet).
739 </para>
740
741 <para>
742 The default fatal behavior is safest because it is
743 the sane reaction given something is out of sync.
744 It is important to realize when your changes are no longer
745 being applied.
746 </para>
747
748 <para>
749 You can change the default behavior by setting this
750 variable to "1", "yes", or "true"
751 in your <filename>local.conf</filename> file, which is
752 located in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500753 <link linkend='build-directory'>Build Directory</link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500754 Here is an example:
755 <literallayout class='monospaced'>
756 BB_DANGLINGAPPENDS_WARNONLY = "1"
757 </literallayout>
758 </para>
759 </glossdef>
760 </glossentry>
761
762 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
763 <info>
764 BB_DISKMON_DIRS[doc] = "Monitors disk space and available inodes during the build and allows you to control the build based on these parameters."
765 </info>
766 <glossdef>
767 <para role="glossdeffirst">
768<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
769 Monitors disk space and available inodes during the build
770 and allows you to control the build based on these
771 parameters.
772 </para>
773
774 <para>
775 Disk space monitoring is disabled by default.
776 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
777 variable to your <filename>conf/local.conf</filename> file found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500778 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500779 Use the following form:
780 <literallayout class='monospaced'>
781 BB_DISKMON_DIRS = "<replaceable>action</replaceable>,<replaceable>dir</replaceable>,<replaceable>threshold</replaceable> [...]"
782
783 where:
784
785 <replaceable>action</replaceable> is:
786 ABORT: Immediately abort the build when
787 a threshold is broken.
788 STOPTASKS: Stop the build after the currently
789 executing tasks have finished when
790 a threshold is broken.
791 WARN: Issue a warning but continue the
792 build when a threshold is broken.
793 Subsequent warnings are issued as
Brad Bishop316dfdd2018-06-25 12:45:53 -0400794 defined by the BB_DISKMON_WARNINTERVAL
795 variable, which must be defined in
796 the conf/local.conf file.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500797
798 <replaceable>dir</replaceable> is:
799 Any directory you choose. You can specify one or
800 more directories to monitor by separating the
801 groupings with a space. If two directories are
802 on the same device, only the first directory
803 is monitored.
804
805 <replaceable>threshold</replaceable> is:
806 Either the minimum available disk space,
807 the minimum number of free inodes, or
808 both. You must specify at least one. To
809 omit one or the other, simply omit the value.
810 Specify the threshold using G, M, K for Gbytes,
811 Mbytes, and Kbytes, respectively. If you do
812 not specify G, M, or K, Kbytes is assumed by
813 default. Do not use GB, MB, or KB.
814 </literallayout>
815 </para>
816
817 <para>
818 Here are some examples:
819 <literallayout class='monospaced'>
820 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
821 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
822 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
823 </literallayout>
824 The first example works only if you also provide
825 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
826 in the <filename>conf/local.conf</filename>.
827 This example causes the build system to immediately
828 abort when either the disk space in <filename>${TMPDIR}</filename> drops
829 below 1 Gbyte or the available free inodes drops below
830 100 Kbytes.
831 Because two directories are provided with the variable, the
832 build system also issue a
833 warning when the disk space in the
834 <filename>${SSTATE_DIR}</filename> directory drops
835 below 1 Gbyte or the number of free inodes drops
836 below 100 Kbytes.
837 Subsequent warnings are issued during intervals as
838 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
839 variable.
840 </para>
841
842 <para>
843 The second example stops the build after all currently
844 executing tasks complete when the minimum disk space
845 in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
846 directory drops below 1 Gbyte.
847 No disk monitoring occurs for the free inodes in this case.
848 </para>
849
850 <para>
851 The final example immediately aborts the build when the
852 number of free inodes in the <filename>${TMPDIR}</filename> directory
853 drops below 100 Kbytes.
854 No disk space monitoring for the directory itself occurs
855 in this case.
856 </para>
857 </glossdef>
858 </glossentry>
859
860 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
861 <info>
862 BB_DISKMON_WARNINTERVAL[doc] = "Defines the disk space and free inode warning intervals. To set these intervals, define the variable in the conf/local.conf file in the Build Directory."
863 </info>
864 <glossdef>
865 <para role="glossdeffirst">
866<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
867 Defines the disk space and free inode warning intervals.
868 To set these intervals, define the variable in your
869 <filename>conf/local.conf</filename> file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500870 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500871 </para>
872
873 <para>
874 If you are going to use the
875 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
876 also use the
877 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
878 and define its action as "WARN".
879 During the build, subsequent warnings are issued each time
880 disk space or number of free inodes further reduces by
881 the respective interval.
882 </para>
883
884 <para>
885 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
886 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
887 the "WARN" action, the disk monitoring interval defaults to
888 the following:
889 <literallayout class='monospaced'>
890 BB_DISKMON_WARNINTERVAL = "50M,5K"
891 </literallayout>
892 </para>
893
894 <para>
895 When specifying the variable in your configuration file,
896 use the following form:
897 <literallayout class='monospaced'>
898 BB_DISKMON_WARNINTERVAL = "<replaceable>disk_space_interval</replaceable>,<replaceable>disk_inode_interval</replaceable>"
899
900 where:
901
902 <replaceable>disk_space_interval</replaceable> is:
903 An interval of memory expressed in either
904 G, M, or K for Gbytes, Mbytes, or Kbytes,
905 respectively. You cannot use GB, MB, or KB.
906
907 <replaceable>disk_inode_interval</replaceable> is:
908 An interval of free inodes expressed in either
909 G, M, or K for Gbytes, Mbytes, or Kbytes,
910 respectively. You cannot use GB, MB, or KB.
911 </literallayout>
912 </para>
913
914 <para>
915 Here is an example:
916 <literallayout class='monospaced'>
917 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
918 BB_DISKMON_WARNINTERVAL = "50M,5K"
919 </literallayout>
920 These variables cause the OpenEmbedded build system to
921 issue subsequent warnings each time the available
922 disk space further reduces by 50 Mbytes or the number
923 of free inodes further reduces by 5 Kbytes in the
924 <filename>${SSTATE_DIR}</filename> directory.
925 Subsequent warnings based on the interval occur each time
926 a respective interval is reached beyond the initial warning
927 (i.e. 1 Gbytes and 100 Kbytes).
928 </para>
929 </glossdef>
930 </glossentry>
931
932 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
933 <info>
934 BB_GENERATE_MIRROR_TARBALLS[doc] = "Causes tarballs of the Git repositories to be placed in the DL_DIR directory."
935 </info>
936 <glossdef>
937 <para role="glossdeffirst">
938<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
939 Causes tarballs of the Git repositories, including the
940 Git metadata, to be placed in the
941 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
942 directory.
943 </para>
944
945 <para>
946 For performance reasons, creating and placing tarballs of
947 the Git repositories is not the default action by the
948 OpenEmbedded build system.
949 <literallayout class='monospaced'>
950 BB_GENERATE_MIRROR_TARBALLS = "1"
951 </literallayout>
952 Set this variable in your <filename>local.conf</filename>
953 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500954 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500955 </para>
956 </glossdef>
957 </glossentry>
958
959 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
960 <info>
961 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."
962 </info>
963 <glossdef>
964 <para role="glossdeffirst">
965<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
966 The maximum number of tasks BitBake should run in parallel
967 at any one time.
968 The OpenEmbedded build system automatically configures
969 this variable to be equal to the number of cores on the
970 build system.
971 For example, a system with a dual core processor that
972 also uses hyper-threading causes the
973 <filename>BB_NUMBER_THREADS</filename> variable to default
974 to "4".
975 </para>
976
977 <para>
978 For single socket systems (i.e. one CPU), you should not
979 have to override this variable to gain optimal parallelism
980 during builds.
981 However, if you have very large systems that employ
982 multiple physical CPUs, you might want to make sure the
983 <filename>BB_NUMBER_THREADS</filename> variable is not
984 set higher than "20".
985 </para>
986
987 <para>
988 For more information on speeding up builds, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400989 "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"
990 section in the Yocto Project Development Tasks Manual.
991 </para>
992 </glossdef>
993 </glossentry>
994
995 <glossentry id='var-BB_SERVER_TIMEOUT'><glossterm>BB_SERVER_TIMEOUT</glossterm>
996 <info>
997 BB_SERVER_TIMEOUT [doc] = "Specifies the time (in seconds) after which to unload the BitBake server due to inactivity."
998 </info>
999 <glossdef>
1000 <para role="glossdeffirst">
1001<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1002 Specifies the time (in seconds) after which to unload the
1003 BitBake server due to inactivity.
1004 Set <filename>BB_SERVER_TIMEOUT</filename> to determine how
1005 long the BitBake server stays resident between invocations.
1006 </para>
1007
1008 <para>
1009 For example, the following statement in your
1010 <filename>local.conf</filename> file instructs the server
1011 to be unloaded after 20 seconds of inactivity:
1012 <literallayout class='monospaced'>
1013 BB_SERVER_TIMEOUT = "20"
1014 </literallayout>
1015 If you want the server to never be unloaded, set
1016 <filename>BB_SERVER_TIMEOUT</filename> to "-1".
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001017 </para>
1018 </glossdef>
1019 </glossentry>
1020
1021 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
1022 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001023 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 -05001024 </info>
1025 <glossdef>
1026 <para role="glossdeffirst">
1027<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1028 Allows you to extend a recipe so that it builds variants of the software.
1029 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
1030 which is a copy of Quilt built to run on the build system;
1031 "crosses" such as <filename>gcc-cross</filename>,
1032 which is a compiler built to run on the build machine but produces binaries
1033 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
1034 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
1035 and "mulitlibs" in the form "<filename>multilib:</filename><replaceable>multilib_name</replaceable>".
1036 </para>
1037
1038 <para>
1039 To build a different variant of the recipe with a minimal amount of code, it usually
1040 is as simple as adding the following to your recipe:
1041 <literallayout class='monospaced'>
1042 BBCLASSEXTEND =+ "native nativesdk"
1043 BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>"
1044 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001045 <note>
1046 <para>
1047 Internally, the <filename>BBCLASSEXTEND</filename>
1048 mechanism generates recipe variants by rewriting
1049 variable values and applying overrides such as
1050 <filename>_class-native</filename>.
1051 For example, to generate a native version of a recipe,
1052 a
1053 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1054 on "foo" is rewritten to a <filename>DEPENDS</filename>
1055 on "foo-native".
1056 </para>
1057
1058 <para>
1059 Even when using <filename>BBCLASSEXTEND</filename>, the
1060 recipe is only parsed once.
1061 Parsing once adds some limitations.
1062 For example, it is not possible to
1063 include a different file depending on the variant,
1064 since <filename>include</filename> statements are
1065 processed when the recipe is parsed.
1066 </para>
1067 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001068 </para>
1069 </glossdef>
1070 </glossentry>
1071
1072 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
1073 <info>
1074 BBFILE_COLLECTIONS[doc] = "Lists the names of configured layers. These names are used to find the other BBFILE_* variables."
1075 </info>
1076 <glossdef>
1077 <para role="glossdeffirst">
1078<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1079 Lists the names of configured layers.
1080 These names are used to find the other <filename>BBFILE_*</filename>
1081 variables.
1082 Typically, each layer will append its name to this variable in its
1083 <filename>conf/layer.conf</filename> file.
1084 </para>
1085 </glossdef>
1086 </glossentry>
1087
1088 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
1089 <info>
1090 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."
1091 </info>
1092 <glossdef>
1093 <para role="glossdeffirst">
1094<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1095 Variable that expands to match files from
1096 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
1097 in a particular layer.
1098 This variable is used in the <filename>conf/layer.conf</filename> file and must
1099 be suffixed with the name of the specific layer (e.g.
1100 <filename>BBFILE_PATTERN_emenlow</filename>).
1101 </para>
1102 </glossdef>
1103 </glossentry>
1104
1105 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
1106 <info>
1107 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."
1108 </info>
1109 <glossdef>
1110 <para role="glossdeffirst">
1111<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1112 Assigns the priority for recipe files in each layer.
1113 </para>
1114
1115 <para>
1116 This variable is useful in situations where the same recipe appears in
1117 more than one layer.
1118 Setting this variable allows you to prioritize a
1119 layer against other layers that contain the same recipe - effectively
1120 letting you control the precedence for the multiple layers.
1121 The precedence established through this variable stands regardless of a
1122 recipe's version
1123 (<link linkend='var-PV'><filename>PV</filename></link> variable).
1124 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
1125 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
1126 lower precedence.
1127 </para>
1128
1129 <para>
1130 A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
1131 precedence.
1132 For example, the value 6 has a higher precedence than the value 5.
1133 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
1134 dependencies (see the
1135 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
1136 more information.
1137 The default priority, if unspecified
1138 for a layer with no dependencies, is the lowest defined priority + 1
1139 (or 1 if no priorities are defined).
1140 </para>
1141 <tip>
1142 You can use the command <filename>bitbake-layers show-layers</filename> to list
1143 all configured layers along with their priorities.
1144 </tip>
1145 </glossdef>
1146 </glossentry>
1147
1148 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
1149 <info>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001150 BBFILES[doc] = "A space-separated list of recipe files BitBake uses to build software."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001151 </info>
1152 <glossdef>
1153 <para role="glossdeffirst">
1154<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001155 A space-separated list of recipe files BitBake uses to
1156 build software.
1157 </para>
1158
1159 <para>
1160 When specifying recipe files, you can pattern match using
1161 Python's
1162 <ulink url='https://docs.python.org/3/library/glob.html'><filename>glob</filename></ulink>
1163 syntax.
1164 For details on the syntax, see the documentation by
1165 following the previous link.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001166 </para>
1167 </glossdef>
1168 </glossentry>
1169
Brad Bishop316dfdd2018-06-25 12:45:53 -04001170 <glossentry id='var-BBFILES_DYNAMIC'><glossterm>BBFILES_DYNAMIC</glossterm>
1171 <info>
1172 BBFILES_DYNAMIC[doc] = "Activates content when identified layers are present."
1173 </info>
1174 <glossdef>
1175 <para role="glossdeffirst">
1176<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1177 Activates content when identified layers are present.
1178 You identify the layers by the collections that the layers
1179 define.
1180 </para>
1181
1182 <para>
1183 Use the <filename>BBFILES_DYNAMIC</filename> variable to
1184 avoid <filename>.bbappend</filename> files whose
1185 corresponding <filename>.bb</filename> file is in a layer
1186 that attempts to modify other layers through
1187 <filename>.bbappend</filename> but does not want to
1188 introduce a hard dependency on those other layers.
1189 </para>
1190
1191 <para>
1192 Use the following form for
1193 <filename>BBFILES_DYNAMIC</filename>:
1194 <literallayout class='monospaced'>
1195 <replaceable>collection_name</replaceable>:<replaceable>filename_pattern</replaceable>
1196 </literallayout>
1197 The following example identifies two collection names and
1198 two filename patterns:
1199 <literallayout class='monospaced'>
1200 BBFILES_DYNAMIC += " \
1201 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
1202 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
1203 "
1204 </literallayout>
1205 This next example shows an error message that occurs
1206 because invalid entries are found, which cause parsing to
1207 abort:
1208 <literallayout class='monospaced'>
1209 ERROR: BBFILES_DYNAMIC entries must be of the form &lt;collection name&gt;:&lt;filename pattern&gt;, not:
1210 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
1211 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
1212 </literallayout>
1213 </para>
1214 </glossdef>
1215 </glossentry>
1216
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001217 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
1218 <info>
1219 BBINCLUDELOGS[doc] = "Variable that controls how BitBake displays logs on build failure."
1220 </info>
1221 <glossdef>
1222 <para role="glossdeffirst">
1223<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1224 Variable that controls how BitBake displays logs on build failure.
1225 </para>
1226 </glossdef>
1227 </glossentry>
1228
1229 <glossentry id='var-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm>
1230 <info>
1231 BBINCLUDELOGS_LINES[doc] = "Amount of log lines printed on failure."
1232 </info>
1233 <glossdef>
1234 <para role="glossdeffirst">
1235<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1236 If
1237 <link linkend='var-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link>
1238 is set, specifies the maximum number of lines from the
1239 task log file to print when reporting a failed task.
1240 If you do not set <filename>BBINCLUDELOGS_LINES</filename>,
1241 the entire log is printed.
1242 </para>
1243 </glossdef>
1244 </glossentry>
1245
1246 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
1247 <info>
1248 BBLAYERS[doc] = "Lists the layers to enable during the build. This variable is defined in the bblayers.conf configuration file."
1249 </info>
1250 <glossdef>
1251 <para role="glossdeffirst">
1252<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1253 Lists the layers to enable during the build.
1254 This variable is defined in the <filename>bblayers.conf</filename> configuration
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001255 file in the
1256 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001257 Here is an example:
1258 <literallayout class='monospaced'>
1259 BBLAYERS = " \
1260 /home/scottrif/poky/meta \
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001261 /home/scottrif/poky/meta-poky \
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001262 /home/scottrif/poky/meta-yocto-bsp \
1263 /home/scottrif/poky/meta-mykernel \
1264 "
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001265 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001266 </para>
1267
1268 <para>
1269 This example enables four layers, one of which is a custom, user-defined layer
1270 named <filename>meta-mykernel</filename>.
1271 </para>
1272 </glossdef>
1273 </glossentry>
1274
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001275 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
1276 <info>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001277 BBMASK[doc] = "Prevents BitBake from processing specific recipes or recipe append files."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001278 </info>
1279 <glossdef>
1280 <para role="glossdeffirst">
1281<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1282 Prevents BitBake from processing recipes and recipe
1283 append files.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001284 </para>
1285
1286 <para>
1287 You can use the <filename>BBMASK</filename> variable
1288 to "hide" these <filename>.bb</filename> and
1289 <filename>.bbappend</filename> files.
1290 BitBake ignores any recipe or recipe append files that
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001291 match any of the expressions.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001292 It is as if BitBake does not see them at all.
1293 Consequently, matching files are not parsed or otherwise
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001294 used by BitBake.
1295 </para>
1296
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001297 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001298 The values you provide are passed to Python's regular
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001299 expression compiler.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001300 Consequently, the syntax follows Python's Regular
1301 Expression (re) syntax.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001302 The expressions are compared against the full paths to
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001303 the files.
1304 For complete syntax information, see Python's
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001305 documentation at
1306 <ulink url='http://docs.python.org/3/library/re.html#re'></ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001307 </para>
1308
1309 <para>
1310 The following example uses a complete regular expression
1311 to tell BitBake to ignore all recipe and recipe append
1312 files in the <filename>meta-ti/recipes-misc/</filename>
1313 directory:
1314 <literallayout class='monospaced'>
1315 BBMASK = "meta-ti/recipes-misc/"
1316 </literallayout>
1317 If you want to mask out multiple directories or recipes,
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001318 you can specify multiple regular expression fragments.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001319 This next example masks out multiple directories and
1320 individual recipes:
1321 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001322 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
1323 BBMASK += "/meta-oe/recipes-support/"
1324 BBMASK += "/meta-foo/.*/openldap"
1325 BBMASK += "opencv.*\.bbappend"
1326 BBMASK += "lzma"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001327 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001328 <note>
1329 When specifying a directory name, use the trailing
1330 slash character to ensure you match just that directory
1331 name.
1332 </note>
1333 </para>
1334 </glossdef>
1335 </glossentry>
1336
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001337 <glossentry id='var-BBMULTICONFIG'><glossterm>BBMULTICONFIG</glossterm>
1338 <info>
1339 BBMULTICONFIG[doc] = "Specifies each separate configuration when you are building targets with multiple configurations."
1340 </info>
1341 <glossdef>
1342 <para role="glossdeffirst">
1343<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1344 Specifies each separate configuration when you are
1345 building targets with multiple configurations.
1346 Use this variable in your
1347 <filename>conf/local.conf</filename> configuration file.
1348 Specify a <replaceable>multiconfigname</replaceable> for
1349 each configuration file you are using.
1350 For example, the following line specifies three
1351 configuration files:
1352 <literallayout class='monospaced'>
1353 BBMULTIFONFIG = "configA configB configC"
1354 </literallayout>
1355 Each configuration file you use must reside in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001356 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001357 <filename>conf/multiconfig</filename> directory
1358 (e.g.
1359 <replaceable>build_directory</replaceable><filename>/conf/multiconfig/configA.conf</filename>).
1360 </para>
1361
1362 <para>
1363 For information on how to use
1364 <filename>BBMULTICONFIG</filename> in an environment that
1365 supports building targets with multiple configurations,
1366 see the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001367 "<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 -05001368 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001369 </para>
1370 </glossdef>
1371 </glossentry>
1372
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001373 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
1374 <info>
1375 BBPATH[doc] = "Used by BitBake to locate .bbclass and configuration files. This variable is analogous to the PATH variable."
1376 </info>
1377 <glossdef>
1378 <para role="glossdeffirst">
1379<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1380 Used by BitBake to locate
1381 <filename>.bbclass</filename> and configuration files.
1382 This variable is analogous to the
1383 <filename>PATH</filename> variable.
1384 <note>
1385 If you run BitBake from a directory outside of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001386 <link linkend='build-directory'>Build Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001387 you must be sure to set
1388 <filename>BBPATH</filename> to point to the
1389 Build Directory.
1390 Set the variable as you would any environment variable
1391 and then run BitBake:
1392 <literallayout class='monospaced'>
1393 $ BBPATH = "<replaceable>build_directory</replaceable>"
1394 $ export BBPATH
1395 $ bitbake <replaceable>target</replaceable>
1396 </literallayout>
1397 </note>
1398 </para>
1399 </glossdef>
1400 </glossentry>
1401
1402 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
1403 <info>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001404 BBSERVER[doc] = "Points to the BitBake remote server."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001405 </info>
1406 <glossdef>
1407 <para role="glossdeffirst">
1408<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001409 If defined in the BitBake environment,
1410 <filename>BBSERVER</filename> points to the BitBake
1411 remote server.
1412 </para>
1413
1414 <para>
1415 Use the following format to export the variable to the
1416 BitBake environment:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001417 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001418 export BBSERVER=localhost:$port"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001419 </literallayout>
1420 </para>
1421
1422 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001423 By default, <filename>BBSERVER</filename> also appears in
1424 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink>.
1425 Consequently, <filename>BBSERVER</filename> is excluded
1426 from checksum and dependency data.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001427 </para>
1428 </glossdef>
1429 </glossentry>
1430
1431 <glossentry id='var-BINCONFIG'><glossterm>BINCONFIG</glossterm>
1432 <info>
1433 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."
1434 </info>
1435 <glossdef>
1436 <para role="glossdeffirst">
1437<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1438 When inheriting the
1439 <link linkend='ref-classes-binconfig-disabled'><filename>binconfig-disabled</filename></link>
1440 class, this variable specifies binary configuration
1441 scripts to disable in favor of using
1442 <filename>pkg-config</filename> to query the information.
1443 The <filename>binconfig-disabled</filename> class will
1444 modify the specified scripts to return an error so that
1445 calls to them can be easily found and replaced.
1446 </para>
1447
1448 <para>
1449 To add multiple scripts, separate them by spaces.
1450 Here is an example from the <filename>libpng</filename>
1451 recipe:
1452 <literallayout class='monospaced'>
1453 BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"
1454 </literallayout>
1455 </para>
1456 </glossdef>
1457 </glossentry>
1458
1459 <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
1460 <info>
1461 BINCONFIG_GLOB[doc] = "When inheriting binconfig.bbclass from a recipe, this variable specifies a wildcard for configuration scripts that need editing."
1462 </info>
1463 <glossdef>
1464 <para role="glossdeffirst">
1465<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1466 When inheriting the
1467 <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
1468 class, this variable specifies a wildcard for
1469 configuration scripts that need editing.
1470 The scripts are edited to correct any paths that have been
1471 set up during compilation so that they are correct for
1472 use when installed into the sysroot and called by the
1473 build processes of other recipes.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001474 <note>
1475 The <filename>BINCONFIG_GLOB</filename> variable
1476 uses
1477 <ulink url='http://tldp.org/LDP/abs/html/globbingref.html'>shell globbing</ulink>,
1478 which is recognition and expansion of wildcards during
1479 pattern matching.
1480 Shell globbing is very similar to
1481 <ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>
1482 and
1483 <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>.
1484 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001485 </para>
1486
1487 <para>
1488 For more information on how this variable works, see
1489 <filename>meta/classes/binconfig.bbclass</filename> in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001490 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001491 You can also find general information on the class in the
1492 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
1493 section.
1494 </para>
1495 </glossdef>
1496 </glossentry>
1497
1498 <glossentry id='var-BP'><glossterm>BP</glossterm>
1499 <info>
1500 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}"
1501 </info>
1502 <glossdef>
1503 <para role="glossdeffirst">
1504<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1505 The base recipe name and version but without any special
1506 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
1507 and so forth).
1508 <filename>BP</filename> is comprised of the following:
1509 <literallayout class="monospaced">
1510 ${BPN}-${PV}
1511 </literallayout>
1512 </para>
1513 </glossdef>
1514 </glossentry>
1515
1516 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
1517 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001518 BPN[doc] = "This variable is a version of the PN variable but removes common suffixes and prefixes."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001519 </info>
1520 <glossdef>
1521 <para role="glossdeffirst">
1522<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001523 This variable is a version of the
1524 <link linkend='var-PN'><filename>PN</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001525 variable with common prefixes and suffixes
1526 removed, such as <filename>nativesdk-</filename>,
1527 <filename>-cross</filename>,
1528 <filename>-native</filename>, and multilib's
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001529 <filename>lib64-</filename> and
1530 <filename>lib32-</filename>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001531 The exact lists of prefixes and suffixes removed are
1532 specified by the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001533 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001534 and
1535 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link>
1536 variables, respectively.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001537 </para>
1538 </glossdef>
1539 </glossentry>
1540
1541 <glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm>
1542 <info>
1543 BUGTRACKER[doc] = "Specifies a URL for an upstream bug tracking website for a recipe."
1544 </info>
1545 <glossdef>
1546 <para role="glossdeffirst">
1547<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1548 Specifies a URL for an upstream bug tracking website for
1549 a recipe.
1550 The OpenEmbedded build system does not use this variable.
1551 Rather, the variable is a useful pointer in case a bug
1552 in the software being built needs to be manually reported.
1553 </para>
1554 </glossdef>
1555 </glossentry>
1556
1557 <glossentry id='var-BUILD_ARCH'><glossterm>BUILD_ARCH</glossterm>
1558 <info>
1559 BUILD_ARCH[doc] = "The name of the building architecture (e.g. i686)."
1560 </info>
1561 <glossdef>
1562 <para role="glossdeffirst">
1563<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1564 Specifies the architecture of the build host
1565 (e.g. <filename>i686</filename>).
1566 The OpenEmbedded build system sets the value of
1567 <filename>BUILD_ARCH</filename> from the machine name
1568 reported by the <filename>uname</filename> command.
1569 </para>
1570 </glossdef>
1571 </glossentry>
1572
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001573 <glossentry id='var-BUILD_AS_ARCH'><glossterm>BUILD_AS_ARCH</glossterm>
1574 <info>
1575 BUILD_AS_ARCH[doc] = "Specifies the architecture-specific assembler flags for the build host."
1576 </info>
1577 <glossdef>
1578 <para role="glossdeffirst">
1579<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1580 Specifies the architecture-specific assembler flags for
1581 the build host. By default, the value of
1582 <filename>BUILD_AS_ARCH</filename> is empty.
1583 </para>
1584 </glossdef>
1585 </glossentry>
1586
1587 <glossentry id='var-BUILD_CC_ARCH'><glossterm>BUILD_CC_ARCH</glossterm>
1588 <info>
1589 BUILD_CC_ARCH[doc] = "Specifies the architecture-specific C compiler flags for the build host."
1590 </info>
1591 <glossdef>
1592 <para role="glossdeffirst">
1593<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1594 Specifies the architecture-specific C compiler flags for
1595 the build host. By default, the value of
1596 <filename>BUILD_CC_ARCH</filename> is empty.
1597 </para>
1598 </glossdef>
1599 </glossentry>
1600
1601 <glossentry id='var-BUILD_CCLD'><glossterm>BUILD_CCLD</glossterm>
1602 <info>
1603 BUILD_CCLD[doc] = "Specifies the linker command to be used for the build host when the C compiler is being used as the linker."
1604 </info>
1605 <glossdef>
1606 <para role="glossdeffirst">
1607<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1608 Specifies the linker command to be used for the build host
1609 when the C compiler is being used as the linker. By default,
1610 <filename>BUILD_CCLD</filename> points to GCC and passes as
1611 arguments the value of
1612 <link linkend='var-BUILD_CC_ARCH'><filename>BUILD_CC_ARCH</filename></link>,
1613 assuming <filename>BUILD_CC_ARCH</filename> is set.
1614 </para>
1615 </glossdef>
1616 </glossentry>
1617
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001618 <glossentry id='var-BUILD_CFLAGS'><glossterm>BUILD_CFLAGS</glossterm>
1619 <info>
1620 BUILD_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the build host."
1621 </info>
1622 <glossdef>
1623 <para role="glossdeffirst">
1624<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1625 Specifies the flags to pass to the C compiler when building
1626 for the build host.
1627 When building in the <filename>-native</filename> context,
1628 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
1629 is set to the value of this variable by default.
1630 </para>
1631 </glossdef>
1632 </glossentry>
1633
1634 <glossentry id='var-BUILD_CPPFLAGS'><glossterm>BUILD_CPPFLAGS</glossterm>
1635 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001636 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 -05001637 </info>
1638 <glossdef>
1639 <para role="glossdeffirst">
1640<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -04001641 Specifies the flags to pass to the C preprocessor
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001642 (i.e. to both the C and the C++ compilers) when building
1643 for the build host.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001644 When building in the <filename>-native</filename> context,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001645 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
1646 is set to the value of this variable by default.
1647 </para>
1648 </glossdef>
1649 </glossentry>
1650
1651 <glossentry id='var-BUILD_CXXFLAGS'><glossterm>BUILD_CXXFLAGS</glossterm>
1652 <info>
1653 BUILD_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the build host."
1654 </info>
1655 <glossdef>
1656 <para role="glossdeffirst">
1657<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1658 Specifies the flags to pass to the C++ compiler when
1659 building for the build host.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001660 When building in the <filename>-native</filename> context,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001661 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
1662 is set to the value of this variable by default.
1663 </para>
1664 </glossdef>
1665 </glossentry>
1666
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001667 <glossentry id='var-BUILD_FC'><glossterm>BUILD_FC</glossterm>
1668 <info>
1669 BUILD_FC[doc] = "Specifies the Fortran compiler command for the build host."
1670 </info>
1671 <glossdef>
1672 <para role="glossdeffirst">
1673<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1674 Specifies the Fortran compiler command for the build host.
1675 By default, <filename>BUILD_FC</filename> points to
1676 Gfortran and passes as arguments the value of
1677 <link linkend='var-BUILD_CC_ARCH'><filename>BUILD_CC_ARCH</filename></link>,
1678 assuming <filename>BUILD_CC_ARCH</filename> is set.
1679 </para>
1680 </glossdef>
1681 </glossentry>
1682
1683 <glossentry id='var-BUILD_LD'><glossterm>BUILD_LD</glossterm>
1684 <info>
1685 BUILD_LD[doc] = "Specifies the linker command for the build host."
1686 </info>
1687 <glossdef>
1688 <para role="glossdeffirst">
1689<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1690 Specifies the linker command for the build host. By default,
1691 <filename>BUILD_LD</filename> points to the GNU linker (ld)
1692 and passes as arguments the value of
1693 <link linkend='var-BUILD_LD_ARCH'><filename>BUILD_LD_ARCH</filename></link>,
1694 assuming <filename>BUILD_LD_ARCH</filename> is set.
1695 </para>
1696 </glossdef>
1697 </glossentry>
1698
1699 <glossentry id='var-BUILD_LD_ARCH'><glossterm>BUILD_LD_ARCH</glossterm>
1700 <info>
1701 BUILD_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the build."
1702 </info>
1703 <glossdef>
1704 <para role="glossdeffirst">
1705<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1706 Specifies architecture-specific linker flags for the build
1707 host. By default, the value of
1708 <filename>BUILD_LD_ARCH</filename> is empty.
1709 </para>
1710 </glossdef>
1711 </glossentry>
1712
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001713 <glossentry id='var-BUILD_LDFLAGS'><glossterm>BUILD_LDFLAGS</glossterm>
1714 <info>
1715 BUILD_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the build host."
1716 </info>
1717 <glossdef>
1718 <para role="glossdeffirst">
1719<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1720 Specifies the flags to pass to the linker when building
1721 for the build host.
1722 When building in the <filename>-native</filename> context,
1723 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
1724 is set to the value of this variable by default.
1725 </para>
1726 </glossdef>
1727 </glossentry>
1728
1729 <glossentry id='var-BUILD_OPTIMIZATION'><glossterm>BUILD_OPTIMIZATION</glossterm>
1730 <info>
1731 BUILD_OPTIMIZATION[doc] = "Specifies the optimization flags passed to the C compiler when building for the build host or the SDK."
1732 </info>
1733 <glossdef>
1734 <para role="glossdeffirst">
1735<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1736 Specifies the optimization flags passed to the C compiler
1737 when building for the build host or the SDK.
1738 The flags are passed through the
1739 <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
1740 and
1741 <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
1742 default values.
1743 </para>
1744
1745 <para>
1746 The default value of the
1747 <filename>BUILD_OPTIMIZATION</filename> variable is
1748 "-O2 -pipe".
1749 </para>
1750 </glossdef>
1751 </glossentry>
1752
1753 <glossentry id='var-BUILD_OS'><glossterm>BUILD_OS</glossterm>
1754 <info>
1755 BUILD_OS[doc] = "The operating system (in lower case) of the building architecture (e.g. Linux)."
1756 </info>
1757 <glossdef>
1758 <para role="glossdeffirst">
1759<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1760 Specifies the operating system in use on the build
1761 host (e.g. "linux").
1762 The OpenEmbedded build system sets the value of
1763 <filename>BUILD_OS</filename> from the OS reported by
1764 the <filename>uname</filename> command - the first word,
1765 converted to lower-case characters.
1766 </para>
1767 </glossdef>
1768 </glossentry>
1769
1770 <glossentry id='var-BUILD_PREFIX'><glossterm>BUILD_PREFIX</glossterm>
1771 <info>
1772 BUILD_PREFIX[doc] = "The toolchain binary prefix used for native recipes."
1773 </info>
1774 <glossdef>
1775 <para role="glossdeffirst">
1776<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1777 The toolchain binary prefix used for native recipes.
1778 The OpenEmbedded build system uses the
1779 <filename>BUILD_PREFIX</filename> value to set the
1780 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001781 when building for <filename>native</filename> recipes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001782 </para>
1783 </glossdef>
1784 </glossentry>
1785
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001786 <glossentry id='var-BUILD_STRIP'><glossterm>BUILD_STRIP</glossterm>
1787 <info>
1788 BUILD_STRIP[doc] = "Specifies the command to be used to strip debugging symbols from binaries produced for the build host."
1789 </info>
1790 <glossdef>
1791 <para role="glossdeffirst">
1792<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1793 Specifies the command to be used to strip debugging symbols
1794 from binaries produced for the build host. By default,
1795 <filename>BUILD_STRIP</filename> points to
1796 <filename>${</filename><link linkend='var-BUILD_PREFIX'><filename>BUILD_PREFIX</filename></link><filename>}strip</filename>.
1797 </para>
1798 </glossdef>
1799 </glossentry>
1800
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001801 <glossentry id='var-BUILD_SYS'><glossterm>BUILD_SYS</glossterm>
1802 <info>
1803 BUILD_SYS[doc] = "The toolchain binary prefix used for native recipes."
1804 </info>
1805 <glossdef>
1806 <para role="glossdeffirst">
1807<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1808 Specifies the system, including the architecture and
1809 the operating system, to use when building for the build
1810 host (i.e. when building <filename>native</filename>
1811 recipes).
1812 </para>
1813
1814 <para>
1815 The OpenEmbedded build system automatically sets this
1816 variable based on
1817 <link linkend='var-BUILD_ARCH'><filename>BUILD_ARCH</filename></link>,
1818 <link linkend='var-BUILD_VENDOR'><filename>BUILD_VENDOR</filename></link>,
1819 and
1820 <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>.
1821 You do not need to set the <filename>BUILD_SYS</filename>
1822 variable yourself.
1823 </para>
1824 </glossdef>
1825 </glossentry>
1826
1827 <glossentry id='var-BUILD_VENDOR'><glossterm>BUILD_VENDOR</glossterm>
1828 <info>
1829 BUILD_VENDOR[doc] = "The vendor name to use when building for the build host."
1830 </info>
1831 <glossdef>
1832 <para role="glossdeffirst">
1833<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1834 Specifies the vendor name to use when building for the
1835 build host.
1836 The default value is an empty string ("").
1837 </para>
1838 </glossdef>
1839 </glossentry>
1840
1841 <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
1842 <info>
1843 BUILDDIR[doc] = "Points to the location of the Build Directory."
1844 </info>
1845 <glossdef>
1846 <para role="glossdeffirst">
1847<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1848 Points to the location of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001849 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001850 You can define this directory indirectly through the
1851 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001852 script by passing in a Build Directory path when you run
1853 the script.
1854 If you run the script and do not provide a Build Directory
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001855 path, the <filename>BUILDDIR</filename> defaults to
1856 <filename>build</filename> in the current directory.
1857 </para>
1858 </glossdef>
1859 </glossentry>
1860
1861 <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>BUILDHISTORY_COMMIT</glossterm>
1862 <info>
1863 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."
1864 </info>
1865 <glossdef>
1866 <para role="glossdeffirst">
1867<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1868 When inheriting the
1869 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1870 class, this variable specifies whether or not to commit the
1871 build history output in a local Git repository.
1872 If set to "1", this local repository will be maintained
1873 automatically by the
1874 <filename>buildhistory</filename>
1875 class and a commit will be created on every
1876 build for changes to each top-level subdirectory of the
1877 build history output (images, packages, and sdk).
1878 If you want to track changes to build history over
1879 time, you should set this value to "1".
1880 </para>
1881
1882 <para>
1883 By default, the <filename>buildhistory</filename> class
1884 does not commit the build history output in a local
1885 Git repository:
1886 <literallayout class='monospaced'>
1887 BUILDHISTORY_COMMIT ?= "0"
1888 </literallayout>
1889 </para>
1890 </glossdef>
1891 </glossentry>
1892
1893 <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>BUILDHISTORY_COMMIT_AUTHOR</glossterm>
1894 <info>
1895 BUILDHISTORY_COMMIT_AUTHOR[doc] = "When inheriting the buildhistory class, this variable specifies the author to use for each Git commit."
1896 </info>
1897 <glossdef>
1898 <para role="glossdeffirst">
1899<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1900 When inheriting the
1901 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1902 class, this variable specifies the author to use for each
1903 Git commit.
1904 In order for the <filename>BUILDHISTORY_COMMIT_AUTHOR</filename>
1905 variable to work, the
1906 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
1907 variable must be set to "1".
1908 </para>
1909
1910 <para>
1911 Git requires that the value you provide for the
1912 <filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable
Brad Bishop316dfdd2018-06-25 12:45:53 -04001913 takes the form of "name <replaceable>email@host</replaceable>".
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001914 Providing an email address or host that is not valid does
1915 not produce an error.
1916 </para>
1917
1918 <para>
1919 By default, the <filename>buildhistory</filename> class
1920 sets the variable as follows:
1921 <literallayout class='monospaced'>
1922 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory &lt;buildhistory@${DISTRO}&gt;"
1923 </literallayout>
1924 </para>
1925 </glossdef>
1926 </glossentry>
1927
1928 <glossentry id='var-BUILDHISTORY_DIR'><glossterm>BUILDHISTORY_DIR</glossterm>
1929 <info>
1930 BUILDHISTORY_DIR[doc] = "When inheriting the buildhistory class, this variable specifies the directory in which build history information is kept."
1931 </info>
1932 <glossdef>
1933 <para role="glossdeffirst">
1934<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1935 When inheriting the
1936 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1937 class, this variable specifies the directory in which
1938 build history information is kept.
1939 For more information on how the variable works, see the
1940 <filename>buildhistory.class</filename>.
1941 </para>
1942
1943 <para>
1944 By default, the <filename>buildhistory</filename> class
1945 sets the directory as follows:
1946 <literallayout class='monospaced'>
1947 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
1948 </literallayout>
1949 </para>
1950 </glossdef>
1951 </glossentry>
1952
1953 <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>BUILDHISTORY_FEATURES</glossterm>
1954 <info>
1955 BUILDHISTORY_FEATURES[doc] = "When inheriting the buildhistory class, this variable specifies the build history features to be enabled."
1956 </info>
1957 <glossdef>
1958 <para role="glossdeffirst">
1959<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1960 When inheriting the
1961 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1962 class, this variable specifies the build history features
1963 to be enabled.
1964 For more information on how build history works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04001965 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
1966 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001967 </para>
1968
1969 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001970 You can specify these features in the form of a
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001971 space-separated list:
1972 <itemizedlist>
1973 <listitem><para><emphasis>image:</emphasis>
1974 Analysis of the contents of images, which
1975 includes the list of installed packages among other
1976 things.
1977 </para></listitem>
1978 <listitem><para><emphasis>package:</emphasis>
1979 Analysis of the contents of individual packages.
1980 </para></listitem>
1981 <listitem><para><emphasis>sdk:</emphasis>
1982 Analysis of the contents of the software
1983 development kit (SDK).
1984 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001985 <listitem><para><emphasis>task:</emphasis>
1986 Save output file signatures for
1987 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state</ulink>
1988 (sstate) tasks.
1989 This saves one file per task and lists the SHA-256
1990 checksums for each file staged (i.e. the output of
1991 the task).
1992 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001993 </itemizedlist>
1994 </para>
1995
1996 <para>
1997 By default, the <filename>buildhistory</filename> class
Brad Bishop316dfdd2018-06-25 12:45:53 -04001998 enables the following features:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001999 <literallayout class='monospaced'>
2000 BUILDHISTORY_FEATURES ?= "image package sdk"
2001 </literallayout>
2002 </para>
2003 </glossdef>
2004 </glossentry>
2005
2006 <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>BUILDHISTORY_IMAGE_FILES</glossterm>
2007 <info>
2008 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."
2009 </info>
2010 <glossdef>
2011 <para role="glossdeffirst">
2012<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2013 When inheriting the
2014 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
2015 class, this variable specifies a list of paths to files
2016 copied from the
2017 image contents into the build history directory under
2018 an "image-files" directory in the directory for
2019 the image, so that you can track the contents of each file.
2020 The default is to copy <filename>/etc/passwd</filename>
2021 and <filename>/etc/group</filename>, which allows you to
2022 monitor for changes in user and group entries.
2023 You can modify the list to include any file.
2024 Specifying an invalid path does not produce an error.
2025 Consequently, you can include files that might
2026 not always be present.
2027 </para>
2028
2029 <para>
2030 By default, the <filename>buildhistory</filename> class
2031 provides paths to the following files:
2032 <literallayout class='monospaced'>
2033 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
2034 </literallayout>
2035 </para>
2036 </glossdef>
2037 </glossentry>
2038
2039 <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>BUILDHISTORY_PUSH_REPO</glossterm>
2040 <info>
2041 BUILDHISTORY_PUSH_REPO[doc] = "When inheriting the buildhistory class, this variable optionally specifies a remote repository to which build history pushes Git changes."
2042 </info>
2043 <glossdef>
2044 <para role="glossdeffirst">
2045<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2046 When inheriting the
2047 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
2048 class, this variable optionally specifies a remote
2049 repository to which build history pushes Git changes.
2050 In order for <filename>BUILDHISTORY_PUSH_REPO</filename>
2051 to work,
2052 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
2053 must be set to "1".
2054 </para>
2055
2056 <para>
2057 The repository should correspond to a remote
2058 address that specifies a repository as understood by
2059 Git, or alternatively to a remote name that you have
2060 set up manually using <filename>git remote</filename>
2061 within the local repository.
2062 </para>
2063
2064 <para>
2065 By default, the <filename>buildhistory</filename> class
2066 sets the variable as follows:
2067 <literallayout class='monospaced'>
2068 BUILDHISTORY_PUSH_REPO ?= ""
2069 </literallayout>
2070 </para>
2071 </glossdef>
2072 </glossentry>
2073
2074 <glossentry id='var-BUILDSDK_CFLAGS'><glossterm>BUILDSDK_CFLAGS</glossterm>
2075 <info>
2076 BUILDSDK_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the SDK."
2077 </info>
2078 <glossdef>
2079 <para role="glossdeffirst">
2080<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2081 Specifies the flags to pass to the C compiler when building
2082 for the SDK.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002083 When building in the <filename>nativesdk-</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002084 context,
2085 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
2086 is set to the value of this variable by default.
2087 </para>
2088 </glossdef>
2089 </glossentry>
2090
2091 <glossentry id='var-BUILDSDK_CPPFLAGS'><glossterm>BUILDSDK_CPPFLAGS</glossterm>
2092 <info>
2093 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."
2094 </info>
2095 <glossdef>
2096 <para role="glossdeffirst">
2097<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2098 Specifies the flags to pass to the C pre-processor
2099 (i.e. to both the C and the C++ compilers) when building
2100 for the SDK.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002101 When building in the <filename>nativesdk-</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002102 context,
2103 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
2104 is set to the value of this variable by default.
2105 </para>
2106 </glossdef>
2107 </glossentry>
2108
2109 <glossentry id='var-BUILDSDK_CXXFLAGS'><glossterm>BUILDSDK_CXXFLAGS</glossterm>
2110 <info>
2111 BUILDSDK_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the SDK."
2112 </info>
2113 <glossdef>
2114 <para role="glossdeffirst">
2115<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2116 Specifies the flags to pass to the C++ compiler when
2117 building for the SDK.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002118 When building in the <filename>nativesdk-</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002119 context,
2120 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
2121 is set to the value of this variable by default.
2122 </para>
2123 </glossdef>
2124 </glossentry>
2125
2126 <glossentry id='var-BUILDSDK_LDFLAGS'><glossterm>BUILDSDK_LDFLAGS</glossterm>
2127 <info>
2128 BUILDSDK_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the SDK."
2129 </info>
2130 <glossdef>
2131 <para role="glossdeffirst">
2132<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2133 Specifies the flags to pass to the linker when building
2134 for the SDK.
2135 When building in the <filename>nativesdk-</filename>
2136 context,
2137 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
2138 is set to the value of this variable by default.
2139 </para>
2140 </glossdef>
2141 </glossentry>
2142
2143 <glossentry id='var-BUILDSTATS_BASE'><glossterm>BUILDSTATS_BASE</glossterm>
2144 <info>
2145 BUILDSTATS_BASE[doc] = "Points to the location of the directory that holds build statistics when you use and enable the buildstats class."
2146 </info>
2147 <glossdef>
2148 <para role="glossdeffirst">
2149<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2150 Points to the location of the directory that holds build
2151 statistics when you use and enable the
2152 <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link>
2153 class.
2154 The <filename>BUILDSTATS_BASE</filename> directory defaults
2155 to
2156 <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/buildstats/</filename>.
2157 </para>
2158 </glossdef>
2159 </glossentry>
2160
2161 <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
2162 <info>
2163 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."
2164 </info>
2165 <glossdef>
2166 <para role="glossdeffirst">
2167<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2168 For the BusyBox recipe, specifies whether to split the
2169 output executable file into two parts: one for features
2170 that require <filename>setuid root</filename>, and one for
2171 the remaining features (i.e. those that do not require
2172 <filename>setuid root</filename>).
2173 </para>
2174
2175 <para>
2176 The <filename>BUSYBOX_SPLIT_SUID</filename> variable
2177 defaults to "1", which results in a single output
2178 executable file.
2179 Set the variable to "0" to split the output file.
2180 </para>
2181 </glossdef>
2182 </glossentry>
2183
2184 </glossdiv>
2185
2186 <glossdiv id='var-glossary-c'><title>C</title>
2187
2188 <glossentry id='var-CACHE'><glossterm>CACHE</glossterm>
2189 <info>
2190 CACHE[doc] = "The directory BitBake uses to store a cache of the metadata."
2191 </info>
2192 <glossdef>
2193 <para role="glossdeffirst">
2194<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2195 Specifies the directory BitBake uses to store a cache
2196 of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002197 <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002198 so it does not need to be parsed every time BitBake is
2199 started.
2200 </para>
2201 </glossdef>
2202 </glossentry>
2203
2204 <glossentry id='var-CC'><glossterm>CC</glossterm>
2205 <info>
2206 CC[doc] = "Minimum command and arguments to run the C compiler."
2207 </info>
2208 <glossdef>
2209 <para role="glossdeffirst">
2210<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2211 The minimal command and arguments used to run the C
2212 compiler.
2213 </para>
2214 </glossdef>
2215 </glossentry>
2216
2217 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
2218 <info>
2219 CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as TARGET_CFLAGS."
2220 </info>
2221 <glossdef>
2222 <para role="glossdeffirst">
2223<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2224 Specifies the flags to pass to the C compiler.
2225 This variable is exported to an environment
2226 variable and thus made visible to the software being
2227 built during the compilation step.
2228 </para>
2229
2230 <para>
2231 Default initialization for <filename>CFLAGS</filename>
2232 varies depending on what is being built:
2233 <itemizedlist>
2234 <listitem><para>
2235 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
2236 when building for the target
2237 </para></listitem>
2238 <listitem><para>
2239 <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
2240 when building for the build host (i.e.
2241 <filename>-native</filename>)
2242 </para></listitem>
2243 <listitem><para>
2244 <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
2245 when building for an SDK (i.e.
2246 <filename>nativesdk-</filename>)
2247 </para></listitem>
2248 </itemizedlist>
2249 </para>
2250 </glossdef>
2251 </glossentry>
2252
2253 <glossentry id='var-CLASSOVERRIDE'><glossterm>CLASSOVERRIDE</glossterm>
2254 <info>
2255 CLASSOVERRIDE[doc] = "An internal variable specifying the special class override that should currently apply (e.g. "class-target", "class-native", and so forth)."
2256 </info>
2257 <glossdef>
2258 <para role="glossdeffirst">
2259<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2260 An internal variable specifying the special class override
2261 that should currently apply (e.g. "class-target",
2262 "class-native", and so forth).
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002263 The classes that use this variable (e.g.
2264 <link linkend='ref-classes-native'><filename>native</filename></link>,
2265 <link linkend='ref-classes-nativesdk'><filename>nativesdk</filename></link>,
2266 and so forth) set the variable to appropriate values.
2267 <note>
2268 <filename>CLASSOVERRIDE</filename> gets its default
2269 "class-target" value from the
2270 <filename>bitbake.conf</filename> file.
2271 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002272 </para>
2273
2274 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002275 As an example, the following override allows you to install
2276 extra files, but only when building for the target:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002277 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002278 do_install_append_class-target() {
2279 install my-extra-file ${D}${sysconfdir}
2280 }
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002281 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002282 Here is an example where <filename>FOO</filename>
2283 is set to "native" when building for the build host, and
2284 to "other" when not building for the build host:
2285 <literallayout class='monospaced'>
2286 FOO_class-native = "native"
2287 FOO = "other"
2288 </literallayout>
2289 The underlying mechanism behind
2290 <filename>CLASSOVERRIDE</filename> is simply that it is
2291 included in the default value of
2292 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002293 </para>
2294 </glossdef>
2295 </glossentry>
2296
2297 <glossentry id='var-CLEANBROKEN'><glossterm>CLEANBROKEN</glossterm>
2298 <info>
2299 CLEANBROKEN[doc] = "Prevents the build system from running 'make clean' during the do_configure task."
2300 </info>
2301 <glossdef>
2302 <para role="glossdeffirst">
2303<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2304 If set to "1" within a recipe,
2305 <filename>CLEANBROKEN</filename> specifies that
2306 the <filename>make clean</filename> command does
2307 not work for the software being built.
2308 Consequently, the OpenEmbedded build system will not try
2309 to run <filename>make clean</filename> during the
2310 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2311 task, which is the default behavior.
2312 </para>
2313 </glossdef>
2314 </glossentry>
2315
2316 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
2317 <info>
2318 COMBINED_FEATURES[doc] = "A set of features common between MACHINE_FEATURES and DISTRO_FEATURES."
2319 </info>
2320 <glossdef>
2321 <para role="glossdeffirst">
2322<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2323 Provides a list of hardware features that are enabled in
2324 both
2325 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
2326 and
2327 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
2328 This select list of features contains features that make
2329 sense to be controlled both at the machine and distribution
2330 configuration level.
2331 For example, the "bluetooth" feature requires hardware
2332 support but should also be optional at the distribution
2333 level, in case the hardware supports Bluetooth but you
2334 do not ever intend to use it.
2335 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002336 </glossdef>
2337 </glossentry>
2338
2339 <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
2340 <info>
2341 COMMON_LICENSE_DIR[doc] = "Points to meta/files/common-licenses in the Source Directory, which is where generic license files reside."
2342 </info>
2343 <glossdef>
2344 <para role="glossdeffirst">
2345<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2346 Points to <filename>meta/files/common-licenses</filename>
2347 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002348 <link linkend='source-directory'>Source Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002349 which is where generic license files reside.
2350 </para>
2351 </glossdef>
2352 </glossentry>
2353
2354 <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
2355 <info>
2356 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."
2357 </info>
2358 <glossdef>
2359 <para role="glossdeffirst">
2360<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2361 A regular expression that resolves to one or more hosts
2362 (when the recipe is native) or one or more targets (when
2363 the recipe is non-native) with which a recipe is compatible.
2364 The regular expression is matched against
2365 <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
2366 You can use the variable to stop recipes from being built
2367 for classes of systems with which the recipes are not
2368 compatible.
2369 Stopping these builds is particularly useful with kernels.
2370 The variable also helps to increase parsing speed
2371 since the build system skips parsing recipes not
2372 compatible with the current system.
2373 </para>
2374 </glossdef>
2375 </glossentry>
2376
2377 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
2378 <info>
2379 COMPATIBLE_MACHINE[doc] = "A regular expression that resolves to one or more target machines with which a recipe is compatible."
2380 </info>
2381 <glossdef>
2382 <para role="glossdeffirst">
2383<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2384 A regular expression that resolves to one or more
2385 target machines with which a recipe is compatible.
2386 The regular expression is matched against
2387 <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
2388 You can use the variable to stop recipes from being built
2389 for machines with which the recipes are not compatible.
2390 Stopping these builds is particularly useful with kernels.
2391 The variable also helps to increase parsing speed
2392 since the build system skips parsing recipes not
2393 compatible with the current machine.
2394 </para>
2395 </glossdef>
2396 </glossentry>
2397
2398 <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
2399 <info>
2400 COMPLEMENTARY_GLOB[doc] = "Defines wildcards to match when installing a list of complementary packages for all the packages installed in an image."
2401 </info>
2402 <glossdef>
2403 <para role="glossdeffirst">
2404<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2405 Defines wildcards to match when installing a list of
2406 complementary packages for all the packages explicitly
2407 (or implicitly) installed in an image.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08002408 <note>
2409 The <filename>COMPLEMENTARY_GLOB</filename> variable
2410 uses Unix filename pattern matching
2411 (<ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>),
2412 which is similar to the Unix style pathname pattern
2413 expansion
2414 (<ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>).
2415 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002416 The resulting list of complementary packages is associated
2417 with an item that can be added to
2418 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
2419 An example usage of this is the "dev-pkgs" item that when
2420 added to <filename>IMAGE_FEATURES</filename> will
2421 install -dev packages (containing headers and other
2422 development files) for every package in the image.
2423 </para>
2424
2425 <para>
2426 To add a new feature item pointing to a wildcard, use a
2427 variable flag to specify the feature item name and
2428 use the value to specify the wildcard.
2429 Here is an example:
2430 <literallayout class='monospaced'>
2431 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
2432 </literallayout>
2433 </para>
2434 </glossdef>
2435 </glossentry>
2436
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002437 <glossentry id='var-COMPONENTS_DIR'><glossterm>COMPONENTS_DIR</glossterm>
2438 <info>
2439 COMPONENTS_DIR[doc] = "Stores sysroot components for each recipe."
2440 </info>
2441 <glossdef>
2442 <para role="glossdeffirst">
2443<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2444 Stores sysroot components for each recipe.
2445 The OpenEmbedded build system uses
2446 <filename>COMPONENTS_DIR</filename> when constructing
2447 recipe-specific sysroots for other recipes.
2448 </para>
2449
2450 <para>
2451 The default is
2452 "<filename>${</filename><link linkend='var-STAGING_DIR'><filename>STAGING_DIR</filename></link><filename>}-components</filename>."
2453 (i.e. "<filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots-components</filename>").
2454 </para>
2455 </glossdef>
2456 </glossentry>
2457
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002458 <glossentry id='var-CONF_VERSION'><glossterm>CONF_VERSION</glossterm>
2459 <info>
2460 CONF_VERSION[doc] = "Tracks the version of local.conf. Increased each time build/conf/ changes incompatibly."
2461 </info>
2462 <glossdef>
2463 <para role="glossdeffirst">
2464<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2465 Tracks the version of the local configuration file
2466 (i.e. <filename>local.conf</filename>).
2467 The value for <filename>CONF_VERSION</filename>
2468 increments each time <filename>build/conf/</filename>
2469 compatibility changes.
2470 </para>
2471 </glossdef>
2472 </glossentry>
2473
2474 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
2475 <info>
2476 CONFFILES[doc] = "Identifies editable or configurable files that are part of a package."
2477 </info>
2478 <glossdef>
2479 <para role="glossdeffirst">
2480<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2481 Identifies editable or configurable files that are part of a package.
2482 If the Package Management System (PMS) is being used to update
2483 packages on the target system, it is possible that
2484 configuration files you have changed after the original installation
2485 and that you now want to remain unchanged are overwritten.
2486 In other words, editable files might exist in the package that you do not
2487 want reset as part of the package update process.
2488 You can use the <filename>CONFFILES</filename> variable to list the files in the
2489 package that you wish to prevent the PMS from overwriting during this update process.
2490 </para>
2491
2492 <para>
2493 To use the <filename>CONFFILES</filename> variable, provide a package name
2494 override that identifies the resulting package.
2495 Then, provide a space-separated list of files.
2496 Here is an example:
2497 <literallayout class='monospaced'>
2498 CONFFILES_${PN} += "${sysconfdir}/file1 \
2499 ${sysconfdir}/file2 ${sysconfdir}/file3"
2500 </literallayout>
2501 </para>
2502
2503 <para>
2504 A relationship exists between the <filename>CONFFILES</filename> and
2505 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
2506 The files listed within <filename>CONFFILES</filename> must be a subset of
2507 the files listed within <filename>FILES</filename>.
2508 Because the configuration files you provide with <filename>CONFFILES</filename>
2509 are simply being identified so that the PMS will not overwrite them,
2510 it makes sense that
2511 the files must already be included as part of the package through the
2512 <filename>FILES</filename> variable.
2513 </para>
2514
2515 <note>
2516 When specifying paths as part of the <filename>CONFFILES</filename> variable,
2517 it is good practice to use appropriate path variables.
2518 For example, <filename>${sysconfdir}</filename> rather than
2519 <filename>/etc</filename> or <filename>${bindir}</filename> rather
2520 than <filename>/usr/bin</filename>.
2521 You can find a list of these variables at the top of the
2522 <filename>meta/conf/bitbake.conf</filename> file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002523 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002524 </note>
2525 </glossdef>
2526 </glossentry>
2527
2528 <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>
2529 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05002530 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 -05002531 </info>
2532 <glossdef>
2533 <para role="glossdeffirst">
2534<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop37a0e4d2017-12-04 01:01:44 -05002535 Identifies the initial RAM filesystem (initramfs) source
2536 files.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002537 The OpenEmbedded build system receives and uses
2538 this kernel Kconfig variable as an environment variable.
2539 By default, the variable is set to null ("").
2540 </para>
2541
2542 <para>
2543 The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be
2544 either a single cpio archive with a
2545 <filename>.cpio</filename> suffix or a
2546 space-separated list of directories and files for building
2547 the initramfs image.
2548 A cpio archive should contain a filesystem archive
2549 to be used as an initramfs image.
2550 Directories should contain a filesystem layout to be
2551 included in the initramfs image.
2552 Files should contain entries according to the format
2553 described by the
2554 <filename>usr/gen_init_cpio</filename> program in the
2555 kernel tree.
2556 </para>
2557
2558 <para>
2559 If you specify multiple directories and files, the
2560 initramfs image will be the aggregate of all of them.
2561 </para>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05002562
2563 <para>
2564 For information on creating an initramfs, see the
2565 "<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 -05002566 section in the Yocto Project Development Tasks Manual.
Brad Bishop37a0e4d2017-12-04 01:01:44 -05002567 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002568 </glossdef>
2569 </glossentry>
2570
2571 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
2572 <info>
2573 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."
2574 </info>
2575 <glossdef>
2576 <para role="glossdeffirst">
2577<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2578 A list of files that contains <filename>autoconf</filename> test results relevant
2579 to the current build.
2580 This variable is used by the Autotools utilities when running
2581 <filename>configure</filename>.
2582 </para>
2583 </glossdef>
2584 </glossentry>
2585
2586 <glossentry id='var-CONFIGURE_FLAGS'><glossterm>CONFIGURE_FLAGS</glossterm>
2587 <info>
2588 CONFIGURE_FLAGS[doc] = "The minimal arguments for GNU configure."
2589 </info>
2590 <glossdef>
2591 <para role="glossdeffirst">
2592<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2593 The minimal arguments for GNU configure.
2594 </para>
2595 </glossdef>
2596 </glossentry>
2597
2598 <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>CONFLICT_DISTRO_FEATURES</glossterm>
2599 <info>
2600 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."
2601 </info>
2602 <glossdef>
2603 <para role="glossdeffirst">
2604<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2605 When inheriting the
2606 <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link>
2607 class, this
2608 variable identifies distribution features that would
2609 be in conflict should the recipe
2610 be built.
2611 In other words, if the
2612 <filename>CONFLICT_DISTRO_FEATURES</filename> variable
2613 lists a feature that also appears in
2614 <filename>DISTRO_FEATURES</filename> within the
2615 current configuration, an error occurs and the
2616 build stops.
2617 </para>
2618 </glossdef>
2619 </glossentry>
2620
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002621 <glossentry id='var-COPYLEFT_LICENSE_EXCLUDE'><glossterm>COPYLEFT_LICENSE_EXCLUDE</glossterm>
2622 <info>
2623 COPYLEFT_LICENSE_EXCLUDE[doc] = "Licenses to exclude in the source archived by the archiver class."
2624 </info>
2625 <glossdef>
2626 <para role="glossdeffirst">
2627<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2628 A space-separated list of licenses to exclude from the
2629 source archived by the
2630 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2631 class.
2632 In other words, if a license in a recipe's
2633 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2634 value is in the value of
2635 <filename>COPYLEFT_LICENSE_EXCLUDE</filename>, then its
2636 source is not archived by the class.
2637 <note>
2638 The <filename>COPYLEFT_LICENSE_EXCLUDE</filename>
2639 variable takes precedence over the
2640 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2641 variable.
2642 </note>
2643 The default value, which is "CLOSED Proprietary", for
2644 <filename>COPYLEFT_LICENSE_EXCLUDE</filename> is set
2645 by the
2646 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2647 class, which is inherited by the
2648 <filename>archiver</filename> class.
2649 </para>
2650 </glossdef>
2651 </glossentry>
2652
2653 <glossentry id='var-COPYLEFT_LICENSE_INCLUDE'><glossterm>COPYLEFT_LICENSE_INCLUDE</glossterm>
2654 <info>
2655 COPYLEFT_LICENSE_INCLUDE[doc] = "Licenses to include in the source archived by the archiver class."
2656 </info>
2657 <glossdef>
2658 <para role="glossdeffirst">
2659<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2660 A space-separated list of licenses to include in the
2661 source archived by the
2662 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2663 class.
2664 In other words, if a license in a recipe's
2665 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2666 value is in the value of
2667 <filename>COPYLEFT_LICENSE_INCLUDE</filename>, then its
2668 source is archived by the class.
2669 </para>
2670
2671 <para>
2672 The default value is set by the
2673 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2674 class, which is inherited by the
2675 <filename>archiver</filename> class.
2676 The default value includes "GPL*", "LGPL*", and "AGPL*".
2677 </para>
2678 </glossdef>
2679 </glossentry>
2680
2681 <glossentry id='var-COPYLEFT_PN_EXCLUDE'><glossterm>COPYLEFT_PN_EXCLUDE</glossterm>
2682 <info>
2683 COPYLEFT_PN_EXCLUDE[doc] = "Recipes to exclude in the source archived by the archiver class."
2684 </info>
2685 <glossdef>
2686 <para role="glossdeffirst">
2687<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2688 A list of recipes to exclude in the source archived
2689 by the
2690 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2691 class.
2692 The <filename>COPYLEFT_PN_EXCLUDE</filename> variable
2693 overrides the license inclusion and exclusion caused
2694 through the
2695 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2696 and
2697 <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link>
2698 variables, respectively.
2699 </para>
2700
2701 <para>
2702 The default value, which is "" indicating to not explicitly
2703 exclude any recipes by name, for
2704 <filename>COPYLEFT_PN_EXCLUDE</filename> is set
2705 by the
2706 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2707 class, which is inherited by the
2708 <filename>archiver</filename> class.
2709 </para>
2710 </glossdef>
2711 </glossentry>
2712
2713 <glossentry id='var-COPYLEFT_PN_INCLUDE'><glossterm>COPYLEFT_PN_INCLUDE</glossterm>
2714 <info>
2715 COPYLEFT_PN_INCLUDE[doc] = "Recipes to include in the source archived by the archiver class."
2716 </info>
2717 <glossdef>
2718 <para role="glossdeffirst">
2719<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2720 A list of recipes to include in the source archived
2721 by the
2722 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2723 class.
2724 The <filename>COPYLEFT_PN_INCLUDE</filename> variable
2725 overrides the license inclusion and exclusion caused
2726 through the
2727 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2728 and
2729 <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link>
2730 variables, respectively.
2731 </para>
2732
2733 <para>
2734 The default value, which is "" indicating to not explicitly
2735 include any recipes by name, for
2736 <filename>COPYLEFT_PN_INCLUDE</filename> is set
2737 by the
2738 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2739 class, which is inherited by the
2740 <filename>archiver</filename> class.
2741 </para>
2742 </glossdef>
2743 </glossentry>
2744
2745 <glossentry id='var-COPYLEFT_RECIPE_TYPES'><glossterm>COPYLEFT_RECIPE_TYPES</glossterm>
2746 <info>
2747 COPYLEFT_RECIPE_TYPES[doc] = "Recipe types to include in the source archived by the archiver class."
2748 </info>
2749 <glossdef>
2750 <para role="glossdeffirst">
2751<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2752 A space-separated list of recipe types to include
2753 in the source archived by the
2754 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2755 class.
2756 Recipe types are <filename>target</filename>,
2757 <filename>native</filename>,
2758 <filename>nativesdk</filename>,
2759 <filename>cross</filename>,
2760 <filename>crosssdk</filename>, and
2761 <filename>cross-canadian</filename>.
2762 </para>
2763
2764 <para>
2765 The default value, which is "target*", for
2766 <filename>COPYLEFT_RECIPE_TYPES</filename> is set
2767 by the
2768 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2769 class, which is inherited by the
2770 <filename>archiver</filename> class.
2771 </para>
2772 </glossdef>
2773 </glossentry>
2774
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002775 <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm>
2776 <info>
2777 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."
2778 </info>
2779 <glossdef>
2780 <para role="glossdeffirst">
2781<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2782 If set to "1" along with the
2783 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
2784 variable, the OpenEmbedded build system copies
2785 into the image the license files, which are located in
2786 <filename>/usr/share/common-licenses</filename>,
2787 for each package.
2788 The license files are placed
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002789 in directories within the image itself during build time.
2790 <note>
2791 The <filename>COPY_LIC_DIRS</filename> does not
2792 offer a path for adding licenses for newly installed
2793 packages to an image, which might be most suitable
2794 for read-only filesystems that cannot be upgraded.
2795 See the
2796 <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link>
2797 variable for additional information.
2798 You can also reference the
2799 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002800 section in the Yocto Project Development Tasks Manual
2801 for information on providing license text.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002802 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002803 </para>
2804 </glossdef>
2805 </glossentry>
2806
2807 <glossentry id='var-COPY_LIC_MANIFEST'><glossterm>COPY_LIC_MANIFEST</glossterm>
2808 <info>
2809 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."
2810 </info>
2811 <glossdef>
2812 <para role="glossdeffirst">
2813<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2814 If set to "1", the OpenEmbedded build system copies
2815 the license manifest for the image to
2816 <filename>/usr/share/common-licenses/license.manifest</filename>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002817 within the image itself during build time.
2818 <note>
2819 The <filename>COPY_LIC_MANIFEST</filename> does not
2820 offer a path for adding licenses for newly installed
2821 packages to an image, which might be most suitable
2822 for read-only filesystems that cannot be upgraded.
2823 See the
2824 <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link>
2825 variable for additional information.
2826 You can also reference the
2827 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002828 section in the Yocto Project Development Tasks Manual
2829 for information on providing license text.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002830 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002831 </para>
2832 </glossdef>
2833 </glossentry>
2834
2835 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
2836 <info>
2837 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."
2838 </info>
2839 <glossdef>
2840 <para role="glossdeffirst">
2841<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2842 Specifies the list of packages to be added to the image.
2843 You should only set this variable in the
2844 <filename>local.conf</filename> configuration file found
2845 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002846 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002847 </para>
2848
2849 <para>
2850 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
2851 </para>
2852 </glossdef>
2853 </glossentry>
2854
2855 <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
2856 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002857 COREBASE[doc] = "Specifies the parent directory of the OpenEmbedded-Core Metadata layer (i.e. meta)."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002858 </info>
2859 <glossdef>
2860 <para role="glossdeffirst">
2861<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -04002862 Specifies the parent directory of the OpenEmbedded-Core
2863 Metadata layer (i.e. <filename>meta</filename>).
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002864 </para>
2865
2866 <para>
2867 It is an important distinction that
2868 <filename>COREBASE</filename> points to the parent of this
2869 layer and not the layer itself.
2870 Consider an example where you have cloned the Poky Git
2871 repository and retained the <filename>poky</filename>
2872 name for your local copy of the repository.
2873 In this case, <filename>COREBASE</filename> points to
2874 the <filename>poky</filename> folder because it is the
2875 parent directory of the <filename>poky/meta</filename>
2876 layer.
2877 </para>
2878 </glossdef>
2879 </glossentry>
2880
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002881 <glossentry id='var-COREBASE_FILES'><glossterm>COREBASE_FILES</glossterm>
2882 <info>
2883 COREBASE_FILES[doc] = "Lists files from the COREBASE directory that should be copied other than the layers listed in the bblayers.conf file."
2884 </info>
2885 <glossdef>
2886 <para role="glossdeffirst">
2887<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2888 Lists files from the
2889 <link linkend='var-COREBASE'><filename>COREBASE</filename></link>
2890 directory that should be copied other than the layers
2891 listed in the <filename>bblayers.conf</filename> file.
2892 The <filename>COREBASE_FILES</filename> variable exists
2893 for the purpose of copying metadata from the
2894 OpenEmbedded build system into the extensible
2895 SDK.
2896 </para>
2897
2898 <para>
2899 Explicitly listing files in <filename>COREBASE</filename>
2900 is needed because it typically contains build
2901 directories and other files that should not normally
2902 be copied into the extensible SDK.
2903 Consequently, the value of
2904 <filename>COREBASE_FILES</filename> is used in order to
2905 only copy the files that are actually needed.
2906 </para>
2907 </glossdef>
2908 </glossentry>
2909
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002910 <glossentry id='var-CPP'><glossterm>CPP</glossterm>
2911 <info>
2912 CPP[doc] = "Minimum command and arguments to run the C preprocessor."
2913 </info>
2914 <glossdef>
2915 <para role="glossdeffirst">
2916<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2917 The minimal command and arguments used to run the C
2918 preprocessor.
2919 </para>
2920 </glossdef>
2921 </glossentry>
2922
2923 <glossentry id='var-CPPFLAGS'><glossterm>CPPFLAGS</glossterm>
2924 <info>
2925 CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers)."
2926 </info>
2927 <glossdef>
2928 <para role="glossdeffirst">
2929<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2930 Specifies the flags to pass to the C pre-processor
2931 (i.e. to both the C and the C++ compilers).
2932 This variable is exported to an environment
2933 variable and thus made visible to the software being
2934 built during the compilation step.
2935 </para>
2936
2937 <para>
2938 Default initialization for <filename>CPPFLAGS</filename>
2939 varies depending on what is being built:
2940 <itemizedlist>
2941 <listitem><para>
2942 <link linkend='var-TARGET_CPPFLAGS'><filename>TARGET_CPPFLAGS</filename></link>
2943 when building for the target
2944 </para></listitem>
2945 <listitem><para>
2946 <link linkend='var-BUILD_CPPFLAGS'><filename>BUILD_CPPFLAGS</filename></link>
2947 when building for the build host (i.e.
2948 <filename>-native</filename>)
2949 </para></listitem>
2950 <listitem><para>
2951 <link linkend='var-BUILDSDK_CPPFLAGS'><filename>BUILDSDK_CPPFLAGS</filename></link>
2952 when building for an SDK (i.e.
2953 <filename>nativesdk-</filename>)
2954 </para></listitem>
2955 </itemizedlist>
2956 </para>
2957 </glossdef>
2958 </glossentry>
2959
2960 <glossentry id='var-CROSS_COMPILE'><glossterm>CROSS_COMPILE</glossterm>
2961 <info>
2962 CROSS_COMPILE[doc] = "The toolchain binary prefix for the target tools."
2963 </info>
2964 <glossdef>
2965 <para role="glossdeffirst">
2966<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2967 The toolchain binary prefix for the target tools.
2968 The <filename>CROSS_COMPILE</filename> variable is the
2969 same as the
2970 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
2971 variable.
2972 <note>
2973 The OpenEmbedded build system sets the
2974 <filename>CROSS_COMPILE</filename> variable only in
2975 certain contexts (e.g. when building for kernel
2976 and kernel module recipes).
2977 </note>
2978 </para>
2979 </glossdef>
2980 </glossentry>
2981
2982 <glossentry id='var-CVSDIR'><glossterm>CVSDIR</glossterm>
2983 <info>
2984 CVSDIR[doc] = "The directory where cvs checkouts will be stored in."
2985 </info>
2986 <glossdef>
2987 <para role="glossdeffirst">
2988<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
2989 The directory in which files checked out under the
2990 CVS system are stored.
2991 </para>
2992 </glossdef>
2993 </glossentry>
2994
2995 <glossentry id='var-CXX'><glossterm>CXX</glossterm>
2996 <info>
2997 CXX[doc] = "Minimum command and arguments to run the C++ compiler."
2998 </info>
2999 <glossdef>
3000 <para role="glossdeffirst">
3001<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3002 The minimal command and arguments used to run the C++
3003 compiler.
3004 </para>
3005 </glossdef>
3006 </glossentry>
3007
3008 <glossentry id='var-CXXFLAGS'><glossterm>CXXFLAGS</glossterm>
3009 <info>
3010 CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler."
3011 </info>
3012 <glossdef>
3013 <para role="glossdeffirst">
3014<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3015 Specifies the flags to pass to the C++ compiler.
3016 This variable is exported to an environment
3017 variable and thus made visible to the software being
3018 built during the compilation step.
3019 </para>
3020
3021 <para>
3022 Default initialization for <filename>CXXFLAGS</filename>
3023 varies depending on what is being built:
3024 <itemizedlist>
3025 <listitem><para>
3026 <link linkend='var-TARGET_CXXFLAGS'><filename>TARGET_CXXFLAGS</filename></link>
3027 when building for the target
3028 </para></listitem>
3029 <listitem><para>
3030 <link linkend='var-BUILD_CXXFLAGS'><filename>BUILD_CXXFLAGS</filename></link>
3031 when building for the build host (i.e.
3032 <filename>-native</filename>)
3033 </para></listitem>
3034 <listitem><para>
3035 <link linkend='var-BUILDSDK_CXXFLAGS'><filename>BUILDSDK_CXXFLAGS</filename></link>
3036 when building for an SDK (i.e.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003037 <filename>nativesdk-</filename>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003038 </para></listitem>
3039 </itemizedlist>
3040 </para>
3041 </glossdef>
3042 </glossentry>
3043
3044 </glossdiv>
3045
3046 <glossdiv id='var-glossary-d'><title>D</title>
3047
3048 <glossentry id='var-D'><glossterm>D</glossterm>
3049 <info>
3050 D[doc] = "The destination directory."
3051 </info>
3052 <glossdef>
3053 <para role="glossdeffirst">
3054<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3055 The destination directory.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003056 The location in the
3057 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003058 where components are installed by the
3059 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
3060 task.
3061 This location defaults to:
3062 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003063 ${WORKDIR}/image
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003064 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003065 <note><title>Caution</title>
3066 Tasks that read from or write to this directory should
3067 run under
Brad Bishop316dfdd2018-06-25 12:45:53 -04003068 <ulink url='&YOCTO_DOCS_OM_URL;#fakeroot-and-pseudo'>fakeroot</ulink>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003069 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003070 </para>
3071 </glossdef>
3072 </glossentry>
3073
3074 <glossentry id='var-DATE'><glossterm>DATE</glossterm>
3075 <info>
3076 DATE[doc] = "The date the build was started using YMD format."
3077 </info>
3078 <glossdef>
3079 <para role="glossdeffirst">
3080<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3081 The date the build was started.
3082 Dates appear using the year, month, and day (YMD) format
3083 (e.g. "20150209" for February 9th, 2015).
3084 </para>
3085 </glossdef>
3086 </glossentry>
3087
3088 <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
3089 <info>
3090 DATETIME[doc] = "The date and time the build was started."
3091 </info>
3092 <glossdef>
3093 <para role="glossdeffirst">
3094<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3095 The date and time on which the current build started.
3096 The format is suitable for timestamps.
3097 </para>
3098 </glossdef>
3099 </glossentry>
3100
3101 <glossentry id='var-DEBIAN_NOAUTONAME'><glossterm>DEBIAN_NOAUTONAME</glossterm>
3102 <info>
3103 DEBIAN_NOAUTONAME[doc] = "Prevents a particular package from being renamed according to Debian package naming."
3104 </info>
3105 <glossdef>
3106 <para role="glossdeffirst">
3107<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3108 When the
3109 <link linkend='ref-classes-debian'><filename>debian</filename></link>
3110 class is inherited, which is the default behavior,
3111 <filename>DEBIAN_NOAUTONAME</filename> specifies a
3112 particular package should not be renamed according to
3113 Debian library package naming.
3114 You must use the package name as an override when you
3115 set this variable.
3116 Here is an example from the <filename>fontconfig</filename>
3117 recipe:
3118 <literallayout class='monospaced'>
3119 DEBIAN_NOAUTONAME_fontconfig-utils = "1"
3120 </literallayout>
3121 </para>
3122 </glossdef>
3123 </glossentry>
3124
3125 <glossentry id='var-DEBIANNAME'><glossterm>DEBIANNAME</glossterm>
3126 <info>
3127 DEBIANNAME[doc] = "Allows you to override the library name for an individual package for Debian library package renaming."
3128 </info>
3129 <glossdef>
3130 <para role="glossdeffirst">
3131<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3132 When the
3133 <link linkend='ref-classes-debian'><filename>debian</filename></link>
3134 class is inherited, which is the default behavior,
3135 <filename>DEBIANNAME</filename> allows you to override the
3136 library name for an individual package.
3137 Overriding the library name in these cases is rare.
3138 You must use the package name as an override when you
3139 set this variable.
3140 Here is an example from the <filename>dbus</filename>
3141 recipe:
3142 <literallayout class='monospaced'>
3143 DEBIANNAME_${PN} = "dbus-1"
3144 </literallayout>
3145 </para>
3146 </glossdef>
3147 </glossentry>
3148
3149 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
3150 <info>
3151 DEBUG_BUILD[doc] = "Specifies to build packages with debugging information. This influences the value of the SELECTED_OPTIMIZATION variable."
3152 </info>
3153 <glossdef>
3154 <para role="glossdeffirst">
3155<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3156 Specifies to build packages with debugging information.
3157 This influences the value of the
3158 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
3159 variable.
3160 </para>
3161 </glossdef>
3162 </glossentry>
3163
3164 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
3165 <info>
3166 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'."
3167 </info>
3168 <glossdef>
3169 <para role="glossdeffirst">
3170<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3171 The options to pass in
3172 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
3173 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
3174 a system for debugging.
3175 This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
3176 </para>
3177 </glossdef>
3178 </glossentry>
3179
3180 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
3181 <info>
3182 DEFAULT_PREFERENCE[doc] = "Specifies a weak bias for recipe selection priority."
3183 </info>
3184 <glossdef>
3185 <para role="glossdeffirst">
3186<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3187 Specifies a weak bias for recipe selection priority.
3188 </para>
3189
3190 <para>
3191 The most common usage of this is variable is to set
3192 it to "-1" within a recipe for a development version of a
3193 piece of software.
3194 Using the variable in this way causes the stable version
3195 of the recipe to build by default in the absence of
3196 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
3197 being used to build the development version.
3198 </para>
3199
3200 <note>
3201 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
3202 is weak and is overridden by
3203 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
3204 if that variable is different between two layers
3205 that contain different versions of the same recipe.
3206 </note>
3207 </glossdef>
3208 </glossentry>
3209
3210 <glossentry id='var-DEFAULTTUNE'><glossterm>DEFAULTTUNE</glossterm>
3211 <info>
3212 DEFAULTTUNE[doc] = "The default CPU and Application Binary Interface (ABI) tunings (i.e. the "tune") used by the OpenEmbedded build system."
3213 </info>
3214 <glossdef>
3215 <para role="glossdeffirst">
3216<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3217 The default CPU and Application Binary Interface (ABI)
3218 tunings (i.e. the "tune") used by the OpenEmbedded build
3219 system.
3220 The <filename>DEFAULTTUNE</filename> helps define
3221 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
3222 </para>
3223
3224 <para>
3225 The default tune is either implicitly or explicitly set
3226 by the machine
3227 (<link linkend='var-MACHINE'><filename>MACHINE</filename></link>).
3228 However, you can override the setting using available tunes
3229 as defined with
3230 <link linkend='var-AVAILTUNES'><filename>AVAILTUNES</filename></link>.
3231 </para>
3232 </glossdef>
3233 </glossentry>
3234
3235 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
3236 <info>
3237 DEPENDS[doc] = "Lists a recipe's build-time dependencies (i.e. other recipe files)."
3238 </info>
3239 <glossdef>
3240 <para role="glossdeffirst">
3241<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003242 Lists a recipe's build-time dependencies.
3243 These are dependencies on other recipes whose
3244 contents (e.g. headers and shared libraries) are needed
3245 by the recipe at build time.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003246 </para>
3247
3248 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003249 As an example, consider a recipe <filename>foo</filename>
3250 that contains the following assignment:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003251 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003252 DEPENDS = "bar"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003253 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003254 The practical effect of the previous assignment is that
3255 all files installed by bar will be available in the
3256 appropriate staging sysroot, given by the
3257 <link linkend='var-STAGING_DIR'><filename>STAGING_DIR*</filename></link>
3258 variables, by the time the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003259 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003260 task for <filename>foo</filename> runs.
3261 This mechanism is implemented by having
3262 <filename>do_configure</filename> depend on the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003263 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003264 task of each recipe listed in <filename>DEPENDS</filename>,
3265 through a
3266 <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>
3267 declaration in the
3268 <link linkend='ref-classes-base'><filename>base</filename></link>
3269 class.
3270 <note>
3271 It seldom is necessary to reference, for example,
3272 <filename>STAGING_DIR_HOST</filename> explicitly.
3273 The standard classes and build-related variables are
3274 configured to automatically use the appropriate staging
3275 sysroots.
3276 </note>
3277 As another example, <filename>DEPENDS</filename> can also
3278 be used to add utilities that run on the build machine
3279 during the build.
3280 For example, a recipe that makes use of a code generator
3281 built by the recipe <filename>codegen</filename> might have
3282 the following:
3283 <literallayout class='monospaced'>
3284 DEPENDS = "codegen-native"
3285 </literallayout>
3286 For more information, see the
3287 <link linkend='ref-classes-native'><filename>native</filename></link>
3288 class and the
3289 <link linkend='var-EXTRANATIVEPATH'><filename>EXTRANATIVEPATH</filename></link>
3290 variable.
3291 <note>
3292 <title>Notes</title>
3293 <itemizedlist>
3294 <listitem><para>
3295 <filename>DEPENDS</filename> is a list of
3296 recipe names.
3297 Or, to be more precise, it is a list of
3298 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
3299 names, which usually match recipe names.
3300 Putting a package name such as "foo-dev" in
3301 <filename>DEPENDS</filename> does not make
3302 sense.
3303 Use "foo" instead, as this will put files
3304 from all the packages that make up
3305 <filename>foo</filename>, which includes
3306 those from <filename>foo-dev</filename>, into
3307 the sysroot.
3308 </para></listitem>
3309 <listitem><para>
3310 One recipe having another recipe in
3311 <filename>DEPENDS</filename> does not by itself
3312 add any runtime dependencies between the
3313 packages produced by the two recipes.
3314 However, as explained in the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003315 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
3316 section in the Yocto Project Overview and
3317 Concepts Manual, runtime dependencies will
3318 often be added automatically, meaning
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003319 <filename>DEPENDS</filename> alone is
3320 sufficient for most recipes.
3321 </para></listitem>
3322 <listitem><para>
3323 Counterintuitively,
3324 <filename>DEPENDS</filename> is often necessary
3325 even for recipes that install precompiled
3326 components.
3327 For example, if <filename>libfoo</filename>
3328 is a precompiled library that links against
3329 <filename>libbar</filename>, then
3330 linking against <filename>libfoo</filename>
3331 requires both <filename>libfoo</filename>
3332 and <filename>libbar</filename> to be available
3333 in the sysroot.
3334 Without a <filename>DEPENDS</filename> from the
3335 recipe that installs <filename>libfoo</filename>
3336 to the recipe that installs
3337 <filename>libbar</filename>, other recipes might
3338 fail to link against
3339 <filename>libfoo</filename>.
3340 </para></listitem>
3341 </itemizedlist>
3342 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003343 </para>
3344
3345 <para>
3346 For information on runtime dependencies, see the
3347 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
3348 variable.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003349 You can also see the
3350 "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
3351 "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
3352 sections in the BitBake User Manual for additional
3353 information on tasks and dependencies.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003354 </para>
3355 </glossdef>
3356 </glossentry>
3357
3358 <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
3359 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003360 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 -05003361 </info>
3362 <glossdef>
3363 <para role="glossdeffirst">
3364<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3365 Points to the general area that the OpenEmbedded build
Brad Bishop316dfdd2018-06-25 12:45:53 -04003366 system uses to place images, packages, SDKs, and other output
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003367 files that are ready to be used outside of the build system.
3368 By default, this directory resides within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003369 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003370 as <filename>${TMPDIR}/deploy</filename>.
3371 </para>
3372
3373 <para>
3374 For more information on the structure of the Build
3375 Directory, see
3376 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
3377 section.
3378 For more detail on the contents of the
3379 <filename>deploy</filename> directory, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003380 "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>",
3381 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>",
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003382 and
Brad Bishop316dfdd2018-06-25 12:45:53 -04003383 "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
3384 sections all in the Yocto Project Overview and Concepts
3385 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003386 </para>
3387 </glossdef>
3388 </glossentry>
3389
3390 <glossentry id='var-DEPLOY_DIR_DEB'><glossterm>DEPLOY_DIR_DEB</glossterm>
3391 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003392 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 -05003393 </info>
3394 <glossdef>
3395 <para role="glossdeffirst">
3396<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3397 Points to the area that the OpenEmbedded build system uses
3398 to place Debian packages that are ready to be used outside
3399 of the build system.
3400 This variable applies only when
3401 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3402 contains "package_deb".
3403 </para>
3404
3405 <para>
3406 The BitBake configuration file initially defines the
3407 <filename>DEPLOY_DIR_DEB</filename> variable as a
3408 sub-folder of
3409 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3410 <literallayout class='monospaced'>
3411 DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
3412 </literallayout>
3413 </para>
3414
3415 <para>
3416 The
3417 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>
3418 class uses the
3419 <filename>DEPLOY_DIR_DEB</filename> variable to make sure
3420 the
3421 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>
3422 task writes Debian packages into the appropriate folder.
3423 For more information on how packaging works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003424 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3425 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003426 </para>
3427 </glossdef>
3428 </glossentry>
3429
3430 <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
3431 <info>
3432 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."
3433 </info>
3434 <glossdef>
3435 <para role="glossdeffirst">
3436<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3437 Points to the area that the OpenEmbedded build system uses
3438 to place images and other associated output files that are
3439 ready to be deployed onto the target machine.
3440 The directory is machine-specific as it contains the
3441 <filename>${MACHINE}</filename> name.
3442 By default, this directory resides within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003443 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003444 as <filename>${DEPLOY_DIR}/images/${MACHINE}/</filename>.
3445 </para>
3446
3447 <para>
3448 For more information on the structure of the Build
3449 Directory, see
3450 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
3451 section.
3452 For more detail on the contents of the
3453 <filename>deploy</filename> directory, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003454 "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
3455 and
3456 "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
3457 sections both in the Yocto Project Overview and Concepts
3458 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003459 </para>
3460 </glossdef>
3461 </glossentry>
3462
3463 <glossentry id='var-DEPLOY_DIR_IPK'><glossterm>DEPLOY_DIR_IPK</glossterm>
3464 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003465 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 -05003466 </info>
3467 <glossdef>
3468 <para role="glossdeffirst">
3469<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3470 Points to the area that the OpenEmbedded build system uses
3471 to place IPK packages that are ready to be used outside of
3472 the build system.
3473 This variable applies only when
3474 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3475 contains "package_ipk".
3476 </para>
3477
3478 <para>
3479 The BitBake configuration file initially defines this
3480 variable as a sub-folder of
3481 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3482 <literallayout class='monospaced'>
3483 DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
3484 </literallayout>
3485 </para>
3486
3487 <para>
3488 The
3489 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>
3490 class uses the
3491 <filename>DEPLOY_DIR_IPK</filename> variable to make sure
3492 the
3493 <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
3494 task writes IPK packages into the appropriate folder.
3495 For more information on how packaging works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003496 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3497 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003498 </para>
3499 </glossdef>
3500 </glossentry>
3501
3502 <glossentry id='var-DEPLOY_DIR_RPM'><glossterm>DEPLOY_DIR_RPM</glossterm>
3503 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003504 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 -05003505 </info>
3506 <glossdef>
3507 <para role="glossdeffirst">
3508<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3509 Points to the area that the OpenEmbedded build system uses
3510 to place RPM packages that are ready to be used outside
3511 of the build system.
3512 This variable applies only when
3513 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3514 contains "package_rpm".
3515 </para>
3516
3517 <para>
3518 The BitBake configuration file initially defines this
3519 variable as a sub-folder of
3520 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3521 <literallayout class='monospaced'>
3522 DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
3523 </literallayout>
3524 </para>
3525
3526 <para>
3527 The
3528 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>
3529 class uses the
3530 <filename>DEPLOY_DIR_RPM</filename> variable to make sure
3531 the
3532 <link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link>
3533 task writes RPM packages into the appropriate folder.
3534 For more information on how packaging works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003535 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3536 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003537 </para>
3538 </glossdef>
3539 </glossentry>
3540
3541 <glossentry id='var-DEPLOY_DIR_TAR'><glossterm>DEPLOY_DIR_TAR</glossterm>
3542 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04003543 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 -05003544 </info>
3545 <glossdef>
3546 <para role="glossdeffirst">
3547<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3548 Points to the area that the OpenEmbedded build system uses
3549 to place tarballs that are ready to be used outside of
3550 the build system.
3551 This variable applies only when
3552 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3553 contains "package_tar".
3554 </para>
3555
3556 <para>
3557 The BitBake configuration file initially defines this
3558 variable as a sub-folder of
3559 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3560 <literallayout class='monospaced'>
3561 DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"
3562 </literallayout>
3563 </para>
3564
3565 <para>
3566 The
3567 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
3568 class uses the
3569 <filename>DEPLOY_DIR_TAR</filename> variable to make sure
3570 the
3571 <link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>
3572 task writes TAR packages into the appropriate folder.
3573 For more information on how packaging works, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003574 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3575 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003576 </para>
3577 </glossdef>
3578 </glossentry>
3579
3580 <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm>
3581 <info>
3582 DEPLOYDIR[doc] = "For recipes that inherit the deploy class, the DEPLOYDIR points to a temporary work area for deployed files."
3583 </info>
3584 <glossdef>
3585 <para role="glossdeffirst">
3586<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3587 When inheriting the
3588 <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
3589 class, the <filename>DEPLOYDIR</filename> points to a
3590 temporary work area for deployed files that is set in the
3591 <filename>deploy</filename> class as follows:
3592 <literallayout class='monospaced'>
3593 DEPLOYDIR = "${WORKDIR}/deploy-${<link linkend='var-PN'><filename>PN</filename></link>}"
3594 </literallayout>
3595 </para>
3596
3597 <para>
3598 Recipes inheriting the <filename>deploy</filename> class
3599 should copy files to be deployed into
3600 <filename>DEPLOYDIR</filename>, and the class will take
3601 care of copying them into
3602 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
3603 afterwards.
3604 </para>
3605 </glossdef>
3606 </glossentry>
3607
3608 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
3609 <info>
3610 DESCRIPTION[doc] = "The package description used by package managers. If not set, DESCRIPTION takes the value of the SUMMARY variable."
3611 </info>
3612 <glossdef>
3613 <para role="glossdeffirst">
3614<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3615 The package description used by package managers.
3616 If not set, <filename>DESCRIPTION</filename> takes
3617 the value of the
3618 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
3619 variable.
3620 </para>
3621 </glossdef>
3622 </glossentry>
3623
3624 <glossentry id='var-DISK_SIGNATURE'><glossterm>DISK_SIGNATURE</glossterm>
3625 <info>
3626 DISK_SIGNATURE[doc] = "A 32-bit MBR disk signature used by directdisk images."
3627 </info>
3628 <glossdef>
3629 <para role="glossdeffirst">
3630<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3631 A 32-bit MBR disk signature used by
3632 <filename>directdisk</filename> images.
3633 </para>
3634
3635 <para>
3636 By default, the signature is set to an automatically
3637 generated random value that allows the OpenEmbedded
3638 build system to create a boot loader.
3639 You can override the signature in the image recipe
3640 by setting <filename>DISK_SIGNATURE</filename> to an
3641 8-digit hex string.
3642 You might want to override
3643 <filename>DISK_SIGNATURE</filename> if you want the disk
3644 signature to remain constant between image builds.
3645 </para>
3646
3647 <para>
3648 When using Linux 3.8 or later, you can use
3649 <filename>DISK_SIGNATURE</filename> to specify the root
3650 by UUID to allow the kernel to locate the root device
3651 even if the device name changes due to differences in
3652 hardware configuration.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003653 By default, <filename>ROOT_VM</filename> is set
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003654 as follows:
3655 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003656 ROOT_VM ?= "root=/dev/sda2"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003657 </literallayout>
3658 However, you can change this to locate the root device
3659 using the disk signature instead:
3660 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003661 ROOT_VM = "root=PARTUUID=${DISK_SIGNATURE}-02"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003662 </literallayout>
3663 </para>
3664
3665 <para>
3666 As previously mentioned, it is possible to set the
3667 <filename>DISK_SIGNATURE</filename> variable in your
3668 <filename>local.conf</filename> file to a fixed
3669 value if you do not want <filename>syslinux.cfg</filename>
3670 changing for each build.
3671 You might find this useful when you want to upgrade the
3672 root filesystem on a device without having to recreate or
3673 modify the master boot record.
3674 </para>
3675 </glossdef>
3676 </glossentry>
3677
3678 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
3679 <info>
3680 DISTRO[doc] = "The short name of the distribution. If the variable is blank, meta/conf/distro/defaultsetup.conf will be used."
3681 </info>
3682 <glossdef>
3683 <para role="glossdeffirst">
3684<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3685 The short name of the distribution.
Brad Bishopd5ae7d92018-06-14 09:52:03 -07003686 For information on the long name of the distribution, see
3687 the
3688 <link linkend='var-DISTRO_NAME'><filename>DISTRO_NAME</filename></link>
3689 variable.
3690 </para>
3691
3692 <para>
3693 The <filename>DISTRO</filename> variable corresponds to a
3694 distribution configuration file whose root name is the
3695 same as the variable's argument and whose filename
3696 extension is <filename>.conf</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003697 For example, the distribution configuration file for the
3698 Poky distribution is named <filename>poky.conf</filename>
3699 and resides in the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003700 <filename>meta-poky/conf/distro</filename> directory of
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003701 the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003702 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003703 </para>
3704
3705 <para>
3706 Within that <filename>poky.conf</filename> file, the
3707 <filename>DISTRO</filename> variable is set as follows:
3708 <literallayout class='monospaced'>
3709 DISTRO = "poky"
3710 </literallayout>
3711 </para>
3712
3713 <para>
3714 Distribution configuration files are located in a
3715 <filename>conf/distro</filename> directory within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003716 <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003717 that contains the distribution configuration.
3718 The value for <filename>DISTRO</filename> must not contain
3719 spaces, and is typically all lower-case.
3720 <note>
Brad Bishopd5ae7d92018-06-14 09:52:03 -07003721 If the <filename>DISTRO</filename> variable is blank,
3722 a set of default configurations are used, which are
3723 specified within
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003724 <filename>meta/conf/distro/defaultsetup.conf</filename>
3725 also in the Source Directory.
3726 </note>
3727 </para>
3728 </glossdef>
3729 </glossentry>
3730
3731 <glossentry id='var-DISTRO_CODENAME'><glossterm>DISTRO_CODENAME</glossterm>
3732 <info>
3733 DISTRO_CODENAME[doc] = "Specifies a codename for the distribution being built."
3734 </info>
3735 <glossdef>
3736 <para role="glossdeffirst">
3737<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3738 Specifies a codename for the distribution being built.
3739 </para>
3740 </glossdef>
3741 </glossentry>
3742
3743 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
3744 <info>
3745 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."
3746 </info>
3747 <glossdef>
3748 <para role="glossdeffirst">
3749<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3750 Specifies a list of distro-specific packages to add to all images.
3751 This variable takes affect through
3752 <filename>packagegroup-base</filename> so the
3753 variable only really applies to the more full-featured
3754 images that include <filename>packagegroup-base</filename>.
3755 You can use this variable to keep distro policy out of
3756 generic images.
3757 As with all other distro variables, you set this variable
3758 in the distro <filename>.conf</filename> file.
3759 </para>
3760 </glossdef>
3761 </glossentry>
3762
3763 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
3764 <info>
3765 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."
3766 </info>
3767 <glossdef>
3768 <para role="glossdeffirst">
3769<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3770 Specifies a list of distro-specific packages to add to all images
3771 if the packages exist.
3772 The packages might not exist or be empty (e.g. kernel modules).
3773 The list of packages are automatically installed but you can
3774 remove them.
3775 </para>
3776 </glossdef>
3777 </glossentry>
3778
3779 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
3780 <info>
3781 DISTRO_FEATURES[doc] = "The features enabled for the distribution."
3782 </info>
3783 <glossdef>
3784 <para role="glossdeffirst">
3785<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3786 The software support you want in your distribution for
3787 various features.
3788 You define your distribution features in the distribution
3789 configuration file.
3790 </para>
3791
3792 <para>
3793 In most cases, the presence or absence of a feature in
3794 <filename>DISTRO_FEATURES</filename> is translated to the
3795 appropriate option supplied to the configure script
3796 during the
3797 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
3798 task for recipes that optionally support the feature.
3799 For example, specifying "x11" in
3800 <filename>DISTRO_FEATURES</filename>, causes
3801 every piece of software built for the target that can
3802 optionally support X11 to have its X11 support enabled.
3803 </para>
3804
3805 <para>
3806 Two more examples are Bluetooth and NFS support.
3807 For a more complete list of features that ships with the
3808 Yocto Project and that you can provide with this variable,
3809 see the
3810 "<link linkend='ref-features-distro'>Distro Features</link>"
3811 section.
3812 </para>
3813 </glossdef>
3814 </glossentry>
3815
3816 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
3817 <info>
3818 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."
3819 </info>
3820 <glossdef>
3821 <para role="glossdeffirst">
3822<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3823 Features to be added to
3824 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
3825 if not also present in
3826 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
3827 </para>
3828
3829 <para>
3830 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
3831 It is not intended to be user-configurable.
3832 It is best to just reference the variable to see which distro features are
3833 being backfilled for all distro configurations.
Brad Bishop316dfdd2018-06-25 12:45:53 -04003834 See the <link linkend='ref-features-backfill'>Feature Backfilling</link> section for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003835 more information.
3836 </para>
3837 </glossdef>
3838 </glossentry>
3839
3840 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
3841 <info>
3842 DISTRO_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from DISTRO_FEATURES_BACKFILL that should not be backfilled (i.e. added to DISTRO_FEATURES) during the build."
3843 </info>
3844 <glossdef>
3845 <para role="glossdeffirst">
3846<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3847 Features from
3848 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
3849 that should not be backfilled (i.e. added to
3850 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
3851 during the build.
3852 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
3853 more information.
3854 </para>
3855 </glossdef>
3856 </glossentry>
3857
3858 <glossentry id='var-DISTRO_FEATURES_DEFAULT'><glossterm>DISTRO_FEATURES_DEFAULT</glossterm>
3859 <info>
3860 DISTRO_FEATURES_DEFAULT[doc] = "Provides the default list of distro features with the exception of any libc-specific features."
3861 </info>
3862 <glossdef>
3863 <para role="glossdeffirst">
3864<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3865 A convenience variable that gives you the default
3866 list of distro features with the exception of any
3867 features specific to the C library
3868 (<filename>libc</filename>).
3869 </para>
3870
3871 <para>
3872 When creating a custom distribution, you might find it
3873 useful to be able to reuse the default
3874 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3875 options without the need to write out the full set.
3876 Here is an example that uses
3877 <filename>DISTRO_FEATURES_DEFAULT</filename> from a
3878 custom distro configuration file:
3879 <literallayout class='monospaced'>
3880 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} ${DISTRO_FEATURES_LIBC} myfeature"
3881 </literallayout>
3882 </para>
3883 </glossdef>
3884 </glossentry>
3885
Brad Bishop6e60e8b2018-02-01 10:27:11 -05003886 <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVE'><glossterm>DISTRO_FEATURES_FILTER_NATIVE</glossterm>
3887 <info>
3888 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."
3889 </info>
3890 <glossdef>
3891 <para role="glossdeffirst">
3892<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3893 Specifies a list of features that if present in
3894 the target
3895 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3896 value should be included in
3897 <filename>DISTRO_FEATURES</filename> when building native
3898 recipes.
3899 This variable is used in addition to the features
3900 filtered using the
3901 <link linkend='var-DISTRO_FEATURES_NATIVE'><filename>DISTRO_FEATURES_NATIVE</filename></link>
3902 variable.
3903 </para>
3904 </glossdef>
3905 </glossentry>
3906
3907 <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVESDK'><glossterm>DISTRO_FEATURES_FILTER_NATIVESDK</glossterm>
3908 <info>
3909 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."
3910 </info>
3911 <glossdef>
3912 <para role="glossdeffirst">
3913<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3914 Specifies a list of features that if present in the target
3915 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3916 value should be included in
3917 <filename>DISTRO_FEATURES</filename> when building
3918 nativesdk recipes.
3919 This variable is used in addition to the features
3920 filtered using the
3921 <link linkend='var-DISTRO_FEATURES_NATIVESDK'><filename>DISTRO_FEATURES_NATIVESDK</filename></link>
3922 variable.
3923 </para>
3924 </glossdef>
3925 </glossentry>
3926
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003927 <glossentry id='var-DISTRO_FEATURES_LIBC'><glossterm>DISTRO_FEATURES_LIBC</glossterm>
3928 <info>
3929 DISTRO_FEATURES_LIBC[doc] = "Specifies the list of distro features that are specific to the C library (libc)."
3930 </info>
3931 <glossdef>
3932 <para role="glossdeffirst">
3933<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3934 A convenience variable that specifies the list of distro
3935 features that are specific to the C library
3936 (<filename>libc</filename>).
3937 Typically, these features are prefixed with "libc-" and
3938 control which features are enabled at during the build
3939 within the C library itself.
3940 </para>
3941 </glossdef>
3942 </glossentry>
3943
Brad Bishop6e60e8b2018-02-01 10:27:11 -05003944 <glossentry id='var-DISTRO_FEATURES_NATIVE'><glossterm>DISTRO_FEATURES_NATIVE</glossterm>
3945 <info>
3946 DISTRO_FEATURES_NATIVE[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building native recipes."
3947 </info>
3948 <glossdef>
3949 <para role="glossdeffirst">
3950<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3951 Specifies a list of features that should be included in
3952 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3953 when building native recipes.
3954 This variable is used in addition to the features
3955 filtered using the
3956 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVE'><filename>DISTRO_FEATURES_FILTER_NATIVE</filename></link>
3957 variable.
3958 </para>
3959 </glossdef>
3960 </glossentry>
3961
3962 <glossentry id='var-DISTRO_FEATURES_NATIVESDK'><glossterm>DISTRO_FEATURES_NATIVESDK</glossterm>
3963 <info>
3964 DISTRO_FEATURES_NATIVESDK[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building nativesdk recipes."
3965 </info>
3966 <glossdef>
3967 <para role="glossdeffirst">
3968<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3969 Specifies a list of features that should be included in
3970 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3971 when building nativesdk recipes.
3972 This variable is used in addition to the features
3973 filtered using the
3974 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVESDK'><filename>DISTRO_FEATURES_FILTER_NATIVESDK</filename></link>
3975 variable.
3976 </para>
3977 </glossdef>
3978 </glossentry>
3979
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003980 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
3981 <info>
3982 DISTRO_NAME[doc] = "The long name of the distribution."
3983 </info>
3984 <glossdef>
3985 <para role="glossdeffirst">
3986<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
3987 The long name of the distribution.
Brad Bishopd5ae7d92018-06-14 09:52:03 -07003988 For information on the short name of the distribution, see
3989 the
3990 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
3991 variable.
3992 </para>
3993
3994 <para>
3995 The <filename>DISTRO_NAME</filename> variable corresponds
3996 to a distribution configuration file whose root name is the
3997 same as the variable's argument and whose filename
3998 extension is <filename>.conf</filename>.
3999 For example, the distribution configuration file for the
4000 Poky distribution is named <filename>poky.conf</filename>
4001 and resides in the
4002 <filename>meta-poky/conf/distro</filename> directory of
4003 the
4004 <link linkend='source-directory'>Source Directory</link>.
4005 </para>
4006
4007 <para>
4008 Within that <filename>poky.conf</filename> file, the
4009 <filename>DISTRO_NAME</filename> variable is set as
4010 follows:
4011 <literallayout class='monospaced'>
4012 DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
4013 </literallayout>
4014 </para>
4015
4016 <para>
4017 Distribution configuration files are located in a
4018 <filename>conf/distro</filename> directory within the
4019 <link linkend='metadata'>Metadata</link>
4020 that contains the distribution configuration.
4021 <note>
4022 If the <filename>DISTRO_NAME</filename> variable is
4023 blank, a set of default configurations are used, which
4024 are specified within
4025 <filename>meta/conf/distro/defaultsetup.conf</filename>
4026 also in the Source Directory.
4027 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004028 </para>
4029 </glossdef>
4030 </glossentry>
4031
4032 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
4033 <info>
4034 DISTRO_VERSION[doc] = "The version of the distribution."
4035 </info>
4036 <glossdef>
4037 <para role="glossdeffirst">
4038<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4039 The version of the distribution.
4040 </para>
4041 </glossdef>
4042 </glossentry>
4043
4044 <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
4045 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004046 DISTROOVERRIDES[doc] = "A colon-separated list of overrides specific to the current distribution."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004047 </info>
4048 <glossdef>
4049 <para role="glossdeffirst">
4050<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004051 A colon-separated list of overrides specific to the
4052 current distribution.
4053 By default, this list includes the value of
4054 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>.
4055 </para>
4056
4057 <para>
4058 You can extend <filename>DISTROOVERRIDES</filename>
4059 to add extra overrides that should apply to
4060 the distribution.
4061 </para>
4062
4063 <para>
4064 The underlying mechanism behind
4065 <filename>DISTROOVERRIDES</filename> is simply that it
4066 is included in the default value of
4067 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004068 </para>
4069 </glossdef>
4070 </glossentry>
4071
4072 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
4073 <info>
4074 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."
4075 </info>
4076 <glossdef>
4077 <para role="glossdeffirst">
4078<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4079 The central download directory used by the build process to
4080 store downloads.
4081 By default, <filename>DL_DIR</filename> gets files
4082 suitable for mirroring for everything except Git
4083 repositories.
4084 If you want tarballs of Git repositories, use the
4085 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
4086 variable.
4087 </para>
4088
4089 <para>
4090 You can set this directory by defining the
4091 <filename>DL_DIR</filename> variable in the
4092 <filename>conf/local.conf</filename> file.
4093 This directory is self-maintaining and you should not have
4094 to touch it.
4095 By default, the directory is <filename>downloads</filename>
4096 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004097 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004098 <literallayout class='monospaced'>
4099 #DL_DIR ?= "${TOPDIR}/downloads"
4100 </literallayout>
4101 To specify a different download directory, simply remove
4102 the comment from the line and provide your directory.
4103 </para>
4104
4105 <para>
4106 During a first build, the system downloads many different
4107 source code tarballs from various upstream projects.
4108 Downloading can take a while, particularly if your network
4109 connection is slow.
4110 Tarballs are all stored in the directory defined by
4111 <filename>DL_DIR</filename> and the build system looks there
4112 first to find source tarballs.
4113 <note>
4114 When wiping and rebuilding, you can preserve this
4115 directory to speed up this part of subsequent
4116 builds.
4117 </note>
4118 </para>
4119
4120 <para>
4121 You can safely share this directory between multiple builds
4122 on the same development machine.
4123 For additional information on how the build process gets
4124 source files when working behind a firewall or proxy server,
4125 see this specific question in the
4126 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
4127 chapter.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05004128 You can also refer to the
4129 "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
4130 Wiki page.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004131 </para>
4132 </glossdef>
4133 </glossentry>
4134
4135 <glossentry id='var-DOC_COMPRESS'><glossterm>DOC_COMPRESS</glossterm>
4136 <info>
4137 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."
4138 </info>
4139 <glossdef>
4140 <para role="glossdeffirst">
4141<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4142 When inheriting the
4143 <link linkend='ref-classes-compress_doc'><filename>compress_doc</filename></link>
4144 class, this variable sets the compression policy used when
4145 the OpenEmbedded build system compresses man pages and info
4146 pages.
4147 By default, the compression method used is gz (gzip).
4148 Other policies available are xz and bz2.
4149 </para>
4150
4151 <para>
4152 For information on policies and on how to use this
4153 variable, see the comments in the
4154 <filename>meta/classes/compress_doc.bbclass</filename> file.
4155 </para>
4156 </glossdef>
4157 </glossentry>
4158
4159 </glossdiv>
4160
4161 <glossdiv id='var-glossary-e'><title>E</title>
4162
4163 <glossentry id='var-EFI_PROVIDER'><glossterm>EFI_PROVIDER</glossterm>
4164 <info>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004165 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 -05004166 </info>
4167 <glossdef>
4168 <para role="glossdeffirst">
4169<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4170 When building bootable images (i.e. where
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004171 <filename>hddimg</filename>, <filename>iso</filename>,
4172 or <filename>wic.vmdk</filename> is in
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004173 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>),
4174 the <filename>EFI_PROVIDER</filename> variable specifies
4175 the EFI bootloader to use.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004176 The default is "grub-efi", but "systemd-boot" can be used
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004177 instead.
4178 </para>
4179
4180 <para>
4181 See the
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004182 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05004183 and
4184 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
4185 classes for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004186 </para>
4187 </glossdef>
4188 </glossentry>
4189
4190 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
4191 <info>
4192 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."
4193 </info>
4194 <glossdef>
4195 <para role="glossdeffirst">
4196<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4197 Variable that controls which locales for
4198 <filename>glibc</filename> are generated during the
4199 build (useful if the target device has 64Mbytes
4200 of RAM or less).
4201 </para>
4202 </glossdef>
4203 </glossentry>
4204
4205 <glossentry id='var-ERR_REPORT_DIR'><glossterm>ERR_REPORT_DIR</glossterm>
4206 <info>
4207 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."
4208 </info>
4209 <glossdef>
4210 <para role="glossdeffirst">
4211<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4212 When used with the
4213 <link linkend='ref-classes-report-error'><filename>report-error</filename></link>
4214 class, specifies the path used for storing the debug files
4215 created by the
4216 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
4217 which allows you to submit build errors you encounter to a
4218 central database.
4219 By default, the value of this variable is
4220 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
4221 </para>
4222
4223 <para>
4224 You can set <filename>ERR_REPORT_DIR</filename> to the path
4225 you want the error reporting tool to store the debug files
4226 as follows in your <filename>local.conf</filename> file:
4227 <literallayout class='monospaced'>
4228 ERR_REPORT_DIR = "<replaceable>path</replaceable>"
4229 </literallayout>
4230 </para>
4231 </glossdef>
4232 </glossentry>
4233
4234 <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
4235 <info>
4236 ERROR_QA[doc] = "Specifies the quality assurance checks whose failures are reported as errors by the OpenEmbedded build system."
4237 </info>
4238 <glossdef>
4239 <para role="glossdeffirst">
4240<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4241 Specifies the quality assurance checks whose failures are
4242 reported as errors by the OpenEmbedded build system.
4243 You set this variable in your distribution configuration
4244 file.
4245 For a list of the checks you can control with this variable,
4246 see the
4247 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
4248 section.
4249 </para>
4250 </glossdef>
4251 </glossentry>
4252
Patrick Williamsf1e5d692016-03-30 15:21:19 -05004253 <glossentry id='var-EXCLUDE_FROM_SHLIBS'><glossterm>EXCLUDE_FROM_SHLIBS</glossterm>
4254 <info>
4255 EXCLUDE_FROM_SHLIBS[doc] = "Causes the OpenEmbedded build system's shared libraries resolver to exclude an entire package when scanning for shared libraries."
4256 </info>
4257 <glossdef>
4258 <para role="glossdeffirst">
4259<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4260 Triggers the OpenEmbedded build system's shared libraries
4261 resolver to exclude an entire package when scanning for
4262 shared libraries.
4263 <note>
4264 The shared libraries resolver's functionality results
4265 in part from the internal function
4266 <filename>package_do_shlibs</filename>, which is part of
4267 the
4268 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
4269 task.
4270 You should be aware that the shared libraries resolver
4271 might implicitly define some dependencies between
4272 packages.
4273 </note>
4274 The <filename>EXCLUDE_FROM_SHLIBS</filename> variable is
4275 similar to the
4276 <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
4277 variable, which excludes a package's particular libraries
4278 only and not the whole package.
4279 </para>
4280
4281 <para>
4282 Use the
4283 <filename>EXCLUDE_FROM_SHLIBS</filename> variable by
4284 setting it to "1" for a particular package:
4285 <literallayout class='monospaced'>
4286 EXCLUDE_FROM_SHLIBS = "1"
4287 </literallayout>
4288 </para>
4289 </glossdef>
4290 </glossentry>
4291
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004292 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
4293 <info>
4294 EXCLUDE_FROM_WORLD[doc] = "Directs BitBake to exclude a recipe from world builds (i.e. bitbake world)."
4295 </info>
4296 <glossdef>
4297 <para role="glossdeffirst">
4298<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4299 Directs BitBake to exclude a recipe from world builds (i.e.
4300 <filename>bitbake world</filename>).
4301 During world builds, BitBake locates, parses and builds all
4302 recipes found in every layer exposed in the
4303 <filename>bblayers.conf</filename> configuration file.
4304 </para>
4305
4306 <para>
4307 To exclude a recipe from a world build using this variable,
4308 set the variable to "1" in the recipe.
4309 </para>
4310
4311 <note>
4312 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
4313 may still be built during a world build in order to satisfy
4314 dependencies of other recipes.
4315 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
4316 only ensures that the recipe is not explicitly added
4317 to the list of build targets in a world build.
4318 </note>
4319 </glossdef>
4320 </glossentry>
4321
4322 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
4323 <info>
4324 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."
4325 </info>
4326 <glossdef>
4327 <para role="glossdeffirst">
4328<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4329 Used with file and pathnames to create a prefix for a recipe's
4330 version based on the recipe's
4331 <link linkend='var-PE'><filename>PE</filename></link> value.
4332 If <filename>PE</filename> is set and greater than zero for a recipe,
4333 <filename>EXTENDPE</filename> becomes that value (e.g if
4334 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
4335 becomes "1_").
4336 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
4337 zero, <filename>EXTENDPE</filename> becomes "".</para>
4338 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
4339 variable for an example.
4340 </para>
4341 </glossdef>
4342 </glossentry>
4343
4344 <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
4345 <info>
4346 EXTENDPKGV[doc] = "The full package version specification as it appears on the final packages produced by a recipe."
4347 </info>
4348 <glossdef>
4349 <para role="glossdeffirst">
4350<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4351 The full package version specification as it appears on the
4352 final packages produced by a recipe.
4353 The variable's value is normally used to fix a runtime
4354 dependency to the exact same version of another package
4355 in the same recipe:
4356 <literallayout class='monospaced'>
4357 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
4358 </literallayout>
4359 </para>
4360
4361 <para>
4362 The dependency relationships are intended to force the
4363 package manager to upgrade these types of packages in
4364 lock-step.
4365 </para>
4366 </glossdef>
4367 </glossentry>
4368
4369 <glossentry id='var-EXTERNAL_KERNEL_TOOLS'><glossterm>EXTERNAL_KERNEL_TOOLS</glossterm>
4370 <info>
4371 EXTERNAL_KERNEL_TOOLS[doc] = "Indicates kernel tools are external to the source tree."
4372 </info>
4373 <glossdef>
4374 <para role="glossdeffirst">
4375<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4376 When set, the <filename>EXTERNAL_KERNEL_TOOLS</filename>
4377 variable indicates that these tools are not in the
4378 source tree.
4379 </para>
4380
4381 <para>
4382 When kernel tools are available in the tree, they are
4383 preferred over any externally installed tools.
4384 Setting the <filename>EXTERNAL_KERNEL_TOOLS</filename>
4385 variable tells the OpenEmbedded build system to prefer
4386 the installed external tools.
4387 See the
4388 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
4389 class in <filename>meta/classes</filename> to see how
4390 the variable is used.
4391 </para>
4392 </glossdef>
4393 </glossentry>
4394
4395 <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
4396 <info>
4397 EXTERNALSRC[doc] = "If externalsrc.bbclass is inherited, this variable points to the source tree, which is outside of the OpenEmbedded build system."
4398 </info>
4399 <glossdef>
4400 <para role="glossdeffirst">
4401<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4402 When inheriting the
4403 <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link>
4404 class, this variable points to the source tree, which is
4405 outside of the OpenEmbedded build system.
4406 When set, this variable sets the
4407 <link linkend='var-S'><filename>S</filename></link>
4408 variable, which is what the OpenEmbedded build system uses
4409 to locate unpacked recipe source code.
4410 </para>
4411
4412 <para>
4413 For more information on
4414 <filename>externalsrc.bbclass</filename>, see the
4415 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
4416 section.
4417 You can also find information on how to use this variable
4418 in the
4419 "<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 -05004420 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004421 </para>
4422 </glossdef>
4423 </glossentry>
4424
4425 <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
4426 <info>
4427 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."
4428 </info>
4429 <glossdef>
4430 <para role="glossdeffirst">
4431<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4432 When inheriting the
4433 <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link>
4434 class, this variable points to the directory in which the
4435 recipe's source code is built, which is outside of the
4436 OpenEmbedded build system.
4437 When set, this variable sets the
4438 <link linkend='var-B'><filename>B</filename></link>
4439 variable, which is what the OpenEmbedded build system uses
4440 to locate the Build Directory.
4441 </para>
4442
4443 <para>
4444 For more information on
4445 <filename>externalsrc.bbclass</filename>, see the
4446 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
4447 section.
4448 You can also find information on how to use this variable
4449 in the
4450 "<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 -05004451 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004452 </para>
4453 </glossdef>
4454 </glossentry>
4455
4456 <glossentry id='var-EXTRA_AUTORECONF'><glossterm>EXTRA_AUTORECONF</glossterm>
4457 <info>
4458 EXTRA_AUTORECONF[doc] = "Extra options passed to the autoreconf command, which is executed during do_configure."
4459 </info>
4460 <glossdef>
4461 <para role="glossdeffirst">
4462<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4463 For recipes inheriting the
4464 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
4465 class, you can use <filename>EXTRA_AUTORECONF</filename> to
4466 specify extra options to pass to the
4467 <filename>autoreconf</filename> command that is
4468 executed during the
4469 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
4470 task.
4471 </para>
4472
4473 <para>
4474 The default value is "--exclude=autopoint".
4475 </para>
4476 </glossdef>
4477 </glossentry>
4478
4479 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
4480 <info>
4481 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."
4482 </info>
4483 <glossdef>
4484 <para role="glossdeffirst">
4485<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4486 A list of additional features to include in an image.
4487 When listing more than one feature, separate them with
4488 a space.
4489 </para>
4490
4491 <para>
4492 Typically, you configure this variable in your
4493 <filename>local.conf</filename> file, which is found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004494 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004495 Although you can use this variable from within a recipe,
4496 best practices dictate that you do not.
4497 <note>
4498 To enable primary features from within the image
4499 recipe, use the
4500 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
4501 variable.
4502 </note>
4503 </para>
4504
4505 <para>
4506 Here are some examples of features you can add:
4507 <literallayout class='monospaced'>
4508"dbg-pkgs" - Adds -dbg packages for all installed packages
4509 including symbol information for debugging and
4510 profiling.
4511
4512"debug-tweaks" - Makes an image suitable for debugging.
4513 For example, allows root logins without
4514 passwords and enables post-installation
4515 logging. See the 'allow-empty-password'
4516 and 'post-install-logging' features in
4517 the "<link linkend='ref-features-image'>Image Features</link>" section for
4518 more information.
4519
4520"dev-pkgs" - Adds -dev packages for all installed packages.
4521 This is useful if you want to develop against
4522 the libraries in the image.
4523
4524"read-only-rootfs" - Creates an image whose root
4525 filesystem is read-only. See the
4526 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
4527 section in the Yocto Project
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004528 Development Tasks Manual for
4529 more information
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004530
4531"tools-debug" - Adds debugging tools such as gdb and
4532 strace.
4533
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004534"tools-sdk" - Adds development tools such as gcc, make,
4535 pkgconfig and so forth.
4536
4537"tools-testapps" - Adds useful testing tools such as
4538 ts_print, aplay, arecord and so
4539 forth.
4540
4541 </literallayout>
4542 </para>
4543
4544 <para>
4545 For a complete list of image features that ships with the
4546 Yocto Project, see the
4547 "<link linkend="ref-features-image">Image Features</link>"
4548 section.
4549 </para>
4550
4551 <para>
4552 For an example that shows how to customize your image by
4553 using this variable, see the
4554 "<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 -05004555 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004556 </para>
4557 </glossdef>
4558 </glossentry>
4559
4560 <glossentry id='var-EXTRA_IMAGECMD'><glossterm>EXTRA_IMAGECMD</glossterm>
4561 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04004562 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 -05004563 </info>
4564 <glossdef>
4565 <para role="glossdeffirst">
4566<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4567 Specifies additional options for the image
4568 creation command that has been specified in
4569 <link linkend='var-IMAGE_CMD'><filename>IMAGE_CMD</filename></link>.
Brad Bishop316dfdd2018-06-25 12:45:53 -04004570 When setting this variable, use an override for the
4571 associated image type.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004572 Here is an example:
4573 <literallayout class='monospaced'>
4574 EXTRA_IMAGECMD_ext3 ?= "-i 4096"
4575 </literallayout>
4576 </para>
4577 </glossdef>
4578 </glossentry>
4579
4580 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
4581 <info>
4582 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."
4583 </info>
4584 <glossdef>
4585 <para role="glossdeffirst">
4586<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4587 A list of recipes to build that do not provide packages
4588 for installing into the root filesystem.
4589 </para>
4590
4591 <para>
4592 Sometimes a recipe is required to build the final image but is not
4593 needed in the root filesystem.
4594 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
4595 list these recipes and thus specify the dependencies.
4596 A typical example is a required bootloader in a machine configuration.
4597 </para>
4598
4599 <note>
4600 To add packages to the root filesystem, see the various
4601 <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
4602 and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
4603 variables.
4604 </note>
4605 </glossdef>
4606 </glossentry>
4607
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004608 <glossentry id='var-EXTRANATIVEPATH'><glossterm>EXTRANATIVEPATH</glossterm>
4609 <info>
4610 EXTRANATIVEPATH[doc] = "A list of subdirectories of ${STAGING_BINDIR_NATIVE} added to the beginning of the environment variable PATH."
4611 </info>
4612 <glossdef>
4613 <para role="glossdeffirst">
4614<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4615 A list of subdirectories of
4616 <filename>${</filename><link linkend='var-STAGING_BINDIR_NATIVE'><filename>STAGING_BINDIR_NATIVE</filename></link><filename>}</filename>
4617 added to the beginning of the environment variable
4618 <filename>PATH</filename>.
4619 As an example, the following prepends
4620 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:"
4621 to <filename>PATH</filename>:
4622 <literallayout class='monospaced'>
4623 EXTRANATIVEPATH = "foo bar"
4624 </literallayout>
4625 </para>
4626 </glossdef>
4627 </glossentry>
4628
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004629 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
4630 <info>
4631 EXTRA_OECMAKE[doc] = "Additional cmake options."
4632 </info>
4633 <glossdef>
4634 <para role="glossdeffirst">
4635<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08004636 Additional
4637 <ulink url='https://cmake.org/overview/'>CMake</ulink>
4638 options.
4639 See the
4640 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
4641 class for additional information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004642 </para>
4643 </glossdef>
4644 </glossentry>
4645
4646 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
4647 <info>
4648 EXTRA_OECONF[doc] = "Additional configure script options."
4649 </info>
4650 <glossdef>
4651 <para role="glossdeffirst">
4652<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4653 Additional <filename>configure</filename> script options.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004654 See
4655 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>
4656 for additional information on passing configure script
4657 options.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004658 </para>
4659 </glossdef>
4660 </glossentry>
4661
4662 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
4663 <info>
4664 EXTRA_OEMAKE[doc] = "Additional GNU make options."
4665 </info>
4666 <glossdef>
4667 <para role="glossdeffirst">
4668<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4669 Additional GNU <filename>make</filename> options.
4670 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05004671
4672 <para>
4673 Because the <filename>EXTRA_OEMAKE</filename> defaults to
4674 "", you need to set the variable to specify any required
4675 GNU options.
4676 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004677
4678 <para>
4679 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
4680 and
4681 <link linkend='var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></link>
4682 also make use of
4683 <filename>EXTRA_OEMAKE</filename> to pass the required
4684 flags.
4685 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004686 </glossdef>
4687 </glossentry>
4688
4689 <glossentry id='var-EXTRA_OESCONS'><glossterm>EXTRA_OESCONS</glossterm>
4690 <info>
4691 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."
4692 </info>
4693 <glossdef>
4694 <para role="glossdeffirst">
4695<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4696 When inheriting the
4697 <link linkend='ref-classes-scons'><filename>scons</filename></link>
4698 class, this variable specifies additional configuration
4699 options you want to pass to the
4700 <filename>scons</filename> command line.
4701 </para>
4702 </glossdef>
4703 </glossentry>
4704
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004705 <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm>
4706 <info>
4707 EXTRA_USERS_PARAMS[doc] = "When a recipe inherits the extrausers class, this variable provides image level user and group operations."
4708 </info>
4709 <glossdef>
4710 <para role="glossdeffirst">
4711<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4712 When inheriting the
4713 <link linkend='ref-classes-extrausers'><filename>extrausers</filename></link>
4714 class, this variable provides image level user and group
4715 operations.
4716 This is a more global method of providing user and group
4717 configuration as compared to using the
4718 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
4719 class, which ties user and group configurations to a
4720 specific recipe.
4721 </para>
4722
4723 <para>
4724 The set list of commands you can configure using the
4725 <filename>EXTRA_USERS_PARAMS</filename> is shown in the
4726 <filename>extrausers</filename> class.
4727 These commands map to the normal Unix commands of the same
4728 names:
4729 <literallayout class='monospaced'>
4730 # EXTRA_USERS_PARAMS = "\
4731 # useradd -p '' tester; \
4732 # groupadd developers; \
4733 # userdel nobody; \
4734 # groupdel -g video; \
4735 # groupmod -g 1020 developers; \
4736 # usermod -s /bin/sh tester; \
4737 # "
4738 </literallayout>
4739 </para>
4740 </glossdef>
4741 </glossentry>
4742
4743 </glossdiv>
4744
4745 <glossdiv id='var-glossary-f'><title>F</title>
4746
4747 <glossentry id='var-FEATURE_PACKAGES'><glossterm>FEATURE_PACKAGES</glossterm>
4748 <info>
4749 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."
4750 </info>
4751 <glossdef>
4752 <para role="glossdeffirst">
4753<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4754 Defines one or more packages to include in an image when
4755 a specific item is included in
4756 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
4757 When setting the value, <filename>FEATURE_PACKAGES</filename>
4758 should have the name of the feature item as an override.
4759 Here is an example:
4760 <literallayout class='monospaced'>
4761 FEATURE_PACKAGES_widget = "<replaceable>package1</replaceable> <replaceable>package2</replaceable>"
4762 </literallayout>
4763 </para>
4764
4765 <para>
4766 In this example, if "widget" were added to
4767 <filename>IMAGE_FEATURES</filename>, <replaceable>package1</replaceable> and
4768 <replaceable>package2</replaceable> would be included in the image.
4769 <note>
4770 Packages installed by features defined through
4771 <filename>FEATURE_PACKAGES</filename> are often package
4772 groups.
4773 While similarly named, you should not confuse the
4774 <filename>FEATURE_PACKAGES</filename> variable with
4775 package groups, which are discussed elsewhere in the
4776 documentation.
4777 </note>
4778 </para>
4779 </glossdef>
4780 </glossentry>
4781
4782 <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm>
4783 <info>
4784 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."
4785 </info>
4786 <glossdef>
4787 <para role="glossdeffirst">
4788<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4789 Points to the base URL of the server and location within
4790 the document-root that provides the metadata and
4791 packages required by OPKG to support runtime package
4792 management of IPK packages.
4793 You set this variable in your
4794 <filename>local.conf</filename> file.
4795 </para>
4796
4797 <para>
4798 Consider the following example:
4799 <literallayout class='monospaced'>
4800 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
4801 </literallayout>
4802 This example assumes you are serving your packages over
4803 HTTP and your databases are located in a directory
4804 named <filename>BOARD-dir</filename>, which is underneath
4805 your HTTP server's document-root.
4806 In this case, the OpenEmbedded build system generates a set
4807 of configuration files for you in your target that work
4808 with the feed.
4809 </para>
4810 </glossdef>
4811 </glossentry>
4812
4813 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
4814 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004815 FILES[doc] = "The list of directories or files that are placed in a package."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004816 </info>
4817 <glossdef>
4818 <para role="glossdeffirst">
4819<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004820 The list of files and directories that are placed in a
4821 package.
4822 The
4823 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
4824 variable lists the packages generated by a recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004825 </para>
4826
4827 <para>
4828 To use the <filename>FILES</filename> variable, provide a
4829 package name override that identifies the resulting package.
4830 Then, provide a space-separated list of files or paths
4831 that identify the files you want included as part of the
4832 resulting package.
4833 Here is an example:
4834 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06004835 FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004836 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08004837 <note><title>Notes</title>
4838 <itemizedlist>
4839 <listitem><para>
4840 When specifying files or paths, you can pattern
4841 match using Python's
4842 <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>
4843 syntax.
4844 For details on the syntax, see the
4845 documentation by following the previous link.
4846 </para></listitem>
4847 <listitem><para>
4848 When specifying paths as part of the
4849 <filename>FILES</filename> variable, it is
4850 good practice to use appropriate path
4851 variables.
4852 For example, use <filename>${sysconfdir}</filename>
4853 rather than <filename>/etc</filename>, or
4854 <filename>${bindir}</filename> rather than
4855 <filename>/usr/bin</filename>.
4856 You can find a list of these variables at the
4857 top of the
4858 <filename>meta/conf/bitbake.conf</filename>
4859 file in the
4860 <link linkend='source-directory'>Source Directory</link>.
4861 You will also find the default values of the
4862 various <filename>FILES_*</filename> variables
4863 in this file.
4864 </para></listitem>
4865 </itemizedlist>
4866 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004867 </para>
4868
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004869 <para>
4870 If some of the files you provide with the
4871 <filename>FILES</filename> variable are editable and you
4872 know they should not be overwritten during the package
4873 update process by the Package Management System (PMS), you
4874 can identify these files so that the PMS will not
4875 overwrite them.
4876 See the
4877 <link linkend='var-CONFFILES'><filename>CONFFILES</filename></link>
4878 variable for information on how to identify these files to
4879 the PMS.
4880 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004881 </glossdef>
4882 </glossentry>
4883
4884 <glossentry id='var-FILES_SOLIBSDEV'><glossterm>FILES_SOLIBSDEV</glossterm>
4885 <info>
4886 FILES_SOLIBSDEV[doc] = "Defines the full path name of the development symbolic link (symlink) for shared libraries on the target platform."
4887 </info>
4888 <glossdef>
4889 <para role="glossdeffirst">
4890<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4891 Defines the file specification to match
4892 <link linkend='var-SOLIBSDEV'><filename>SOLIBSDEV</filename></link>.
4893 In other words, <filename>FILES_SOLIBSDEV</filename>
4894 defines the full path name of the development symbolic link
4895 (symlink) for shared libraries on the target platform.
4896 </para>
4897
4898 <para>
4899 The following statement from the
4900 <filename>bitbake.conf</filename> shows how it is set:
4901 <literallayout class='monospaced'>
4902 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
4903 </literallayout>
4904 </para>
4905 </glossdef>
4906 </glossentry>
4907
4908 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
4909 <info>
4910 FILESEXTRAPATHS[doc] = "Extends the search path the OpenEmbedded build system uses when looking for files and patches as it processes recipes and append files."
4911 </info>
4912 <glossdef>
4913 <para role="glossdeffirst">
4914<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
4915 Extends the search path the OpenEmbedded build system uses
4916 when looking for files and patches as it processes recipes
4917 and append files.
4918 The default directories BitBake uses when it processes
4919 recipes are initially defined by the
4920 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4921 variable.
4922 You can extend <filename>FILESPATH</filename> variable
4923 by using <filename>FILESEXTRAPATHS</filename>.
4924 </para>
4925
4926 <para>
4927 Best practices dictate that you accomplish this by using
4928 <filename>FILESEXTRAPATHS</filename> from within a
4929 <filename>.bbappend</filename> file and that you prepend
4930 paths as follows:
4931 <literallayout class='monospaced'>
4932 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
4933 </literallayout>
4934 In the above example, the build system first looks for files
4935 in a directory that has the same name as the corresponding
4936 append file.
4937 <note>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004938 <para>When extending
4939 <filename>FILESEXTRAPATHS</filename>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004940 be sure to use the immediate expansion
4941 (<filename>:=</filename>) operator.
4942 Immediate expansion makes sure that BitBake evaluates
4943 <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
4944 at the time the directive is encountered rather than at
4945 some later time when expansion might result in a
4946 directory that does not contain the files you need.
4947 </para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004948
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004949 <para>Also, include the trailing separating colon
4950 character if you are prepending.
4951 The trailing colon character is necessary because you
4952 are directing BitBake to extend the path by prepending
4953 directories to the search path.</para>
4954 </note>
4955 Here is another common use:
4956 <literallayout class='monospaced'>
4957 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
4958 </literallayout>
4959 In this example, the build system extends the
4960 <filename>FILESPATH</filename> variable to include a
4961 directory named <filename>files</filename> that is in the
4962 same directory as the corresponding append file.
4963 </para>
4964
4965 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004966 This next example specifically adds three paths:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004967 <literallayout class='monospaced'>
4968 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
4969 </literallayout>
4970 </para>
4971
4972 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004973 A final example shows how you can extend the search path
4974 and include a
4975 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>-specific
4976 override, which is useful in a BSP layer:
4977 <literallayout class='monospaced'>
4978 FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:"
4979 </literallayout>
4980 The previous statement appears in the
4981 <filename>linux-yocto-dev.bbappend</filename> file, which
4982 is found in the Yocto Project
Brad Bishop316dfdd2018-06-25 12:45:53 -04004983 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05004984 in
4985 <filename>meta-intel/common/recipes-kernel/linux</filename>.
4986 Here, the machine override is a special
4987 <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
4988 definition for multiple <filename>meta-intel</filename>
4989 machines.
4990 <note>
4991 For a layer that supports a single BSP, the override
4992 could just be the value of <filename>MACHINE</filename>.
4993 </note>
4994 </para>
4995
4996 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05004997 By prepending paths in <filename>.bbappend</filename>
4998 files, you allow multiple append files that reside in
4999 different layers but are used for the same recipe to
5000 correctly extend the path.
5001 </para>
5002 </glossdef>
5003 </glossentry>
5004
5005 <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
5006 <info>
5007 FILESOVERRIDES[doc] = "A subset of OVERRIDES used by the OpenEmbedded build system for creating FILESPATH."
5008 </info>
5009 <glossdef>
5010 <para role="glossdeffirst">
5011<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5012 A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
5013 used by the OpenEmbedded build system for creating
5014 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
5015 You can find more information on how overrides are handled
5016 in the
Brad Bishop316dfdd2018-06-25 12:45:53 -04005017 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005018 </para>
5019
5020 <para>
5021 By default, the <filename>FILESOVERRIDES</filename>
5022 variable is defined as:
5023 <literallayout class='monospaced'>
5024 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
5025 </literallayout>
5026
5027 <note>
5028 Do not hand-edit the <filename>FILESOVERRIDES</filename>
5029 variable.
5030 The values match up with expected overrides and are
5031 used in an expected manner by the build system.
5032 </note>
5033 </para>
5034 </glossdef>
5035 </glossentry>
5036
5037 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
5038 <info>
5039 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."
5040 </info>
5041 <glossdef>
5042 <para role="glossdeffirst">
5043<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5044 The default set of directories the OpenEmbedded build system
5045 uses when searching for patches and files.
5046 During the build process, BitBake searches each directory in
5047 <filename>FILESPATH</filename> in the specified order when
5048 looking for files and patches specified by each
Brad Bishop316dfdd2018-06-25 12:45:53 -04005049 <filename>file://</filename> URI in a recipe's
5050 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
5051 statements.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005052 </para>
5053
5054 <para>
5055 The default value for the <filename>FILESPATH</filename>
5056 variable is defined in the <filename>base.bbclass</filename>
5057 class found in <filename>meta/classes</filename> in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005058 <link linkend='source-directory'>Source Directory</link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005059 <literallayout class='monospaced'>
5060 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
5061 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
5062 </literallayout>
5063 <note>
5064 Do not hand-edit the <filename>FILESPATH</filename>
5065 variable.
5066 If you want the build system to look in directories
5067 other than the defaults, extend the
5068 <filename>FILESPATH</filename> variable by using the
5069 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
5070 variable.
5071 </note>
5072 Be aware that the default <filename>FILESPATH</filename>
5073 directories do not map to directories in custom layers
5074 where append files (<filename>.bbappend</filename>)
5075 are used.
5076 If you want the build system to find patches or files
5077 that reside with your append files, you need to extend
5078 the <filename>FILESPATH</filename> variable by using
Brad Bishop316dfdd2018-06-25 12:45:53 -04005079 the <filename>FILESEXTRAPATHS</filename> variable.
5080 </para>
5081
5082 <para>
5083 You can find out more about the patching process in the
5084 "<ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>Patching</ulink>"
5085 section in the Yocto Project Overview and Concepts Manual
5086 and the
5087 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code'>Patching Code</ulink>"
5088 section in the Yocto Project Development Tasks Manual.
5089 See the
5090 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
5091 task as well.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005092 </para>
5093 </glossdef>
5094 </glossentry>
5095
5096 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
5097 <info>
5098 FILESYSTEM_PERMS_TABLES[doc] = "Allows you to define your own file permissions settings table as part of your configuration for the packaging process."
5099 </info>
5100 <glossdef>
5101 <para role="glossdeffirst">
5102<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5103 Allows you to define your own file permissions settings table as part of
5104 your configuration for the packaging process.
5105 For example, suppose you need a consistent set of custom permissions for
5106 a set of groups and users across an entire work project.
5107 It is best to do this in the packages themselves but this is not always
5108 possible.
5109 </para>
5110
5111 <para>
5112 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
5113 is located in the <filename>meta/files</filename> folder in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005114 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005115 If you create your own file permissions setting table, you should place it in your
5116 layer or the distro's layer.
5117 </para>
5118
5119 <para>
5120 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
5121 <filename>conf/local.conf</filename> file, which is found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005122 <link linkend='build-directory'>Build Directory</link>, to
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005123 point to your custom <filename>fs-perms.txt</filename>.
5124 You can specify more than a single file permissions setting table.
5125 The paths you specify to these files must be defined within the
5126 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
5127 </para>
5128
5129 <para>
5130 For guidance on how to create your own file permissions settings table file,
5131 examine the existing <filename>fs-perms.txt</filename>.
5132 </para>
5133 </glossdef>
5134 </glossentry>
5135
5136 <glossentry id='var-FONT_EXTRA_RDEPENDS'><glossterm>FONT_EXTRA_RDEPENDS</glossterm>
5137 <info>
5138 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'."
5139 </info>
5140 <glossdef>
5141 <para role="glossdeffirst">
5142<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5143 When inheriting the
5144 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
5145 class, this variable specifies the runtime dependencies
5146 for font packages.
5147 By default, the <filename>FONT_EXTRA_RDEPENDS</filename>
5148 is set to "fontconfig-utils".
5149 </para>
5150 </glossdef>
5151 </glossentry>
5152
5153 <glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm>
5154 <info>
5155 FONT_PACKAGES[doc] = "When a recipe inherits the fontcache class, this variable identifies packages containing font files that need to be cached by Fontconfig."
5156 </info>
5157 <glossdef>
5158 <para role="glossdeffirst">
5159<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5160 When inheriting the
5161 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
5162 class, this variable identifies packages containing font
5163 files that need to be cached by Fontconfig.
5164 By default, the <filename>fontcache</filename> class assumes
5165 that fonts are in the recipe's main package
5166 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
5167 Use this variable if fonts you need are in a package
5168 other than that main package.
5169 </para>
5170 </glossdef>
5171 </glossentry>
5172
Patrick Williamsc0f7c042017-02-23 20:41:17 -06005173 <glossentry id='var-FORCE_RO_REMOVE'><glossterm>FORCE_RO_REMOVE</glossterm>
5174 <info>
5175 FORCE_RO_REMOVE[doc] = "Forces the removal of the packages listed in ROOTFS_RO_UNNEEDED during the generation of the root filesystem."
5176 </info>
5177 <glossdef>
5178 <para role="glossdeffirst">
5179<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5180 Forces the removal of the packages listed in
5181 <filename>ROOTFS_RO_UNNEEDED</filename> during the
5182 generation of the root filesystem.
5183 </para>
5184
5185 <para>
5186 Set the variable to "1" to force the removal of these
5187 packages.
5188 </para>
5189 </glossdef>
5190 </glossentry>
5191
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005192 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
5193 <info>
5194 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'."
5195 </info>
5196 <glossdef>
5197 <para role="glossdeffirst">
5198<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5199 The options to pass in
5200 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
5201 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
5202 when compiling an optimized system.
5203 This variable defaults to
5204 "-O2 -pipe ${DEBUG_FLAGS}".
5205 </para>
5206 </glossdef>
5207 </glossentry>
5208 </glossdiv>
5209
5210 <glossdiv id='var-glossary-g'><title>G</title>
5211
Brad Bishop316dfdd2018-06-25 12:45:53 -04005212 <glossentry id='var-GCCPIE'><glossterm>GCCPIE</glossterm>
5213 <info>
5214 GCCPIE[doc] = "Enables Position Independent Executables (PIE) within the GNU C Compiler (GCC)."
5215 </info>
5216 <glossdef>
5217 <para role="glossdeffirst">
5218<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5219 Enables Position Independent Executables (PIE) within the
5220 GNU C Compiler (GCC).
5221 Enabling PIE in the GCC makes Return Oriented Programming
5222 (ROP) attacks much more difficult to
5223 execute.
5224 </para>
5225
5226 <para>
5227 By default the <filename>security_flags.inc</filename>
5228 file enables PIE by setting the variable as follows:
5229 <literallayout class='monospaced'>
5230 GCCPIE ?= "--enable-default-pie"
5231 </literallayout>
5232 </para>
5233 </glossdef>
5234 </glossentry>
5235
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08005236 <glossentry id='var-GCCVERSION'><glossterm>GCCVERSION</glossterm>
5237 <info>
5238 GCCVERSION[doc] = "Specifies the default version of the GNU C Compiler (GCC) to use."
5239 </info>
5240 <glossdef>
5241 <para role="glossdeffirst">
5242<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5243 Specifies the default version of the GNU C Compiler (GCC)
5244 used for compilation.
5245 By default, <filename>GCCVERSION</filename> is set to
5246 "8.x" in the
5247 <filename>meta/conf/distro/include/tcmode-default.inc</filename>
5248 include file:
5249 <literallayout class='monospaced'>
5250 GCCVERSION ?= "8.%"
5251 </literallayout>
5252 You can override this value by setting it in a configuration
5253 file such as the <filename>local.conf</filename>.
5254 </para>
5255 </glossdef>
5256 </glossentry>
5257
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005258 <glossentry id='var-GDB'><glossterm>GDB</glossterm>
5259 <info>
5260 GDB[doc] = "The minimal command and arguments to run the GNU Debugger."
5261 </info>
5262 <glossdef>
5263 <para role="glossdeffirst">
5264<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5265 The minimal command and arguments to run the GNU Debugger.
5266 </para>
5267 </glossdef>
5268 </glossentry>
5269
5270 <glossentry id='var-GITDIR'><glossterm>GITDIR</glossterm>
5271 <info>
5272 GITDIR[doc] = "The directory where Git clones will be stored."
5273 </info>
5274 <glossdef>
5275 <para role="glossdeffirst">
5276<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5277 The directory in which a local copy of a Git repository
5278 is stored when it is cloned.
5279 </para>
5280 </glossdef>
5281 </glossentry>
5282
5283 <glossentry id='var-GLIBC_GENERATE_LOCALES'><glossterm>GLIBC_GENERATE_LOCALES</glossterm>
5284 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04005285 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 -05005286 </info>
5287 <glossdef>
5288 <para role="glossdeffirst">
5289<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5290 Specifies the list of GLIBC locales to generate should you
Brad Bishop316dfdd2018-06-25 12:45:53 -04005291 not wish to generate all LIBC locals, which can be time
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005292 consuming.
5293 <note>
5294 If you specifically remove the locale
5295 <filename>en_US.UTF-8</filename>, you must set
5296 <link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link>
5297 appropriately.
5298 </note>
5299 </para>
5300
5301 <para>
5302 You can set <filename>GLIBC_GENERATE_LOCALES</filename>
5303 in your <filename>local.conf</filename> file.
5304 By default, all locales are generated.
5305 <literallayout class='monospaced'>
5306 GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
5307 </literallayout>
5308 </para>
5309 </glossdef>
5310 </glossentry>
5311
5312 <glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm>
5313 <info>
5314 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."
5315 </info>
5316 <glossdef>
5317 <para role="glossdeffirst">
5318<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5319 When inheriting the
5320 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
5321 class, this variable
5322 specifies for a package what parameters should be passed
5323 to the <filename>groupadd</filename> command
5324 if you wish to add a group to the system when the package
5325 is installed.
5326 </para>
5327
5328 <para>
5329 Here is an example from the <filename>dbus</filename>
5330 recipe:
5331 <literallayout class='monospaced'>
5332 GROUPADD_PARAM_${PN} = "-r netdev"
5333 </literallayout>
5334 For information on the standard Linux shell command
5335 <filename>groupadd</filename>, see
5336 <ulink url='http://linux.die.net/man/8/groupadd'></ulink>.
5337 </para>
5338 </glossdef>
5339 </glossentry>
5340
5341 <glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm>
5342 <info>
5343 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."
5344 </info>
5345 <glossdef>
5346 <para role="glossdeffirst">
5347<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5348 When inheriting the
5349 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
5350 class, this variable
5351 specifies for a package what parameters should be passed
5352 to the <filename>groupmems</filename> command
5353 if you wish to modify the members of a group when the
5354 package is installed.
5355 </para>
5356
5357 <para>
5358 For information on the standard Linux shell command
5359 <filename>groupmems</filename>, see
5360 <ulink url='http://linux.die.net/man/8/groupmems'></ulink>.
5361 </para>
5362 </glossdef>
5363 </glossentry>
5364
5365 <glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm>
5366 <info>
5367 GRUB_GFXSERIAL[doc] = "Configures the GNU GRand Unified Bootloader (GRUB) to have graphics and serial in the boot menu."
5368 </info>
5369 <glossdef>
5370 <para role="glossdeffirst">
5371<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5372 Configures the GNU GRand Unified Bootloader (GRUB) to have
5373 graphics and serial in the boot menu.
5374 Set this variable to "1" in your
5375 <filename>local.conf</filename> or distribution
5376 configuration file to enable graphics and serial
5377 in the menu.
5378 </para>
5379
5380 <para>
5381 See the
5382 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5383 class for more information on how this variable is used.
5384 </para>
5385 </glossdef>
5386 </glossentry>
5387
5388 <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm>
5389 <info>
5390 GRUB_OPTS[doc] = "Additional options to add to the GNU GRand Unified Bootloader (GRUB) configuration."
5391 </info>
5392 <glossdef>
5393 <para role="glossdeffirst">
5394<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5395 Additional options to add to the GNU GRand Unified
5396 Bootloader (GRUB) configuration.
5397 Use a semi-colon character (<filename>;</filename>) to
5398 separate multiple options.
5399 </para>
5400
5401 <para>
5402 The <filename>GRUB_OPTS</filename> variable is optional.
5403 See the
5404 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5405 class for more information on how this variable is used.
5406 </para>
5407 </glossdef>
5408 </glossentry>
5409
5410 <glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm>
5411 <info>
5412 GRUB_TIMEOUT[doc] = "Specifies the timeout before executing the default LABEL in the GNU GRand Unified Bootloader (GRUB)."
5413 </info>
5414 <glossdef>
5415 <para role="glossdeffirst">
5416<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5417 Specifies the timeout before executing the default
5418 <filename>LABEL</filename> in the GNU GRand Unified
5419 Bootloader (GRUB).
5420 </para>
5421
5422 <para>
5423 The <filename>GRUB_TIMEOUT</filename> variable is optional.
5424 See the
5425 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5426 class for more information on how this variable is used.
5427 </para>
5428 </glossdef>
5429 </glossentry>
5430
5431 <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm>
5432 <info>
5433 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."
5434 </info>
5435 <glossdef>
5436 <para role="glossdeffirst">
5437<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5438 When inheriting the
5439 <link linkend='ref-classes-gtk-immodules-cache'><filename>gtk-immodules-cache</filename></link>
5440 class, this variable specifies the packages that contain the
5441 GTK+ input method modules being installed when the modules
5442 are in packages other than the main package.
5443 </para>
5444 </glossdef>
5445 </glossentry>
5446
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005447 </glossdiv>
5448
5449 <glossdiv id='var-glossary-h'><title>H</title>
5450
5451 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
5452 <info>
5453 HOMEPAGE[doc] = "Website where more information about the software the recipe is building can be found."
5454 </info>
5455 <glossdef>
5456 <para role="glossdeffirst">
5457<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5458 Website where more information about the software the recipe is building
5459 can be found.
5460 </para>
5461 </glossdef>
5462 </glossentry>
5463
5464 <glossentry id='var-HOST_ARCH'><glossterm>HOST_ARCH</glossterm>
5465 <info>
5466 HOST_ARCH[doc] = "The name of the target architecture. Normally same as the TARGET_ARCH."
5467
5468 </info>
5469 <glossdef>
5470 <para role="glossdeffirst">
5471<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5472 The name of the target architecture, which is normally
5473 the same as
5474 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
5475 The OpenEmbedded build system supports many
5476 architectures.
5477 Here is an example list of architectures supported.
5478 This list is by no means complete as the architecture
5479 is configurable:
5480 <literallayout class='monospaced'>
5481 arm
5482 i586
5483 x86_64
5484 powerpc
5485 powerpc64
5486 mips
5487 mipsel
5488 </literallayout>
5489 </para>
5490 </glossdef>
5491 </glossentry>
5492
5493 <glossentry id='var-HOST_CC_ARCH'><glossterm>HOST_CC_ARCH</glossterm>
5494 <info>
5495 HOST_CC_ARCH[doc] = "The name of the host architecture. Normally same as the TARGET_CC_ARCH."
5496 </info>
5497 <glossdef>
5498 <para role="glossdeffirst">
5499<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5500 Specifies architecture-specific compiler flags that are
5501 passed to the C compiler.
5502 </para>
5503
5504 <para>
5505 Default initialization for <filename>HOST_CC_ARCH</filename>
5506 varies depending on what is being built:
5507 <itemizedlist>
5508 <listitem><para>
5509 <link linkend='var-TARGET_CC_ARCH'><filename>TARGET_CC_ARCH</filename></link>
5510 when building for the target
5511 </para></listitem>
5512 <listitem><para>
5513 <filename>BUILD_CC_ARCH</filename>
5514 when building for the build host (i.e.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05005515 <filename>-native</filename>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005516 </para></listitem>
5517 <listitem><para>
5518 <filename>BUILDSDK_CC_ARCH</filename>
5519 when building for an SDK (i.e.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05005520 <filename>nativesdk-</filename>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005521 </para></listitem>
5522 </itemizedlist>
5523 </para>
5524 </glossdef>
5525 </glossentry>
5526
5527 <glossentry id='var-HOST_OS'><glossterm>HOST_OS</glossterm>
5528 <info>
5529 HOST_OS[doc] = "The name of the target operating system. Normally the same as the TARGET_OS."
5530 </info>
5531 <glossdef>
5532 <para role="glossdeffirst">
5533<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5534 Specifies the name of the target operating system, which
5535 is normally the same as the
5536 <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>.
5537 The variable can be set to "linux" for <filename>glibc</filename>-based systems and
Brad Bishop37a0e4d2017-12-04 01:01:44 -05005538 to "linux-musl" for <filename>musl</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005539 For ARM/EABI targets, there are also "linux-gnueabi" and
Brad Bishop37a0e4d2017-12-04 01:01:44 -05005540 "linux-musleabi" values possible.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005541 </para>
5542 </glossdef>
5543 </glossentry>
5544
5545 <glossentry id='var-HOST_PREFIX'><glossterm>HOST_PREFIX</glossterm>
5546 <info>
5547 HOST_PREFIX[doc] = "The prefix for the cross compile toolchain. Normally same as the TARGET_PREFIX."
5548 </info>
5549 <glossdef>
5550 <para role="glossdeffirst">
5551<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5552 Specifies the prefix for the cross-compile toolchain.
5553 <filename>HOST_PREFIX</filename> is normally the same as
5554 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>.
5555 </para>
5556 </glossdef>
5557 </glossentry>
5558
5559 <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
5560 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04005561 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 -05005562 </info>
5563 <glossdef>
5564 <para role="glossdeffirst">
5565<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5566 Specifies the system, including the architecture and the
5567 operating system, for which the build is occurring
5568 in the context of the current recipe.
5569 </para>
5570
5571 <para>
5572 The OpenEmbedded build system automatically sets this
5573 variable based on
5574 <link linkend='var-HOST_ARCH'><filename>HOST_ARCH</filename></link>,
5575 <link linkend='var-HOST_VENDOR'><filename>HOST_VENDOR</filename></link>,
5576 and
5577 <link linkend='var-HOST_OS'><filename>HOST_OS</filename></link>
5578 variables.
5579 <note>
5580 You do not need to set the variable yourself.
5581 </note>
5582 </para>
5583
5584 <para>
5585 Consider these two examples:
5586 <itemizedlist>
5587 <listitem><para>Given a native recipe on a 32-bit
5588 x86 machine running Linux, the value is
5589 "i686-linux".
5590 </para></listitem>
5591 <listitem><para>Given a recipe being built for a
5592 little-endian MIPS target running Linux,
5593 the value might be "mipsel-linux".
5594 </para></listitem>
5595 </itemizedlist>
5596 </para>
5597 </glossdef>
5598 </glossentry>
5599
Brad Bishop6e60e8b2018-02-01 10:27:11 -05005600 <glossentry id='var-HOSTTOOLS'><glossterm>HOSTTOOLS</glossterm>
5601 <info>
5602 HOSTTOOLS[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks."
5603 </info>
5604 <glossdef>
5605 <para role="glossdeffirst">
5606<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5607 A space-separated list (filter) of tools on the build host
5608 that should be allowed to be called from within build tasks.
5609 Using this filter helps reduce the possibility of host
5610 contamination.
5611 If a tool specified in the value of
5612 <filename>HOSTTOOLS</filename> is not found on the
5613 build host, the OpenEmbedded build system produces
5614 an error and the build is not started.
5615 </para>
5616
5617 <para>
5618 For additional information, see
5619 <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link>.
5620 </para>
5621 </glossdef>
5622 </glossentry>
5623
5624 <glossentry id='var-HOSTTOOLS_NONFATAL'><glossterm>HOSTTOOLS_NONFATAL</glossterm>
5625 <info>
5626 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."
5627 </info>
5628 <glossdef>
5629 <para role="glossdeffirst">
5630<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5631 A space-separated list (filter) of tools on the build host
5632 that should be allowed to be called from within build tasks.
5633 Using this filter helps reduce the possibility of host
5634 contamination.
5635 Unlike
5636 <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link>,
Brad Bishop316dfdd2018-06-25 12:45:53 -04005637 the OpenEmbedded build system does not produce an error
Brad Bishop6e60e8b2018-02-01 10:27:11 -05005638 if a tool specified in the value of
5639 <filename>HOSTTOOLS_NONFATAL</filename> is not found on the
5640 build host.
5641 Thus, you can use <filename>HOSTTOOLS_NONFATAL</filename>
5642 to filter optional host tools.
5643 </para>
5644 </glossdef>
5645 </glossentry>
5646
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005647 <glossentry id='var-HOST_VENDOR'><glossterm>HOST_VENDOR</glossterm>
5648 <info>
5649 HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR."
5650 </info>
5651 <glossdef>
5652 <para role="glossdeffirst">
5653<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5654 Specifies the name of the vendor.
5655 <filename>HOST_VENDOR</filename> is normally the same as
Brad Bishop316dfdd2018-06-25 12:45:53 -04005656 <link linkend='var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005657 </para>
5658 </glossdef>
5659 </glossentry>
5660
5661 </glossdiv>
5662
5663 <glossdiv id='var-glossary-i'><title>I</title>
5664
5665 <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm>
5666 <info>
5667 ICECC_DISABLED[doc] = "Disables or enables the icecc (Icecream) function."
5668 </info>
5669 <glossdef>
5670 <para role="glossdeffirst">
5671<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5672 Disables or enables the <filename>icecc</filename>
5673 (Icecream) function.
5674 For more information on this function and best practices
5675 for using this variable, see the
5676 "<link linkend='ref-classes-icecc'><filename>icecc.bbclass</filename></link>"
5677 section.
5678 </para>
5679
5680 <para>
5681 Setting this variable to "1" in your
5682 <filename>local.conf</filename> disables the function:
5683 <literallayout class='monospaced'>
5684 ICECC_DISABLED ??= "1"
5685 </literallayout>
5686 To enable the function, set the variable as follows:
5687 <literallayout class='monospaced'>
5688 ICECC_DISABLED = ""
5689 </literallayout>
5690 </para>
5691 </glossdef>
5692 </glossentry>
5693
5694 <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm>
5695 <info>
5696 ICECC_ENV_EXEC[doc] = "Points to the icecc-create-env script that you provide."
5697 </info>
5698 <glossdef>
5699 <para role="glossdeffirst">
5700<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5701 Points to the <filename>icecc-create-env</filename> script
5702 that you provide.
5703 This variable is used by the
5704 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5705 class.
5706 You set this variable in your
5707 <filename>local.conf</filename> file.
5708 </para>
5709
5710 <para>
5711 If you do not point to a script that you provide, the
5712 OpenEmbedded build system uses the default script provided
5713 by the <filename>icecc-create-env.bb</filename> recipe,
5714 which is a modified version and not the one that comes with
5715 <filename>icecc</filename>.
5716 </para>
5717 </glossdef>
5718 </glossentry>
5719
5720 <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm>
5721 <info>
5722 ICECC_PARALLEL_MAKE[doc] = "Extra options passed to the make command during the do_compile task that specify parallel compilation."
5723 </info>
5724 <glossdef>
5725 <para role="glossdeffirst">
5726<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5727 Extra options passed to the <filename>make</filename>
5728 command during the
5729 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
5730 task that specify parallel compilation.
5731 This variable usually takes the form of
5732 "-j <replaceable>x</replaceable>", where
5733 <replaceable>x</replaceable> represents the maximum
5734 number of parallel threads <filename>make</filename> can
5735 run.
5736 <note>
5737 The options passed affect builds on all enabled
5738 machines on the network, which are machines running the
5739 <filename>iceccd</filename> daemon.
5740 </note>
5741 </para>
5742
5743 <para>
5744 If your enabled machines support multiple cores,
5745 coming up with the maximum number of parallel threads
5746 that gives you the best performance could take some
5747 experimentation since machine speed, network lag,
5748 available memory, and existing machine loads can all
5749 affect build time.
5750 Consequently, unlike the
5751 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
5752 variable, there is no rule-of-thumb for setting
5753 <filename>ICECC_PARALLEL_MAKE</filename> to achieve
5754 optimal performance.
5755 </para>
5756
5757 <para>
5758 If you do not set <filename>ICECC_PARALLEL_MAKE</filename>,
5759 the build system does not use it (i.e. the system does
5760 not detect and assign the number of cores as is done with
5761 <filename>PARALLEL_MAKE</filename>).
5762 </para>
5763 </glossdef>
5764 </glossentry>
5765
5766 <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm>
5767 <info>
5768 ICECC_PATH[doc] = "The location of the icecc binary."
5769 </info>
5770 <glossdef>
5771 <para role="glossdeffirst">
5772<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5773 The location of the <filename>icecc</filename> binary.
5774 You can set this variable in your
5775 <filename>local.conf</filename> file.
5776 If your <filename>local.conf</filename> file does not define
5777 this variable, the
5778 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5779 class attempts to define it by locating
5780 <filename>icecc</filename> using <filename>which</filename>.
5781 </para>
5782 </glossdef>
5783 </glossentry>
5784
5785 <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm>
5786 <info>
5787 ICECC_USER_CLASS_BL[doc] = "Identifies user classes that you do not want the Icecream distributed compile support to consider."
5788 </info>
5789 <glossdef>
5790 <para role="glossdeffirst">
5791<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5792 Identifies user classes that you do not want the
5793 Icecream distributed compile support to consider.
5794 This variable is used by the
5795 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5796 class.
5797 You set this variable in your
5798 <filename>local.conf</filename> file.
5799 </para>
5800
5801 <para>
5802 When you list classes using this variable, you are
5803 "blacklisting" them from distributed compilation across
5804 remote hosts.
5805 Any classes you list will be distributed and compiled
5806 locally.
5807 </para>
5808 </glossdef>
5809 </glossentry>
5810
5811 <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm>
5812 <info>
5813 ICECC_USER_PACKAGE_BL[doc] = "Identifies user recipes that you do not want the Icecream distributed compile support to consider."
5814 </info>
5815 <glossdef>
5816 <para role="glossdeffirst">
5817<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5818 Identifies user recipes that you do not want the
5819 Icecream distributed compile support to consider.
5820 This variable is used by the
5821 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5822 class.
5823 You set this variable in your
5824 <filename>local.conf</filename> file.
5825 </para>
5826
5827 <para>
5828 When you list packages using this variable, you are
5829 "blacklisting" them from distributed compilation across
5830 remote hosts.
5831 Any packages you list will be distributed and compiled
5832 locally.
5833 </para>
5834 </glossdef>
5835 </glossentry>
5836
5837 <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm>
5838 <info>
5839 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."
5840 </info>
5841 <glossdef>
5842 <para role="glossdeffirst">
5843<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5844 Identifies user recipes that use an empty
5845 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
5846 variable that you want to force remote distributed
5847 compilation on using the Icecream distributed compile
5848 support.
5849 This variable is used by the
5850 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5851 class.
5852 You set this variable in your
5853 <filename>local.conf</filename> file.
5854 </para>
5855 </glossdef>
5856 </glossentry>
5857
5858 <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
5859 <info>
5860 IMAGE_BASENAME[doc] = "The base name of image output files."
5861 </info>
5862 <glossdef>
5863 <para role="glossdeffirst">
5864<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5865 The base name of image output files.
5866 This variable defaults to the recipe name
5867 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
5868 </para>
5869 </glossdef>
5870 </glossentry>
5871
5872 <glossentry id='var-IMAGE_BOOT_FILES'><glossterm>IMAGE_BOOT_FILES</glossterm>
5873 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04005874 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 -05005875 </info>
5876 <glossdef>
5877 <para role="glossdeffirst">
5878<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5879 A space-separated list of files installed into the
Brad Bishop316dfdd2018-06-25 12:45:53 -04005880 boot partition when preparing an image using the Wic tool
5881 with the <filename>bootimg-partition</filename> source
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005882 plugin.
Brad Bishop316dfdd2018-06-25 12:45:53 -04005883 By default, the files are installed under the same name as
5884 the source files.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005885 To change the installed name, separate it from the
5886 original name with a semi-colon (;).
5887 Source files need to be located in
5888 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>.
5889 Here are two examples:
5890
5891 <literallayout class="monospaced">
5892 IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
5893 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
5894 </literallayout>
5895 </para>
5896
5897 <para>
5898 Alternatively, source files can be picked up using
5899 a glob pattern.
Brad Bishop316dfdd2018-06-25 12:45:53 -04005900 In this case, the destination file must have the same name
5901 as the base name of the source file path.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005902 To install files into a directory within the
5903 target location, pass its name after a semi-colon
5904 (;).
5905 Here are two examples:
5906 <literallayout class="monospaced">
5907 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
5908 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"
5909 </literallayout>
5910 The first example installs all files from
5911 <filename>${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles</filename>
5912 into the root of the target partition.
5913 The second example installs the same files into a
5914 <filename>boot</filename> directory within the
5915 target partition.
5916 </para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04005917
5918 <para>
5919 You can find information on how to use the Wic tool in the
5920 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
5921 section of the Yocto Project Development Tasks Manual.
5922 Reference material for Wic is located in the
5923 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>OpenEmbedded Kickstart (.wks) Reference</ulink>"
5924 chapter.
5925 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005926 </glossdef>
5927 </glossentry>
5928
5929 <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
5930 <info>
5931 IMAGE_CLASSES[doc] = "A list of classes that all images should inherit."
5932 </info>
5933 <glossdef>
5934 <para role="glossdeffirst">
5935<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5936 A list of classes that all images should inherit.
5937 You typically use this variable to specify the list of
5938 classes that register the different types of images
5939 the OpenEmbedded build system creates.
5940 </para>
5941
5942 <para>
5943 The default value for <filename>IMAGE_CLASSES</filename> is
5944 <filename>image_types</filename>.
5945 You can set this variable in your
5946 <filename>local.conf</filename> or in a distribution
5947 configuration file.
5948 </para>
5949
5950 <para>
5951 For more information, see
5952 <filename>meta/classes/image_types.bbclass</filename> in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05005953 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005954 </para>
5955 </glossdef>
5956 </glossentry>
5957
5958 <glossentry id='var-IMAGE_CMD'><glossterm>IMAGE_CMD</glossterm>
5959 <info>
5960 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)."
5961 </info>
5962 <glossdef>
5963 <para role="glossdeffirst">
5964<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5965 Specifies the command to create the image file for a
5966 specific image type, which corresponds to the value set
5967 set in
5968 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
5969 (e.g. <filename>ext3</filename>,
5970 <filename>btrfs</filename>, and so forth).
5971 When setting this variable, you should use
5972 an override for the associated type.
5973 Here is an example:
5974 <literallayout class='monospaced'>
5975 IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \
5976 --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \
5977 ${EXTRA_IMAGECMD}"
5978 </literallayout>
5979 </para>
5980
5981 <para>
5982 You typically do not need to set this variable unless
5983 you are adding support for a new image type.
5984 For more examples on how to set this variable, see the
5985 <link linkend='ref-classes-image_types'><filename>image_types</filename></link>
5986 class file, which is
5987 <filename>meta/classes/image_types.bbclass</filename>.
5988 </para>
5989 </glossdef>
5990 </glossentry>
5991
5992 <glossentry id='var-IMAGE_DEVICE_TABLES'><glossterm>IMAGE_DEVICE_TABLES</glossterm>
5993 <info>
5994 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."
5995 </info>
5996 <glossdef>
5997 <para role="glossdeffirst">
5998<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
5999 Specifies one or more files that contain custom device
6000 tables that are passed to the
6001 <filename>makedevs</filename> command as part of creating
6002 an image.
6003 These files list basic device nodes that should be
6004 created under <filename>/dev</filename> within the image.
6005 If <filename>IMAGE_DEVICE_TABLES</filename> is not set,
6006 <filename>files/device_table-minimal.txt</filename> is
6007 used, which is located by
6008 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
6009 For details on how you should write device table files,
6010 see <filename>meta/files/device_table-minimal.txt</filename>
6011 as an example.
6012 </para>
6013 </glossdef>
6014 </glossentry>
6015
6016 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
6017 <info>
6018 IMAGE_FEATURES[doc] = "The primary list of features to include in an image. Configure this variable in an image recipe."
6019 </info>
6020 <glossdef>
6021 <para role="glossdeffirst">
6022<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6023 The primary list of features to include in an image.
6024 Typically, you configure this variable in an image recipe.
6025 Although you can use this variable from your
6026 <filename>local.conf</filename> file, which is found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006027 <link linkend='build-directory'>Build Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006028 best practices dictate that you do not.
6029 <note>
6030 To enable extra features from outside the image recipe,
6031 use the
6032 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
6033 </note>
6034 </para>
6035
6036 <para>
6037 For a list of image features that ships with the Yocto
6038 Project, see the
6039 "<link linkend="ref-features-image">Image Features</link>"
6040 section.
6041 </para>
6042
6043 <para>
6044 For an example that shows how to customize your image by
6045 using this variable, see the
6046 "<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 -05006047 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006048 </para>
6049 </glossdef>
6050 </glossentry>
6051
6052 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
6053 <info>
6054 IMAGE_FSTYPES[doc] = "Formats of root filesystem images that you want to have created."
6055 </info>
6056 <glossdef>
6057 <para role="glossdeffirst">
6058<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6059 Specifies the formats the OpenEmbedded build system uses
6060 during the build when creating the root filesystem.
6061 For example, setting <filename>IMAGE_FSTYPES</filename>
6062 as follows causes the build system to create root
6063 filesystems using two formats: <filename>.ext3</filename>
6064 and <filename>.tar.bz2</filename>:
6065 <literallayout class='monospaced'>
6066 IMAGE_FSTYPES = "ext3 tar.bz2"
6067 </literallayout>
6068 </para>
6069
6070 <para>
6071 For the complete list of supported image formats from which
6072 you can choose, see
6073 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
6074 </para>
6075
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006076 <note><title>Notes</title>
6077 <itemizedlist>
6078 <listitem><para>
6079 If you add "live" to
6080 <filename>IMAGE_FSTYPES</filename> inside an image
6081 recipe, be sure that you do so prior to the
6082 "inherit image" line of the recipe or the live
6083 image will not build.
6084 </para></listitem>
6085 <listitem><para>
6086 Due to the way the OpenEmbedded build system
6087 processes this variable, you cannot update its
6088 contents by using <filename>_append</filename> or
6089 <filename>_prepend</filename>.
6090 You must use the <filename>+=</filename>
6091 operator to add one or more options to the
6092 <filename>IMAGE_FSTYPES</filename> variable.
6093 </para></listitem>
6094 </itemizedlist>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006095 </note>
6096 </glossdef>
6097 </glossentry>
6098
6099 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
6100 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006101 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 -05006102 </info>
6103 <glossdef>
6104 <para role="glossdeffirst">
6105<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -04006106 Used by recipes to specify the packages to install into an
6107 image through the
6108 <link linkend='ref-classes-image'><filename>image</filename></link>
6109 class.
6110 Use the <filename>IMAGE_INSTALL</filename> variable with
6111 care to avoid ordering issues.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006112 </para>
6113
6114 <para>
6115 Image recipes set <filename>IMAGE_INSTALL</filename>
6116 to specify the packages to install into an image through
6117 <filename>image.bbclass</filename>.
Brad Bishop316dfdd2018-06-25 12:45:53 -04006118 Additionally, "helper" classes such as the
6119 <link linkend='ref-classes-core-image'><filename>core-image</filename></link>
6120 class exist that can take lists used with
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006121 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006122 and turn them into auto-generated entries in
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006123 <filename>IMAGE_INSTALL</filename> in addition to its
6124 default contents.
6125 </para>
6126
6127 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006128 When you use this variable, it is best to use it as follows:
6129 <literallayout class='monospaced'>
6130 IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>"
6131 </literallayout>
6132 Be sure to include the space between the quotation character
6133 and the start of the package name or names.
Brad Bishop316dfdd2018-06-25 12:45:53 -04006134 <note><title>Caution</title>
6135 <itemizedlist>
6136 <listitem><para>
6137 When working with a
6138 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
6139 image, do not use the
6140 <filename>IMAGE_INSTALL</filename> variable to
6141 specify packages for installation.
6142 Instead, use the
6143 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
6144 variable, which allows the initial RAM
6145 filesystem (initramfs) recipe to use a fixed
6146 set of packages and not be affected by
6147 <filename>IMAGE_INSTALL</filename>.
6148 For information on creating an initramfs, see
6149 the
6150 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
6151 section in the Yocto Project Development Tasks
6152 Manual.
6153 </para></listitem>
6154 <listitem><para>
6155 Using <filename>IMAGE_INSTALL</filename> with
6156 the
6157 <ulink url='&YOCTO_DOCS_BB_URL;#appending-and-prepending'><filename>+=</filename></ulink>
6158 BitBake operator within the
6159 <filename>/conf/local.conf</filename> file or
6160 from within an image recipe is not recommended.
6161 Use of this operator in these ways can cause
6162 ordering issues.
6163 Since <filename>core-image.bbclass</filename>
6164 sets <filename>IMAGE_INSTALL</filename> to a
6165 default value using the
6166 <ulink url='&YOCTO_DOCS_BB_URL;#setting-a-default-value'><filename>?=</filename></ulink>
6167 operator, using a <filename>+=</filename>
6168 operation against
6169 <filename>IMAGE_INSTALL</filename> results in
6170 unexpected behavior when used within
6171 <filename>conf/local.conf</filename>.
6172 Furthermore, the same operation from within
6173 an image recipe may or may not succeed
6174 depending on the specific situation.
6175 In both these cases, the behavior is contrary
6176 to how most users expect the
6177 <filename>+=</filename> operator to work.
6178 </para></listitem>
6179 </itemizedlist>
6180 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006181 </para>
6182 </glossdef>
6183 </glossentry>
6184
6185 <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
6186 <info>
6187 IMAGE_LINGUAS[doc] = "Specifies the list of locales to install into the image during the root filesystem construction process."
6188 </info>
6189 <glossdef>
6190 <para role="glossdeffirst">
6191<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6192 Specifies the list of locales to install into the image
6193 during the root filesystem construction process.
6194 The OpenEmbedded build system automatically splits locale
6195 files, which are used for localization, into separate
6196 packages.
6197 Setting the <filename>IMAGE_LINGUAS</filename> variable
6198 ensures that any locale packages that correspond to packages
6199 already selected for installation into the image are also
6200 installed.
6201 Here is an example:
6202 <literallayout class='monospaced'>
6203 IMAGE_LINGUAS = "pt-br de-de"
6204 </literallayout>
6205 </para>
6206
6207 <para>
6208 In this example, the build system ensures any Brazilian
6209 Portuguese and German locale files that correspond to
6210 packages in the image are installed (i.e.
6211 <filename>*-locale-pt-br</filename>
6212 and <filename>*-locale-de-de</filename> as well as
6213 <filename>*-locale-pt</filename>
6214 and <filename>*-locale-de</filename>, since some software
6215 packages only provide locale files by language and not by
6216 country-specific language).
6217 </para>
6218
6219 <para>
6220 See the
6221 <link linkend='var-GLIBC_GENERATE_LOCALES'><filename>GLIBC_GENERATE_LOCALES</filename></link>
6222 variable for information on generating GLIBC locales.
6223 </para>
6224 </glossdef>
6225 </glossentry>
6226
6227 <glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm>
6228 <info>
6229 IMAGE_MANIFEST[doc] = "The manifest file for the image. This file lists all the installed packages that make up the image."
6230 </info>
6231 <glossdef>
6232 <para role="glossdeffirst">
6233<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6234 The manifest file for the image.
6235 This file lists all the installed packages that make up
6236 the image.
6237 The file contains package information on a line-per-package
6238 basis as follows:
6239 <literallayout class='monospaced'>
6240 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
6241 </literallayout>
6242 </para>
6243
6244 <para>
6245 The
6246 <link linkend='ref-classes-image'><filename>image</filename></link>
6247 class defines the manifest file as follows:
6248 <literallayout class='monospaced'>
6249 IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"
6250 </literallayout>
6251 The location is derived using the
6252 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
6253 and
6254 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>
6255 variables.
6256 You can find information on how the image
6257 is created in the
Brad Bishop316dfdd2018-06-25 12:45:53 -04006258 "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
6259 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006260 </para>
6261 </glossdef>
6262 </glossentry>
6263
6264 <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
6265 <info>
6266 IMAGE_NAME[doc] = "The name of the output image files minus the extension."
6267 </info>
6268 <glossdef>
6269 <para role="glossdeffirst">
6270<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6271 The name of the output image files minus the extension.
6272 This variable is derived using the
6273 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
6274 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
6275 and
6276 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
6277 variables:
6278 <literallayout class='monospaced'>
6279 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
6280 </literallayout>
6281 </para>
6282 </glossdef>
6283 </glossentry>
6284
6285 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
6286 <info>
6287 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."
6288 </info>
6289 <glossdef>
6290 <para role="glossdeffirst">
6291<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6292 Defines a multiplier that the build system applies to the initial image
6293 size for cases when the multiplier times the returned disk usage value
6294 for the image is greater than the sum of
6295 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
6296 and
6297 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
6298 The result of the multiplier applied to the initial image size creates
6299 free disk space in the image as overhead.
6300 By default, the build process uses a multiplier of 1.3 for this variable.
6301 This default value results in 30% free disk space added to the image when this
6302 method is used to determine the final generated image size.
6303 You should be aware that post install scripts and the package management
6304 system uses disk space inside this overhead area.
6305 Consequently, the multiplier does not produce an image with
6306 all the theoretical free disk space.
6307 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
6308 for information on how the build system determines the overall image size.
6309 </para>
6310
6311 <para>
6312 The default 30% free disk space typically gives the image enough room to boot
6313 and allows for basic post installs while still leaving a small amount of
6314 free disk space.
6315 If 30% free space is inadequate, you can increase the default value.
6316 For example, the following setting gives you 50% free space added to the image:
6317 <literallayout class='monospaced'>
6318 IMAGE_OVERHEAD_FACTOR = "1.5"
6319 </literallayout>
6320 </para>
6321
6322 <para>
6323 Alternatively, you can ensure a specific amount of free disk space is added
6324 to the image by using the
6325 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
6326 variable.
6327 </para>
6328 </glossdef>
6329 </glossentry>
6330
6331 <glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm>
6332 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006333 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 -05006334 </info>
6335 <glossdef>
6336 <para role="glossdeffirst">
6337<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -04006338 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006339 by the OpenEmbedded build system.
6340 The variable is defined appropriately by the
6341 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
6342 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
6343 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
6344 or
6345 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
6346 class.
6347 <note><title>Warning</title>
6348 The <filename>package_tar</filename> class is broken
6349 and is not supported.
6350 It is recommended that you do not use it.
6351 </note>
6352 </para>
6353
6354 <para>
6355 The
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006356 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_*</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006357 and
6358 <link linkend='ref-classes-image'><filename>image</filename></link>
6359 classes use the <filename>IMAGE_PKGTYPE</filename> for
6360 packaging up images and SDKs.
6361 </para>
6362
6363 <para>
6364 You should not set the <filename>IMAGE_PKGTYPE</filename>
6365 manually.
6366 Rather, the variable is set indirectly through the
6367 appropriate
6368 <link linkend='ref-classes-package'><filename>package_*</filename></link>
6369 class using the
6370 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
6371 variable.
6372 The OpenEmbedded build system uses the first package type
6373 (e.g. DEB, RPM, or IPK) that appears with the variable
6374 <note>
6375 Files using the <filename>.tar</filename> format are
6376 never used as a substitute packaging format for DEB,
6377 RPM, and IPK formatted files for your image or SDK.
6378 </note>
6379 </para>
6380 </glossdef>
6381 </glossentry>
6382
6383 <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
6384 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006385 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 -05006386 </info>
6387 <glossdef>
6388 <para role="glossdeffirst">
6389<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6390 Specifies a list of functions to call once the
Brad Bishop316dfdd2018-06-25 12:45:53 -04006391 OpenEmbedded build system creates the final image
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006392 output files.
6393 You can specify functions separated by semicolons:
6394 <literallayout class='monospaced'>
6395 IMAGE_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
6396 </literallayout>
6397 </para>
6398
6399 <para>
6400 If you need to pass the root filesystem path to a command
6401 within the function, you can use
6402 <filename>${IMAGE_ROOTFS}</filename>, which points to
6403 the directory that becomes the root filesystem image.
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006404 See the
6405 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
6406 variable for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006407 </para>
6408 </glossdef>
6409 </glossentry>
6410
6411 <glossentry id='var-IMAGE_PREPROCESS_COMMAND'><glossterm>IMAGE_PREPROCESS_COMMAND</glossterm>
6412 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006413 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 -05006414 </info>
6415 <glossdef>
6416 <para role="glossdeffirst">
6417<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6418 Specifies a list of functions to call before the
Brad Bishop316dfdd2018-06-25 12:45:53 -04006419 OpenEmbedded build system creates the final image
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006420 output files.
6421 You can specify functions separated by semicolons:
6422 <literallayout class='monospaced'>
6423 IMAGE_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
6424 </literallayout>
6425 </para>
6426
6427 <para>
6428 If you need to pass the root filesystem path to a command
6429 within the function, you can use
6430 <filename>${IMAGE_ROOTFS}</filename>, which points to
6431 the directory that becomes the root filesystem image.
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006432 See the
6433 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
6434 variable for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006435 </para>
6436 </glossdef>
6437 </glossentry>
6438
6439 <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
6440 <info>
6441 IMAGE_ROOTFS[doc] = "The location of the root filesystem while it is under construction (i.e. during do_rootfs)."
6442 </info>
6443 <glossdef>
6444 <para role="glossdeffirst">
6445<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6446 The location of the root filesystem while it is under
6447 construction (i.e. during the
6448 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
6449 task).
6450 This variable is not configurable.
6451 Do not change it.
6452 </para>
6453 </glossdef>
6454 </glossentry>
6455
6456 <glossentry id='var-IMAGE_ROOTFS_ALIGNMENT'><glossterm>IMAGE_ROOTFS_ALIGNMENT</glossterm>
6457 <info>
6458 IMAGE_ROOTFS_ALIGNMENT[doc] = "Specifies the alignment for the output image file in Kbytes."
6459 </info>
6460 <glossdef>
6461 <para role="glossdeffirst">
6462<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6463 Specifies the alignment for the output image file in
6464 Kbytes.
6465 If the size of the image is not a multiple of
6466 this value, then the size is rounded up to the nearest
6467 multiple of the value.
6468 The default value is "1".
6469 See
6470 <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
6471 for additional information.
6472 </para>
6473 </glossdef>
6474 </glossentry>
6475
6476 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
6477 <info>
6478 IMAGE_ROOTFS_EXTRA_SPACE[doc] = "Defines additional free disk space created in the image in Kbytes. By default, this variable is set to '0'."
6479 </info>
6480 <glossdef>
6481 <para role="glossdeffirst">
6482<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6483 Defines additional free disk space created in the image in Kbytes.
6484 By default, this variable is set to "0".
6485 This free disk space is added to the image after the build system determines
6486 the image size as described in
6487 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
6488 </para>
6489
6490 <para>
6491 This variable is particularly useful when you want to ensure that a
6492 specific amount of free disk space is available on a device after an image
6493 is installed and running.
6494 For example, to be sure 5 Gbytes of free disk space is available, set the
6495 variable as follows:
6496 <literallayout class='monospaced'>
6497 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
6498 </literallayout>
6499 </para>
6500
6501 <para>
6502 For example, the Yocto Project Build Appliance specifically requests 40 Gbytes
6503 of extra space with the line:
6504 <literallayout class='monospaced'>
6505 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
6506 </literallayout>
6507 </para>
6508 </glossdef>
6509 </glossentry>
6510
6511 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
6512 <info>
6513 IMAGE_ROOTFS_SIZE[doc] = "Defines the size in Kbytes for the generated image."
6514 </info>
6515 <glossdef>
6516 <para role="glossdeffirst">
6517<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6518 Defines the size in Kbytes for the generated image.
6519 The OpenEmbedded build system determines the final size for the generated
6520 image using an algorithm that takes into account the initial disk space used
6521 for the generated image, a requested size for the image, and requested
6522 additional free disk space to be added to the image.
6523 Programatically, the build system determines the final size of the
6524 generated image as follows:
6525 <literallayout class='monospaced'>
6526 if (image-du * overhead) &lt; rootfs-size:
6527 internal-rootfs-size = rootfs-size + xspace
6528 else:
6529 internal-rootfs-size = (image-du * overhead) + xspace
6530
6531 where:
6532
6533 image-du = Returned value of the du command on
6534 the image.
6535
6536 overhead = IMAGE_OVERHEAD_FACTOR
6537
6538 rootfs-size = IMAGE_ROOTFS_SIZE
6539
6540 internal-rootfs-size = Initial root filesystem
6541 size before any modifications.
6542
6543 xspace = IMAGE_ROOTFS_EXTRA_SPACE
6544 </literallayout>
6545 </para>
6546
6547 <para>
6548 See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
6549 and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
6550 variables for related information.
6551<!-- In the above example, <filename>overhead</filename> is defined by the
6552 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
6553 variable, <filename>xspace</filename> is defined by the
6554 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
6555 variable, and <filename>du</filename> is the results of the disk usage command
6556 on the initially generated image. -->
6557 </para>
6558 </glossdef>
6559 </glossentry>
6560
6561 <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm>
6562 <info>
6563 IMAGE_TYPEDEP[doc] = "Specifies a dependency from one image type on another."
6564 </info>
6565 <glossdef>
6566 <para role="glossdeffirst">
6567<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6568 Specifies a dependency from one image type on another.
6569 Here is an example from the
6570 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
6571 class:
6572 <literallayout class='monospaced'>
6573 IMAGE_TYPEDEP_live = "ext3"
6574 </literallayout>
6575 </para>
6576
6577 <para>
6578 In the previous example, the variable ensures that when
6579 "live" is listed with the
6580 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6581 variable, the OpenEmbedded build system produces an
6582 <filename>ext3</filename> image first since one of the
6583 components of the live
6584 image is an <filename>ext3</filename>
6585 formatted partition containing the root
6586 filesystem.
6587 </para>
6588 </glossdef>
6589 </glossentry>
6590
6591 <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
6592 <info>
6593 IMAGE_TYPES[doc] = "Specifies the complete list of supported image types by default."
6594 </info>
6595 <glossdef>
6596 <para role="glossdeffirst">
6597<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6598 Specifies the complete list of supported image types
6599 by default:
6600 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006601 btrfs
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006602 cpio
6603 cpio.gz
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006604 cpio.lz4
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006605 cpio.lzma
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006606 cpio.xz
6607 cramfs
6608 elf
6609 ext2
6610 ext2.bz2
6611 ext2.gz
6612 ext2.lzma
6613 ext3
6614 ext3.gz
6615 ext4
6616 ext4.gz
6617 hdddirect
6618 hddimg
6619 iso
6620 jffs2
6621 jffs2.sum
6622 multiubi
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006623 squashfs
6624 squashfs-lzo
6625 squashfs-xz
6626 tar
6627 tar.bz2
6628 tar.gz
6629 tar.lz4
6630 tar.xz
6631 ubi
6632 ubifs
Patrick Williamsf1e5d692016-03-30 15:21:19 -05006633 wic
6634 wic.bz2
6635 wic.gz
6636 wic.lzma
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006637 </literallayout>
6638 </para>
6639
6640 <para>
6641 For more information about these types of images, see
6642 <filename>meta/classes/image_types*.bbclass</filename>
6643 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006644 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006645 </para>
6646 </glossdef>
6647 </glossentry>
6648
6649 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
6650 <info>
6651 INC_PR[doc] = "Helps define the recipe revision for recipes that share a common include file."
6652 </info>
6653 <glossdef>
6654 <para role="glossdeffirst">
6655<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6656 Helps define the recipe revision for recipes that share
6657 a common <filename>include</filename> file.
6658 You can think of this variable as part of the recipe revision
6659 as set from within an include file.
6660 </para>
6661
6662 <para>
6663 Suppose, for example, you have a set of recipes that
6664 are used across several projects.
6665 And, within each of those recipes the revision
6666 (its <link linkend='var-PR'><filename>PR</filename></link>
6667 value) is set accordingly.
6668 In this case, when the revision of those recipes changes,
6669 the burden is on you to find all those recipes and
6670 be sure that they get changed to reflect the updated
6671 version of the recipe.
6672 In this scenario, it can get complicated when recipes
6673 that are used in many places and provide common functionality
6674 are upgraded to a new revision.
6675 </para>
6676
6677 <para>
6678 A more efficient way of dealing with this situation is
6679 to set the <filename>INC_PR</filename> variable inside
6680 the <filename>include</filename> files that the recipes
6681 share and then expand the <filename>INC_PR</filename>
6682 variable within the recipes to help
6683 define the recipe revision.
6684 </para>
6685
6686 <para>
6687 The following provides an example that shows how to use
6688 the <filename>INC_PR</filename> variable
6689 given a common <filename>include</filename> file that
6690 defines the variable.
6691 Once the variable is defined in the
6692 <filename>include</filename> file, you can use the
6693 variable to set the <filename>PR</filename> values in
6694 each recipe.
6695 You will notice that when you set a recipe's
6696 <filename>PR</filename> you can provide more granular
6697 revisioning by appending values to the
6698 <filename>INC_PR</filename> variable:
6699 <literallayout class='monospaced'>
Brad Bishopb1114e52019-02-13 07:56:10 -05006700 recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
6701 recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
6702 recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
6703 recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006704 </literallayout>
6705 The first line of the example establishes the baseline
6706 revision to be used for all recipes that use the
6707 <filename>include</filename> file.
6708 The remaining lines in the example are from individual
6709 recipes and show how the <filename>PR</filename> value
6710 is set.
6711 </para>
6712 </glossdef>
6713 </glossentry>
6714
6715 <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
6716 <info>
6717 INCOMPATIBLE_LICENSE[doc] = "Specifies a space-separated list of license names (as they would appear in LICENSE) that should be excluded from the build."
6718 </info>
6719 <glossdef>
6720 <para role="glossdeffirst">
6721<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6722 Specifies a space-separated list of license names
6723 (as they would appear in
6724 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
6725 that should be excluded from the build.
6726 Recipes that provide no alternatives to listed incompatible
6727 licenses are not built.
6728 Packages that are individually licensed with the specified
6729 incompatible licenses will be deleted.
6730 </para>
6731
6732 <note>
6733 This functionality is only regularly tested using
6734 the following setting:
6735 <literallayout class='monospaced'>
6736 INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
6737 </literallayout>
6738 Although you can use other settings, you might be required
6739 to remove dependencies on or provide alternatives to
6740 components that are required to produce a functional system
6741 image.
6742 </note>
6743 </glossdef>
6744 </glossentry>
6745
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006746 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
6747 <info>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05006748 INHERIT[doc] = "Causes the named class or classes to be inherited globally."
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006749 </info>
6750 <glossdef>
6751 <para role="glossdeffirst">
6752<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop6e60e8b2018-02-01 10:27:11 -05006753 Causes the named class or classes to be inherited globally.
6754 Anonymous functions in the class or classes
6755 are not executed for the
6756 base configuration and in each individual recipe.
6757 The OpenEmbedded build system ignores changes to
6758 <filename>INHERIT</filename> in individual recipes.
6759 </para>
6760
6761 <para>
6762 For more information on <filename>INHERIT</filename>, see
6763 the
6764 "<ulink url="&YOCTO_DOCS_BB_URL;#inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -04006765 section in the Bitbake User Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05006766 </para>
6767 </glossdef>
6768 </glossentry>
6769
6770 <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm>
6771 <info>
6772 INHERIT_DISTRO[doc] = "Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable."
6773 </info>
6774 <glossdef>
6775 <para role="glossdeffirst">
6776<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6777 Lists classes that will be inherited at the
6778 distribution level.
6779 It is unlikely that you want to edit this variable.
6780 </para>
6781
6782 <para>
6783 The default value of the variable is set as follows in the
6784 <filename>meta/conf/distro/defaultsetup.conf</filename>
6785 file:
6786 <literallayout class='monospaced'>
6787 INHERIT_DISTRO ?= "debian devshell sstate license"
6788 </literallayout>
6789 </para>
6790 </glossdef>
6791 </glossentry>
6792
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006793 <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
6794 <info>
6795 INHIBIT_DEFAULT_DEPS[doc] = "Prevents the default dependencies, namely the C compiler and standard C library (libc), from being added to DEPENDS."
6796 </info>
6797 <glossdef>
6798 <para role="glossdeffirst">
6799<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6800 Prevents the default dependencies, namely the C compiler
6801 and standard C library (libc), from being added to
6802 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
6803 This variable is usually used within recipes that do not
6804 require any compilation using the C compiler.
6805 </para>
6806
6807 <para>
6808 Set the variable to "1" to prevent the default dependencies
6809 from being added.
6810 </para>
6811 </glossdef>
6812 </glossentry>
6813
6814 <glossentry id='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><glossterm>INHIBIT_PACKAGE_DEBUG_SPLIT</glossterm>
6815 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006816 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 -05006817 </info>
6818 <glossdef>
6819 <para role="glossdeffirst">
6820<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6821 Prevents the OpenEmbedded build system from splitting
6822 out debug information during packaging.
6823 By default, the build system splits out debugging
6824 information during the
6825 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
6826 task.
6827 For more information on how debug information is split out,
6828 see the
6829 <link linkend='var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></link>
6830 variable.
6831 </para>
6832
6833 <para>
6834 To prevent the build system from splitting out
6835 debug information during packaging, set the
6836 <filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename> variable
6837 as follows:
6838 <literallayout class='monospaced'>
6839 INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
6840 </literallayout>
6841 </para>
6842 </glossdef>
6843 </glossentry>
6844
6845 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
6846 <info>
6847 INHIBIT_PACKAGE_STRIP[doc] = "If set to "1", causes the build to not strip binaries in resulting packages."
6848 </info>
6849 <glossdef>
6850 <para role="glossdeffirst">
6851<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006852 If set to "1", causes the build to not strip binaries in
6853 resulting packages and prevents the
6854 <filename>-dbg</filename> package from containing the
6855 source files.
6856 </para>
6857
6858 <para>
6859 By default, the OpenEmbedded build system strips
6860 binaries and puts the debugging symbols into
6861 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-dbg</filename>.
6862 Consequently, you should not set
6863 <filename>INHIBIT_PACKAGE_STRIP</filename> when you plan
6864 to debug in general.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006865 </para>
6866 </glossdef>
6867 </glossentry>
6868
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006869 <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
6870 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006871 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 -05006872 </info>
6873 <glossdef>
6874 <para role="glossdeffirst">
6875<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6876 Defines the format for the output image of an initial
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006877 RAM filesystem (initramfs), which is used during boot.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006878 Supported formats are the same as those supported by the
6879 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6880 variable.
6881 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006882
6883 <para>
6884 The default value of this variable, which is set in the
6885 <filename>meta/conf/bitbake.conf</filename> configuration
6886 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006887 <link linkend='source-directory'>Source Directory</link>,
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006888 is "cpio.gz".
6889 The Linux kernel's initramfs mechanism, as opposed to the
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006890 initial RAM filesystem
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006891 <ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink>
6892 mechanism, expects an optionally compressed cpio
6893 archive.
6894 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006895 </glossdef>
6896 </glossentry>
6897
6898 <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>
6899 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006900 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 -05006901 </info>
6902 <glossdef>
6903 <para role="glossdeffirst">
6904<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006905 Specifies the
6906 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
6907 name of an image recipe that is used to build an initial
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006908 RAM filesystem (initramfs) image.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006909 In other words, the <filename>INITRAMFS_IMAGE</filename>
6910 variable causes an additional recipe to be built as
6911 a dependency to whatever root filesystem recipe you
6912 might be using (e.g. <filename>core-image-sato</filename>).
6913 The initramfs image recipe you provide should set
6914 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6915 to
6916 <link linkend='var-INITRAMFS_FSTYPES'><filename>INITRAMFS_FSTYPES</filename></link>.
6917 </para>
6918
6919 <para>
6920 An initramfs image provides a temporary root filesystem
6921 used for early system initialization (e.g. loading of
6922 modules needed to locate and mount the "real" root
6923 filesystem).
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006924 <note>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006925 See the <filename>meta/recipes-core/images/core-image-minimal-initramfs.bb</filename>
6926 recipe in the
6927 <link linkend='source-directory'>Source Directory</link>
6928 for an example initramfs recipe.
6929 To select this sample recipe as the one built
6930 to provide the initramfs image,
6931 set <filename>INITRAMFS_IMAGE</filename> to
6932 "core-image-minimal-initramfs".
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006933 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006934 </para>
6935
6936 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006937 You can also find more information by referencing the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006938 <filename>meta-poky/conf/local.conf.sample.extended</filename>
Brad Bishop316dfdd2018-06-25 12:45:53 -04006939 configuration file in the Source Directory,
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006940 the
6941 <link linkend='ref-classes-image'><filename>image</filename></link>
6942 class, and the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006943 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006944 class to see how to use the
6945 <filename>INITRAMFS_IMAGE</filename> variable.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006946 </para>
6947
6948 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006949 If <filename>INITRAMFS_IMAGE</filename> is empty, which is
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006950 the default, then no initramfs image is built.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006951 </para>
6952
6953 <para>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006954 For more information, you can also see the
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006955 <link linkend='var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></link>
6956 variable, which allows the generated image to be bundled
6957 inside the kernel image.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006958 Additionally, for information on creating an initramfs
6959 image, see the
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006960 "<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 -05006961 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006962 </para>
6963 </glossdef>
6964 </glossentry>
6965
6966 <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
6967 <info>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006968 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 -05006969 </info>
6970 <glossdef>
6971 <para role="glossdeffirst">
6972<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
6973 Controls whether or not the image recipe specified by
6974 <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006975 is run through an extra pass
6976 (<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>)
6977 during kernel compilation in order to build a single binary
Brad Bishop37a0e4d2017-12-04 01:01:44 -05006978 that contains both the kernel image and the initial RAM
6979 filesystem (initramfs) image.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06006980 This makes use of the
6981 <link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link>
6982 kernel feature.
6983 <note>
6984 Using an extra compilation pass to bundle the initramfs
6985 avoids a circular dependency between the kernel recipe and
6986 the initramfs recipe should the initramfs include kernel
6987 modules.
6988 Should that be the case, the initramfs recipe depends on
6989 the kernel for the kernel modules, and the kernel depends
6990 on the initramfs recipe since the initramfs is bundled
6991 inside the kernel image.
6992 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05006993 </para>
6994
6995 <para>
6996 The combined binary is deposited into the
6997 <filename>tmp/deploy</filename> directory, which is part
6998 of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05006999 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007000 </para>
7001
7002 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007003 Setting the variable to "1" in a configuration file causes the
7004 OpenEmbedded build system to generate a kernel image with the
Brad Bishop316dfdd2018-06-25 12:45:53 -04007005 initramfs specified in <filename>INITRAMFS_IMAGE</filename>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007006 bundled within:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007007 <literallayout class='monospaced'>
7008 INITRAMFS_IMAGE_BUNDLE = "1"
7009 </literallayout>
7010 By default, the
7011 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
7012 class sets this variable to a null string as follows:
7013 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06007014 INITRAMFS_IMAGE_BUNDLE ?= ""
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007015 </literallayout>
7016 <note>
7017 You must set the
7018 <filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in
7019 a configuration file.
7020 You cannot set the variable in a recipe file.
7021 </note>
7022 See the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05007023 <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 -05007024 file for additional information.
Brad Bishop37a0e4d2017-12-04 01:01:44 -05007025 Also, for information on creating an initramfs, see the
7026 "<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 -05007027 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007028 </para>
7029 </glossdef>
7030 </glossentry>
7031
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007032 <glossentry id='var-INITRAMFS_LINK_NAME'><glossterm>INITRAMFS_LINK_NAME</glossterm>
7033 <info>
7034 INITRAMFS_LINK_NAME[doc] = "The link name of the initial RAM filesystem image."
7035 </info>
7036 <glossdef>
7037 <para role="glossdeffirst">
7038<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7039 The link name of the initial RAM filesystem image.
7040 This variable is set in the
7041 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7042 file as follows:
7043 <literallayout class='monospaced'>
7044 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"
7045 </literallayout>
7046 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7047 variable, which is set in the same file, has the following
7048 value:
7049 <literallayout class='monospaced'>
7050 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7051 </literallayout>
7052 </para>
7053
7054 <para>
7055 See the
7056 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7057 variable for additional information.
7058 </para>
7059 </glossdef>
7060 </glossentry>
7061
7062 <glossentry id='var-INITRAMFS_NAME'><glossterm>INITRAMFS_NAME</glossterm>
7063 <info>
7064 INITRAMFS_NAME[doc] = "The base name of the initial RAM filesystem image."
7065 </info>
7066 <glossdef>
7067 <para role="glossdeffirst">
7068<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7069 The base name of the initial RAM filesystem image.
7070 This variable is set in the
7071 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7072 file as follows:
7073 <literallayout class='monospaced'>
7074 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"
7075 </literallayout>
7076 The value of the
7077 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7078 variable, which is set in the same file, has the following
7079 value:
7080 <literallayout class='monospaced'>
7081 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7082 </literallayout>
7083 </para>
7084 </glossdef>
7085 </glossentry>
7086
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007087 <glossentry id='var-INITRD'><glossterm>INITRD</glossterm>
7088 <info>
7089 INITRD[doc] = "Indicates a list of filesystem images to concatenate and use as an initial RAM disk (initrd)."
7090 </info>
7091 <glossdef>
7092 <para role="glossdeffirst">
7093<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7094 Indicates list of filesystem images to concatenate and use
7095 as an initial RAM disk (<filename>initrd</filename>).
7096 </para>
7097
7098 <para>
7099 The <filename>INITRD</filename> variable is an optional
7100 variable used with the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05007101 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007102 class.
7103 </para>
7104 </glossdef>
7105 </glossentry>
7106
7107 <glossentry id='var-INITRD_IMAGE'><glossterm>INITRD_IMAGE</glossterm>
7108 <info>
7109 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."
7110 </info>
7111 <glossdef>
7112 <para role="glossdeffirst">
7113<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7114 When building a "live" bootable image (i.e. when
7115 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
7116 contains "live"), <filename>INITRD_IMAGE</filename>
7117 specifies the image recipe that should be built
7118 to provide the initial RAM disk image.
7119 The default value is "core-image-minimal-initramfs".
7120 </para>
7121
7122 <para>
7123 See the
7124 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
7125 class for more information.
7126 </para>
7127 </glossdef>
7128 </glossentry>
7129
7130 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
7131 <info>
7132 INITSCRIPT_NAME[doc] = "The filename of the initialization script as installed to ${sysconfdir}/init.d."
7133 </info>
7134 <glossdef>
7135 <para role="glossdeffirst">
7136<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7137 The filename of the initialization script as installed to
7138 <filename>${sysconfdir}/init.d</filename>.
7139 </para>
7140
7141 <para>
7142 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
7143 The variable is mandatory.
7144 </para>
7145 </glossdef>
7146 </glossentry>
7147
7148 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
7149 <info>
7150 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."
7151 </info>
7152 <glossdef>
7153 <para role="glossdeffirst">
7154<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7155 A list of the packages that contain initscripts.
7156 If multiple packages are specified, you need to append the package name
7157 to the other <filename>INITSCRIPT_*</filename> as an override.
7158 </para>
7159
7160 <para>
7161 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
7162 The variable is optional and defaults to the
7163 <link linkend='var-PN'><filename>PN</filename></link> variable.
7164 </para>
7165 </glossdef>
7166 </glossentry>
7167
7168 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
7169 <info>
7170 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."
7171 </info>
7172 <glossdef>
7173 <para role="glossdeffirst">
7174<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7175 Specifies the options to pass to <filename>update-rc.d</filename>.
7176 Here is an example:
7177 <literallayout class='monospaced'>
7178 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
7179 </literallayout>
7180 </para>
7181
7182 <para>
7183 In this example, the script has a runlevel of 99,
7184 starts the script in initlevels 2 and 5, and
7185 stops the script in levels 0, 1 and 6.
7186 </para>
7187
7188 <para>
7189 The variable's default value is "defaults", which is
7190 set in the
7191 <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
7192 class.
7193 </para>
7194
7195 <para>
7196 The value in
7197 <filename>INITSCRIPT_PARAMS</filename> is passed through
7198 to the <filename>update-rc.d</filename> command.
7199 For more information on valid parameters, please see the
7200 <filename>update-rc.d</filename> manual page at
7201 <ulink url='http://www.tin.org/bin/man.cgi?section=8&amp;topic=update-rc.d'></ulink>.
7202 </para>
7203 </glossdef>
7204 </glossentry>
7205
7206 <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
7207 <info>
7208 INSANE_SKIP[doc] = "Specifies the QA checks to skip for a specific package within a recipe."
7209 </info>
7210 <glossdef>
7211 <para role="glossdeffirst">
7212<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7213 Specifies the QA checks to skip for a specific package
7214 within a recipe.
7215 For example, to skip the check for symbolic link
7216 <filename>.so</filename> files in the main package of a
7217 recipe, add the following to the recipe.
7218 The package name override must be used, which in this
7219 example is <filename>${PN}</filename>:
7220 <literallayout class='monospaced'>
7221 INSANE_SKIP_${PN} += "dev-so"
7222 </literallayout>
7223 </para>
7224
7225 <para>
7226 See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
7227 section for a list of the valid QA checks you can
7228 specify using this variable.
7229 </para>
7230 </glossdef>
7231 </glossentry>
7232
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05007233 <glossentry id='var-INSTALL_TIMEZONE_FILE'><glossterm>INSTALL_TIMEZONE_FILE</glossterm>
7234 <info>
7235 INSTALL_TIMEZONE_FILE[doc] = "Enables installation of the /etc/timezone file."
7236 </info>
7237 <glossdef>
7238 <para role="glossdeffirst">
7239<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7240 By default, the <filename>tzdata</filename> recipe packages
7241 an <filename>/etc/timezone</filename> file.
7242 Set the <filename>INSTALL_TIMEZONE_FILE</filename>
7243 variable to "0" at the configuration level to disable this
7244 behavior.
7245 </para>
7246 </glossdef>
7247 </glossentry>
7248
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007249 <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
7250 <info>
7251 IPK_FEED_URIS[doc] = "List of ipkg feed records to put into generated image."
7252 </info>
7253 <glossdef>
7254 <para role="glossdeffirst">
7255<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7256 When the IPK backend is in use and package management
7257 is enabled on the target, you can use this variable to
7258 set up <filename>opkg</filename> in the target image
7259 to point to package feeds on a nominated server.
7260 Once the feed is established, you can perform
7261 installations or upgrades using the package manager
7262 at runtime.
7263 </para>
7264 </glossdef>
7265 </glossentry>
7266
7267<!--
7268 <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
7269 <glossdef>
7270 <para>
7271 An environment variable that defines the directory where
7272 post installation hooks are installed for the
7273 post install environment.
7274 This variable is fixed as follows:
7275 <literallayout class='monospaced'>
7276 ${WORKDIR}/intercept_scripts
7277 </literallayout>
7278 </para>
7279
7280 <para>
7281 After installation of a target's root filesystem,
7282 post installation scripts, which are essentially bash scripts,
7283 are all executed just a single time.
7284 Limiting execution of these scripts minimizes installation
7285 time that would be lengthened due to certain packages
7286 triggering redundant operations.
7287 For example, consider the installation of font packages
7288 as a common example.
7289 Without limiting the execution of post installation scripts,
7290 all font directories would be rescanned to create the
7291 cache after each individual font package was installed.
7292 </para>
7293
7294 <para>
7295 Do not edit the <filename>INTERCEPT_DIR</filename>
7296 variable.
7297 </para>
7298 </glossdef>
7299 </glossentry>
7300-->
7301
7302 </glossdiv>
7303
7304<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
7305<!-- </glossdiv>-->
7306
7307 <glossdiv id='var-glossary-k'><title>K</title>
7308
7309 <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
7310 <info>
7311 KARCH[doc] = "Defines the kernel architecture used when assembling the configuration. You define the KARCH variable in the BSP Descriptions."
7312 </info>
7313 <glossdef>
7314 <para role="glossdeffirst">
7315<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7316 Defines the kernel architecture used when assembling
7317 the configuration.
7318 Architectures supported for this release are:
7319 <literallayout class='monospaced'>
7320 powerpc
7321 i386
7322 x86_64
7323 arm
7324 qemu
7325 mips
7326 </literallayout>
7327 </para>
7328
7329 <para>
7330 You define the <filename>KARCH</filename> variable in the
7331 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
7332 </para>
7333 </glossdef>
7334 </glossentry>
7335
7336 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
7337 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04007338 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 -05007339 </info>
7340 <glossdef>
7341 <para role="glossdeffirst">
7342<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7343 A regular expression used by the build process to explicitly
7344 identify the kernel branch that is validated, patched,
7345 and configured during a build.
7346 You must set this variable to ensure the exact kernel
7347 branch you want is being used by the build process.
7348 </para>
7349
7350 <para>
7351 Values for this variable are set in the kernel's recipe
7352 file and the kernel's append file.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007353 For example, if you are using the
7354 <filename>linux-yocto_4.12</filename> kernel, the kernel
7355 recipe file is the
7356 <filename>meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007357 file.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007358 <filename>KBRANCH</filename> is set as follows in that
7359 kernel recipe file:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007360 <literallayout class='monospaced'>
7361 KBRANCH ?= "standard/base"
7362 </literallayout>
7363 </para>
7364
7365 <para>
7366 This variable is also used from the kernel's append file
7367 to identify the kernel branch specific to a particular
7368 machine or target hardware.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007369 Continuing with the previous kernel example, the kernel's
7370 append file (i.e.
7371 <filename>linux-yocto_4.12.bbappend</filename>) is located
7372 in the BSP layer for a given machine.
7373 For example, the append file for the Beaglebone,
7374 EdgeRouter, and generic versions of both 32 and 64-bit IA
7375 machines (<filename>meta-yocto-bsp</filename>) is named
7376 <filename>meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend</filename>.
7377 Here are the related statements from that append file:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007378 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007379 KBRANCH_genericx86 = "standard/base"
7380 KBRANCH_genericx86-64 = "standard/base"
7381 KBRANCH_edgerouter = "standard/edgerouter"
7382 KBRANCH_beaglebone = "standard/beaglebone"
7383 KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007384 </literallayout>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007385 The <filename>KBRANCH</filename> statements identify
7386 the kernel branch to use when building for each
7387 supported BSP.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007388 </para>
7389 </glossdef>
7390 </glossentry>
7391
7392 <glossentry id='var-KBUILD_DEFCONFIG'><glossterm>KBUILD_DEFCONFIG</glossterm>
7393 <info>
7394 KBUILD_DEFCONFIG[doc] = "Specifies an "in-tree" kernel configuration file for use during a kernel build."
7395 </info>
7396 <glossdef>
7397 <para role="glossdeffirst">
7398<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7399 When used with the
7400 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
7401 class, specifies an "in-tree" kernel configuration file
7402 for use during a kernel build.
7403 </para>
7404
7405 <para>
7406 Typically, when using a <filename>defconfig</filename> to
7407 configure a kernel during a build, you place the
7408 file in your layer in the same manner as you would
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007409 place patch files and configuration fragment files (i.e.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007410 "out-of-tree").
7411 However, if you want to use a <filename>defconfig</filename>
7412 file that is part of the kernel tree (i.e. "in-tree"),
7413 you can use the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007414 <filename>KBUILD_DEFCONFIG</filename> variable and append
7415 the
7416 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
7417 variable to point to the <filename>defconfig</filename>
7418 file.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007419 </para>
7420
7421 <para>
7422 To use the variable, set it in the append file for your
7423 kernel recipe using the following form:
7424 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007425 KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007426 </literallayout>
7427 Here is an example from a "raspberrypi2"
7428 <filename>KMACHINE</filename> build that uses a
7429 <filename>defconfig</filename> file named
7430 "bcm2709_defconfig":
7431 <literallayout class='monospaced'>
7432 KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig"
7433 </literallayout>
7434 As an alternative, you can use the following within your
7435 append file:
7436 <literallayout class='monospaced'>
7437 KBUILD_DEFCONFIG_pn-linux-yocto ?= <replaceable>defconfig_file</replaceable>
7438 </literallayout>
7439 For more information on how to use the
7440 <filename>KBUILD_DEFCONFIG</filename> variable, see the
7441 "<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 -04007442 section in the Yocto Project Linux Kernel Development
7443 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007444 </para>
7445 </glossdef>
7446 </glossentry>
7447
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007448 <glossentry id='var-KERNEL_ALT_IMAGETYPE'><glossterm>KERNEL_ALT_IMAGETYPE</glossterm>
7449 <info>
7450 KERNEL_ALT_IMAGETYPE[doc] = "Specifies an alternate kernel image type for creation."
7451 </info>
7452 <glossdef>
7453 <para role="glossdeffirst">
7454<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7455 Specifies an alternate kernel image type for creation in
7456 addition to the kernel image type specified using the
7457 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
7458 variable.
7459 </para>
7460 </glossdef>
7461 </glossentry>
7462
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007463 <glossentry id='var-KERNEL_ARTIFACT_NAME'><glossterm>KERNEL_ARTIFACT_NAME</glossterm>
7464 <info>
7465 KERNEL_ARTIFACT_NAME[doc] = "Specifies the name of all of the build artifacts."
7466 </info>
7467 <glossdef>
7468 <para role="glossdeffirst">
7469<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7470 Specifies the name of all of the build artifacts.
7471 You can change the name of the artifacts by changing the
7472 <filename>KERNEL_ARTIFACT_NAME</filename> variable.
7473 </para>
7474
7475 <para>
7476 The value of <filename>KERNEL_ARTIFACT_NAME</filename>,
7477 which is set in the
7478 <filename> meta/classes/kernel-artifact-names.bbclass</filename>
7479 file, has the following default value:
7480 <literallayout class='monospaced'>
7481 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7482 </literallayout>
7483 </para>
7484
7485 <para>
7486 See the
7487 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
7488 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
7489 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
7490 and
7491 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7492 variables for additional information.
7493 <note>
7494 The <filename>IMAGE_VERSION_SUFFIX</filename> variable
7495 is set to
7496 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>.
7497 </note>
7498 </para>
7499 </glossdef>
7500 </glossentry>
7501
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007502 <glossentry id='var-KERNEL_CLASSES'><glossterm>KERNEL_CLASSES</glossterm>
7503 <info>
7504 KERNEL_CLASSES[doc] = "A list of classes defining kernel image types that kernel class should inherit."
7505 </info>
7506 <glossdef>
7507 <para role="glossdeffirst">
7508<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7509 A list of classes defining kernel image types that the
7510 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
7511 class should inherit.
7512 You typically append this variable to enable extended image
7513 types.
7514 An example is the "kernel-fitimage", which enables
7515 fitImage support and resides in
7516 <filename>meta/classes/kernel-fitimage.bbclass</filename>.
7517 You can register custom kernel image types with the
7518 <filename>kernel</filename> class using this variable.
7519 </para>
7520 </glossdef>
7521 </glossentry>
7522
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007523 <glossentry id='var-KERNEL_DEVICETREE'><glossterm>KERNEL_DEVICETREE</glossterm>
7524 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04007525 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 -05007526 </info>
7527 <glossdef>
7528 <para role="glossdeffirst">
7529<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7530 Specifies the name of the generated Linux kernel device tree
7531 (i.e. the <filename>.dtb</filename>) file.
7532 <note>
7533 Legacy support exists for specifying the full path
7534 to the device tree.
7535 However, providing just the <filename>.dtb</filename>
7536 file is preferred.
7537 </note>
7538 In order to use this variable, you must have the include
7539 files in your kernel recipe:
7540 <literallayout class='monospaced'>
7541 require recipes-kernel/linux/linux-dtb.inc
7542 </literallayout>
7543 or
7544 <literallayout class='monospaced'>
7545 require recipes-kernel/linux/linux-yocto.inc
7546 </literallayout>
7547 </para>
7548 </glossdef>
7549 </glossentry>
7550
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007551 <glossentry id='var-KERNEL_DTB_LINK_NAME'><glossterm>KERNEL_DTB_LINK_NAME</glossterm>
7552 <info>
7553 KERNEL_DTB_LINK_NAME[doc] = "The link name of the kernel device tree binary (DTB)."
7554 </info>
7555 <glossdef>
7556 <para role="glossdeffirst">
7557<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7558 The link name of the kernel device tree binary (DTB).
7559 This variable is set in the
7560 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7561 file as follows:
7562 <literallayout class='monospaced'>
7563 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7564 </literallayout>
7565 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7566 variable, which is set in the same file, has the following
7567 value:
7568 <literallayout class='monospaced'>
7569 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7570 </literallayout>
7571 </para>
7572
7573 <para>
7574 See the
7575 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7576 variable for additional information.
7577 </para>
7578 </glossdef>
7579 </glossentry>
7580
7581 <glossentry id='var-KERNEL_DTB_NAME'><glossterm>KERNEL_DTB_NAME</glossterm>
7582 <info>
7583 KERNEL_DTB_NAME[doc] = "The base name of the kernel device tree binary (DTB)."
7584 </info>
7585 <glossdef>
7586 <para role="glossdeffirst">
7587<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7588 The base name of the kernel device tree binary (DTB).
7589 This variable is set in the
7590 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7591 file as follows:
7592 <literallayout class='monospaced'>
7593 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7594 </literallayout>
7595 The value of the
7596 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7597 variable, which is set in the same file, has the following
7598 value:
7599 <literallayout class='monospaced'>
7600 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7601 </literallayout>
7602 </para>
7603 </glossdef>
7604 </glossentry>
7605
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007606 <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
7607 <info>
7608 KERNEL_EXTRA_ARGS[doc] = "Specifies additional make command-line arguments the OpenEmbedded build system passes on when compiling the kernel."
7609 </info>
7610 <glossdef>
7611 <para role="glossdeffirst">
7612<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7613 Specifies additional <filename>make</filename>
7614 command-line arguments the OpenEmbedded build system
7615 passes on when compiling the kernel.
7616 </para>
7617 </glossdef>
7618 </glossentry>
7619
7620 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
7621 <info>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007622 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 -05007623 </info>
7624 <glossdef>
7625 <para role="glossdeffirst">
7626<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007627 Includes additional kernel metadata.
7628 In the OpenEmbedded build system, the default Board Support
7629 Packages (BSPs)
7630 <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007631 is provided through
7632 the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007633 and
7634 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>
7635 variables.
7636 You can use the <filename>KERNEL_FEATURES</filename>
7637 variable from within the kernel recipe or kernel append
7638 file to further add metadata for all BSPs or specific
7639 BSPs.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007640 </para>
7641
7642 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007643 The metadata you add through this variable includes config
7644 fragments and features descriptions,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007645 which usually includes patches as well as config fragments.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007646 You typically override the
7647 <filename>KERNEL_FEATURES</filename> variable for a
7648 specific machine.
7649 In this way, you can provide validated, but optional,
7650 sets of kernel configurations and features.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007651 </para>
7652
7653 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007654 For example, the following example from the
7655 <filename>linux-yocto-rt_4.12</filename> kernel recipe
7656 adds "netfilter" and "taskstats" features to all BSPs
7657 as well as "virtio" configurations to all QEMU machines.
7658 The last two statements add specific configurations to
7659 targeted machine types:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007660 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05007661 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
7662 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007663 KERNEL_FEATURES_append_qemuall = " cfg/virtio.scc"
7664 KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"
7665 KERNEL_FEATURES_append_qemux86-64 = " cfg/sound.scc" </literallayout></para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007666 </glossdef>
7667 </glossentry>
7668
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007669 <glossentry id='var-KERNEL_FIT_LINK_NAME'><glossterm>KERNEL_FIT_LINK_NAME</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007670 <info>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007671 KERNEL_FIT_LINK_NAME[doc] = "The link name of the kernel flattened image tree (FIT) image."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007672 </info>
7673 <glossdef>
7674 <para role="glossdeffirst">
7675<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007676 The link name of the kernel flattened image tree (FIT) image.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007677 This variable is set in the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007678 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7679 file as follows:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007680 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007681 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7682 </literallayout>
7683 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7684 variable, which is set in the same file, has the following
7685 value:
7686 <literallayout class='monospaced'>
7687 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007688 </literallayout>
7689 </para>
7690
7691 <para>
7692 See the
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007693 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7694 variable for additional information.
7695 </para>
7696 </glossdef>
7697 </glossentry>
7698
7699 <glossentry id='var-KERNEL_FIT_NAME'><glossterm>KERNEL_FIT_NAME</glossterm>
7700 <info>
7701 KERNEL_FIT_NAME[doc] = "The base name of the kernel flattened image tree (FIT) image."
7702 </info>
7703 <glossdef>
7704 <para role="glossdeffirst">
7705<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7706 The base name of the kernel flattened image tree (FIT) image.
7707 This variable is set in the
7708 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7709 file as follows:
7710 <literallayout class='monospaced'>
7711 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7712 </literallayout>
7713 The value of the
7714 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7715 variable, which is set in the same file, has the following
7716 value:
7717 <literallayout class='monospaced'>
7718 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7719 </literallayout>
7720 </para>
7721 </glossdef>
7722 </glossentry>
7723
7724 <glossentry id='var-KERNEL_IMAGE_LINK_NAME'><glossterm>KERNEL_IMAGE_LINK_NAME</glossterm>
7725 <info>
7726 KERNEL_IMAGE_LINK_NAME[doc] = "The link name for the kernel image."
7727 </info>
7728 <glossdef>
7729 <para role="glossdeffirst">
7730<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7731 The link name for the kernel image.
7732 This variable is set in the
7733 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7734 file as follows:
7735 <literallayout class='monospaced'>
7736 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7737 </literallayout>
7738 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7739 variable, which is set in the same file, has the following
7740 value:
7741 <literallayout class='monospaced'>
7742 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7743 </literallayout>
7744 </para>
7745
7746 <para>
7747 See the
7748 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7749 variable for additional information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007750 </para>
7751 </glossdef>
7752 </glossentry>
7753
7754 <glossentry id='var-KERNEL_IMAGE_MAXSIZE'><glossterm>KERNEL_IMAGE_MAXSIZE</glossterm>
7755 <info>
7756 KERNEL_IMAGE_MAXSIZE[doc] = "The maximum allowable size in kilobytes of the kernel image file."
7757 </info>
7758 <glossdef>
7759 <para role="glossdeffirst">
7760<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7761 Specifies the maximum size of the kernel image file in
7762 kilobytes.
7763 If <filename>KERNEL_IMAGE_MAXSIZE</filename> is set,
7764 the size of the kernel image file is checked against
7765 the set value during the
7766 <link linkend='ref-tasks-sizecheck'><filename>do_sizecheck</filename></link>
7767 task.
7768 The task fails if the kernel image file is larger than
7769 the setting.
7770 </para>
7771
7772 <para>
7773 <filename>KERNEL_IMAGE_MAXSIZE</filename> is useful for
7774 target devices that have a limited amount of space in
7775 which the kernel image must be stored.
7776 </para>
7777
7778 <para>
7779 By default, this variable is not set, which means the
7780 size of the kernel image is not checked.
7781 </para>
7782 </glossdef>
7783 </glossentry>
7784
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08007785 <glossentry id='var-KERNEL_IMAGE_NAME'><glossterm>KERNEL_IMAGE_NAME</glossterm>
7786 <info>
7787 KERNEL_IMAGE_NAME[doc] = "The base name of the kernel image."
7788 </info>
7789 <glossdef>
7790 <para role="glossdeffirst">
7791<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7792 The base name of the kernel image.
7793 This variable is set in the
7794 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7795 file as follows:
7796 <literallayout class='monospaced'>
7797 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7798 </literallayout>
7799 The value of the
7800 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7801 variable, which is set in the same file, has the following
7802 value:
7803 <literallayout class='monospaced'>
7804 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7805 </literallayout>
7806 </para>
7807 </glossdef>
7808 </glossentry>
7809
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007810 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
7811 <info>
7812 KERNEL_IMAGETYPE[doc] = "The type of kernel to build for a device, usually set by the machine configuration files and defaults to 'zImage'."
7813 </info>
7814 <glossdef>
7815 <para role="glossdeffirst">
7816<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7817 The type of kernel to build for a device, usually set by the
7818 machine configuration files and defaults to "zImage".
7819 This variable is used
7820 when building the kernel and is passed to <filename>make</filename> as the target to
7821 build.
7822 </para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007823
7824 <para>
7825 If you want to build an alternate kernel image type, use the
7826 <link linkend='var-KERNEL_ALT_IMAGETYPE'><filename>KERNEL_ALT_IMAGETYPE</filename></link>
7827 variable.
7828 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007829 </glossdef>
7830 </glossentry>
7831
7832 <glossentry id='var-KERNEL_MODULE_AUTOLOAD'><glossterm>KERNEL_MODULE_AUTOLOAD</glossterm>
7833 <info>
7834 KERNEL_MODULE_AUTOLOAD[doc] = "Lists kernel modules that need to be auto-loaded during boot"
7835 </info>
7836 <glossdef>
7837 <para role="glossdeffirst">
7838<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7839 Lists kernel modules that need to be auto-loaded during
7840 boot.
7841 <note>
7842 This variable replaces the deprecated
7843 <link linkend='var-module_autoload'><filename>module_autoload</filename></link>
7844 variable.
7845 </note>
7846 </para>
7847
7848 <para>
7849 You can use the <filename>KERNEL_MODULE_AUTOLOAD</filename>
7850 variable anywhere that it can be
7851 recognized by the kernel recipe or by an out-of-tree kernel
7852 module recipe (e.g. a machine configuration file, a
7853 distribution configuration file, an append file for the
7854 recipe, or the recipe itself).
7855 </para>
7856
7857 <para>
7858 Specify it as follows:
7859 <literallayout class='monospaced'>
7860 KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name1</replaceable> <replaceable>module_name2</replaceable> <replaceable>module_name3</replaceable>"
7861 </literallayout>
7862 </para>
7863
7864 <para>
7865 Including <filename>KERNEL_MODULE_AUTOLOAD</filename> causes
7866 the OpenEmbedded build system to populate the
7867 <filename>/etc/modules-load.d/modname.conf</filename>
7868 file with the list of modules to be auto-loaded on boot.
7869 The modules appear one-per-line in the file.
7870 Here is an example of the most common use case:
7871 <literallayout class='monospaced'>
7872 KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name</replaceable>"
7873 </literallayout>
7874 </para>
7875
7876 <para>
7877 For information on how to populate the
7878 <filename>modname.conf</filename> file with
7879 <filename>modprobe.d</filename> syntax lines, see the
7880 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
7881 variable.
7882 </para>
7883 </glossdef>
7884 </glossentry>
7885
7886 <glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm>KERNEL_MODULE_PROBECONF</glossterm>
7887 <info>
7888 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."
7889 </info>
7890 <glossdef>
7891 <para role="glossdeffirst">
7892<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7893 Provides a list of modules for which the OpenEmbedded
7894 build system expects to find
7895 <filename>module_conf_</filename><replaceable>modname</replaceable>
7896 values that specify configuration for each of the modules.
7897 For information on how to provide those module
7898 configurations, see the
7899 <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
7900 variable.
7901 </para>
7902 </glossdef>
7903 </glossentry>
7904
7905 <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
7906 <info>
7907 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)."
7908 </info>
7909 <glossdef>
7910 <para role="glossdeffirst">
7911<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7912 The location of the kernel sources.
7913 This variable is set to the value of the
7914 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
7915 within the
7916 <link linkend='ref-classes-module'><filename>module</filename></link>
7917 class.
7918 For information on how this variable is used, see the
7919 "<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 -04007920 section in the Yocto Project Linux Kernel Development
7921 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007922 </para>
7923
7924 <para>
7925 To help maximize compatibility with out-of-tree drivers
7926 used to build modules, the OpenEmbedded build system also
7927 recognizes and uses the
7928 <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
7929 variable, which is identical to the
7930 <filename>KERNEL_PATH</filename> variable.
7931 Both variables are common variables used by external
7932 Makefiles to point to the kernel source directory.
7933 </para>
7934 </glossdef>
7935 </glossentry>
7936
7937 <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
7938 <info>
7939 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)."
7940 </info>
7941 <glossdef>
7942 <para role="glossdeffirst">
7943<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7944 The location of the kernel sources.
7945 This variable is set to the value of the
7946 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
7947 within the
7948 <link linkend='ref-classes-module'><filename>module</filename></link>
7949 class.
7950 For information on how this variable is used, see the
7951 "<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 -04007952 section in the Yocto Project Linux Kernel Development
7953 Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007954 </para>
7955
7956 <para>
7957 To help maximize compatibility with out-of-tree drivers
7958 used to build modules, the OpenEmbedded build system also
7959 recognizes and uses the
7960 <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
7961 variable, which is identical to the
7962 <filename>KERNEL_SRC</filename> variable.
7963 Both variables are common variables used by external
7964 Makefiles to point to the kernel source directory.
7965 </para>
7966 </glossdef>
7967 </glossentry>
7968
Patrick Williamsf1e5d692016-03-30 15:21:19 -05007969 <glossentry id='var-KERNEL_VERSION'><glossterm>KERNEL_VERSION</glossterm>
7970 <info>
7971 KERNEL_VERSION[doc] = "Specifies the version of the kernel as extracted from version.h or utsrelease.h within the kernel sources."
7972 </info>
7973 <glossdef>
7974 <para role="glossdeffirst">
7975<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7976 Specifies the version of the kernel as extracted from
7977 <filename>version.h</filename> or
7978 <filename>utsrelease.h</filename> within the kernel sources.
7979 Effects of setting this variable do not take affect until
7980 the kernel has been configured.
7981 Consequently, attempting to refer to this variable in
7982 contexts prior to configuration will not work.
7983 </para>
7984 </glossdef>
7985 </glossentry>
7986
7987 <glossentry id='var-KERNELDEPMODDEPEND'><glossterm>KERNELDEPMODDEPEND</glossterm>
7988 <info>
7989 KERNELDEPMODDEPEND[doc] = "Specifies whether or not to use the data referenced through the PKGDATA_DIR directory."
7990 </info>
7991 <glossdef>
7992 <para role="glossdeffirst">
7993<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
7994 Specifies whether the data referenced through
7995 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
7996 is needed or not.
7997 The <filename>KERNELDEPMODDEPEND</filename> does not
7998 control whether or not that data exists,
7999 but simply whether or not it is used.
8000 If you do not need to use the data, set the
8001 <filename>KERNELDEPMODDEPEND</filename> variable in your
8002 <filename>initramfs</filename> recipe.
8003 Setting the variable there when the data is not needed
8004 avoids a potential dependency loop.
8005 </para>
8006 </glossdef>
8007 </glossentry>
8008
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008009 <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
8010 <info>
8011 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."
8012 </info>
8013 <glossdef>
8014 <para role="glossdeffirst">
8015<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8016 Provides a short description of a configuration fragment.
8017 You use this variable in the <filename>.scc</filename>
8018 file that describes a configuration fragment file.
8019 Here is the variable used in a file named
8020 <filename>smp.scc</filename> to describe SMP being
8021 enabled:
8022 <literallayout class='monospaced'>
8023 define KFEATURE_DESCRIPTION "Enable SMP"
8024 </literallayout>
8025 </para>
8026 </glossdef>
8027 </glossentry>
8028
8029 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
8030 <info>
8031 KMACHINE[doc] = "The machine as known by the kernel."
8032 </info>
8033 <glossdef>
8034 <para role="glossdeffirst">
8035<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8036 The machine as known by the kernel.
8037 Sometimes the machine name used by the kernel does not
8038 match the machine name used by the OpenEmbedded build
8039 system.
8040 For example, the machine name that the OpenEmbedded build
8041 system understands as
8042 <filename>core2-32-intel-common</filename> goes by a
8043 different name in the Linux Yocto kernel.
8044 The kernel understands that machine as
8045 <filename>intel-core2-32</filename>.
8046 For cases like these, the <filename>KMACHINE</filename>
8047 variable maps the kernel machine name to the OpenEmbedded
8048 build system machine name.
8049 </para>
8050
8051 <para>
8052 These mappings between different names occur in the
8053 Yocto Linux Kernel's <filename>meta</filename> branch.
8054 As an example take a look in the
8055 <filename>common/recipes-kernel/linux/linux-yocto_3.19.bbappend</filename>
8056 file:
8057 <literallayout class='monospaced'>
8058 LINUX_VERSION_core2-32-intel-common = "3.19.0"
8059 COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}"
8060 SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"
8061 SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
8062 KMACHINE_core2-32-intel-common = "intel-core2-32"
8063 KBRANCH_core2-32-intel-common = "standard/base"
8064 KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"
8065 </literallayout>
8066 The <filename>KMACHINE</filename> statement says that
8067 the kernel understands the machine name as
8068 "intel-core2-32".
8069 However, the OpenEmbedded build system understands the
8070 machine as "core2-32-intel-common".
8071 </para>
8072
8073 </glossdef>
8074 </glossentry>
8075
8076 <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
8077 <info>
8078 KTYPE[doc] = "Defines the kernel type to be used in assembling the configuration."
8079 </info>
8080 <glossdef>
8081 <para role="glossdeffirst">
8082<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8083 Defines the kernel type to be used in assembling the
8084 configuration.
8085 The linux-yocto recipes define "standard", "tiny",
8086 and "preempt-rt" kernel types.
8087 See the
8088 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
8089 section in the Yocto Project Linux Kernel Development
8090 Manual for more information on kernel types.
8091 </para>
8092
8093 <para>
8094 You define the <filename>KTYPE</filename> variable in the
8095 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
8096 The value you use must match the value used for the
8097 <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
8098 value used by the kernel recipe.
8099 </para>
8100 </glossdef>
8101 </glossentry>
8102 </glossdiv>
8103
8104 <glossdiv id='var-glossary-l'><title>L</title>
8105
8106 <glossentry id='var-LABELS'><glossterm>LABELS</glossterm>
8107 <info>
8108 LABELS[doc] = "Provides a list of targets for automatic configuration."
8109 </info>
8110 <glossdef>
8111 <para role="glossdeffirst">
8112<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8113 Provides a list of targets for automatic configuration.
8114 </para>
8115
8116 <para>
8117 See the
8118 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
8119 class for more information on how this variable is used.
8120 </para>
8121 </glossdef>
8122 </glossentry>
8123
8124 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
8125 <info>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05008126 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 -05008127 </info>
8128 <glossdef>
8129 <para role="glossdeffirst">
8130<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop6e60e8b2018-02-01 10:27:11 -05008131 Lists the layers, separated by spaces, on which this
8132 recipe depends.
8133 Optionally, you can specify a specific layer version for a
8134 dependency by adding it to the end of the layer name.
8135 Here is an example:
8136 <literallayout class='monospaced'>
8137 LAYERDEPENDS_mylayer = "anotherlayer (=3)"
8138 </literallayout>
8139 In this previous example, version 3 of "anotherlayer"
8140 is compared against
8141 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>.
8142 </para>
8143
8144 <para>
8145 An error is produced if any dependency is missing or
8146 the version numbers (if specified) do not match exactly.
8147 This variable is used in the
8148 <filename>conf/layer.conf</filename> file and must be
8149 suffixed with the name of the specific layer (e.g.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008150 <filename>LAYERDEPENDS_mylayer</filename>).
8151 </para>
8152 </glossdef>
8153 </glossentry>
8154
8155 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
8156 <info>
8157 LAYERDIR[doc] = "When used inside the layer.conf configuration file, this variable provides the path of the current layer."
8158 </info>
8159 <glossdef>
8160 <para role="glossdeffirst">
8161<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8162 When used inside the <filename>layer.conf</filename> configuration
8163 file, this variable provides the path of the current layer.
8164 This variable is not available outside of <filename>layer.conf</filename>
8165 and references are expanded immediately when parsing of the file completes.
8166 </para>
8167 </glossdef>
8168 </glossentry>
8169
Brad Bishop6e60e8b2018-02-01 10:27:11 -05008170 <glossentry id='var-LAYERRECOMMENDS'><glossterm>LAYERRECOMMENDS</glossterm>
8171 <info>
8172 LAYERRECOMMENDS[doc] = "Lists the layers, separated by spaces, recommended for use with this layer."
8173 </info>
8174 <glossdef>
8175 <para role="glossdeffirst">
8176<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8177 Lists the layers, separated by spaces, recommended for
8178 use with this layer.
8179 </para>
8180
8181 <para>
8182 Optionally, you can specify a specific layer version for a
8183 recommendation by adding the version to the end of the
8184 layer name.
8185 Here is an example:
8186 <literallayout class='monospaced'>
8187 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"
8188 </literallayout>
8189 In this previous example, version 3 of "anotherlayer" is
8190 compared against
8191 <filename>LAYERVERSION_anotherlayer</filename>.
8192 </para>
8193
8194 <para>
8195 This variable is used in the
8196 <filename>conf/layer.conf</filename> file and must be
8197 suffixed with the name of the specific layer (e.g.
8198 <filename>LAYERRECOMMENDS_mylayer</filename>).
8199 </para>
8200 </glossdef>
8201 </glossentry>
8202
Brad Bishop316dfdd2018-06-25 12:45:53 -04008203 <glossentry id='var-LAYERSERIES_COMPAT'><glossterm>LAYERSERIES_COMPAT</glossterm>
8204 <info>
8205 LAYERSERIES_COMPAT[doc] = "Lists the OpenEmbedded-Core versions for which a layer is compatible."
8206 </info>
8207 <glossdef>
8208 <para role="glossdeffirst">
8209<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8210 Lists the versions of the
8211 <link linkend='oe-core'>OpenEmbedded-Core</link> for which
8212 a layer is compatible.
8213 Using the <filename>LAYERSERIES_COMPAT</filename> variable
8214 allows the layer maintainer to indicate which combinations
8215 of the layer and OE-Core can be expected to work.
8216 The variable gives the system a way to detect when a layer
8217 has not been tested with new releases of OE-Core (e.g.
8218 the layer is not maintained).
8219 </para>
8220
8221 <para>
8222 To specify the OE-Core versions for which a layer is
8223 compatible, use this variable in your layer's
8224 <filename>conf/layer.conf</filename> configuration file.
8225 For the list, use the Yocto Project
8226 <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Release Name</ulink>
8227 (e.g. &DISTRO_NAME_NO_CAP;).
8228 To specify multiple OE-Core versions for the layer,
8229 use a space-separated list:
8230 <literallayout class='monospaced'>
8231 LAYERSERIES_COMPAT_<replaceable>layer_root_name</replaceable> = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;"
8232 </literallayout>
8233 <note>
8234 Setting <filename>LAYERSERIES_COMPAT</filename> is
8235 required by the Yocto Project Compatible version 2
8236 standard.
8237 The OpenEmbedded build system produces a warning if
8238 the variable is not set for any given layer.
8239 </note>
8240 </para>
8241
8242 <para>
8243 See the
8244 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-layer'>Creating Your Own Layer</ulink>"
8245 section in the Yocto Project Development Tasks Manual.
8246 </para>
8247 </glossdef>
8248 </glossentry>
8249
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008250 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
8251 <info>
8252 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."
8253 </info>
8254 <glossdef>
8255 <para role="glossdeffirst">
8256<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8257 Optionally specifies the version of a layer as a single number.
8258 You can use this within
8259 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
8260 for another layer in order to depend on a specific version
8261 of the layer.
8262 This variable is used in the <filename>conf/layer.conf</filename> file
8263 and must be suffixed with the name of the specific layer (e.g.
8264 <filename>LAYERVERSION_mylayer</filename>).
8265 </para>
8266 </glossdef>
8267 </glossentry>
8268
8269 <glossentry id='var-LD'><glossterm>LD</glossterm>
8270 <info>
8271 LD[doc] = "Minimal command and arguments to run the linker."
8272 </info>
8273 <glossdef>
8274 <para role="glossdeffirst">
8275<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8276 The minimal command and arguments used to run the
8277 linker.
8278 </para>
8279 </glossdef>
8280 </glossentry>
8281
8282 <glossentry id='var-LDFLAGS'><glossterm>LDFLAGS</glossterm>
8283 <info>
8284 LDFLAGS[doc] = "Specifies the flags to pass to the linker."
8285 </info>
8286 <glossdef>
8287 <para role="glossdeffirst">
8288<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8289 Specifies the flags to pass to the linker.
8290 This variable is exported to an environment
8291 variable and thus made visible to the software being
8292 built during the compilation step.
8293 </para>
8294
8295 <para>
8296 Default initialization for <filename>LDFLAGS</filename>
8297 varies depending on what is being built:
8298 <itemizedlist>
8299 <listitem><para>
8300 <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link>
8301 when building for the target
8302 </para></listitem>
8303 <listitem><para>
8304 <link linkend='var-BUILD_LDFLAGS'><filename>BUILD_LDFLAGS</filename></link>
8305 when building for the build host (i.e.
8306 <filename>-native</filename>)
8307 </para></listitem>
8308 <listitem><para>
8309 <link linkend='var-BUILDSDK_LDFLAGS'><filename>BUILDSDK_LDFLAGS</filename></link>
8310 when building for an SDK (i.e.
8311 <filename>nativesdk-</filename>)
8312 </para></listitem>
8313 </itemizedlist>
8314 </para>
8315 </glossdef>
8316 </glossentry>
8317
8318 <glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>
8319 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04008320 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 -05008321 </info>
8322 <glossdef>
8323 <para role="glossdeffirst">
8324<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8325 Specifies the lead (or primary) compiled library file
Brad Bishop316dfdd2018-06-25 12:45:53 -04008326 (i.e. <filename>.so</filename>) that the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008327 <link linkend='ref-classes-debian'><filename>debian</filename></link>
8328 class applies its naming policy to given a recipe that
8329 packages multiple libraries.
8330 </para>
8331
8332 <para>
8333 This variable works in conjunction with the
8334 <filename>debian</filename> class.
8335 </para>
8336 </glossdef>
8337 </glossentry>
8338
8339 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
8340 <info>
8341 LIC_FILES_CHKSUM[doc] = "Checksums of the license text in the recipe source code."
8342 </info>
8343 <glossdef>
8344 <para role="glossdeffirst">
8345<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8346 Checksums of the license text in the recipe source code.
8347 </para>
8348
8349 <para>
8350 This variable tracks changes in license text of the source
8351 code files.
8352 If the license text is changed, it will trigger a build
8353 failure, which gives the developer an opportunity to review any
8354 license change.
8355 </para>
8356
8357 <para>
8358 This variable must be defined for all recipes (unless
8359 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8360 is set to "CLOSED").</para>
8361 <para>For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04008362 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
8363 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008364 </para>
8365 </glossdef>
8366 </glossentry>
8367
8368 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
8369 <info>
8370 LICENSE[doc] = "The list of source licenses for the recipe. The logical operators &amp;, '|', and parentheses can be used."
8371 </info>
8372 <glossdef>
8373 <para role="glossdeffirst">
8374<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8375 The list of source licenses for the recipe.
8376 Follow these rules:
8377 <itemizedlist>
8378 <listitem><para>Do not use spaces within individual
8379 license names.</para></listitem>
8380 <listitem><para>Separate license names using
8381 | (pipe) when there is a choice between licenses.
8382 </para></listitem>
8383 <listitem><para>Separate license names using
8384 &amp; (ampersand) when multiple licenses exist
8385 that cover different parts of the source.
8386 </para></listitem>
8387 <listitem><para>You can use spaces between license
8388 names.</para></listitem>
8389 <listitem><para>For standard licenses, use the names
8390 of the files in
8391 <filename>meta/files/common-licenses/</filename>
8392 or the
8393 <link linkend='var-SPDXLICENSEMAP'><filename>SPDXLICENSEMAP</filename></link>
8394 flag names defined in
8395 <filename>meta/conf/licenses.conf</filename>.
8396 </para></listitem>
8397 </itemizedlist>
8398 </para>
8399
8400 <para>
8401 Here are some examples:
8402 <literallayout class='monospaced'>
8403 LICENSE = "LGPLv2.1 | GPLv3"
8404 LICENSE = "MPL-1 &amp; LGPLv2.1"
8405 LICENSE = "GPLv2+"
8406 </literallayout>
8407 The first example is from the recipes for Qt, which the user
8408 may choose to distribute under either the LGPL version
8409 2.1 or GPL version 3.
8410 The second example is from Cairo where two licenses cover
8411 different parts of the source code.
8412 The final example is from <filename>sysstat</filename>,
8413 which presents a single license.
8414 </para>
8415
8416 <para>
8417 You can also specify licenses on a per-package basis to
8418 handle situations where components of the output have
8419 different licenses.
8420 For example, a piece of software whose code is
8421 licensed under GPLv2 but has accompanying documentation
8422 licensed under the GNU Free Documentation License 1.2 could
8423 be specified as follows:
8424 <literallayout class='monospaced'>
8425 LICENSE = "GFDL-1.2 &amp; GPLv2"
8426 LICENSE_${PN} = "GPLv2"
8427 LICENSE_${PN}-doc = "GFDL-1.2"
8428 </literallayout>
8429 </para>
8430 </glossdef>
8431 </glossentry>
8432
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05008433 <glossentry id='var-LICENSE_CREATE_PACKAGE'><glossterm>LICENSE_CREATE_PACKAGE</glossterm>
8434 <info>
8435 LICENSE_CREATE_PACKAGE[doc] = "Creates an extra package (i.e. ${PN}-lic) for each recipe and adds that package to the RRECOMMENDS+${PN}."
8436 </info>
8437 <glossdef>
8438 <para role="glossdeffirst">
8439<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8440 Setting <filename>LICENSE_CREATE_PACKAGE</filename>
8441 to "1" causes the OpenEmbedded build system to create
8442 an extra package (i.e.
8443 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-lic</filename>)
8444 for each recipe and to add those packages to the
8445 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link><filename>_${PN}</filename>.
8446 </para>
8447
8448 <para>
8449 The <filename>${PN}-lic</filename> package installs a
8450 directory in <filename>/usr/share/licenses</filename>
8451 named <filename>${PN}</filename>, which is the recipe's
8452 base name, and installs files in that directory that
8453 contain license and copyright information (i.e. copies of
8454 the appropriate license files from
8455 <filename>meta/common-licenses</filename> that match the
8456 licenses specified in the
8457 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8458 variable of the recipe metadata and copies of files marked
8459 in
8460 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
8461 as containing license text).
8462 </para>
8463
8464 <para>
8465 For related information on providing license text, see the
8466 <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
8467 variable, the
8468 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
8469 variable, and the
8470 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008471 section in the Yocto Project Development Tasks Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05008472 </para>
8473 </glossdef>
8474 </glossentry>
8475
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008476 <glossentry id='var-LICENSE_FLAGS'><glossterm>LICENSE_FLAGS</glossterm>
8477 <info>
8478 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."
8479 </info>
8480 <glossdef>
8481 <para role="glossdeffirst">
8482<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8483 Specifies additional flags for a recipe you must
8484 whitelist through
8485 <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
8486 in order to allow the recipe to be built.
8487 When providing multiple flags, separate them with
8488 spaces.
8489 </para>
8490
8491 <para>
8492 This value is independent of
8493 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8494 and is typically used to mark recipes that might
8495 require additional licenses in order to be used in a
8496 commercial product.
8497 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04008498 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8499 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008500 </para>
8501 </glossdef>
8502 </glossentry>
8503
8504 <glossentry id='var-LICENSE_FLAGS_WHITELIST'><glossterm>LICENSE_FLAGS_WHITELIST</glossterm>
8505 <info>
8506 LICENSE_FLAGS_WHITELIST[doc] = "Lists license flags that when specified in LICENSE_FLAGS within a recipe should not prevent that recipe from being built."
8507 </info>
8508 <glossdef>
8509 <para role="glossdeffirst">
8510<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8511 Lists license flags that when specified in
8512 <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
8513 within a recipe should not prevent that recipe from being
8514 built.
8515 This practice is otherwise known as "whitelisting"
8516 license flags.
8517 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04008518 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8519 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008520 </para>
8521 </glossdef>
8522 </glossentry>
8523
8524 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
8525 <info>
8526 LICENSE_PATH[doc] = "Path to additional licenses used during the build."
8527 </info>
8528 <glossdef>
8529 <para role="glossdeffirst">
8530<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8531 Path to additional licenses used during the build.
8532 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
8533 to define the directory that holds common license text used during the build.
8534 The <filename>LICENSE_PATH</filename> variable allows you to extend that
8535 location to other areas that have additional licenses:
8536 <literallayout class='monospaced'>
8537 LICENSE_PATH += "<replaceable>path-to-additional-common-licenses</replaceable>"
8538 </literallayout>
8539 </para>
8540 </glossdef>
8541 </glossentry>
8542
8543 <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
8544 <info>
8545 LINUX_KERNEL_TYPE[doc] = "Defines the kernel type to be used in assembling the configuration."
8546 </info>
8547 <glossdef>
8548 <para role="glossdeffirst">
8549<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8550 Defines the kernel type to be used in assembling the
8551 configuration.
8552 The linux-yocto recipes define "standard", "tiny", and
8553 "preempt-rt" kernel types.
8554 See the
8555 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
8556 section in the Yocto Project Linux Kernel Development
8557 Manual for more information on kernel types.
8558 </para>
8559
8560 <para>
8561 If you do not specify a
8562 <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
8563 "standard".
8564 Together with
8565 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
8566 the <filename>LINUX_KERNEL_TYPE</filename> variable
8567 defines the search
8568 arguments used by the kernel tools to find the appropriate
8569 description within the kernel
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008570 <link linkend='metadata'>Metadata</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008571 with which to build out the sources and configuration.
8572 </para>
8573 </glossdef>
8574 </glossentry>
8575
8576 <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
8577 <info>
8578 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."
8579 </info>
8580 <glossdef>
8581 <para role="glossdeffirst">
8582<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8583 The Linux version from <filename>kernel.org</filename>
8584 on which the Linux kernel image being built using the
8585 OpenEmbedded build system is based.
8586 You define this variable in the kernel recipe.
8587 For example, the <filename>linux-yocto-3.4.bb</filename>
8588 kernel recipe found in
8589 <filename>meta/recipes-kernel/linux</filename>
8590 defines the variables as follows:
8591 <literallayout class='monospaced'>
8592 LINUX_VERSION ?= "3.4.24"
8593 </literallayout>
8594 </para>
8595
8596 <para>
8597 The <filename>LINUX_VERSION</filename> variable is used to
8598 define <link linkend='var-PV'><filename>PV</filename></link>
8599 for the recipe:
8600 <literallayout class='monospaced'>
8601 PV = "${LINUX_VERSION}+git${SRCPV}"
8602 </literallayout>
8603 </para>
8604 </glossdef>
8605 </glossentry>
8606
8607 <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
8608 <info>
8609 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."
8610 </info>
8611 <glossdef>
8612 <para role="glossdeffirst">
8613<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8614 A string extension compiled into the version
8615 string of the Linux kernel built with the OpenEmbedded
8616 build system.
8617 You define this variable in the kernel recipe.
8618 For example, the linux-yocto kernel recipes all define
8619 the variable as follows:
8620 <literallayout class='monospaced'>
8621 LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
8622 </literallayout>
8623 </para>
8624
8625 <para>
8626 Defining this variable essentially sets the
8627 Linux kernel configuration item
8628 <filename>CONFIG_LOCALVERSION</filename>, which is visible
8629 through the <filename>uname</filename> command.
8630 Here is an example that shows the extension assuming it
8631 was set as previously shown:
8632 <literallayout class='monospaced'>
8633 $ uname -r
8634 3.7.0-rc8-custom
8635 </literallayout>
8636 </para>
8637 </glossdef>
8638 </glossentry>
8639
8640 <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
8641 <info>
8642 LOG_DIR[doc] = "Specifies the directory to which the OpenEmbedded build system writes overall log files. The default directory is ${TMPDIR}/log"
8643 </info>
8644 <glossdef>
8645 <para role="glossdeffirst">
8646<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8647 Specifies the directory to which the OpenEmbedded build
8648 system writes overall log files.
8649 The default directory is <filename>${TMPDIR}/log</filename>.
8650 </para>
8651
8652 <para>
8653 For the directory containing logs specific to each task,
8654 see the <link linkend='var-T'><filename>T</filename></link>
8655 variable.
8656 </para>
8657 </glossdef>
8658 </glossentry>
8659
8660 </glossdiv>
8661
8662 <glossdiv id='var-glossary-m'><title>M</title>
8663
8664 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
8665 <info>
8666 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."
8667 </info>
8668 <glossdef>
8669 <para role="glossdeffirst">
8670<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8671 Specifies the target device for which the image is built.
8672 You define <filename>MACHINE</filename> in the
8673 <filename>local.conf</filename> file found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008674 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008675 By default, <filename>MACHINE</filename> is set to
8676 "qemux86", which is an x86-based architecture machine to
8677 be emulated using QEMU:
8678 <literallayout class='monospaced'>
8679 MACHINE ?= "qemux86"
8680 </literallayout>
8681 </para>
8682
8683 <para>
8684 The variable corresponds to a machine configuration file of the
8685 same name, through which machine-specific configurations are set.
8686 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
8687 exists the corresponding <filename>qemux86.conf</filename> machine
8688 configuration file, which can be found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05008689 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008690 in <filename>meta/conf/machine</filename>.
8691 </para>
8692
8693 <para>
8694 The list of machines supported by the Yocto Project as
8695 shipped include the following:
8696 <literallayout class='monospaced'>
8697 MACHINE ?= "qemuarm"
8698 MACHINE ?= "qemuarm64"
8699 MACHINE ?= "qemumips"
8700 MACHINE ?= "qemumips64"
8701 MACHINE ?= "qemuppc"
8702 MACHINE ?= "qemux86"
8703 MACHINE ?= "qemux86-64"
8704 MACHINE ?= "genericx86"
8705 MACHINE ?= "genericx86-64"
8706 MACHINE ?= "beaglebone"
8707 MACHINE ?= "mpc8315e-rdb"
8708 MACHINE ?= "edgerouter"
8709 </literallayout>
8710 The last five are Yocto Project reference hardware boards, which
8711 are provided in the <filename>meta-yocto-bsp</filename> layer.
8712 <note>Adding additional Board Support Package (BSP) layers
8713 to your configuration adds new possible settings for
8714 <filename>MACHINE</filename>.
8715 </note>
8716 </para>
8717 </glossdef>
8718 </glossentry>
8719
8720 <glossentry id='var-MACHINE_ARCH'><glossterm>MACHINE_ARCH</glossterm>
8721 <info>
8722 MACHINE_ARCH[doc] = "Specifies the name of the machine-specific architecture. This variable is set automatically from MACHINE or TUNE_PKGARCH."
8723 </info>
8724 <glossdef>
8725 <para role="glossdeffirst">
8726<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8727 Specifies the name of the machine-specific architecture.
8728 This variable is set automatically from
8729 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
8730 or
8731 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>.
8732 You should not hand-edit the
8733 <filename>MACHINE_ARCH</filename> variable.
8734 </para>
8735 </glossdef>
8736 </glossentry>
8737
8738 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
8739 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04008740 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 -05008741 </info>
8742 <glossdef>
8743 <para role="glossdeffirst">
8744<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8745 A list of required machine-specific packages to install as part of
8746 the image being built.
8747 The build process depends on these packages being present.
Brad Bishop316dfdd2018-06-25 12:45:53 -04008748 Furthermore, because this is a "machine-essential" variable, the list of
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008749 packages are essential for the machine to boot.
8750 The impact of this variable affects images based on
8751 <filename>packagegroup-core-boot</filename>,
8752 including the <filename>core-image-minimal</filename> image.
8753 </para>
8754
8755 <para>
8756 This variable is similar to the
8757 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
8758 variable with the exception that the image being built has a build
8759 dependency on the variable's list of packages.
8760 In other words, the image will not build if a file in this list is not found.
8761 </para>
8762
8763 <para>
8764 As an example, suppose the machine for which you are building requires
8765 <filename>example-init</filename> to be run during boot to initialize the hardware.
8766 In this case, you would use the following in the machine's
8767 <filename>.conf</filename> configuration file:
8768 <literallayout class='monospaced'>
8769 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
8770 </literallayout>
8771 </para>
8772 </glossdef>
8773 </glossentry>
8774
8775 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
8776 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04008777 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 -05008778 </info>
8779 <glossdef>
8780 <para role="glossdeffirst">
8781<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8782 A list of recommended machine-specific packages to install as part of
8783 the image being built.
8784 The build process does not depend on these packages being present.
Brad Bishop316dfdd2018-06-25 12:45:53 -04008785 However, because this is a "machine-essential" variable, the list of
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008786 packages are essential for the machine to boot.
8787 The impact of this variable affects images based on
8788 <filename>packagegroup-core-boot</filename>,
8789 including the <filename>core-image-minimal</filename> image.
8790 </para>
8791
8792 <para>
8793 This variable is similar to the
8794 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
8795 variable with the exception that the image being built does not have a build
8796 dependency on the variable's list of packages.
8797 In other words, the image will still build if a package in this list is not found.
8798 Typically, this variable is used to handle essential kernel modules, whose
8799 functionality may be selected to be built into the kernel rather than as a module,
8800 in which case a package will not be produced.
8801 </para>
8802
8803 <para>
8804 Consider an example where you have a custom kernel where a specific touchscreen
8805 driver is required for the machine to be usable.
8806 However, the driver can be built as a module or
8807 into the kernel depending on the kernel configuration.
8808 If the driver is built as a module, you want it to be installed.
8809 But, when the driver is built into the kernel, you still want the
8810 build to succeed.
8811 This variable sets up a "recommends" relationship so that in the latter case,
8812 the build will not fail due to the missing package.
8813 To accomplish this, assuming the package for the module was called
8814 <filename>kernel-module-ab123</filename>, you would use the
8815 following in the machine's <filename>.conf</filename> configuration
8816 file:
8817 <literallayout class='monospaced'>
8818 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
8819 </literallayout>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05008820 <note>
8821 In this example, the
8822 <filename>kernel-module-ab123</filename> recipe
8823 needs to explicitly set its
8824 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
8825 variable to ensure that BitBake does not use the
8826 kernel recipe's
8827 <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link>
8828 variable to satisfy the dependency.
8829 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008830 </para>
8831
8832 <para>
8833 Some examples of these machine essentials are flash, screen, keyboard, mouse,
8834 or touchscreen drivers (depending on the machine).
8835 </para>
8836 </glossdef>
8837 </glossentry>
8838
8839 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
8840 <info>
8841 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."
8842 </info>
8843 <glossdef>
8844 <para role="glossdeffirst">
8845<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8846 A list of machine-specific packages to install as part of the
8847 image being built that are not essential for the machine to boot.
8848 However, the build process for more fully-featured images
8849 depends on the packages being present.
8850 </para>
8851
8852 <para>
8853 This variable affects all images based on
8854 <filename>packagegroup-base</filename>, which does not include the
8855 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
8856 images.
8857 </para>
8858
8859 <para>
8860 The variable is similar to the
8861 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
8862 variable with the exception that the image being built has a build
8863 dependency on the variable's list of packages.
8864 In other words, the image will not build if a file in this list is not found.
8865 </para>
8866
8867 <para>
8868 An example is a machine that has WiFi capability but is not
8869 essential for the machine to boot the image.
8870 However, if you are building a more fully-featured image, you want to enable
8871 the WiFi.
8872 The package containing the firmware for the WiFi hardware is always
8873 expected to exist, so it is acceptable for the build process to depend upon
8874 finding the package.
8875 In this case, assuming the package for the firmware was called
8876 <filename>wifidriver-firmware</filename>, you would use the following in the
8877 <filename>.conf</filename> file for the machine:
8878 <literallayout class='monospaced'>
8879 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
8880 </literallayout>
8881 </para>
8882 </glossdef>
8883 </glossentry>
8884
8885 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
8886 <info>
8887 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."
8888 </info>
8889 <glossdef>
8890 <para role="glossdeffirst">
8891<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8892 A list of machine-specific packages to install as part of the
8893 image being built that are not essential for booting the machine.
8894 The image being built has no build dependency on this list of packages.
8895 </para>
8896
8897 <para>
8898 This variable affects only images based on
8899 <filename>packagegroup-base</filename>, which does not include the
8900 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
8901 images.
8902 </para>
8903
8904 <para>
8905 This variable is similar to the
8906 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
8907 variable with the exception that the image being built does not have a build
8908 dependency on the variable's list of packages.
8909 In other words, the image will build if a file in this list is not found.
8910 </para>
8911
8912 <para>
8913 An example is a machine that has WiFi capability but is not essential
8914 For the machine to boot the image.
8915 However, if you are building a more fully-featured image, you want to enable
8916 WiFi.
8917 In this case, the package containing the WiFi kernel module will not be produced
8918 if the WiFi driver is built into the kernel, in which case you still want the
8919 build to succeed instead of failing as a result of the package not being found.
8920 To accomplish this, assuming the package for the module was called
8921 <filename>kernel-module-examplewifi</filename>, you would use the
8922 following in the <filename>.conf</filename> file for the machine:
8923 <literallayout class='monospaced'>
8924 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
8925 </literallayout>
8926 </para>
8927 </glossdef>
8928 </glossentry>
8929
8930 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
8931 <info>
8932 MACHINE_FEATURES[doc] = "Specifies the list of hardware features the MACHINE supports."
8933 </info>
8934 <glossdef>
8935 <para role="glossdeffirst">
8936<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8937 Specifies the list of hardware features the
8938 <link linkend='var-MACHINE'><filename>MACHINE</filename></link> is capable
8939 of supporting.
8940 For related information on enabling features, see the
8941 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>,
8942 <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>,
8943 and
8944 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
8945 variables.
8946 </para>
8947
8948 <para>
8949 For a list of hardware features supported by the Yocto
8950 Project as shipped, see the
8951 "<link linkend='ref-features-machine'>Machine Features</link>"
8952 section.
8953 </para>
8954 </glossdef>
8955 </glossentry>
8956
8957 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
8958 <info>
8959 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."
8960 </info>
8961 <glossdef>
8962 <para role="glossdeffirst">
8963<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8964 Features to be added to
8965 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
8966 if not also present in
8967 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
8968 </para>
8969
8970 <para>
8971 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
8972 It is not intended to be user-configurable.
8973 It is best to just reference the variable to see which machine features are
8974 being backfilled for all machine configurations.
Brad Bishop316dfdd2018-06-25 12:45:53 -04008975 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008976 more information.
8977 </para>
8978 </glossdef>
8979 </glossentry>
8980
8981 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
8982 <info>
8983 MACHINE_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from MACHINE_FEATURES_BACKFILL that should not be backfilled (i.e. added to MACHINE_FEATURES) during the build."
8984 </info>
8985 <glossdef>
8986 <para role="glossdeffirst">
8987<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
8988 Features from
8989 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
8990 that should not be backfilled (i.e. added to
8991 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
8992 during the build.
Brad Bishop316dfdd2018-06-25 12:45:53 -04008993 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05008994 more information.
8995 </para>
8996 </glossdef>
8997 </glossentry>
8998
8999 <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
9000 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009001 MACHINEOVERRIDES[doc] = "A colon-separated list of overrides that apply to the current machine."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009002 </info>
9003 <glossdef>
9004 <para role="glossdeffirst">
9005<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009006 A colon-separated list of overrides that apply to the
9007 current machine.
9008 By default, this list includes the value of
9009 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009010 </para>
9011
9012 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009013 You can extend <filename>MACHINEOVERRIDES</filename>
9014 to add extra overrides that should apply to a machine.
9015 For example, all machines emulated in QEMU (e.g.
9016 <filename>qemuarm</filename>, <filename>qemux86</filename>,
9017 and so forth) include a file named
9018 <filename>meta/conf/machine/include/qemu.inc</filename>
9019 that prepends the following override to
9020 <filename>MACHINEOVERRIDES</filename>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009021 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009022 MACHINEOVERRIDES =. "qemuall:"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009023 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009024 This override allows variables to be overriden for all
9025 machines emulated in QEMU, like in the following example
9026 from the <filename>connman-conf</filename> recipe:
9027 <literallayout class='monospaced'>
9028 SRC_URI_append_qemuall = "file://wired.config \
9029 file://wired-setup \
9030 "
9031 </literallayout>
9032 The underlying mechanism behind
9033 <filename>MACHINEOVERRIDES</filename> is simply that it is
9034 included in the default value of
9035 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009036 </para>
9037 </glossdef>
9038 </glossentry>
9039
9040 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
9041 <info>
9042 MAINTAINER[doc] = "The email address of the distribution maintainer."
9043 </info>
9044 <glossdef>
9045 <para role="glossdeffirst">
9046<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9047 The email address of the distribution maintainer.
9048 </para>
9049 </glossdef>
9050 </glossentry>
9051
9052 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
9053 <info>
9054 MIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."
9055 </info>
9056 <glossdef>
9057 <para role="glossdeffirst">
9058<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9059 Specifies additional paths from which the OpenEmbedded
9060 build system gets source code.
9061 When the build system searches for source code, it first
9062 tries the local download directory.
9063 If that location fails, the build system tries locations
9064 defined by
9065 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
9066 the upstream source, and then locations specified by
9067 <filename>MIRRORS</filename> in that order.
9068 </para>
9069
9070 <para>
9071 Assuming your distribution
9072 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
9073 is "poky", the default value for
9074 <filename>MIRRORS</filename> is defined in the
9075 <filename>conf/distro/poky.conf</filename> file in the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05009076 <filename>meta-poky</filename> Git repository.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009077 </para>
9078 </glossdef>
9079 </glossentry>
9080
9081 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
9082 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04009083 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 -05009084 </info>
9085 <glossdef>
9086 <para role="glossdeffirst">
9087<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9088 Specifies a prefix has been added to
9089 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
Brad Bishop316dfdd2018-06-25 12:45:53 -04009090 of a recipe or package (i.e. a Multilib version).
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009091 The variable is used in places where the prefix needs to be
9092 added to or removed from a the name (e.g. the
9093 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
9094 <filename>MLPREFIX</filename> gets set when a prefix has been
9095 added to <filename>PN</filename>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009096 <note>
9097 The "ML" in <filename>MLPREFIX</filename> stands for
9098 "MultiLib".
9099 This representation is historical and comes from
9100 a time when <filename>nativesdk</filename> was a suffix
9101 rather than a prefix on the recipe name.
9102 When <filename>nativesdk</filename> was turned into a
9103 prefix, it made sense to set
9104 <filename>MLPREFIX</filename> for it as well.
9105 </note>
9106 </para>
9107
9108 <para>
9109 To help understand when <filename>MLPREFIX</filename>
9110 might be needed, consider when
9111 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
9112 is used to provide a <filename>nativesdk</filename> version
9113 of a recipe in addition to the target version.
9114 If that recipe declares build-time dependencies on tasks in
9115 other recipes by using
9116 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>,
9117 then a dependency on "foo" will automatically get rewritten
9118 to a dependency on "nativesdk-foo".
9119 However, dependencies like the following will not get
9120 rewritten automatically:
9121 <literallayout class='monospaced'>
9122 do_foo[depends] += "<replaceable>recipe</replaceable>:do_foo"
9123 </literallayout>
9124 If you want such a dependency to also get transformed,
9125 you can do the following:
9126 <literallayout class='monospaced'>
9127 do_foo[depends] += "${MLPREFIX}<replaceable>recipe</replaceable>:do_foo"
9128 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009129 </para>
9130 </glossdef>
9131 </glossentry>
9132
9133 <glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm>
9134 <info>
9135 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."
9136 </info>
9137 <glossdef>
9138 <para role="glossdeffirst">
9139<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9140 This variable has been replaced by the
9141 <filename>KERNEL_MODULE_AUTOLOAD</filename> variable.
9142 You should replace all occurrences of
9143 <filename>module_autoload</filename> with additions to
9144 <filename>KERNEL_MODULE_AUTOLOAD</filename>, for example:
9145 <literallayout class='monospaced'>
9146 module_autoload_rfcomm = "rfcomm"
9147 </literallayout>
9148 </para>
9149
9150 <para>
9151 should now be replaced with:
9152 <literallayout class='monospaced'>
9153 KERNEL_MODULE_AUTOLOAD += "rfcomm"
9154 </literallayout>
9155 See the
9156 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
9157 variable for more information.
9158 </para>
9159 </glossdef>
9160 </glossentry>
9161
9162 <glossentry id='var-module_conf'><glossterm>module_conf</glossterm>
9163 <info>
9164 module_conf[doc] = "Specifies modprobe.d syntax lines for inclusion in the /etc/modprobe.d/modname.conf file."
9165 </info>
9166 <glossdef>
9167 <para role="glossdeffirst">
9168<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9169 Specifies
9170 <ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink>
9171 syntax lines for inclusion in the
9172 <filename>/etc/modprobe.d/modname.conf</filename> file.
9173 </para>
9174
9175 <para>
9176 You can use this variable anywhere that it can be
9177 recognized by the kernel recipe or out-of-tree kernel
9178 module recipe (e.g. a machine configuration file, a
9179 distribution configuration file, an append file for the
9180 recipe, or the recipe itself).
9181 If you use this variable, you must also be sure to list
9182 the module name in the
9183 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
9184 variable.
9185 </para>
9186
9187 <para>
9188 Here is the general syntax:
9189 <literallayout class='monospaced'>
9190 module_conf_<replaceable>module_name</replaceable> = "<replaceable>modprobe.d-syntax</replaceable>"
9191 </literallayout>
9192 You must use the kernel module name override.
9193 </para>
9194
9195 <para>
9196 Run <filename>man modprobe.d</filename> in the shell to
9197 find out more information on the exact syntax
9198 you want to provide with <filename>module_conf</filename>.
9199 </para>
9200
9201 <para>
9202 Including <filename>module_conf</filename> causes the
9203 OpenEmbedded build system to populate the
9204 <filename>/etc/modprobe.d/modname.conf</filename>
9205 file with <filename>modprobe.d</filename> syntax lines.
9206 Here is an example that adds the options
9207 <filename>arg1</filename> and <filename>arg2</filename>
9208 to a module named <filename>mymodule</filename>:
9209 <literallayout class='monospaced'>
9210 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
9211 </literallayout>
9212 </para>
9213
9214 <para>
9215 For information on how to specify kernel modules to
9216 auto-load on boot, see the
9217 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
9218 variable.
9219 </para>
9220 </glossdef>
9221 </glossentry>
9222
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009223 <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
9224 <info>
9225 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."
9226 </info>
9227 <glossdef>
9228 <para role="glossdeffirst">
9229<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9230 Controls creation of the <filename>modules-*.tgz</filename>
9231 file.
9232 Set this variable to "0" to disable creation of this
9233 file, which contains all of the kernel modules resulting
9234 from a kernel build.
9235 </para>
9236 </glossdef>
9237 </glossentry>
9238
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08009239 <glossentry id='var-MODULE_TARBALL_LINK_NAME'><glossterm>MODULE_TARBALL_LINK_NAME</glossterm>
9240 <info>
9241 MODULE_TARBALL_LINK_NAME[doc] = "The link name of the kernel module tarball."
9242 </info>
9243 <glossdef>
9244 <para role="glossdeffirst">
9245<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9246 The link name of the kernel module tarball.
9247 This variable is set in the
9248 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
9249 file as follows:
9250 <literallayout class='monospaced'>
9251 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
9252 </literallayout>
9253 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
9254 variable, which is set in the same file, has the following
9255 value:
9256 <literallayout class='monospaced'>
9257 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
9258 </literallayout>
9259 </para>
9260
9261 <para>
9262 See the
9263 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
9264 variable for additional information.
9265 </para>
9266 </glossdef>
9267 </glossentry>
9268
9269 <glossentry id='var-MODULE_TARBALL_NAME'><glossterm>MODULE_TARBALL_NAME</glossterm>
9270 <info>
9271 MODULE_TARBALL_NAME[doc] = "The base name of the kernel module tarball."
9272 </info>
9273 <glossdef>
9274 <para role="glossdeffirst">
9275<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9276 The base name of the kernel module tarball.
9277 This variable is set in the
9278 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
9279 file as follows:
9280 <literallayout class='monospaced'>
9281 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"
9282 </literallayout>
9283 The value of the
9284 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
9285 variable, which is set in the same file, has the following
9286 value:
9287 <literallayout class='monospaced'>
9288 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
9289 </literallayout>
9290 </para>
9291 </glossdef>
9292 </glossentry>
9293
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009294<!--
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009295 <glossentry id='var-MULTIMACH_HOST_SYS'><glossterm>MULTIMACH_HOST_SYS</glossterm>
9296 <info>
9297 MULTIMACH_HOST_SYS[doc] = "Separates files for different machines such that you can build for multiple host machines using the same output directories."
9298 </info>
9299 <glossdef>
9300 <para role="glossdeffirst">
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009301-->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009302<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009303<!--
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009304 Serves the same purpose as
9305 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
9306 but for the "HOST" system, in situations that involve a
9307 "HOST" and a "TARGET" system.
9308 See the
9309 <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link>
9310 variable for more information.
9311 </para>
9312
9313 <para>
9314 The default value of this variable is:
9315 <literallayout class='monospaced'>
9316 ${PACKAGE_ARCH}${HOST_VENDOR}-${HOST_OS}
9317 </literallayout>
9318 </para>
9319 </glossdef>
9320 </glossentry>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009321-->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009322
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009323 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
9324 <info>
9325 MULTIMACH_TARGET_SYS[doc] = "Separates files for different machines such that you can build for multiple target machines using the same output directories."
9326 </info>
9327 <glossdef>
9328 <para role="glossdeffirst">
9329<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009330 Uniquely identifies the type of the target system for
9331 which packages are being built.
9332 This variable allows output for different types of target
9333 systems to be put into different subdirectories of the same
9334 output directory.
9335 </para>
9336
9337 <para>
9338 The default value of this variable is:
9339 <literallayout class='monospaced'>
9340 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}
9341 </literallayout>
9342 Some classes (e.g.
9343 <link linkend='ref-classes-cross-canadian'><filename>cross-canadian</filename></link>)
9344 modify the <filename>MULTIMACH_TARGET_SYS</filename> value.
9345 </para>
9346
9347 <para>
9348 See the
9349 <link linkend='var-STAMP'><filename>STAMP</filename></link>
9350 variable for an example.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009351 See the
9352 <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link>
9353 variable for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009354 </para>
9355 </glossdef>
9356 </glossentry>
9357
9358 </glossdiv>
9359
9360 <glossdiv id='var-glossary-n'><title>N</title>
9361
9362 <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
9363 <info>
9364 NATIVELSBSTRING[doc] = "A string identifying the host distribution."
9365 </info>
9366 <glossdef>
9367 <para role="glossdeffirst">
9368<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9369 A string identifying the host distribution.
9370 Strings consist of the host distributor ID
9371 followed by the release, as reported by the
9372 <filename>lsb_release</filename> tool
9373 or as read from <filename>/etc/lsb-release</filename>.
9374 For example, when running a build on Ubuntu 12.10, the value
9375 is "Ubuntu-12.10".
9376 If this information is unable to be determined, the value
9377 resolves to "Unknown".
9378 </para>
9379
9380 <para>
9381 This variable is used by default to isolate native shared
9382 state packages for different distributions (e.g. to avoid
9383 problems with <filename>glibc</filename> version
9384 incompatibilities).
9385 Additionally, the variable is checked against
9386 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
9387 if that variable is set.
9388 </para>
9389 </glossdef>
9390 </glossentry>
9391
9392 <glossentry id='var-NM'><glossterm>NM</glossterm>
9393 <info>
9394 NM[doc] = "Minimal command and arguments to run 'nm'."
9395 </info>
9396 <glossdef>
9397 <para role="glossdeffirst">
9398<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9399 The minimal command and arguments to run
9400 <filename>nm</filename>.
9401 </para>
9402 </glossdef>
9403 </glossentry>
9404
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08009405 <glossentry id='var-NO_GENERIC_LICENSE'><glossterm>NO_GENERIC_LICENSE</glossterm>
9406 <info>
9407 NO_GENERIC_LICENSE[doc] = "Used to allow copying a license that does not exist in common licenses."
9408 </info>
9409 <glossdef>
9410 <para role="glossdeffirst">
9411<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9412 Avoids QA errors when you use a non-common, non-CLOSED
9413 license in a recipe.
9414 Packages exist, such as the linux-firmware package, with
9415 many licenses that are not in any way common.
9416 Also, new licenses are added occasionally to avoid
9417 introducing a lot of common license files, which are only
9418 applicable to a specific package.
9419 <filename>NO_GENERIC_LICENSE</filename> is used to allow
9420 copying a license that does not exist in common licenses.
9421 </para>
9422
9423 <para>
9424 The following example shows how to add
9425 <filename>NO_GENERIC_LICENSE</filename> to a recipe:
9426 <literallayout class='monospaced'>
9427 NO_GENERIC_LICENSE[<replaceable>license_name</replaceable>] = "<replaceable>license_file_in_fetched_source</replaceable>"
9428 </literallayout>
9429 The following is an example that uses the
9430 <filename>LICENSE.Abilis.txt</filename> file as the license
9431 from the fetched source:
9432 <literallayout class='monospaced'>
9433 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
9434 </literallayout>
9435 </para>
9436 </glossdef>
9437 </glossentry>
9438
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009439 <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
9440 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -04009441 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 -05009442 </info>
9443 <glossdef>
9444 <para role="glossdeffirst">
9445<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9446 Prevents installation of all "recommended-only" packages.
9447 Recommended-only packages are packages installed only
9448 through the
9449 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
9450 variable).
9451 Setting the <filename>NO_RECOMMENDATIONS</filename> variable
9452 to "1" turns this feature on:
9453 <literallayout class='monospaced'>
9454 NO_RECOMMENDATIONS = "1"
9455 </literallayout>
9456 </para>
9457
9458 <para>
9459 You can set this variable globally in your
9460 <filename>local.conf</filename> file or you can attach it to
9461 a specific image recipe by using the recipe name override:
9462 <literallayout class='monospaced'>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05009463 NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "1"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009464 </literallayout>
9465 </para>
9466
9467 <para>
9468 It is important to realize that if you choose to not install
9469 packages using this variable and some other packages are
9470 dependent on them (i.e. listed in a recipe's
9471 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
9472 variable), the OpenEmbedded build system ignores your
9473 request and will install the packages to avoid dependency
9474 errors.
9475 <note>
9476 Some recommended packages might be required for certain
9477 system functionality, such as kernel modules.
9478 It is up to you to add packages with the
9479 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
9480 variable.
9481 </note>
9482 </para>
9483
9484 <para>
9485 Support for this variable exists only when using the
9486 IPK and RPM packaging backend.
9487 Support does not exist for DEB.
9488 </para>
9489
9490 <para>
9491 See the
9492 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
9493 and the
9494 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
9495 variables for related information.
9496 </para>
9497 </glossdef>
9498 </glossentry>
9499
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009500 <glossentry id='var-NOAUTOPACKAGEDEBUG'><glossterm>NOAUTOPACKAGEDEBUG</glossterm>
9501 <info>
9502 NOAUTOPACKAGEDEBUG[doc] = "Disables auto package from splitting .debug files."
9503 </info>
9504 <glossdef>
9505 <para role="glossdeffirst">
9506<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9507 Disables auto package from splitting
9508 <filename>.debug</filename> files. If a recipe requires
9509 <filename>FILES_${PN}-dbg</filename> to be set manually,
9510 the <filename>NOAUTOPACKAGEDEBUG</filename> can be defined
9511 allowing you to define the content of the debug package.
9512 For example:
9513 <literallayout class='monospaced'>
9514 NOAUTOPACKAGEDEBUG = "1"
9515 FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
9516 FILES_${PN}-dbg = "/usr/src/debug/"
9517 FILES_${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"
9518 </literallayout>
9519 </para>
9520 </glossdef>
9521 </glossentry>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009522 </glossdiv>
9523
9524 <glossdiv id='var-glossary-o'><title>O</title>
9525
9526 <glossentry id='var-OBJCOPY'><glossterm>OBJCOPY</glossterm>
9527 <info>
9528 OBJCOPY[doc] = "Minimal command and arguments to run 'objcopy'."
9529 </info>
9530 <glossdef>
9531 <para role="glossdeffirst">
9532<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9533 The minimal command and arguments to run
9534 <filename>objcopy</filename>.
9535 </para>
9536 </glossdef>
9537 </glossentry>
9538
9539 <glossentry id='var-OBJDUMP'><glossterm>OBJDUMP</glossterm>
9540 <info>
9541 OBJDUMP[doc] = "Minimal command and arguments to run 'objdump'."
9542 </info>
9543 <glossdef>
9544 <para role="glossdeffirst">
9545<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9546 The minimal command and arguments to run
9547 <filename>objdump</filename>.
9548 </para>
9549 </glossdef>
9550 </glossentry>
9551
9552 <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
9553 <info>
9554 OE_BINCONFIG_EXTRA_MANGLE[doc] = "When a recipe inherits the binconfig.bbclass class, this variable specifies additional arguments passed to the "sed" command."
9555 </info>
9556 <glossdef>
9557 <para role="glossdeffirst">
9558<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9559 When inheriting the
9560 <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
9561 class, this variable
9562 specifies additional arguments passed to the "sed" command.
9563 The sed command alters any paths in configuration scripts
9564 that have been set up during compilation.
9565 Inheriting this class results in all paths in these scripts
9566 being changed to point into the
9567 <filename>sysroots/</filename> directory so that all builds
9568 that use the script will use the correct directories
9569 for the cross compiling layout.
9570 </para>
9571
9572 <para>
9573 See the <filename>meta/classes/binconfig.bbclass</filename>
9574 in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009575 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009576 for details on how this class applies these additional
9577 sed command arguments.
9578 For general information on the
Brad Bishop316dfdd2018-06-25 12:45:53 -04009579 <filename>binconfig</filename> class, see the
9580 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009581 section.
9582 </para>
9583 </glossdef>
9584 </glossentry>
9585
9586 <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
9587 <info>
9588 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."
9589 </info>
9590 <glossdef>
9591 <para role="glossdeffirst">
9592<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9593 An internal variable used to tell the OpenEmbedded build
9594 system what Python modules to import for every Python
9595 function run by the system.
9596 </para>
9597
9598 <note>
9599 Do not set this variable.
9600 It is for internal use only.
9601 </note>
9602 </glossdef>
9603 </glossentry>
9604
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05009605 <glossentry id='var-OE_INIT_ENV_SCRIPT'><glossterm>OE_INIT_ENV_SCRIPT</glossterm>
9606 <info>
9607 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."
9608 </info>
9609 <glossdef>
9610 <para role="glossdeffirst">
9611<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9612 The name of the build environment setup script for the
9613 purposes of setting up the environment within the
9614 extensible SDK.
9615 The default value is "oe-init-build-env".
9616 </para>
9617
9618 <para>
9619 If you use a custom script to set up your build
9620 environment, set the
9621 <filename>OE_INIT_ENV_SCRIPT</filename> variable to its
9622 name.
9623 </para>
9624 </glossdef>
9625 </glossentry>
9626
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009627 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
9628 <info>
9629 OE_TERMINAL[doc] = "Controls how the OpenEmbedded build system spawns interactive terminals on the host development system."
9630 </info>
9631 <glossdef>
9632 <para role="glossdeffirst">
9633<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9634 Controls how the OpenEmbedded build system spawns
9635 interactive terminals on the host development system
9636 (e.g. using the BitBake command with the
9637 <filename>-c devshell</filename> command-line option).
9638 For more information, see the
9639 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009640 in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009641 </para>
9642
9643 <para>
9644 You can use the following values for the
9645 <filename>OE_TERMINAL</filename> variable:
9646 <literallayout class='monospaced'>
9647 auto
9648 gnome
9649 xfce
9650 rxvt
9651 screen
9652 konsole
9653 none
9654 </literallayout>
9655 </para>
9656 </glossdef>
9657 </glossentry>
9658
9659 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
9660 <info>
9661 OEROOT[doc] = "The directory from which the top-level build environment setup script is sourced."
9662 </info>
9663 <glossdef>
9664 <para role="glossdeffirst">
9665<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9666 The directory from which the top-level build environment
9667 setup script is sourced.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009668 The Yocto Project provides a top-level build environment
9669 setup script:
9670 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
9671 When you run this script, the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009672 <filename>OEROOT</filename> variable resolves to the
9673 directory that contains the script.
9674 </para>
9675
9676 <para>
9677 For additional information on how this variable is used,
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009678 see the initialization script.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009679 </para>
9680 </glossdef>
9681 </glossentry>
9682
9683 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
9684 <info>
9685 OLDEST_KERNEL[doc] = "Declares the oldest version of the Linux kernel that the produced binaries must support."
9686 </info>
9687 <glossdef>
9688 <para role="glossdeffirst">
9689<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9690 Declares the oldest version of the Linux kernel that the
9691 produced binaries must support.
9692 This variable is passed into the build of the Embedded
9693 GNU C Library (<filename>glibc</filename>).
9694 </para>
9695
9696 <para>
9697 The default for this variable comes from the
9698 <filename>meta/conf/bitbake.conf</filename> configuration
9699 file.
9700 You can override this default by setting the variable
9701 in a custom distribution configuration file.
9702 </para>
9703 </glossdef>
9704 </glossentry>
9705
9706 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
9707 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009708 OVERRIDES[doc] = "A colon-separated list of overrides that currently apply."
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009709 </info>
9710 <glossdef>
9711 <para role="glossdeffirst">
9712<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009713 A colon-separated list of overrides that currently apply.
9714 Overrides are a BitBake mechanism that allows variables to
9715 be selectively overridden at the end of parsing.
9716 The set of overrides in <filename>OVERRIDES</filename>
9717 represents the "state" during building, which includes
9718 the current recipe being built, the machine for which
9719 it is being built, and so forth.
9720 </para>
9721
9722 <para>
9723 As an example, if the string "an-override" appears as an
9724 element in the colon-separated list in
9725 <filename>OVERRIDES</filename>, then the following
9726 assignment will override <filename>FOO</filename> with the
9727 value "overridden" at the end of parsing:
9728 <literallayout class='monospaced'>
9729 FOO_an-override = "overridden"
9730 </literallayout>
9731 See the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009732 "<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009733 section in the BitBake User Manual for more information on
9734 the overrides mechanism.
9735 </para>
9736
9737 <para>
9738 The default value of <filename>OVERRIDES</filename>
9739 includes the values of the
9740 <link linkend='var-CLASSOVERRIDE'><filename>CLASSOVERRIDE</filename></link>,
9741 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>,
9742 and
9743 <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
9744 variables.
9745 Another important override included by default is
9746 <filename>pn-${PN}</filename>.
9747 This override allows variables to be set for a single
9748 recipe within configuration (<filename>.conf</filename>)
9749 files.
9750 Here is an example:
9751 <literallayout class='monospaced'>
9752 FOO_pn-myrecipe = "myrecipe-specific value"
9753 </literallayout>
9754 <note><title>Tip</title>
9755 An easy way to see what overrides apply is to search for
9756 <filename>OVERRIDES</filename> in the output of the
9757 <filename>bitbake -e</filename> command.
9758 See the
Brad Bishop316dfdd2018-06-25 12:45:53 -04009759 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-debugging-viewing-variable-values'>Viewing Variable Values</ulink>"
9760 section in the Yocto Project Development Tasks
9761 Manual for more information.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06009762 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009763 </para>
9764 </glossdef>
9765 </glossentry>
9766 </glossdiv>
9767
9768 <glossdiv id='var-glossary-p'><title>P</title>
9769
9770 <glossentry id='var-P'><glossterm>P</glossterm>
9771 <info>
9772 P[doc] = "The recipe name and version. P is comprised of ${PN}-${PV}."
9773 </info>
9774 <glossdef>
9775 <para role="glossdeffirst">
9776<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9777 The recipe name and version.
9778 <filename>P</filename> is comprised of the following:
9779 <literallayout class='monospaced'>
9780 ${PN}-${PV}
9781 </literallayout>
9782 </para>
9783 </glossdef>
9784 </glossentry>
9785
9786 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
9787 <info>
9788 PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages."
9789 </info>
9790 <glossdef>
9791 <para role="glossdeffirst">
9792<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9793 The architecture of the resulting package or packages.
9794 </para>
9795
9796 <para>
9797 By default, the value of this variable is set to
9798 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
9799 when building for the target,
Brad Bishop316dfdd2018-06-25 12:45:53 -04009800 <link linkend='var-BUILD_ARCH'><filename>BUILD_ARCH</filename></link>
9801 when building for the
9802 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009803 for the SDK.
Brad Bishop316dfdd2018-06-25 12:45:53 -04009804 <note>
9805 See
9806 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>
9807 for more information.
9808 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009809 However, if your recipe's output packages are built
Brad Bishop316dfdd2018-06-25 12:45:53 -04009810 specific to the target machine rather than generally for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009811 the architecture of the machine, you should set
9812 <filename>PACKAGE_ARCH</filename> to the value of
9813 <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>
9814 in the recipe as follows:
9815 <literallayout class='monospaced'>
9816 PACKAGE_ARCH = "${MACHINE_ARCH}"
9817 </literallayout>
9818 </para>
9819 </glossdef>
9820 </glossentry>
9821
9822 <glossentry id='var-PACKAGE_ARCHS'><glossterm>PACKAGE_ARCHS</glossterm>
9823 <info>
9824 PACKAGE_ARCHS[doc] = "A list of architectures compatible with the given target in order of priority."
9825 </info>
9826 <glossdef>
9827 <para role="glossdeffirst">
9828<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9829 Specifies a list of architectures compatible with
9830 the target machine.
9831 This variable is set automatically and should not
9832 normally be hand-edited.
9833 Entries are separated using spaces and listed in order
9834 of priority.
9835 The default value for
9836 <filename>PACKAGE_ARCHS</filename> is "all any noarch
9837 ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
9838 </para>
9839 </glossdef>
9840 </glossentry>
9841
9842 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
9843 <info>
9844 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."
9845 </info>
9846 <glossdef>
9847 <para role="glossdeffirst">
9848<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9849 Enables easily adding packages to
9850 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
9851 before <filename>${<link linkend='var-PN'>PN</link>}</filename>
9852 so that those added packages can pick up files that would normally be
9853 included in the default package.
9854 </para>
9855 </glossdef>
9856 </glossentry>
9857
9858 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
9859 <info>
9860 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."
9861 </info>
9862 <glossdef>
9863 <para role="glossdeffirst">
9864<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9865 This variable, which is set in the
9866 <filename>local.conf</filename> configuration file found in
9867 the <filename>conf</filename> folder of the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05009868 <link linkend='build-directory'>Build Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009869 specifies the package manager the OpenEmbedded build system
9870 uses when packaging data.
9871 </para>
9872
9873 <para>
9874 You can provide one or more of the following arguments for
9875 the variable:
9876 <literallayout class='monospaced'>
9877 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"
9878 </literallayout>
9879 <note><title>Warning</title>
9880 While it is a legal option, the
Brad Bishop316dfdd2018-06-25 12:45:53 -04009881 <filename>package_tar</filename> class has limited
9882 functionality due to no support for package
9883 dependencies by that backend.
9884 Therefore, it is recommended that you do not use it.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009885 </note>
9886 The build system uses only the first argument in the list
9887 as the package manager when creating your image or SDK.
9888 However, packages will be created using any additional
9889 packaging classes you specify.
9890 For example, if you use the following in your
9891 <filename>local.conf</filename> file:
9892 <literallayout class='monospaced'>
9893 PACKAGE_CLASSES ?= "package_ipk"
9894 </literallayout>
9895 The OpenEmbedded build system uses the IPK package manager
9896 to create your image or SDK.
9897 </para>
9898
9899 <para>
9900 For information on packaging and build performance effects
9901 as a result of the package manager in use, see the
9902 "<link linkend='ref-classes-package'><filename>package.bbclass</filename></link>"
9903 section.
9904 </para>
9905 </glossdef>
9906 </glossentry>
9907
9908 <glossentry id='var-PACKAGE_DEBUG_SPLIT_STYLE'><glossterm>PACKAGE_DEBUG_SPLIT_STYLE</glossterm>
9909 <info>
9910 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)."
9911 </info>
9912 <glossdef>
9913 <para role="glossdeffirst">
9914<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9915 Determines how to split up the binary and debug information
9916 when creating <filename>*-dbg</filename> packages to be
9917 used with the GNU Project Debugger (GDB).
9918 </para>
9919
9920 <para>
9921 With the
9922 <filename>PACKAGE_DEBUG_SPLIT_STYLE</filename> variable,
9923 you can control where debug information, which can include
9924 or exclude source files, is stored:
9925 <itemizedlist>
9926 <listitem><para>
9927 ".debug": Debug symbol files are placed next
9928 to the binary in a <filename>.debug</filename>
9929 directory on the target.
9930 For example, if a binary is installed into
9931 <filename>/bin</filename>, the corresponding debug
9932 symbol files are installed in
9933 <filename>/bin/.debug</filename>.
9934 Source files are placed in
9935 <filename>/usr/src/debug</filename>.
9936 This is the default behavior.
9937 </para></listitem>
9938 <listitem><para>
9939 "debug-file-directory": Debug symbol files are
9940 placed under <filename>/usr/lib/debug</filename>
9941 on the target, and separated by the path from where
9942 the binary is installed.
9943 For example, if a binary is installed in
9944 <filename>/bin</filename>, the corresponding debug
9945 symbols are installed in
9946 <filename>/usr/lib/debug/bin</filename>.
9947 Source files are placed in
9948 <filename>/usr/src/debug</filename>.
9949 </para></listitem>
9950 <listitem><para>
9951 "debug-without-src": The same behavior as
9952 ".debug" previously described with the exception
9953 that no source files are installed.
9954 </para></listitem>.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08009955 <listitem><para>
9956 "debug-with-srcpkg": The same behavior as
9957 ".debug" previously described with the exception
9958 that all source files are placed in a separate
9959 <filename>*-src</filename> pkg.
9960 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009961 </itemizedlist>
9962 </para>
9963
9964 <para>
9965 You can find out more about debugging using GDB by reading
9966 the
9967 "<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 -05009968 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009969 </para>
9970 </glossdef>
9971 </glossentry>
9972
Patrick Williamsf1e5d692016-03-30 15:21:19 -05009973 <glossentry id='var-PACKAGE_EXCLUDE_COMPLEMENTARY'><glossterm>PACKAGE_EXCLUDE_COMPLEMENTARY</glossterm>
9974 <info>
9975 PACKAGE_EXCLUDE_COMPLEMENTARY[doc] = "Prevents specific packages from being installed when you are installing complementary packages."
9976 </info>
9977 <glossdef>
9978 <para role="glossdeffirst">
9979<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
9980 Prevents specific packages from being installed when
9981 you are installing complementary packages.
9982 </para>
9983
9984 <para>
9985 You might find that you want to prevent installing certain
9986 packages when you are installing complementary packages.
9987 For example, if you are using
9988 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
9989 to install <filename>dev-pkgs</filename>, you might not want
9990 to install all packages from a particular multilib.
9991 If you find yourself in this situation, you can use the
9992 <filename>PACKAGE_EXCLUDE_COMPLEMENTARY</filename> variable
9993 to specify regular expressions to match the packages you
9994 want to exclude.
9995 </para>
9996 </glossdef>
9997 </glossentry>
9998
Patrick Williamsc124f4f2015-09-15 14:41:29 -05009999 <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
10000 <info>
10001 PACKAGE_EXCLUDE[doc] = "Packages to exclude from the installation. If a listed package is required, an error is generated."
10002 </info>
10003 <glossdef>
10004 <para role="glossdeffirst">
10005<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10006 Lists packages that should not be installed into an image.
10007 For example:
10008 <literallayout class='monospaced'>
10009 PACKAGE_EXCLUDE = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."
10010 </literallayout>
10011 </para>
10012
10013 <para>
10014 You can set this variable globally in your
10015 <filename>local.conf</filename> file or you can attach it to
10016 a specific image recipe by using the recipe name override:
10017 <literallayout class='monospaced'>
10018 PACKAGE_EXCLUDE_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"
10019 </literallayout>
10020 </para>
10021
10022 <para>
10023 If you choose to not install
10024 a package using this variable and some other package is
10025 dependent on it (i.e. listed in a recipe's
10026 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
10027 variable), the OpenEmbedded build system generates a fatal
10028 installation error.
10029 Because the build system halts the process with a fatal
10030 error, you can use the variable with an iterative
10031 development process to remove specific components from a
10032 system.
10033 </para>
10034
10035 <para>
10036 Support for this variable exists only when using the
10037 IPK and RPM packaging backend.
10038 Support does not exist for DEB.
10039 </para>
10040
10041 <para>
10042 See the
10043 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
10044 and the
10045 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
10046 variables for related information.
10047 </para>
10048 </glossdef>
10049 </glossentry>
10050
10051 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
10052 <info>
10053 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."
10054 </info>
10055 <glossdef>
10056 <para role="glossdeffirst">
10057<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10058 Specifies the list of architectures compatible with the device CPU.
10059 This variable is useful when you build for several different devices that use
10060 miscellaneous processors such as XScale and ARM926-EJS.
10061 </para>
10062 </glossdef>
10063 </glossentry>
10064
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010065 <glossentry id='var-PACKAGE_FEED_ARCHS'><glossterm>PACKAGE_FEED_ARCHS</glossterm>
10066 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040010067 PACKAGE_FEED_ARCHS[doc] = "Optionally specifies user-defined package architectures when constructing package feed URIs."
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010068 </info>
10069 <glossdef>
10070 <para role="glossdeffirst">
10071<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040010072 Optionally specifies the package architectures used as
10073 part of the package feed URIs during the build.
10074 When used, the <filename>PACKAGE_FEED_ARCHS</filename>
10075 variable is appended to the final package feed URI, which
10076 is constructed using the
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010077 <link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
10078 and
10079 <link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>
10080 variables.
Brad Bishop316dfdd2018-06-25 12:45:53 -040010081 <note><title>Tip</title>
10082 You can use the <filename>PACKAGE_FEEDS_ARCHS</filename>
10083 variable to whitelist specific package architectures.
10084 If you do not need to whitelist specific architectures,
10085 which is a common case, you can omit this variable.
10086 Omitting the variable results in all available
10087 architectures for the current machine being included
10088 into remote package feeds.
10089 </note>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050010090 </para>
10091
10092 <para>
10093 Consider the following example where the
10094 <filename>PACKAGE_FEED_URIS</filename>,
10095 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
10096 <filename>PACKAGE_FEED_ARCHS</filename> variables are
10097 defined in your <filename>local.conf</filename> file:
10098 <literallayout class='monospaced'>
10099 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
10100 https://example.com/packagerepos/updates"
10101 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
10102 PACKAGE_FEED_ARCHS = "all core2-64"
10103 </literallayout>
10104 Given these settings, the resulting package feeds are
10105 as follows:
10106 <literallayout class='monospaced'>
10107 https://example.com/packagerepos/release/rpm/all
10108 https://example.com/packagerepos/release/rpm/core2-64
10109 https://example.com/packagerepos/release/rpm-dev/all
10110 https://example.com/packagerepos/release/rpm-dev/core2-64
10111 https://example.com/packagerepos/updates/rpm/all
10112 https://example.com/packagerepos/updates/rpm/core2-64
10113 https://example.com/packagerepos/updates/rpm-dev/all
10114 https://example.com/packagerepos/updates/rpm-dev/core2-64
10115 </literallayout>
10116 </para>
10117 </glossdef>
10118 </glossentry>
10119
10120 <glossentry id='var-PACKAGE_FEED_BASE_PATHS'><glossterm>PACKAGE_FEED_BASE_PATHS</glossterm>
10121 <info>
10122 PACKAGE_FEED_BASE_PATHS[doc] = "Specifies base path used when constructing package feed URIs."
10123 </info>
10124 <glossdef>
10125 <para role="glossdeffirst">
10126<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10127 Specifies the base path used when constructing package feed
10128 URIs.
10129 The <filename>PACKAGE_FEED_BASE_PATHS</filename> variable
10130 makes up the middle portion of a package feed URI used
10131 by the OpenEmbedded build system.
10132 The base path lies between the
10133 <link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
10134 and
10135 <link linkend='var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></link>
10136 variables.
10137 </para>
10138
10139 <para>
10140 Consider the following example where the
10141 <filename>PACKAGE_FEED_URIS</filename>,
10142 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
10143 <filename>PACKAGE_FEED_ARCHS</filename> variables are
10144 defined in your <filename>local.conf</filename> file:
10145 <literallayout class='monospaced'>
10146 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
10147 https://example.com/packagerepos/updates"
10148 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
10149 PACKAGE_FEED_ARCHS = "all core2-64"
10150 </literallayout>
10151 Given these settings, the resulting package feeds are
10152 as follows:
10153 <literallayout class='monospaced'>
10154 https://example.com/packagerepos/release/rpm/all
10155 https://example.com/packagerepos/release/rpm/core2-64
10156 https://example.com/packagerepos/release/rpm-dev/all
10157 https://example.com/packagerepos/release/rpm-dev/core2-64
10158 https://example.com/packagerepos/updates/rpm/all
10159 https://example.com/packagerepos/updates/rpm/core2-64
10160 https://example.com/packagerepos/updates/rpm-dev/all
10161 https://example.com/packagerepos/updates/rpm-dev/core2-64
10162 </literallayout>
10163 </para>
10164 </glossdef>
10165 </glossentry>
10166
10167 <glossentry id='var-PACKAGE_FEED_URIS'><glossterm>PACKAGE_FEED_URIS</glossterm>
10168 <info>
10169 PACKAGE_FEED_URIS[doc] = "Specifies the front portion of the package feed URI used by the OpenEmbedded build system."
10170 </info>
10171 <glossdef>
10172 <para role="glossdeffirst">
10173<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10174 Specifies the front portion of the package feed URI
10175 used by the OpenEmbedded build system.
10176 Each final package feed URI is comprised of
10177 <filename>PACKAGE_FEED_URIS</filename>,
10178 <link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>,
10179 and
10180 <link linkend='var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></link>
10181 variables.
10182 </para>
10183
10184 <para>
10185 Consider the following example where the
10186 <filename>PACKAGE_FEED_URIS</filename>,
10187 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
10188 <filename>PACKAGE_FEED_ARCHS</filename> variables are
10189 defined in your <filename>local.conf</filename> file:
10190 <literallayout class='monospaced'>
10191 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
10192 https://example.com/packagerepos/updates"
10193 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
10194 PACKAGE_FEED_ARCHS = "all core2-64"
10195 </literallayout>
10196 Given these settings, the resulting package feeds are
10197 as follows:
10198 <literallayout class='monospaced'>
10199 https://example.com/packagerepos/release/rpm/all
10200 https://example.com/packagerepos/release/rpm/core2-64
10201 https://example.com/packagerepos/release/rpm-dev/all
10202 https://example.com/packagerepos/release/rpm-dev/core2-64
10203 https://example.com/packagerepos/updates/rpm/all
10204 https://example.com/packagerepos/updates/rpm/core2-64
10205 https://example.com/packagerepos/updates/rpm-dev/all
10206 https://example.com/packagerepos/updates/rpm-dev/core2-64
10207 </literallayout>
10208 </para>
10209 </glossdef>
10210 </glossentry>
10211
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010212 <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
10213 <info>
10214 PACKAGE_GROUP[doc] = "Defines one or more packages to include in an image when a specific item is included in IMAGE_FEATURES."
10215 </info>
10216 <glossdef>
10217 <para role="glossdeffirst">
10218<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10219 The <filename>PACKAGE_GROUP</filename> variable has been
10220 renamed to
10221 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>.
10222 See the variable description for
10223 <filename>FEATURE_PACKAGES</filename> for information.
10224 </para>
10225
10226 <para>
10227 If if you use the <filename>PACKAGE_GROUP</filename>
10228 variable, the OpenEmbedded build system issues a warning
10229 message.
10230 </para>
10231 </glossdef>
10232 </glossentry>
10233
10234 <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
10235 <info>
10236 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."
10237 </info>
10238 <glossdef>
10239 <para role="glossdeffirst">
10240<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10241 The final list of packages passed to the package manager
10242 for installation into the image.
10243 </para>
10244
10245 <para>
10246 Because the package manager controls actual installation
10247 of all packages, the list of packages passed using
10248 <filename>PACKAGE_INSTALL</filename> is not the final list
10249 of packages that are actually installed.
10250 This variable is internal to the image construction
10251 code.
10252 Consequently, in general, you should use the
10253 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
10254 variable to specify packages for installation.
10255 The exception to this is when working with
10256 the
10257 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
10258 image.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050010259 When working with an initial RAM filesystem (initramfs)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010260 image, use the <filename>PACKAGE_INSTALL</filename>
10261 variable.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050010262 For information on creating an initramfs, see the
10263 "<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 -050010264 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010265 </para>
10266 </glossdef>
10267 </glossentry>
10268
10269 <glossentry id='var-PACKAGE_INSTALL_ATTEMPTONLY'><glossterm>PACKAGE_INSTALL_ATTEMPTONLY</glossterm>
10270 <info>
10271 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."
10272 </info>
10273 <glossdef>
10274 <para role="glossdeffirst">
10275<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10276 Specifies a list of packages the OpenEmbedded build
10277 system attempts to install when creating an image.
10278 If a listed package fails to install, the build system
10279 does not generate an error.
10280 This variable is generally not user-defined.
10281 </para>
10282 </glossdef>
10283 </glossentry>
10284
10285 <glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm>PACKAGE_PREPROCESS_FUNCS</glossterm>
10286 <info>
10287 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."
10288 </info>
10289 <glossdef>
10290 <para role="glossdeffirst">
10291<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10292 Specifies a list of functions run to pre-process the
10293 <link linkend='var-PKGD'><filename>PKGD</filename></link>
10294 directory prior to splitting the files out to individual
10295 packages.
10296 </para>
10297 </glossdef>
10298 </glossentry>
10299
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010300 <glossentry id='var-PACKAGE_WRITE_DEPS'><glossterm>PACKAGE_WRITE_DEPS</glossterm>
10301 <info>
10302 PACKAGE_WRITE_DEPS[doc] = "Specifies post-installation and pre-installation script dependencies on native/cross tools."
10303 </info>
10304 <glossdef>
10305 <para role="glossdeffirst">
10306<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10307 Specifies a list of dependencies for post-installation and
10308 pre-installation scripts on native/cross tools.
10309 If your post-installation or pre-installation script can
10310 execute at rootfs creation time rather than on the
10311 target but depends on a native tool in order to execute,
10312 you need to list the tools in
Brad Bishopd5ae7d92018-06-14 09:52:03 -070010313 <filename>PACKAGE_WRITE_DEPS</filename>.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010314 </para>
10315
10316 <para>
10317 For information on running post-installation scripts, see
10318 the
10319 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010320 section in the Yocto Project Development Tasks Manual.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010321 </para>
10322 </glossdef>
10323 </glossentry>
10324
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010325 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
10326 <info>
10327 PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis."
10328 </info>
10329 <glossdef>
10330 <para role="glossdeffirst">
10331<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10332 This variable provides a means of enabling or disabling
10333 features of a recipe on a per-recipe basis.
10334 <filename>PACKAGECONFIG</filename> blocks are defined
10335 in recipes when you specify features and then arguments
10336 that define feature behaviors.
10337 Here is the basic block structure:
10338 <literallayout class='monospaced'>
10339 PACKAGECONFIG ??= "f1 f2 f3 ..."
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010340 PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1,rt-recs-f1"
10341 PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2,rt-recs-f2"
10342 PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3,rt-recs-f3"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010343 </literallayout>
10344 </para>
10345
10346 <para>
10347 The <filename>PACKAGECONFIG</filename>
10348 variable itself specifies a space-separated list of the
10349 features to enable.
10350 Following the features, you can determine the behavior of
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010351 each feature by providing up to five order-dependent
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010352 arguments, which are separated by commas.
10353 You can omit any argument you like but must retain the
10354 separating commas.
10355 The order is important and specifies the following:
10356 <orderedlist>
10357 <listitem><para>Extra arguments
10358 that should be added to the configure script
10359 argument list
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010360 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
10361 or
10362 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010363 if the feature is enabled.</para></listitem>
10364 <listitem><para>Extra arguments
10365 that should be added to <filename>EXTRA_OECONF</filename>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010366 or <filename>PACKAGECONFIG_CONFARGS</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010367 if the feature is disabled.
10368 </para></listitem>
10369 <listitem><para>Additional build dependencies
10370 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
10371 that should be added if the feature is enabled.
10372 </para></listitem>
10373 <listitem><para>Additional runtime dependencies
10374 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
10375 that should be added if the feature is enabled.
10376 </para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010377 <listitem><para>Additional runtime recommendations
10378 (<link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)
10379 that should be added if the feature is enabled.
10380 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010381 </orderedlist>
10382 </para>
10383
10384 <para>
10385 Consider the following
10386 <filename>PACKAGECONFIG</filename> block taken from the
10387 <filename>librsvg</filename> recipe.
10388 In this example the feature is <filename>croco</filename>,
10389 which has three arguments that determine the feature's
10390 behavior.
10391 <literallayout class='monospaced'>
10392 PACKAGECONFIG ??= "croco"
10393 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
10394 </literallayout>
10395 The <filename>--with-croco</filename> and
10396 <filename>libcroco</filename> arguments apply only if
10397 the feature is enabled.
10398 In this case, <filename>--with-croco</filename> is
10399 added to the configure script argument list and
10400 <filename>libcroco</filename> is added to
Brad Bishop316dfdd2018-06-25 12:45:53 -040010401 <filename>DEPENDS</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010402 On the other hand, if the feature is disabled say through
10403 a <filename>.bbappend</filename> file in another layer, then
10404 the second argument <filename>--without-croco</filename> is
10405 added to the configure script rather than
10406 <filename>--with-croco</filename>.
10407 </para>
10408
10409 <para>
10410 The basic <filename>PACKAGECONFIG</filename> structure
10411 previously described holds true regardless of whether you
10412 are creating a block or changing a block.
10413 When creating a block, use the structure inside your
10414 recipe.
10415 </para>
10416
10417 <para>
10418 If you want to change an existing
10419 <filename>PACKAGECONFIG</filename> block, you can do so
10420 one of two ways:
10421 <itemizedlist>
10422 <listitem><para><emphasis>Append file:</emphasis>
10423 Create an append file named
10424 <replaceable>recipename</replaceable><filename>.bbappend</filename>
10425 in your layer and override the value of
10426 <filename>PACKAGECONFIG</filename>.
10427 You can either completely override the variable:
10428 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010429 PACKAGECONFIG = "f4 f5"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010430 </literallayout>
10431 Or, you can just append the variable:
10432 <literallayout class='monospaced'>
10433 PACKAGECONFIG_append = " f4"
10434 </literallayout></para></listitem>
10435 <listitem><para><emphasis>Configuration file:</emphasis>
10436 This method is identical to changing the block
10437 through an append file except you edit your
10438 <filename>local.conf</filename> or
10439 <filename><replaceable>mydistro</replaceable>.conf</filename> file.
10440 As with append files previously described,
10441 you can either completely override the variable:
10442 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080010443 PACKAGECONFIG_pn-<replaceable>recipename</replaceable> = "f4 f5"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010444 </literallayout>
10445 Or, you can just amend the variable:
10446 <literallayout class='monospaced'>
10447 PACKAGECONFIG_append_pn-<replaceable>recipename</replaceable> = " f4"
10448 </literallayout></para></listitem>
10449 </itemizedlist>
10450 </para>
10451 </glossdef>
10452 </glossentry>
10453
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010454 <glossentry id='var-PACKAGECONFIG_CONFARGS'><glossterm>PACKAGECONFIG_CONFARGS</glossterm>
10455 <info>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010456 PACKAGECONFIG_CONFARGS[doc] = "A space-separated list of configuration options generated from the PACKAGECONFIG setting."
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010457 </info>
10458 <glossdef>
10459 <para role="glossdeffirst">
10460<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10461 A space-separated list of configuration options generated
10462 from the
10463 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
10464 setting.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010465 </para>
10466
10467 <para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010468 Classes such as
10469 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
10470 and
10471 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
10472 use <filename>PACKAGECONFIG_CONFARGS</filename> to pass
Brad Bishop316dfdd2018-06-25 12:45:53 -040010473 <filename>PACKAGECONFIG</filename> options to
10474 <filename>configure</filename> and
Brad Bishop6e60e8b2018-02-01 10:27:11 -050010475 <filename>cmake</filename>, respectively.
10476 If you are using
10477 <filename>PACKAGECONFIG</filename> but not a class that
10478 handles the <filename>do_configure</filename> task, then
10479 you need to use
10480 <filename>PACKAGECONFIG_CONFARGS</filename> appropriately.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010481 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010482 </glossdef>
10483 </glossentry>
10484
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010485 <glossentry id='var-PACKAGEGROUP_DISABLE_COMPLEMENTARY'><glossterm>PACKAGEGROUP_DISABLE_COMPLEMENTARY</glossterm>
10486 <info>
10487 PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents automatic creation of the normal complementary packages such as -dev and -dbg in a packagegroup recipe."
10488 </info>
10489 <glossdef>
10490 <para role="glossdeffirst">
10491<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10492 For recipes inheriting the
10493 <link linkend='ref-classes-packagegroup'><filename>packagegroup</filename></link>
10494 class, setting
10495 <filename>PACKAGEGROUP_DISABLE_COMPLEMENTARY</filename> to
10496 "1" specifies that the normal complementary packages
10497 (i.e. <filename>-dev</filename>,
10498 <filename>-dbg</filename>, and so forth) should not be
10499 automatically created by the
10500 <filename>packagegroup</filename> recipe, which is the
10501 default behavior.
10502 </para>
10503 </glossdef>
10504 </glossentry>
10505
10506 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
10507 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040010508 PACKAGES[doc] = "The list of packages the recipe creates."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010509 </info>
10510 <glossdef>
10511 <para role="glossdeffirst">
10512<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040010513 The list of packages the recipe creates.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010514 The default value is the following:
10515 <literallayout class='monospaced'>
10516 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
10517 </literallayout>
10518 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010519
10520 <para>
10521 During packaging, the
10522 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
10523 task goes through <filename>PACKAGES</filename> and uses
10524 the
10525 <link linkend='var-FILES'><filename>FILES</filename></link>
10526 variable corresponding to each package to assign files to
10527 the package.
10528 If a file matches the <filename>FILES</filename> variable
10529 for more than one package in <filename>PACKAGES</filename>,
10530 it will be assigned to the earliest (leftmost) package.
10531 </para>
10532
10533 <para>
10534 Packages in the variable's list that are empty (i.e. where
10535 none of the patterns in
10536 <filename>FILES_</filename><replaceable>pkg</replaceable>
10537 match any files installed by the
10538 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
10539 task) are not generated, unless generation is forced through
10540 the
10541 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>
10542 variable.
10543 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010544 </glossdef>
10545 </glossentry>
10546
10547 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
10548 <info>
10549 PACKAGES_DYNAMIC[doc] = "A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes."
10550 </info>
10551 <glossdef>
10552 <para role="glossdeffirst">
10553<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10554 A promise that your recipe satisfies runtime dependencies
10555 for optional modules that are found in other recipes.
10556 <filename>PACKAGES_DYNAMIC</filename>
10557 does not actually satisfy the dependencies, it only states that
10558 they should be satisfied.
10559 For example, if a hard, runtime dependency
10560 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
10561 of another package is satisfied
10562 at build time through the <filename>PACKAGES_DYNAMIC</filename>
10563 variable, but a package with the module name is never actually
10564 produced, then the other package will be broken.
10565 Thus, if you attempt to include that package in an image,
10566 you will get a dependency failure from the packaging system
10567 during the
10568 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
10569 task.
10570 </para>
10571
10572 <para>
10573 Typically, if there is a chance that such a situation can
10574 occur and the package that is not created is valid
10575 without the dependency being satisfied, then you should use
10576 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
10577 (a soft runtime dependency) instead of
10578 <filename>RDEPENDS</filename>.
10579 </para>
10580
10581 <para>
10582 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
10583 variable when you are splitting packages, see the
10584 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010585 in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010586 </para>
10587 </glossdef>
10588 </glossentry>
10589
10590 <glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm>
10591 <info>
10592 PACKAGESPLITFUNCS[doc] = "Specifies a list of functions run to perform additional splitting of files into individual packages."
10593 </info>
10594 <glossdef>
10595 <para role="glossdeffirst">
10596<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10597 Specifies a list of functions run to perform additional
10598 splitting of files into individual packages.
10599 Recipes can either prepend to this variable or prepend
10600 to the <filename>populate_packages</filename> function
10601 in order to perform additional package splitting.
10602 In either case, the function should set
10603 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>,
10604 <link linkend='var-FILES'><filename>FILES</filename></link>,
10605 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
10606 and other packaging variables appropriately in order to
10607 perform the desired splitting.
10608 </para>
10609 </glossdef>
10610 </glossentry>
10611
10612 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
10613 <info>
10614 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."
10615 </info>
10616 <glossdef>
10617 <para role="glossdeffirst">
10618<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10619 Extra options passed to the <filename>make</filename>
10620 command during the
10621 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
10622 task in order to specify parallel compilation on the local
10623 build host.
10624 This variable is usually in the form "-j <replaceable>x</replaceable>",
10625 where <replaceable>x</replaceable> represents the maximum
10626 number of parallel threads <filename>make</filename> can
10627 run.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010628 <note><title>Caution</title>
10629 In order for <filename>PARALLEL_MAKE</filename> to be
10630 effective, <filename>make</filename> must be called
10631 with
10632 <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.
10633 An easy way to ensure this is to use the
10634 <filename>oe_runmake</filename> function.
10635 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010636 </para>
10637
10638 <para>
10639 By default, the OpenEmbedded build system automatically
10640 sets this variable to be equal to the number of cores the
10641 build system uses.
10642 <note>
10643 If the software being built experiences dependency
10644 issues during the <filename>do_compile</filename>
10645 task that result in race conditions, you can clear
10646 the <filename>PARALLEL_MAKE</filename> variable within
10647 the recipe as a workaround.
10648 For information on addressing race conditions, see the
10649 "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010650 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010651 </note>
10652 For single socket systems (i.e. one CPU), you should not
10653 have to override this variable to gain optimal parallelism
10654 during builds.
10655 However, if you have very large systems that employ
10656 multiple physical CPUs, you might want to make sure the
10657 <filename>PARALLEL_MAKE</filename> variable is not
10658 set higher than "-j 20".
10659 </para>
10660
10661 <para>
10662 For more information on speeding up builds, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040010663 "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"
10664 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010665 </para>
10666 </glossdef>
10667 </glossentry>
10668
10669 <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
10670 <info>
10671 PARALLEL_MAKEINST[doc] = "Extra options passed to the make install command during the do_install task in order to specify parallel installation."
10672 </info>
10673 <glossdef>
10674 <para role="glossdeffirst">
10675<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10676 Extra options passed to the
10677 <filename>make install</filename> command during the
10678 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
10679 task in order to specify parallel installation.
10680 This variable defaults to the value of
10681 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010682 <note><title>Notes and Cautions</title>
10683 <para>In order for <filename>PARALLEL_MAKEINST</filename>
10684 to be
10685 effective, <filename>make</filename> must be called
10686 with
10687 <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.
10688 An easy way to ensure this is to use the
10689 <filename>oe_runmake</filename> function.</para>
10690
10691 <para>If the software being built experiences
10692 dependency issues during the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010693 <filename>do_install</filename> task that result in
10694 race conditions, you can clear the
10695 <filename>PARALLEL_MAKEINST</filename> variable within
10696 the recipe as a workaround.
10697 For information on addressing race conditions, see the
10698 "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050010699 section in the Yocto Project Development Tasks Manual.
10700 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010701 </note>
10702 </para>
10703 </glossdef>
10704 </glossentry>
10705
10706 <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
10707 <info>
10708 PATCHRESOLVE[doc] = "Enable or disable interactive patch resolution."
10709 </info>
10710 <glossdef>
10711 <para role="glossdeffirst">
10712<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10713 Determines the action to take when a patch fails.
10714 You can set this variable to one of two values: "noop" and
10715 "user".
10716 </para>
10717
10718 <para>
10719 The default value of "noop" causes the build to simply fail
10720 when the OpenEmbedded build system cannot successfully
10721 apply a patch.
10722 Setting the value to "user" causes the build system to
10723 launch a shell and places you in the right location so that
10724 you can manually resolve the conflicts.
10725 </para>
10726
10727 <para>
10728 Set this variable in your
10729 <filename>local.conf</filename> file.
10730 </para>
10731 </glossdef>
10732 </glossentry>
10733
10734 <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
10735 <info>
10736 PATCHTOOL[doc] = "Specifies the utility used to apply patches for a recipe during do_patch."
10737 </info>
10738 <glossdef>
10739 <para role="glossdeffirst">
10740<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10741 Specifies the utility used to apply patches for a recipe
10742 during the
10743 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
10744 task.
10745 You can specify one of three utilities: "patch", "quilt", or
10746 "git".
10747 The default utility used is "quilt" except for the
10748 quilt-native recipe itself.
10749 Because the quilt tool is not available at the
10750 time quilt-native is being patched, it uses "patch".
10751 </para>
10752
10753 <para>
10754 If you wish to use an alternative patching tool, set the
10755 variable in the recipe using one of the following:
10756 <literallayout class='monospaced'>
10757 PATCHTOOL = "patch"
10758 PATCHTOOL = "quilt"
10759 PATCHTOOL = "git"
10760 </literallayout>
10761 </para>
10762 </glossdef>
10763 </glossentry>
10764
10765 <glossentry id='var-PE'><glossterm>PE</glossterm>
10766 <info>
10767 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."
10768 </info>
10769 <glossdef>
10770 <para role="glossdeffirst">
10771<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10772 The epoch of the recipe.
10773 By default, this variable is unset.
10774 The variable is used to make upgrades possible when the
10775 versioning scheme changes in some backwards incompatible
10776 way.
10777 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010778
10779 <para>
10780 <filename>PE</filename> is the default value of the
10781 <link linkend='var-PKGE'><filename>PKGE</filename></link>
10782 variable.
10783 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010784 </glossdef>
10785 </glossentry>
10786
10787 <glossentry id='var-PF'><glossterm>PF</glossterm>
10788 <info>
10789 PF[doc] = "Specifies the recipe or package name and includes all version and revision numbers. This variable is comprised of ${PN}-${EXTENDPE}${PV}-${PR}."
10790 </info>
10791 <glossdef>
10792 <para role="glossdeffirst">
10793<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10794 Specifies the recipe or package name and includes all version and revision
10795 numbers (i.e. <filename>glibc-2.13-r20+svnr15508/</filename> and
10796 <filename>bash-4.2-r1/</filename>).
10797 This variable is comprised of the following:
10798 <literallayout class='monospaced'>
10799 ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
10800 </literallayout>
10801 </para>
10802 </glossdef>
10803 </glossentry>
10804
10805 <glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm>
10806 <info>
10807 PIXBUF_PACKAGES[doc] = "When a recipe inherits the pixbufcache class, this variable identifies packages that contain the pixbuf loaders used with gdk-pixbuf."
10808 </info>
10809 <glossdef>
10810 <para role="glossdeffirst">
10811<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10812 When inheriting the
10813 <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link>
10814 class, this variable identifies packages that contain
10815 the pixbuf loaders used with
10816 <filename>gdk-pixbuf</filename>.
10817 By default, the <filename>pixbufcache</filename> class
10818 assumes that the loaders are in the recipe's main package
10819 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
10820 Use this variable if the loaders you need are in a package
10821 other than that main package.
10822 </para>
10823 </glossdef>
10824 </glossentry>
10825
10826 <glossentry id='var-PKG'><glossterm>PKG</glossterm>
10827 <info>
10828 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."
10829 </info>
10830 <glossdef>
10831 <para role="glossdeffirst">
10832<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10833 The name of the resulting package created by the
10834 OpenEmbedded build system.
10835 <note>
10836 When using the <filename>PKG</filename> variable, you
10837 must use a package name override.
10838 </note>
10839 </para>
10840
10841 <para>
10842 For example, when the
10843 <link linkend='ref-classes-debian'><filename>debian</filename></link>
10844 class renames the output package, it does so by setting
10845 <filename>PKG_<replaceable>packagename</replaceable></filename>.
10846 </para>
10847 </glossdef>
10848 </glossentry>
10849
10850 <glossentry id='var-PKG_CONFIG_PATH'><glossterm>PKG_CONFIG_PATH</glossterm>
10851 <info>
10852 PKG_CONFIG_PATH[doc] = "Path to pkg-config files for the current build context."
10853 </info>
10854 <glossdef>
10855 <para role="glossdeffirst">
10856<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10857 The path to <filename>pkg-config</filename> files for the
10858 current build context.
10859 <filename>pkg-config</filename> reads this variable
10860 from the environment.
10861 </para>
10862 </glossdef>
10863 </glossentry>
10864
10865 <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
10866 <info>
10867 PKGD[doc] = "Points to the destination directory for files to be packaged before they are split into individual packages."
10868 </info>
10869 <glossdef>
10870 <para role="glossdeffirst">
10871<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10872 Points to the destination directory for files to be
10873 packaged before they are split into individual packages.
10874 This directory defaults to the following:
10875 <literallayout class='monospaced'>
10876 ${WORKDIR}/package
10877 </literallayout>
10878 </para>
10879
10880 <para>
10881 Do not change this default.
10882 </para>
10883 </glossdef>
10884 </glossentry>
10885
10886 <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
10887 <info>
10888 PKGDATA_DIR[doc] = "Points to a shared, global-state directory that holds data generated during the packaging process."
10889 </info>
10890 <glossdef>
10891 <para role="glossdeffirst">
10892<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10893 Points to a shared, global-state directory that holds data
10894 generated during the packaging process.
10895 During the packaging process, the
10896 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
10897 task packages data for each recipe and installs it into
10898 this temporary, shared area.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010899 This directory defaults to the following, which you should
10900 not change:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010901 <literallayout class='monospaced'>
10902 ${STAGING_DIR_HOST}/pkgdata
10903 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010904 For examples of how this data is used, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040010905 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
10906 section in the Yocto Project Overview and Concepts Manual
10907 and the
10908 "<ulink url='&YOCTO_DOCS_DEV_URL;#viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></ulink>"
10909 section in the Yocto Project Development Tasks Manual.
10910 For more information on the shared, global-state directory,
10911 see
10912 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010913 </para>
10914 </glossdef>
10915 </glossentry>
10916
10917 <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
10918 <info>
10919 PKGDEST[doc] = "Points to the parent directory for files to be packaged after they have been split into individual packages."
10920 </info>
10921 <glossdef>
10922 <para role="glossdeffirst">
10923<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
10924 Points to the parent directory for files to be packaged
10925 after they have been split into individual packages.
10926 This directory defaults to the following:
10927 <literallayout class='monospaced'>
10928 ${WORKDIR}/packages-split
10929 </literallayout>
10930 </para>
10931
10932 <para>
10933 Under this directory, the build system creates
10934 directories for each package specified in
10935 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
10936 Do not change this default.
10937 </para>
10938 </glossdef>
10939 </glossentry>
10940
10941 <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
10942 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010943 PKGDESTWORK[doc] = "Points to a temporary work area where the do_package task saves package metadata."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010944 </info>
10945 <glossdef>
10946 <para role="glossdeffirst">
10947<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010948 Points to a temporary work area where the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010949 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010950 task saves package metadata.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010951 The <filename>PKGDESTWORK</filename> location defaults to
10952 the following:
10953 <literallayout class='monospaced'>
10954 ${WORKDIR}/pkgdata
10955 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010956 Do not change this default.
10957 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010958
10959 <para>
10960 The
10961 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
10962 task copies the package metadata from
10963 <filename>PKGDESTWORK</filename> to
10964 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
10965 to make it available globally.
10966 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010967 </glossdef>
10968 </glossentry>
10969
10970 <glossentry id='var-PKGE'><glossterm>PKGE</glossterm>
10971 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010972 PKGE[doc] = "The epoch of the package(s) built by the recipe."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010973 </info>
10974 <glossdef>
10975 <para role="glossdeffirst">
10976<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010977 The epoch of the package(s) built by the recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010978 By default, <filename>PKGE</filename> is set to
10979 <link linkend='var-PE'><filename>PE</filename></link>.
10980 </para>
10981 </glossdef>
10982 </glossentry>
10983
10984 <glossentry id='var-PKGR'><glossterm>PKGR</glossterm>
10985 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010986 PKGR[doc] = "The revision of the package(s) built by the recipe."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010987 </info>
10988 <glossdef>
10989 <para role="glossdeffirst">
10990<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060010991 The revision of the package(s) built by the recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050010992 By default, <filename>PKGR</filename> is set to
10993 <link linkend='var-PR'><filename>PR</filename></link>.
10994 </para>
10995 </glossdef>
10996 </glossentry>
10997
10998 <glossentry id='var-PKGV'><glossterm>PKGV</glossterm>
10999 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011000 PKGV[doc] = "The version of the package(s) built by the recipe."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011001 </info>
11002 <glossdef>
11003 <para role="glossdeffirst">
11004<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011005 The version of the package(s) built by the
11006 recipe.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011007 By default, <filename>PKGV</filename> is set to
11008 <link linkend='var-PV'><filename>PV</filename></link>.
11009 </para>
11010 </glossdef>
11011 </glossentry>
11012
11013 <glossentry id='var-PN'><glossterm>PN</glossterm>
11014 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011015 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 -050011016 </info>
11017 <glossdef>
11018 <para role="glossdeffirst">
11019<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11020 This variable can have two separate functions depending on the context: a recipe
11021 name or a resulting package name.
11022 </para>
11023
11024 <para>
11025 <filename>PN</filename> refers to a recipe name in the context of a file used
11026 by the OpenEmbedded build system as input to create a package.
11027 The name is normally extracted from the recipe file name.
11028 For example, if the recipe is named
11029 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
11030 will be "expat".
11031 </para>
11032
11033 <para>
11034 The variable refers to a package name in the context of a file created or produced by the
11035 OpenEmbedded build system.
11036 </para>
11037
11038 <para>
11039 If applicable, the <filename>PN</filename> variable also contains any special
11040 suffix or prefix.
11041 For example, using <filename>bash</filename> to build packages for the native
11042 machine, <filename>PN</filename> is <filename>bash-native</filename>.
11043 Using <filename>bash</filename> to build packages for the target and for Multilib,
11044 <filename>PN</filename> would be <filename>bash</filename> and
11045 <filename>lib64-bash</filename>, respectively.
11046 </para>
11047 </glossdef>
11048 </glossentry>
11049
11050 <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>
11051 <info>
11052 PNBLACKLIST[doc] = "Lists recipes you do not want the OpenEmbedded build system to build."
11053 </info>
11054 <glossdef>
11055 <para role="glossdeffirst">
11056<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11057 Lists recipes you do not want the OpenEmbedded build system
11058 to build.
11059 This variable works in conjunction with the
11060 <link linkend='ref-classes-blacklist'><filename>blacklist</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011061 class, which is inherited globally.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011062 </para>
11063
11064 <para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011065 To prevent a recipe from being built, use the
11066 <filename>PNBLACKLIST</filename> variable in your
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011067 <filename>local.conf</filename> file.
11068 Here is an example that prevents
11069 <filename>myrecipe</filename> from being built:
11070 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011071 PNBLACKLIST[myrecipe] = "Not supported by our organization."
11072 </literallayout>
11073 </para>
11074 </glossdef>
11075 </glossentry>
11076
11077 <glossentry id='var-POPULATE_SDK_POST_HOST_COMMAND'><glossterm>POPULATE_SDK_POST_HOST_COMMAND</glossterm>
11078 <info>
11079 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."
11080 </info>
11081 <glossdef>
11082 <para role="glossdeffirst">
11083<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11084 Specifies a list of functions to call once the
11085 OpenEmbedded build system has created the host part of
11086 the SDK.
11087 You can specify functions separated by semicolons:
11088 <literallayout class='monospaced'>
11089 POPULATE_SDK_POST_HOST_COMMAND += "<replaceable>function</replaceable>; ... "
11090 </literallayout>
11091 </para>
11092
11093 <para>
11094 If you need to pass the SDK path to a command
11095 within a function, you can use
11096 <filename>${SDK_DIR}</filename>, which points to
11097 the parent directory used by the OpenEmbedded build
11098 system when creating SDK output.
11099 See the
11100 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
11101 variable for more information.
11102 </para>
11103 </glossdef>
11104 </glossentry>
11105
11106 <glossentry id='var-POPULATE_SDK_POST_TARGET_COMMAND'><glossterm>POPULATE_SDK_POST_TARGET_COMMAND</glossterm>
11107 <info>
11108 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."
11109 </info>
11110 <glossdef>
11111 <para role="glossdeffirst">
11112<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11113 Specifies a list of functions to call once the
11114 OpenEmbedded build system has created the target part of
11115 the SDK.
11116 You can specify functions separated by semicolons:
11117 <literallayout class='monospaced'>
11118 POPULATE_SDK_POST_TARGET_COMMAND += "<replaceable>function</replaceable>; ... "
11119 </literallayout>
11120 </para>
11121
11122 <para>
11123 If you need to pass the SDK path to a command
11124 within a function, you can use
11125 <filename>${SDK_DIR}</filename>, which points to
11126 the parent directory used by the OpenEmbedded build
11127 system when creating SDK output.
11128 See the
11129 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
11130 variable for more information.
11131 </para>
11132 </glossdef>
11133 </glossentry>
11134
11135 <glossentry id='var-PR'><glossterm>PR</glossterm>
11136 <info>
11137 PR[doc] = "The revision of the recipe. The default value for this variable is 'r0'."
11138 </info>
11139 <glossdef>
11140 <para role="glossdeffirst">
11141<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011142 The revision of the recipe. The default value for this
11143 variable is "r0".
11144 Subsequent revisions of the recipe conventionally have the
11145 values "r1", "r2", and so forth.
11146 When
11147 <link linkend='var-PV'><filename>PV</filename></link>
11148 increases, <filename>PR</filename> is conventionally reset
11149 to "r0".
11150 <note>
11151 The OpenEmbedded build system does not need the aid of
11152 <filename>PR</filename> to know when to rebuild a
11153 recipe.
11154 The build system uses the task
Brad Bishop316dfdd2018-06-25 12:45:53 -040011155 <ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>input checksums</ulink>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011156 along with the
11157 <link linkend='structure-build-tmp-stamps'>stamp</link>
11158 and
Brad Bishop316dfdd2018-06-25 12:45:53 -040011159 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state cache</ulink>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011160 mechanisms.
11161 </note>
11162 The <filename>PR</filename> variable primarily becomes
11163 significant when a package manager dynamically installs
11164 packages on an already built image.
11165 In this case, <filename>PR</filename>, which is the default
11166 value of
11167 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
11168 helps the package manager distinguish which package is the
11169 most recent one in cases where many packages have the same
11170 <filename>PV</filename> (i.e. <filename>PKGV</filename>).
11171 A component having many packages with the same
11172 <filename>PV</filename> usually means that the packages all
11173 install the same upstream version, but with later
11174 (<filename>PR</filename>) version packages including
11175 packaging fixes.
11176 <note>
11177 <filename>PR</filename> does not need to be increased
11178 for changes that do not change the package contents or
11179 metadata.
11180 </note>
11181 Because manually managing <filename>PR</filename> can be
11182 cumbersome and error-prone, an automated solution exists.
11183 See the
11184 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011185 section in the Yocto Project Development Tasks Manual
11186 for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011187 </para>
11188 </glossdef>
11189 </glossentry>
11190
11191 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
11192 <info>
11193 PREFERRED_PROVIDER[doc] = "If multiple recipes provide an item, this variable determines which recipe should be given preference."
11194 </info>
11195 <glossdef>
11196 <para role="glossdeffirst">
11197<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040011198 If multiple recipes provide the same item, this variable
11199 determines which recipe is preferred and thus provides
11200 the item (i.e. the preferred provider).
11201 You should always suffix this variable with the name of the
11202 provided item.
11203 And, you should define the variable using the preferred
11204 recipe's name
11205 (<link linkend='var-PN'><filename>PN</filename></link>).
11206 Here is a common example:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011207 <literallayout class='monospaced'>
11208 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
Brad Bishop316dfdd2018-06-25 12:45:53 -040011209 </literallayout>
11210 In the previous example, multiple recipes are providing
11211 "virtual/kernel".
11212 The <filename>PREFERRED_PROVIDER</filename> variable is
11213 set with the name (<filename>PN</filename>) of the recipe
11214 you prefer to provide "virtual/kernel".
11215 </para>
11216
11217 <para>
11218 Following are more examples:
11219 <literallayout class='monospaced'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011220 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
11221 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
11222 </literallayout>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011223 For more information, see the
11224 "<ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>Using Virtual Providers</ulink>"
11225 section in the Yocto Project Development Tasks Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011226 <note>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011227 If you use a <filename>virtual/*</filename> item
11228 with <filename>PREFERRED_PROVIDER</filename>, then any
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011229 recipe that
11230 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011231 that item but is not selected (defined) by
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011232 <filename>PREFERRED_PROVIDER</filename> is prevented
11233 from building, which is usually desirable since this
11234 mechanism is designed to select between mutually
11235 exclusive alternative providers.
11236 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011237 </para>
11238 </glossdef>
11239 </glossentry>
11240
11241 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
11242 <info>
11243 PREFERRED_VERSION[doc] = "If there are multiple versions of recipes available, this variable determines which recipe should be given preference."
11244 </info>
11245 <glossdef>
11246 <para role="glossdeffirst">
11247<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011248 If multiple versions of recipes exist, this
11249 variable determines which version is given preference.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011250 You must always suffix the variable with the
11251 <link linkend='var-PN'><filename>PN</filename></link>
11252 you want to select, and you should set the
11253 <link linkend='var-PV'><filename>PV</filename></link>
11254 accordingly for precedence.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011255 </para>
11256
11257 <para>
11258 The <filename>PREFERRED_VERSION</filename> variable
11259 supports limited wildcard use through the
11260 "<filename>%</filename>" character.
11261 You can use the character to match any number of
11262 characters, which can be useful when specifying versions
11263 that contain long revision numbers that potentially change.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011264 Here are two examples:
11265 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011266 PREFERRED_VERSION_python = "3.4.0"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011267 PREFERRED_VERSION_linux-yocto = "4.12%"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011268 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011269 <note><title>Important</title>
11270 The use of the "<filename>%</filename>" character
11271 is limited in that it only works at the end of the
11272 string.
11273 You cannot use the wildcard character in any other
11274 location of the string.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011275 </note>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080011276 </para>
11277
11278 <para>
11279 The specified version is matched against
11280 <link linkend='var-PV'><filename>PV</filename></link>,
11281 which does not necessarily match the version part of
11282 the recipe's filename.
11283 For example, consider two recipes
11284 <filename>foo_1.2.bb</filename> and
11285 <filename>foo_git.bb</filename> where
11286 <filename>foo_git.bb</filename> contains the following
11287 assignment:
11288 <literallayout class='monospaced'>
11289 PV = "1.1+git${SRCPV}"
11290 </literallayout>
11291 In this case, the correct way to select
11292 <filename>foo_git.bb</filename> is by using an
11293 assignment such as the following:
11294 <literallayout class='monospaced'>
11295 PREFERRED_VERSION_foo = "1.1+git%"
11296 </literallayout>
11297 Compare that previous example against the following
11298 incorrect example, which does not work:
11299 <literallayout class='monospaced'>
11300 PREFERRED_VERSION_foo = "git"
11301 </literallayout>
11302 </para>
11303
11304 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011305 Sometimes the <filename>PREFERRED_VERSION</filename>
11306 variable can be set by configuration files in a way that
11307 is hard to change.
11308 You can use
11309 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
11310 to set a machine-specific override.
11311 Here is an example:
11312 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011313 PREFERRED_VERSION_linux-yocto_qemux86 = "4.12%"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011314 </literallayout>
11315 Although not recommended, worst case, you can also use the
11316 "forcevariable" override, which is the strongest override
11317 possible.
11318 Here is an example:
11319 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011320 PREFERRED_VERSION_linux-yocto_forcevariable = "4.12%"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011321 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011322 <note>
11323 The <filename>_forcevariable</filename> override is
11324 not handled specially.
11325 This override only works because the default value of
Brad Bishop316dfdd2018-06-25 12:45:53 -040011326 <filename>OVERRIDES</filename> includes
11327 "forcevariable".
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011328 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011329 </para>
11330 </glossdef>
11331 </glossentry>
11332
11333 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
11334 <info>
11335 PREMIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."
11336 </info>
11337 <glossdef>
11338 <para role="glossdeffirst">
11339<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11340 Specifies additional paths from which the OpenEmbedded
11341 build system gets source code.
11342 When the build system searches for source code, it first
11343 tries the local download directory.
11344 If that location fails, the build system tries locations
11345 defined by <filename>PREMIRRORS</filename>, the upstream
11346 source, and then locations specified by
11347 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
11348 in that order.
11349 </para>
11350
11351 <para>
11352 Assuming your distribution
11353 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
11354 is "poky", the default value for
11355 <filename>PREMIRRORS</filename> is defined in the
11356 <filename>conf/distro/poky.conf</filename> file in the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011357 <filename>meta-poky</filename> Git repository.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011358 </para>
11359
11360 <para>
11361 Typically, you could add a specific server for the
11362 build system to attempt before any others by adding
11363 something like the following to the
11364 <filename>local.conf</filename> configuration file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011365 <link linkend='build-directory'>Build Directory</link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011366 <literallayout class='monospaced'>
11367 PREMIRRORS_prepend = "\
11368 git://.*/.* http://www.yoctoproject.org/sources/ \n \
11369 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
11370 http://.*/.* http://www.yoctoproject.org/sources/ \n \
11371 https://.*/.* http://www.yoctoproject.org/sources/ \n"
11372 </literallayout>
11373 These changes cause the build system to intercept
11374 Git, FTP, HTTP, and HTTPS requests and direct them to
11375 the <filename>http://</filename> sources mirror.
11376 You can use <filename>file://</filename> URLs to point
11377 to local directories or network shares as well.
11378 </para>
11379 </glossdef>
11380 </glossentry>
11381
11382 <glossentry id='var-PRIORITY'><glossterm>PRIORITY</glossterm>
11383 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011384 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 -050011385 </info>
11386 <glossdef>
11387 <para role="glossdeffirst">
11388<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11389 Indicates the importance of a package.
11390 </para>
11391
11392 <para>
11393 <filename>PRIORITY</filename> is considered to be part of
11394 the distribution policy because the importance of any given
11395 recipe depends on the purpose for which the distribution
11396 is being produced.
11397 Thus, <filename>PRIORITY</filename> is not normally set
11398 within recipes.
11399 </para>
11400
11401 <para>
11402 You can set <filename>PRIORITY</filename> to "required",
11403 "standard", "extra", and "optional", which is the default.
11404 </para>
11405 </glossdef>
11406 </glossentry>
11407
11408 <glossentry id='var-PRIVATE_LIBS'><glossterm>PRIVATE_LIBS</glossterm>
11409 <info>
11410 PRIVATE_LIBS[doc] = "Specifies libraries installed within a recipe that should be ignored by the OpenEmbedded build system's shared library resolver."
11411 </info>
11412 <glossdef>
11413 <para role="glossdeffirst">
11414<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11415 Specifies libraries installed within a recipe that
11416 should be ignored by the OpenEmbedded build system's
11417 shared library resolver.
11418 This variable is typically used when software being
11419 built by a recipe has its own private versions of a
11420 library normally provided by another recipe.
11421 In this case, you would not want the package containing
11422 the private libraries to be set as a dependency on other
11423 unrelated packages that should instead depend on the
11424 package providing the standard version of the library.
11425 </para>
11426
11427 <para>
11428 Libraries specified in this variable should be specified
11429 by their file name.
11430 For example, from the Firefox recipe in meta-browser:
11431 <literallayout class='monospaced'>
11432 PRIVATE_LIBS = "libmozjs.so \
11433 libxpcom.so \
11434 libnspr4.so \
11435 libxul.so \
11436 libmozalloc.so \
11437 libplc4.so \
11438 libplds4.so"
11439 </literallayout>
11440 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011441
11442 <para>
11443 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040011444 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
11445 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011446 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011447 </glossdef>
11448 </glossentry>
11449
11450 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
11451 <info>
11452 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."
11453 </info>
11454 <glossdef>
11455 <para role="glossdeffirst">
11456<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11457 A list of aliases by which a particular recipe can be
11458 known.
11459 By default, a recipe's own
11460 <filename><link linkend='var-PN'>PN</link></filename>
11461 is implicitly already in its <filename>PROVIDES</filename>
11462 list.
11463 If a recipe uses <filename>PROVIDES</filename>, the
11464 additional aliases are synonyms for the recipe and can
11465 be useful satisfying dependencies of other recipes during
11466 the build as specified by
11467 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
11468 </para>
11469
11470 <para>
11471 Consider the following example
11472 <filename>PROVIDES</filename> statement from a recipe
11473 file <filename>libav_0.8.11.bb</filename>:
11474 <literallayout class='monospaced'>
11475 PROVIDES += "libpostproc"
11476 </literallayout>
11477 The <filename>PROVIDES</filename> statement results in
11478 the "libav" recipe also being known as "libpostproc".
11479 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011480
11481 <para>
11482 In addition to providing recipes under alternate names,
11483 the <filename>PROVIDES</filename> mechanism is also used
11484 to implement virtual targets.
11485 A virtual target is a name that corresponds to some
11486 particular functionality (e.g. a Linux kernel).
11487 Recipes that provide the functionality in question list the
11488 virtual target in <filename>PROVIDES</filename>.
11489 Recipes that depend on the functionality in question can
Brad Bishop316dfdd2018-06-25 12:45:53 -040011490 include the virtual target in <filename>DEPENDS</filename>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011491 to leave the choice of provider open.
11492 </para>
11493
11494 <para>
11495 Conventionally, virtual targets have names on the form
11496 "virtual/function" (e.g. "virtual/kernel").
11497 The slash is simply part of the name and has no
11498 syntactical significance.
11499 </para>
11500
11501 <para>
11502 The
11503 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
11504 variable is used to select which particular recipe
11505 provides a virtual target.
11506 <note>
11507 <para>A corresponding mechanism for virtual runtime
11508 dependencies (packages) exists.
11509 However, the mechanism does not depend on any special
11510 functionality beyond ordinary variable assignments.
11511 For example,
11512 <filename>VIRTUAL-RUNTIME_dev_manager</filename>
11513 refers to the package of the component that manages
11514 the <filename>/dev</filename> directory.</para>
11515
11516 <para>Setting the "preferred provider" for runtime
11517 dependencies is as simple as using the following
11518 assignment in a configuration file:</para>
11519 <literallayout class='monospaced'>
11520 VIRTUAL-RUNTIME_dev_manager = "udev"
11521 </literallayout>
11522 </note>
11523 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011524 </glossdef>
11525 </glossentry>
11526
11527 <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
11528 <info>
11529 PRSERV_HOST[doc] = "The network based PR service host and port."
11530 </info>
11531 <glossdef>
11532 <para role="glossdeffirst">
11533<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11534 The network based
11535 <link linkend='var-PR'><filename>PR</filename></link>
11536 service host and port.
11537 </para>
11538
11539 <para>
11540 The <filename>conf/local.conf.sample.extended</filename>
11541 configuration file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050011542 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011543 shows how the <filename>PRSERV_HOST</filename> variable is
11544 set:
11545 <literallayout class='monospaced'>
11546 PRSERV_HOST = "localhost:0"
11547 </literallayout>
11548 You must set the variable if you want to automatically
11549 start a local
11550 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.
11551 You can set <filename>PRSERV_HOST</filename> to other
11552 values to use a remote PR service.
11553 </para>
11554 </glossdef>
11555 </glossentry>
11556
11557 <glossentry id='var-PTEST_ENABLED'><glossterm>PTEST_ENABLED</glossterm>
11558 <info>
11559 PRSERV_HOST[doc] = "Specifies whether or not Package Test (ptest) functionality is enabled when building a recipe."
11560 </info>
11561 <glossdef>
11562 <para role="glossdeffirst">
11563<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11564 Specifies whether or not
11565 <ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Package Test</ulink>
11566 (ptest) functionality is enabled when building a recipe.
11567 You should not set this variable directly.
11568 Enabling and disabling building Package Tests
11569 at build time should be done by adding "ptest" to (or
11570 removing it from)
11571 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
11572 </para>
11573 </glossdef>
11574 </glossentry>
11575
11576 <glossentry id='var-PV'><glossterm>PV</glossterm>
11577 <info>
11578 PV[doc] = "The version of the recipe. The version is normally extracted from the recipe filename."
11579 </info>
11580 <glossdef>
11581 <para role="glossdeffirst">
11582<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11583 The version of the recipe.
11584 The version is normally extracted from the recipe filename.
11585 For example, if the recipe is named
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011586 <filename>expat_2.0.1.bb</filename>, then the default value
11587 of <filename>PV</filename> will be "2.0.1".
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011588 <filename>PV</filename> is generally not overridden within
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011589 a recipe unless it is building an unstable (i.e.
11590 development) version from a source code repository
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011591 (e.g. Git or Subversion).
11592 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011593
11594 <para>
11595 <filename>PV</filename> is the default value of the
11596 <link linkend='var-PKGV'><filename>PKGV</filename></link>
11597 variable.
11598 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011599 </glossdef>
11600 </glossentry>
11601
11602 <glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>
11603 <info>
11604 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."
11605 </info>
11606 <glossdef>
11607 <para role="glossdeffirst">
11608<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11609 When used by recipes that inherit the
11610 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
11611 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
11612 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
11613 or
11614 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
11615 classes, denotes the Application Binary Interface (ABI)
11616 currently in use for Python.
11617 By default, the ABI is "m".
11618 You do not have to set this variable as the OpenEmbedded
11619 build system sets it for you.
11620 </para>
11621
11622 <para>
11623 The OpenEmbedded build system uses the ABI to construct
11624 directory names used when installing the Python headers
11625 and libraries in sysroot
11626 (e.g. <filename>.../python3.3m/...</filename>).
11627 </para>
11628
11629 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040011630 Recipes that inherit the <filename>distutils</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011631 class during cross-builds also use this variable to
11632 locate the headers and libraries of the appropriate Python
11633 that the extension is targeting.
11634 </para>
11635 </glossdef>
11636 </glossentry>
11637
11638 <glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>
11639 <info>
11640 PYTHON_PN[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, specifies the major Python version being built."
11641 </info>
11642 <glossdef>
11643 <para role="glossdeffirst">
11644<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11645 When used by recipes that inherit the
11646 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
11647 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
11648 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
11649 or
11650 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
11651 classes, specifies the major Python version being built.
11652 For Python 2.x, <filename>PYTHON_PN</filename> would
11653 be "python2". For Python 3.x, the variable would be
11654 "python3".
11655 You do not have to set this variable as the
11656 OpenEmbedded build system automatically sets it for you.
11657 </para>
11658
11659 <para>
11660 The variable allows recipes to use common infrastructure
11661 such as the following:
11662 <literallayout class='monospaced'>
11663 DEPENDS += "${PYTHON_PN}-native"
11664 </literallayout>
11665 In the previous example, the version of the dependency
11666 is <filename>PYTHON_PN</filename>.
11667 </para>
11668 </glossdef>
11669 </glossentry>
11670
11671 </glossdiv>
11672
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011673 <glossdiv id='var-glossary-r'><title>R</title>
11674
11675 <glossentry id='var-RANLIB'><glossterm>RANLIB</glossterm>
11676 <info>
11677 RANLIB[doc] = "Minimal command and arguments to run 'ranlib'."
11678 </info>
11679 <glossdef>
11680 <para role="glossdeffirst">
11681<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11682 The minimal command and arguments to run
11683 <filename>ranlib</filename>.
11684 </para>
11685 </glossdef>
11686 </glossentry>
11687
11688 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
11689 <info>
11690 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."
11691 </info>
11692 <glossdef>
11693 <para role="glossdeffirst">
11694<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11695 The list of packages that conflict with packages.
11696 Note that packages will not be installed if conflicting
11697 packages are not first removed.
11698 </para>
11699
11700 <para>
11701 Like all package-controlling variables, you must always use
11702 them in conjunction with a package name override.
11703 Here is an example:
11704 <literallayout class='monospaced'>
11705 RCONFLICTS_${PN} = "<replaceable>another_conflicting_package_name</replaceable>"
11706 </literallayout>
11707 </para>
11708
11709 <para>
11710 BitBake, which the OpenEmbedded build system uses, supports
11711 specifying versioned dependencies.
11712 Although the syntax varies depending on the packaging
11713 format, BitBake hides these differences from you.
11714 Here is the general syntax to specify versions with
11715 the <filename>RCONFLICTS</filename> variable:
11716 <literallayout class='monospaced'>
11717 RCONFLICTS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
11718 </literallayout>
11719 For <filename>operator</filename>, you can specify the
11720 following:
11721 <literallayout class='monospaced'>
11722 =
11723 &lt;
11724 &gt;
11725 &lt;=
11726 &gt;=
11727 </literallayout>
11728 For example, the following sets up a dependency on version
11729 1.2 or greater of the package <filename>foo</filename>:
11730 <literallayout class='monospaced'>
11731 RCONFLICTS_${PN} = "foo (>= 1.2)"
11732 </literallayout>
11733 </para>
11734 </glossdef>
11735 </glossentry>
11736
11737 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
11738 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011739 RDEPENDS[doc] = "Lists runtime dependencies of a package."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011740 </info>
11741 <glossdef>
11742 <para role="glossdeffirst">
11743<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011744 Lists runtime dependencies of a package.
11745 These dependencies are other packages that must be
11746 installed in order for the package to function correctly.
11747 As an example, the following assignment declares that the
11748 package <filename>foo</filename> needs the packages
11749 <filename>bar</filename> and <filename>baz</filename> to
11750 be installed:
11751 <literallayout class='monospaced'>
11752 RDEPENDS_foo = "bar baz"
11753 </literallayout>
11754 The most common types of package runtime dependencies are
11755 automatically detected and added.
11756 Therefore, most recipes do not need to set
11757 <filename>RDEPENDS</filename>.
11758 For more information, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040011759 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
11760 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011761 </para>
11762
11763 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011764 The practical effect of the above
11765 <filename>RDEPENDS</filename> assignment is that
11766 <filename>bar</filename> and <filename>baz</filename>
11767 will be declared as dependencies inside the package
11768 <filename>foo</filename> when it is written out by one of
11769 the
11770 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>
11771 tasks.
11772 Exactly how this is done depends on which package format
11773 is used, which is determined by
11774 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>.
11775 When the corresponding package manager installs the
11776 package, it will know to also install the packages on
11777 which it depends.
11778 </para>
11779
11780 <para>
11781 To ensure that the packages <filename>bar</filename> and
11782 <filename>baz</filename> get built, the previous
11783 <filename>RDEPENDS</filename> assignment also causes a task
11784 dependency to be added.
11785 This dependency is from the recipe's
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011786 <link linkend='ref-tasks-build'><filename>do_build</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011787 (not to be confused with
11788 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>)
11789 task to the <filename>do_package_write_*</filename>
11790 task of the recipes that build <filename>bar</filename> and
11791 <filename>baz</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011792 </para>
11793
11794 <para>
11795 The names of the packages you list within
11796 <filename>RDEPENDS</filename> must be the names of other
11797 packages - they cannot be recipe names.
11798 Although package names and recipe names usually match,
11799 the important point here is that you are
11800 providing package names within the
11801 <filename>RDEPENDS</filename> variable.
11802 For an example of the default list of packages created from
11803 a recipe, see the
11804 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
11805 variable.
11806 </para>
11807
11808 <para>
11809 Because the <filename>RDEPENDS</filename> variable applies
11810 to packages being built, you should always use the variable
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011811 in a form with an attached package name (remember that a
11812 single recipe can build multiple packages).
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011813 For example, suppose you are building a development package
11814 that depends on the <filename>perl</filename> package.
11815 In this case, you would use the following
11816 <filename>RDEPENDS</filename> statement:
11817 <literallayout class='monospaced'>
11818 RDEPENDS_${PN}-dev += "perl"
11819 </literallayout>
11820 In the example, the development package depends on
11821 the <filename>perl</filename> package.
11822 Thus, the <filename>RDEPENDS</filename> variable has the
11823 <filename>${PN}-dev</filename> package name as part of the
11824 variable.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011825 <note>
11826 <title>Caution</title>
11827 <filename>RDEPENDS_${PN}-dev</filename> includes
11828 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>
11829 by default.
11830 This default is set in the BitBake configuration file
11831 (<filename>meta/conf/bitbake.conf</filename>).
11832 Be careful not to accidentally remove
11833 <filename>${PN}</filename> when modifying
11834 <filename>RDEPENDS_${PN}-dev</filename>.
11835 Use the "+=" operator rather than the "=" operator.
11836 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011837 </para>
11838
11839 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011840 The package names you use with
11841 <filename>RDEPENDS</filename> must appear as they would in
11842 the <filename>PACKAGES</filename> variable.
11843 The
11844 <link linkend='var-PKG'><filename>PKG</filename></link>
11845 variable allows a different name to be used for
11846 the final package (e.g. the
11847 <link linkend='ref-classes-debian'><filename>debian</filename></link>
11848 class uses this to rename packages), but this final package
11849 name cannot be used with <filename>RDEPENDS</filename>,
11850 which makes sense as <filename>RDEPENDS</filename> is meant
11851 to be independent of the package format used.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011852 </para>
11853
11854 <para>
11855 BitBake, which the OpenEmbedded build system uses, supports
11856 specifying versioned dependencies.
11857 Although the syntax varies depending on the packaging
11858 format, BitBake hides these differences from you.
11859 Here is the general syntax to specify versions with
11860 the <filename>RDEPENDS</filename> variable:
11861 <literallayout class='monospaced'>
11862 RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
11863 </literallayout>
Brad Bishop37a0e4d2017-12-04 01:01:44 -050011864 For <replaceable>operator</replaceable>, you can specify the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011865 following:
11866 <literallayout class='monospaced'>
11867 =
11868 &lt;
11869 &gt;
11870 &lt;=
11871 &gt;=
11872 </literallayout>
Brad Bishop37a0e4d2017-12-04 01:01:44 -050011873 For <replaceable>version</replaceable>, provide the version
11874 number.
11875 <note><title>Tip</title>
11876 You can use
11877 <link linkend='var-EXTENDPKGV'><filename>EXTENDPKGV</filename></link>
11878 to provide a full package version specification.
11879 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011880 For example, the following sets up a dependency on version
11881 1.2 or greater of the package <filename>foo</filename>:
11882 <literallayout class='monospaced'>
11883 RDEPENDS_${PN} = "foo (>= 1.2)"
11884 </literallayout>
11885 </para>
11886
11887 <para>
11888 For information on build-time dependencies, see the
11889 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
11890 variable.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060011891 You can also see the
11892 "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
11893 "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
11894 sections in the BitBake User Manual for additional
11895 information on tasks and dependencies.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011896 </para>
11897 </glossdef>
11898 </glossentry>
11899
11900 <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm>
11901 <info>
11902 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."
11903 </info>
11904 <glossdef>
11905 <para role="glossdeffirst">
11906<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11907 When inheriting the
11908 <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link>
11909 class, this
11910 variable identifies distribution features that must
11911 exist in the current configuration in order for the
11912 OpenEmbedded build system to build the recipe.
11913 In other words, if the
11914 <filename>REQUIRED_DISTRO_FEATURES</filename> variable
11915 lists a feature that does not appear in
11916 <filename>DISTRO_FEATURES</filename> within the
11917 current configuration, an error occurs and the
11918 build stops.
11919 </para>
11920 </glossdef>
11921 </glossentry>
11922
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011923 <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
11924 <info>
11925 RM_WORK_EXCLUDE[doc] = "With rm_work enabled, this variable specifies a list of packages whose work directories should not be removed."
11926 </info>
11927 <glossdef>
11928 <para role="glossdeffirst">
11929<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11930 With <filename>rm_work</filename> enabled, this
11931 variable specifies a list of recipes whose work directories
11932 should not be removed.
11933 See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
11934 section for more details.
11935 </para>
11936 </glossdef>
11937 </glossentry>
11938
11939 <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm>
11940 <info>
11941 ROOT_HOME[doc] = "Defines the root home directory."
11942 </info>
11943 <glossdef>
11944 <para role="glossdeffirst">
11945<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11946 Defines the root home directory.
11947 By default, this directory is set as follows in the
11948 BitBake configuration file:
11949 <literallayout class='monospaced'>
11950 ROOT_HOME ??= "/home/root"
11951 </literallayout>
11952 <note>
11953 This default value is likely used because some
11954 embedded solutions prefer to have a read-only root
11955 filesystem and prefer to keep writeable data in one
11956 place.
11957 </note>
11958 </para>
11959
11960 <para>
11961 You can override the default by setting the variable
11962 in any layer or in the <filename>local.conf</filename> file.
11963 Because the default is set using a "weak" assignment
11964 (i.e. "??="), you can use either of the following forms
11965 to define your override:
11966 <literallayout class='monospaced'>
11967 ROOT_HOME = "/root"
11968 ROOT_HOME ?= "/root"
11969 </literallayout>
11970 These override examples use <filename>/root</filename>,
11971 which is probably the most commonly used override.
11972 </para>
11973 </glossdef>
11974 </glossentry>
11975
11976 <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>
11977 <info>
11978 ROOTFS[doc] = "Indicates a filesystem image to include as the root filesystem."
11979 </info>
11980 <glossdef>
11981 <para role="glossdeffirst">
11982<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
11983 Indicates a filesystem image to include as the root
11984 filesystem.
11985 </para>
11986
11987 <para>
11988 The <filename>ROOTFS</filename> variable is an optional
11989 variable used with the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050011990 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050011991 class.
11992 </para>
11993 </glossdef>
11994 </glossentry>
11995
11996 <glossentry id='var-ROOTFS_POSTINSTALL_COMMAND'><glossterm>ROOTFS_POSTINSTALL_COMMAND</glossterm>
11997 <info>
11998 ROOTFS_POSTINSTALL_COMMAND[doc] = "Specifies a list of functions to call after installing packages."
11999 </info>
12000 <glossdef>
12001 <para role="glossdeffirst">
12002<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12003 Specifies a list of functions to call after the
12004 OpenEmbedded build system has installed packages.
12005 You can specify functions separated by semicolons:
12006 <literallayout class='monospaced'>
12007 ROOTFS_POSTINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
12008 </literallayout>
12009 </para>
12010
12011 <para>
12012 If you need to pass the root filesystem path to a command
12013 within a function, you can use
12014 <filename>${IMAGE_ROOTFS}</filename>, which points to
12015 the directory that becomes the root filesystem image.
12016 See the
12017 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12018 variable for more information.
12019 </para>
12020 </glossdef>
12021 </glossentry>
12022
12023 <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
12024 <info>
12025 ROOTFS_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the root filesystem."
12026 </info>
12027 <glossdef>
12028 <para role="glossdeffirst">
12029<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12030 Specifies a list of functions to call once the
12031 OpenEmbedded build system has created the root filesystem.
12032 You can specify functions separated by semicolons:
12033 <literallayout class='monospaced'>
12034 ROOTFS_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
12035 </literallayout>
12036 </para>
12037
12038 <para>
12039 If you need to pass the root filesystem path to a command
12040 within a function, you can use
12041 <filename>${IMAGE_ROOTFS}</filename>, which points to
12042 the directory that becomes the root filesystem image.
12043 See the
12044 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12045 variable for more information.
12046 </para>
12047 </glossdef>
12048 </glossentry>
12049
12050 <glossentry id='var-ROOTFS_POSTUNINSTALL_COMMAND'><glossterm>ROOTFS_POSTUNINSTALL_COMMAND</glossterm>
12051 <info>
12052 ROOTFS_POSTUNINSTALL_COMMAND[doc] = "Specifies a list of functions to call after removal of unneeded packages."
12053 </info>
12054 <glossdef>
12055 <para role="glossdeffirst">
12056<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12057 Specifies a list of functions to call after the
12058 OpenEmbedded build system has removed unnecessary
12059 packages.
12060 When runtime package management is disabled in the
12061 image, several packages are removed including
12062 <filename>base-passwd</filename>,
12063 <filename>shadow</filename>, and
12064 <filename>update-alternatives</filename>.
12065 You can specify functions separated by semicolons:
12066 <literallayout class='monospaced'>
12067 ROOTFS_POSTUNINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
12068 </literallayout>
12069 </para>
12070
12071 <para>
12072 If you need to pass the root filesystem path to a command
12073 within a function, you can use
12074 <filename>${IMAGE_ROOTFS}</filename>, which points to
12075 the directory that becomes the root filesystem image.
12076 See the
12077 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12078 variable for more information.
12079 </para>
12080 </glossdef>
12081 </glossentry>
12082
12083 <glossentry id='var-ROOTFS_PREPROCESS_COMMAND'><glossterm>ROOTFS_PREPROCESS_COMMAND</glossterm>
12084 <info>
12085 ROOTFS_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the root filesystem."
12086 </info>
12087 <glossdef>
12088 <para role="glossdeffirst">
12089<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12090 Specifies a list of functions to call before the
12091 OpenEmbedded build system has created the root filesystem.
12092 You can specify functions separated by semicolons:
12093 <literallayout class='monospaced'>
12094 ROOTFS_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
12095 </literallayout>
12096 </para>
12097
12098 <para>
12099 If you need to pass the root filesystem path to a command
12100 within a function, you can use
12101 <filename>${IMAGE_ROOTFS}</filename>, which points to
12102 the directory that becomes the root filesystem image.
12103 See the
12104 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
12105 variable for more information.
12106 </para>
12107 </glossdef>
12108 </glossentry>
12109
12110 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
12111 <info>
12112 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."
12113 </info>
12114 <glossdef>
12115 <para role="glossdeffirst">
12116<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12117 A list of package name aliases that a package also provides.
12118 These aliases are useful for satisfying runtime dependencies
12119 of other packages both during the build and on the target
12120 (as specified by
12121 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
12122 <note>
12123 A package's own name is implicitly already in its
12124 <filename>RPROVIDES</filename> list.
12125 </note>
12126 </para>
12127
12128 <para>
12129 As with all package-controlling variables, you must always
12130 use the variable in conjunction with a package name override.
12131 Here is an example:
12132 <literallayout class='monospaced'>
12133 RPROVIDES_${PN} = "widget-abi-2"
12134 </literallayout>
12135 </para>
12136 </glossdef>
12137 </glossentry>
12138
12139 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
12140 <info>
12141 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."
12142 </info>
12143 <glossdef>
12144 <para role="glossdeffirst">
12145<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12146 A list of packages that extends the usability of a package
12147 being built.
12148 The package being built does not depend on this list of
12149 packages in order to successfully build, but rather
12150 uses them for extended usability.
12151 To specify runtime dependencies for packages, see the
12152 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
12153 variable.
12154 </para>
12155
12156 <para>
12157 The package manager will automatically install the
12158 <filename>RRECOMMENDS</filename> list of packages when
12159 installing the built package.
12160 However, you can prevent listed packages from being
12161 installed by using the
12162 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
12163 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
12164 and
12165 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
12166 variables.
12167 </para>
12168
12169 <para>
12170 Packages specified in
12171 <filename>RRECOMMENDS</filename> need not actually be
12172 produced.
12173 However, a recipe must exist that provides each package,
12174 either through the
12175 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
12176 or
12177 <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link>
12178 variables or the
12179 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>
12180 variable, or an error will occur during the build.
12181 If such a recipe does exist and the package is not produced,
12182 the build continues without error.
12183 </para>
12184
12185 <para>
12186 Because the <filename>RRECOMMENDS</filename> variable
12187 applies to packages being built, you should always attach
12188 an override to the variable to specify the particular
12189 package whose usability is being extended.
12190 For example, suppose you are building a development package
12191 that is extended to support wireless functionality.
12192 In this case, you would use the following:
12193 <literallayout class='monospaced'>
12194 RRECOMMENDS_${PN}-dev += "<replaceable>wireless_package_name</replaceable>"
12195 </literallayout>
12196 In the example, the package name
12197 (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
12198 must appear as it would in the
Brad Bishop316dfdd2018-06-25 12:45:53 -040012199 <filename>PACKAGES</filename> namespace before any renaming
12200 of the output package by classes such as
12201 <filename>debian.bbclass</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012202 </para>
12203
12204 <para>
12205 BitBake, which the OpenEmbedded build system uses, supports
12206 specifying versioned recommends.
12207 Although the syntax varies depending on the packaging
12208 format, BitBake hides these differences from you.
12209 Here is the general syntax to specify versions with
12210 the <filename>RRECOMMENDS</filename> variable:
12211 <literallayout class='monospaced'>
12212 RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
12213 </literallayout>
12214 For <filename>operator</filename>, you can specify the
12215 following:
12216 <literallayout class='monospaced'>
12217 =
12218 &lt;
12219 &gt;
12220 &lt;=
12221 &gt;=
12222 </literallayout>
12223 For example, the following sets up a recommend on version
12224 1.2 or greater of the package <filename>foo</filename>:
12225 <literallayout class='monospaced'>
12226 RRECOMMENDS_${PN} = "foo (>= 1.2)"
12227 </literallayout>
12228 </para>
12229 </glossdef>
12230 </glossentry>
12231
12232 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
12233 <info>
12234 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."
12235 </info>
12236 <glossdef>
12237 <para role="glossdeffirst">
12238<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12239 A list of packages replaced by a package.
12240 The package manager uses this variable to determine which
12241 package should be installed to replace other package(s)
12242 during an upgrade.
12243 In order to also have the other package(s) removed at the
12244 same time, you must add the name of the other
12245 package to the
12246 <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
12247 </para>
12248
12249 <para>
12250 As with all package-controlling variables, you must use
12251 this variable in conjunction with a package name
12252 override.
12253 Here is an example:
12254 <literallayout class='monospaced'>
12255 RREPLACES_${PN} = "<replaceable>other_package_being_replaced</replaceable>"
12256 </literallayout>
12257 </para>
12258
12259 <para>
12260 BitBake, which the OpenEmbedded build system uses, supports
12261 specifying versioned replacements.
12262 Although the syntax varies depending on the packaging
12263 format, BitBake hides these differences from you.
12264 Here is the general syntax to specify versions with
12265 the <filename>RREPLACES</filename> variable:
12266 <literallayout class='monospaced'>
12267 RREPLACES_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
12268 </literallayout>
12269 For <filename>operator</filename>, you can specify the
12270 following:
12271 <literallayout class='monospaced'>
12272 =
12273 &lt;
12274 &gt;
12275 &lt;=
12276 &gt;=
12277 </literallayout>
12278 For example, the following sets up a replacement using
12279 version 1.2 or greater of the package
12280 <filename>foo</filename>:
12281 <literallayout class='monospaced'>
12282 RREPLACES_${PN} = "foo (>= 1.2)"
12283 </literallayout>
12284 </para>
12285 </glossdef>
12286 </glossentry>
12287
12288 <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
12289 <info>
12290 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."
12291 </info>
12292 <glossdef>
12293 <para role="glossdeffirst">
12294<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12295 A list of additional packages that you can suggest for
12296 installation by the package manager at the time a package
12297 is installed.
12298 Not all package managers support this functionality.
12299 </para>
12300
12301 <para>
12302 As with all package-controlling variables, you must always
12303 use this variable in conjunction with a package name
12304 override.
12305 Here is an example:
12306 <literallayout class='monospaced'>
12307 RSUGGESTS_${PN} = "<replaceable>useful_package</replaceable> <replaceable>another_package</replaceable>"
12308 </literallayout>
12309 </para>
12310 </glossdef>
12311 </glossentry>
12312
12313 </glossdiv>
12314
12315 <glossdiv id='var-glossary-s'><title>S</title>
12316
12317 <glossentry id='var-S'><glossterm>S</glossterm>
12318 <info>
12319 S[doc] = "The location in the Build Directory where unpacked package source code resides."
12320 </info>
12321 <glossdef>
12322 <para role="glossdeffirst">
12323<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12324 The location in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050012325 <link linkend='build-directory'>Build Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012326 where unpacked recipe source code resides.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012327 By default, this directory is
12328 <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>,
12329 where <filename>${BPN}</filename> is the base recipe name
12330 and <filename>${PV}</filename> is the recipe version.
12331 If the source tarball extracts the code to a directory
12332 named anything other than <filename>${BPN}-${PV}</filename>,
Brad Bishopd7bf8c12018-02-25 22:55:05 -050012333 or if the source code is fetched from an SCM such as
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012334 Git or Subversion, then you must set <filename>S</filename>
12335 in the recipe so that the OpenEmbedded build system
12336 knows where to find the unpacked source.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012337 </para>
12338
12339 <para>
12340 As an example, assume a
Brad Bishopd7bf8c12018-02-25 22:55:05 -050012341 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012342 top-level folder named <filename>poky</filename> and a
12343 default Build Directory at <filename>poky/build</filename>.
12344 In this case, the work directory the build system uses
12345 to keep the unpacked recipe for <filename>db</filename>
12346 is the following:
12347 <literallayout class='monospaced'>
12348 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
12349 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012350 The unpacked source code resides in the
12351 <filename>db-5.1.19</filename> folder.
12352 </para>
12353
12354 <para>
12355 This next example assumes a Git repository.
12356 By default, Git repositories are cloned to
12357 <filename>${WORKDIR}/git</filename> during
12358 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>.
12359 Since this path is different from the default value of
12360 <filename>S</filename>, you must set it specifically
12361 so the source can be located:
12362 <literallayout class='monospaced'>
12363 SRC_URI = "git://path/to/repo.git"
12364 S = "${WORKDIR}/git"
12365 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012366 </para>
12367 </glossdef>
12368 </glossentry>
12369
12370 <glossentry id='var-SANITY_REQUIRED_UTILITIES'><glossterm>SANITY_REQUIRED_UTILITIES</glossterm>
12371 <info>
12372 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."
12373 </info>
12374 <glossdef>
12375 <para role="glossdeffirst">
12376<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12377 Specifies a list of command-line utilities that should be
12378 checked for during the initial sanity checking process when
12379 running BitBake.
12380 If any of the utilities are not installed on the build host,
12381 then BitBake immediately exits with an error.
12382 </para>
12383 </glossdef>
12384 </glossentry>
12385
12386 <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
12387 <info>
12388 SANITY_TESTED_DISTROS[doc] = "A list of the host distribution identifiers that the build system has been tested against."
12389 </info>
12390 <glossdef>
12391 <para role="glossdeffirst">
12392<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12393 A list of the host distribution identifiers that the
12394 build system has been tested against.
12395 Identifiers consist of the host distributor ID
12396 followed by the release,
12397 as reported by the <filename>lsb_release</filename> tool
12398 or as read from <filename>/etc/lsb-release</filename>.
12399 Separate the list items with explicit newline
12400 characters (<filename>\n</filename>).
12401 If <filename>SANITY_TESTED_DISTROS</filename> is not empty
12402 and the current value of
12403 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
12404 does not appear in the list, then the build system reports
12405 a warning that indicates the current host distribution has
12406 not been tested as a build host.
12407 </para>
12408 </glossdef>
12409 </glossentry>
12410
12411 <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
12412 <info>
12413 SDK_ARCH[doc] = "The target architecture for the SDK."
12414 </info>
12415 <glossdef>
12416 <para role="glossdeffirst">
12417<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12418 The target architecture for the SDK.
12419 Typically, you do not directly set this variable.
12420 Instead, use
12421 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
12422 </para>
12423 </glossdef>
12424 </glossentry>
12425
12426 <glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>
12427 <info>
12428 SDK_DEPLOY[doc] = "The directory set up and used by the populate_sdk_base to which the SDK is deployed."
12429 </info>
12430 <glossdef>
12431 <para role="glossdeffirst">
12432<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12433 The directory set up and used by the
12434 <link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012435 class to which the SDK is deployed.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012436 The <filename>populate_sdk_base</filename> class defines
12437 <filename>SDK_DEPLOY</filename> as follows:
12438 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012439 SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012440 </literallayout>
12441 </para>
12442 </glossdef>
12443 </glossentry>
12444
12445 <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm>
12446 <info>
12447 SDK_DIR[doc] = "The parent directory used by the OpenEmbedded build system when creating SDK output."
12448 </info>
12449 <glossdef>
12450 <para role="glossdeffirst">
12451<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12452 The parent directory used by the OpenEmbedded build system
12453 when creating SDK output.
12454 The
12455 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12456 class defines the variable as follows:
12457 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012458 SDK_DIR = "${WORKDIR}/sdk"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012459 </literallayout>
12460 <note>
12461 The <filename>SDK_DIR</filename> directory is a
12462 temporary directory as it is part of
12463 <filename>WORKDIR</filename>.
12464 The final output directory is
12465 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
12466 </note>
12467 </para>
12468 </glossdef>
12469 </glossentry>
12470
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012471 <glossentry id='var-SDK_EXT_TYPE'><glossterm>SDK_EXT_TYPE</glossterm>
12472 <info>
12473 SDK_EXT_TYPE[doc] = "Controls whether or not shared state artifacts are copied into the extensible SDK."
12474 </info>
12475 <glossdef>
12476 <para role="glossdeffirst">
12477<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12478 Controls whether or not shared state artifacts are copied
12479 into the extensible SDK.
12480 The default value of "full" copies all of the required
12481 shared state artifacts into the extensible SDK.
12482 The value "minimal" leaves these artifacts out of the
12483 SDK.
12484 <note>
12485 If you set the variable to "minimal", you need to
12486 ensure
12487 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
12488 is set in the SDK's configuration to enable the
12489 artifacts to be fetched as needed.
12490 </note>
12491 </para>
12492 </glossdef>
12493 </glossentry>
12494
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012495 <glossentry id='var-SDK_HOST_MANIFEST'><glossterm>SDK_HOST_MANIFEST</glossterm>
12496 <info>
12497 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."
12498 </info>
12499 <glossdef>
12500 <para role="glossdeffirst">
12501<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12502 The manifest file for the host part of the SDK.
12503 This file lists all the installed packages that make up
Brad Bishop316dfdd2018-06-25 12:45:53 -040012504 the host part of the SDK.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012505 The file contains package information on a line-per-package
12506 basis as follows:
12507 <literallayout class='monospaced'>
12508 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
12509 </literallayout>
12510 </para>
12511
12512 <para>
12513 The
12514 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12515 class defines the manifest file as follows:
12516 <literallayout class='monospaced'>
12517 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"
12518 </literallayout>
12519 The location is derived using the
12520 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>
12521 and
12522 <link linkend='var-TOOLCHAIN_OUTPUTNAME'><filename>TOOLCHAIN_OUTPUTNAME</filename></link>
12523 variables.
12524 </para>
12525 </glossdef>
12526 </glossentry>
12527
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012528 <glossentry id='var-SDK_INCLUDE_PKGDATA'><glossterm>SDK_INCLUDE_PKGDATA</glossterm>
12529 <info>
12530 SDK_INCLUDE_PKGDATA[doc] = "When set to "1", specifies to include the packagedata for all recipes in the "world" target in the extensible SDK."
12531 </info>
12532 <glossdef>
12533 <para role="glossdeffirst">
12534<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12535 When set to "1", specifies to include the packagedata for
12536 all recipes in the "world" target in the extensible SDK.
12537 Including this data allows the
12538 <filename>devtool search</filename> command to find these
12539 recipes in search results, as well as allows the
12540 <filename>devtool add</filename> command to map
12541 dependencies more effectively.
12542 <note>
12543 Enabling the <filename>SDK_INCLUDE_PKGDATA</filename>
12544 variable significantly increases build time because
12545 all of world needs to be built.
12546 Enabling the variable also slightly increases the size
12547 of the extensible SDK.
12548 </note>
12549 </para>
12550 </glossdef>
12551 </glossentry>
12552
Patrick Williamsc0f7c042017-02-23 20:41:17 -060012553 <glossentry id='var-SDK_INCLUDE_TOOLCHAIN'><glossterm>SDK_INCLUDE_TOOLCHAIN</glossterm>
12554 <info>
12555 SDK_INCLUDE_TOOLCHAIN[doc] = "When set to "1", specifies to include the toolchain in the extensible SDK."
12556 </info>
12557 <glossdef>
12558 <para role="glossdeffirst">
12559<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12560 When set to "1", specifies to include the toolchain in the
12561 extensible SDK.
12562 Including the toolchain is useful particularly when
12563 <link linkend='var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></link>
12564 is set to "minimal" to keep the SDK reasonably small
12565 but you still want to provide a usable toolchain.
12566 For example, suppose you want to use the toolchain from an
12567 IDE (e.g. Eclipse) or from other tools and you do not
12568 want to perform additional steps to install the toolchain.
12569 </para>
12570
12571 <para>
12572 The <filename>SDK_INCLUDE_TOOLCHAIN</filename> variable
12573 defaults to "0" if <filename>SDK_EXT_TYPE</filename>
12574 is set to "minimal", and defaults to "1" if
12575 <filename>SDK_EXT_TYPE</filename> is set to "full".
12576 </para>
12577 </glossdef>
12578 </glossentry>
12579
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012580 <glossentry id='var-SDK_INHERIT_BLACKLIST'><glossterm>SDK_INHERIT_BLACKLIST</glossterm>
12581 <info>
12582 SDK_INHERIT_BLACKLIST[doc] = "A list of classes to remove from the INHERIT value globally within the extensible SDK configuration."
12583 </info>
12584 <glossdef>
12585 <para role="glossdeffirst">
12586<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12587 A list of classes to remove from the
12588 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
12589 value globally within the extensible SDK configuration.
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012590 The
12591 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12592 class sets the default value:
12593 <literallayout class='monospaced'>
12594 SDK_INHERIT_BLACKLIST ?= "buildhistory icecc"
12595 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012596 </para>
12597
12598 <para>
12599 Some classes are not generally applicable within
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012600 the extensible SDK context.
12601 You can use this variable to disable those classes.
12602 </para>
12603
12604 <para>
12605 For additional information on how to customize the
12606 extensible SDK's configuration, see the
12607 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12608 section in the Yocto Project Application Development and
12609 the Extensible Software Development Kit (eSDK) manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012610 </para>
12611 </glossdef>
12612 </glossentry>
12613
12614 <glossentry id='var-SDK_LOCAL_CONF_BLACKLIST'><glossterm>SDK_LOCAL_CONF_BLACKLIST</glossterm>
12615 <info>
12616 SDK_LOCAL_CONF_BLACKLIST[doc] = "A list of variables not allowed through from the build system configuration into the extensible SDK configuration."
12617 </info>
12618 <glossdef>
12619 <para role="glossdeffirst">
12620<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012621 A list of variables not allowed through from the
12622 OpenEmbedded build system configuration into the extensible
12623 SDK configuration.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012624 Usually, these are variables that are specific to the
12625 machine on which the build system is running and thus
12626 would be potentially problematic within the extensible SDK.
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012627 </para>
12628
12629 <para>By default,
12630 <filename>SDK_LOCAL_CONF_BLACKLIST</filename> is set in the
12631 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12632 class and excludes the following variables:
12633 <literallayout class='monospaced'>
12634 <link linkend='var-CONF_VERSION'>CONF_VERSION</link>
12635 <link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link>
12636 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'>BB_NUMBER_PARSE_THREADS</ulink>
12637 <link linkend='var-PARALLEL_MAKE'>PARALLEL_MAKE</link>
12638 <link linkend='var-PRSERV_HOST'>PRSERV_HOST</link>
12639 <link linkend='var-SSTATE_MIRRORS'>SSTATE_MIRRORS</link>
12640 <link linkend='var-DL_DIR'>DL_DIR</link>
12641 <link linkend='var-SSTATE_DIR'>SSTATE_DIR</link>
12642 <link linkend='var-TMPDIR'>TMPDIR</link>
12643 <link linkend='var-BB_SERVER_TIMEOUT'>BB_SERVER_TIMEOUT</link>
12644 </literallayout>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012645 </para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012646
12647 <para>
12648 For additional information on how to customize the
12649 extensible SDK's configuration, see the
12650 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12651 section in the Yocto Project Application Development and
12652 the Extensible Software Development Kit (eSDK) manual.
12653 </para>
12654
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012655 </glossdef>
12656 </glossentry>
12657
12658 <glossentry id='var-SDK_LOCAL_CONF_WHITELIST'><glossterm>SDK_LOCAL_CONF_WHITELIST</glossterm>
12659 <info>
12660 SDK_LOCAL_CONF_WHITELIST[doc] = "A list of variables allowed through from the build system configuration into the extensible SDK configuration."
12661 </info>
12662 <glossdef>
12663 <para role="glossdeffirst">
12664<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012665 A list of variables allowed through from the OpenEmbedded
12666 build system configuration into the extensible SDK
12667 configuration.
12668 By default, the list of variables is empty and is set in
12669 the
12670 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12671 class.
12672 </para>
12673
12674 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012675 This list overrides the variables specified using the
12676 <link linkend='var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></link>
12677 variable as well as any variables identified by automatic
12678 blacklisting due to the "/" character being found at the
12679 start of the value, which is usually indicative of being a
12680 path and thus might not be valid on the system where the
12681 SDK is installed.
12682 </para>
Brad Bishopd5ae7d92018-06-14 09:52:03 -070012683
12684 <para>
12685 For additional information on how to customize the
12686 extensible SDK's configuration, see the
12687 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12688 section in the Yocto Project Application Development and
12689 the Extensible Software Development Kit (eSDK) manual.
12690 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012691 </glossdef>
12692 </glossentry>
12693
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012694 <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
12695 <info>
12696 SDK_NAME[doc] = "The base name for SDK output files."
12697 </info>
12698 <glossdef>
12699 <para role="glossdeffirst">
12700<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12701 The base name for SDK output files.
12702 The name is derived from the
12703 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
12704 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
12705 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
12706 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
12707 and
12708 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
12709 variables:
12710 <literallayout class='monospaced'>
12711 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
12712 </literallayout>
12713 </para>
12714 </glossdef>
12715 </glossentry>
12716
12717 <glossentry id='var-SDK_OS'><glossterm>SDK_OS</glossterm>
12718 <info>
12719 SDK_OS[doc] = "The operating system for which the SDK will be built."
12720 </info>
12721 <glossdef>
12722 <para role="glossdeffirst">
12723<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12724 Specifies the operating system for which the SDK
12725 will be built.
12726 The default value is the value of
12727 <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>.
12728 </para>
12729 </glossdef>
12730 </glossentry>
12731
12732 <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>
12733 <info>
12734 SDK_OUTPUT[doc] = "The location used by the OpenEmbedded build system when creating SDK output."
12735 </info>
12736 <glossdef>
12737 <para role="glossdeffirst">
12738<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12739 The location used by the OpenEmbedded build system when
12740 creating SDK output.
12741 The
12742 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12743 class defines the variable as follows:
12744 <literallayout class='monospaced'>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012745 SDK_DIR = "${WORKDIR}/sdk"
12746 SDK_OUTPUT = "${SDK_DIR}/image"
12747 SDK_DEPLOY = "${DEPLOY_DIR}/sdk"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012748 </literallayout>
12749 <note>
12750 The <filename>SDK_OUTPUT</filename> directory is a
12751 temporary directory as it is part of
Brad Bishop316dfdd2018-06-25 12:45:53 -040012752 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
12753 by way of
12754 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012755 The final output directory is
12756 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
12757 </note>
12758 </para>
12759 </glossdef>
12760 </glossentry>
12761
12762 <glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm>
12763 <info>
12764 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."
12765 </info>
12766 <glossdef>
12767 <para role="glossdeffirst">
12768<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12769 Specifies a list of architectures compatible with
12770 the SDK machine.
12771 This variable is set automatically and should not
12772 normally be hand-edited.
12773 Entries are separated using spaces and listed in order
12774 of priority.
12775 The default value for
12776 <filename>SDK_PACKAGE_ARCHS</filename> is "all any noarch
12777 ${SDK_ARCH}-${SDKPKGSUFFIX}".
12778 </para>
12779 </glossdef>
12780 </glossentry>
12781
12782 <glossentry id='var-SDK_POSTPROCESS_COMMAND'><glossterm>SDK_POSTPROCESS_COMMAND</glossterm>
12783 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040012784 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 -050012785 </info>
12786 <glossdef>
12787 <para role="glossdeffirst">
12788<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12789 Specifies a list of functions to call once the
Brad Bishop316dfdd2018-06-25 12:45:53 -040012790 OpenEmbedded build system creates the SDK.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012791 You can specify functions separated by semicolons:
12792 <literallayout class='monospaced'>
12793 SDK_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
12794 </literallayout>
12795 </para>
12796
12797 <para>
12798 If you need to pass an SDK path to a command within a
12799 function, you can use
12800 <filename>${SDK_DIR}</filename>, which points to
12801 the parent directory used by the OpenEmbedded build system
12802 when creating SDK output.
12803 See the
12804 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
12805 variable for more information.
12806 </para>
12807 </glossdef>
12808 </glossentry>
12809
12810 <glossentry id='var-SDK_PREFIX'><glossterm>SDK_PREFIX</glossterm>
12811 <info>
12812 SDK_PREFIX[doc] = "The toolchain binary prefix used for nativesdk recipes."
12813 </info>
12814 <glossdef>
12815 <para role="glossdeffirst">
12816<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012817 The toolchain binary prefix used for
12818 <filename>nativesdk</filename> recipes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012819 The OpenEmbedded build system uses the
12820 <filename>SDK_PREFIX</filename> value to set the
12821 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
12822 when building <filename>nativesdk</filename> recipes.
12823 The default value is "${SDK_SYS}-".
12824 </para>
12825 </glossdef>
12826 </glossentry>
12827
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012828 <glossentry id='var-SDK_RECRDEP_TASKS'><glossterm>SDK_RECRDEP_TASKS</glossterm>
12829 <info>
12830 SDK_RECRDEP_TASKS[doc] = "A list of shared state tasks added to the extensible SDK."
12831 </info>
12832 <glossdef>
12833 <para role="glossdeffirst">
12834<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12835 A list of shared state tasks added to the extensible SDK.
12836 By default, the following tasks are added:
12837 <literallayout class='monospaced'>
12838 do_populate_lic
12839 do_package_qa
12840 do_populate_sysroot
12841 do_deploy
12842 </literallayout>
12843 Despite the default value of "" for the
12844 <filename>SDK_RECRDEP_TASKS</filename> variable, the
12845 above four tasks are always added to the SDK.
12846 To specify tasks beyond these four, you need to use
12847 the <filename>SDK_RECRDEP_TASKS</filename> variable (e.g.
12848 you are defining additional tasks that are needed in
12849 order to build
12850 <link linkend='var-SDK_TARGETS'><filename>SDK_TARGETS</filename></link>).
12851 </para>
12852 </glossdef>
12853 </glossentry>
12854
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012855 <glossentry id='var-SDK_SYS'><glossterm>SDK_SYS</glossterm>
12856 <info>
12857 SDK_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the SDK will be built."
12858 </info>
12859 <glossdef>
12860 <para role="glossdeffirst">
12861<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12862 Specifies the system, including the architecture and the
12863 operating system, for which the SDK will be built.
12864 </para>
12865
12866 <para>
12867 The OpenEmbedded build system automatically sets this
12868 variable based on
12869 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
12870 <link linkend='var-SDK_VENDOR'><filename>SDK_VENDOR</filename></link>,
12871 and
12872 <link linkend='var-SDK_OS'><filename>SDK_OS</filename></link>.
12873 You do not need to set the <filename>SDK_SYS</filename>
12874 variable yourself.
12875 </para>
12876 </glossdef>
12877 </glossentry>
12878
12879 <glossentry id='var-SDK_TARGET_MANIFEST'><glossterm>SDK_TARGET_MANIFEST</glossterm>
12880 <info>
12881 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."
12882 </info>
12883 <glossdef>
12884 <para role="glossdeffirst">
12885<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12886 The manifest file for the target part of the SDK.
12887 This file lists all the installed packages that make up
12888 the target part of the SDK.
12889 The file contains package information on a line-per-package
12890 basis as follows:
12891 <literallayout class='monospaced'>
12892 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
12893 </literallayout>
12894 </para>
12895
12896 <para>
12897 The
12898 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12899 class defines the manifest file as follows:
12900 <literallayout class='monospaced'>
12901 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"
12902 </literallayout>
12903 The location is derived using the
12904 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>
12905 and
12906 <link linkend='var-TOOLCHAIN_OUTPUTNAME'><filename>TOOLCHAIN_OUTPUTNAME</filename></link>
12907 variables.
12908 </para>
12909 </glossdef>
12910 </glossentry>
12911
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012912 <glossentry id='var-SDK_TARGETS'><glossterm>SDK_TARGETS</glossterm>
12913 <info>
12914 SDK_TARGETS[doc] = "A list of targets to install from shared state as part of the standard or extensible SDK installation."
12915 </info>
12916 <glossdef>
12917 <para role="glossdeffirst">
12918<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12919 A list of targets to install from shared state as part of
12920 the standard or extensible SDK installation.
12921 The default value is "${PN}" (i.e. the image from which
12922 the SDK is built).
12923 </para>
12924
12925 <para>
12926 The <filename>SDK_TARGETS</filename> variable is an
12927 internal variable and typically would not be changed.
12928 </para>
12929 </glossdef>
12930 </glossentry>
12931
12932 <glossentry id='var-SDK_TITLE'><glossterm>SDK_TITLE</glossterm>
12933 <info>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080012934 SDK_TITLE[doc] = "The title to be printed when running the SDK installer."
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012935 </info>
12936 <glossdef>
12937 <para role="glossdeffirst">
12938<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080012939 The title to be printed when running the SDK installer.
12940 By default, this title is based on the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012941 <link linkend='var-DISTRO_NAME'><filename>DISTRO_NAME</filename></link>
12942 or
12943 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080012944 variable and is set in the
12945 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12946 class as follows:
12947 <literallayout class='monospaced'>
12948 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
12949 </literallayout>
12950 For the default distribution "poky",
12951 <filename>SDK_TITLE</filename> is set to
12952 "Poky (Yocto Project Reference Distro)".
12953 </para>
12954
12955 <para>
12956 For information on how to change this default title,
12957 see the
12958 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-changing-the-sdk-installer-title'>Changing the Extensible SDK Installer Title</ulink>"
12959 section in the Yocto Project Application Development and
12960 the Extensible Software Development Kit (eSDK) manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050012961 </para>
12962 </glossdef>
12963 </glossentry>
12964
12965 <glossentry id='var-SDK_UPDATE_URL'><glossterm>SDK_UPDATE_URL</glossterm>
12966 <info>
12967 SDK_UPDATE_URL[doc] = "An optional URL for an update server for the extensible SDK."
12968 </info>
12969 <glossdef>
12970 <para role="glossdeffirst">
12971<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12972 An optional URL for an update server for the extensible
12973 SDK.
12974 If set, the value is used as the default update server when
12975 running <filename>devtool sdk-update</filename> within the
12976 extensible SDK.
12977 </para>
12978 </glossdef>
12979 </glossentry>
12980
Patrick Williamsc124f4f2015-09-15 14:41:29 -050012981 <glossentry id='var-SDK_VENDOR'><glossterm>SDK_VENDOR</glossterm>
12982 <info>
12983 SDK_VENDOR[doc] = "Specifies the name of the SDK vendor."
12984 </info>
12985 <glossdef>
12986 <para role="glossdeffirst">
12987<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
12988 Specifies the name of the SDK vendor.
12989 </para>
12990 </glossdef>
12991 </glossentry>
12992
12993 <glossentry id='var-SDK_VERSION'><glossterm>SDK_VERSION</glossterm>
12994 <info>
12995 SDK_VERSION[doc] = "Specifies the version for the SDK."
12996 </info>
12997 <glossdef>
12998 <para role="glossdeffirst">
12999<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13000 Specifies the version of the SDK.
13001 The distribution configuration file (e.g.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013002 <filename>/meta-poky/conf/distro/poky.conf</filename>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013003 defines the <filename>SDK_VERSION</filename> as follows:
13004 <literallayout class='monospaced'>
13005 SDK_VERSION := "${@'${DISTRO_VERSION}'.replace('snapshot-${DATE}','snapshot')}"
13006 </literallayout>
13007 </para>
13008
13009 <para>
13010 For additional information, see the
13011 <link linkend='var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></link>
13012 and
13013 <link linkend='var-DATE'><filename>DATE</filename></link>
13014 variables.
13015 </para>
13016 </glossdef>
13017 </glossentry>
13018
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080013019 <glossentry id='var-SDKEXTPATH'><glossterm>SDKEXTPATH</glossterm>
13020 <info>
13021 SDKEXTPATH[doc] = "The default installation directory for the extensible SDK."
13022 </info>
13023 <glossdef>
13024 <para role="glossdeffirst">
13025<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13026 The default installation directory for the Extensible SDK.
13027 By default, this directory is based on the
13028 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
13029 variable and is set in the
13030 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
13031 class as follows:
13032 <literallayout class='monospaced'>
13033 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
13034 </literallayout>
13035 For the default distribution "poky", the
13036 <filename>SDKEXTPATH</filename> is set to "poky_sdk".
13037 </para>
13038
13039 <para>
13040 For information on how to change this default directory,
13041 see the
13042 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-changing-the-default-sdk-installation-directory'>Changing the Default SDK Installation Directory</ulink>"
13043 section in the Yocto Project Application Development and
13044 the Extensible Software Development Kit (eSDK) manual.
13045 </para>
13046 </glossdef>
13047 </glossentry>
13048
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013049 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
13050 <info>
13051 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'."
13052 </info>
13053 <glossdef>
13054 <para role="glossdeffirst">
13055<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13056 Equivalent to
13057 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
13058 However, this variable applies to the SDK generated from an
13059 image using the following command:
13060 <literallayout class='monospaced'>
13061 $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
13062 </literallayout>
13063 </para>
13064 </glossdef>
13065 </glossentry>
13066
13067 <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
13068 <info>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013069 SDKMACHINE[doc] = "Specifies the architecture (i.e. i686 or x86_64) for which to build SDK items."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013070 </info>
13071 <glossdef>
13072 <para role="glossdeffirst">
13073<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050013074 The machine for which the SDK is built.
13075 In other words, the SDK is built such that it
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013076 runs on the target you specify with the
13077 <filename>SDKMACHINE</filename> value.
13078 The value points to a corresponding
13079 <filename>.conf</filename> file under
13080 <filename>conf/machine-sdk/</filename>.
13081 </para>
13082
13083 <para>
13084 You can use "i686" and "x86_64" as possible values
13085 for this variable. The variable defaults to "i686"
13086 and is set in the local.conf file in the Build Directory.
13087 <literallayout class='monospaced'>
13088 SDKMACHINE ?= "i686"
13089 </literallayout>
13090 <note>
13091 You cannot set the <filename>SDKMACHINE</filename>
13092 variable in your distribution configuration file.
13093 If you do, the configuration will not take affect.
13094 </note>
13095 </para>
13096 </glossdef>
13097 </glossentry>
13098
13099 <glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>
13100 <info>
13101 SDKPATH[doc] = "Defines the path offered to the user for installation of the SDK that is generated by the OpenEmbedded build system."
13102 </info>
13103 <glossdef>
13104 <para role="glossdeffirst">
13105<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13106 Defines the path offered to the user for installation
13107 of the SDK that is generated by the OpenEmbedded build
13108 system.
13109 The path appears as the default location for installing
13110 the SDK when you run the SDK's installation script.
13111 You can override the offered path when you run the
13112 script.
13113 </para>
13114 </glossdef>
13115 </glossentry>
13116
13117 <glossentry id='var-SDKTARGETSYSROOT'><glossterm>SDKTARGETSYSROOT</glossterm>
13118 <info>
13119 SDKTARGETSYSROOT[doc] = "Full path to the sysroot used for cross-compilation within an SDK as it will be when installed into the default SDKPATH."
13120 </info>
13121 <glossdef>
13122 <para role="glossdeffirst">
13123<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13124 The full path to the sysroot used for cross-compilation
13125 within an SDK as it will be when installed into the
13126 default
13127 <link linkend='var-SDKPATH'><filename>SDKPATH</filename></link>.
13128 </para>
13129 </glossdef>
13130 </glossentry>
13131
13132 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
13133 <info>
13134 SECTION[doc] = "The section in which packages should be categorized. Package management utilities can make use of this variable."
13135 </info>
13136 <glossdef>
13137 <para role="glossdeffirst">
13138<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13139 The section in which packages should be categorized.
13140 Package management utilities can make use of this variable.
13141 </para>
13142 </glossdef>
13143 </glossentry>
13144
13145 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
13146 <info>
13147 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."
13148 </info>
13149 <glossdef>
13150 <para role="glossdeffirst">
13151<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13152 Specifies the optimization flags passed to the C compiler
13153 when building for the target.
13154 The flags are passed through the default value of the
13155 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
13156 variable.
13157 </para>
13158
13159 <para>
13160 The <filename>SELECTED_OPTIMIZATION</filename> variable
13161 takes the value of
13162 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
13163 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
13164 If that is the case, the value of
13165 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
13166 </para>
13167 </glossdef>
13168 </glossentry>
13169
13170 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
13171 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013172 SERIAL_CONSOLE[doc] = "Defines the serial consoles (TTYs) to enable using getty."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013173 </info>
13174 <glossdef>
13175 <para role="glossdeffirst">
13176<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040013177 Defines a serial console (TTY) to enable using
13178 <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013179 Provide a value that specifies the baud rate followed by
13180 the TTY device name separated by a space.
13181 You cannot specify more than one TTY device:
13182 <literallayout class='monospaced'>
13183 SERIAL_CONSOLE = "115200 ttyS0"
13184 </literallayout>
13185 <note>
13186 The <filename>SERIAL_CONSOLE</filename> variable
13187 is deprecated.
13188 Please use the
13189 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
13190 variable.
13191 </note>
13192 </para>
13193 </glossdef>
13194 </glossentry>
13195
13196 <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
13197 <info>
13198 SERIAL_CONSOLES[doc] = "Defines the serial consoles (TTYs) to enable using getty."
13199 </info>
13200 <glossdef>
13201 <para role="glossdeffirst">
13202<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040013203 Defines a serial console (TTY) to enable using
13204 <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013205 Provide a value that specifies the baud rate followed by
13206 the TTY device name separated by a semicolon.
13207 Use spaces to separate multiple devices:
13208 <literallayout class='monospaced'>
13209 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
13210 </literallayout>
13211 </para>
13212 </glossdef>
13213 </glossentry>
13214
13215 <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
13216 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060013217 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 -050013218 </info>
13219 <glossdef>
13220 <para role="glossdeffirst">
13221<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060013222 Specifies serial consoles, which must be listed in
13223 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>,
13224 to check against <filename>/proc/console</filename>
13225 before enabling them using getty.
13226 This variable allows aliasing in the format:
13227 &lt;device&gt;:&lt;alias&gt;.
13228 If a device was listed as "sclp_line0"
13229 in <filename>/dev/</filename> and "ttyS0" was listed
13230 in <filename>/proc/console</filename>, you would do the
13231 following:
13232 <literallayout class='monospaced'>
13233 SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0"
13234 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013235 This variable is currently only supported with SysVinit
13236 (i.e. not with systemd).
13237 </para>
13238 </glossdef>
13239 </glossentry>
13240
13241 <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
13242 <info>
13243 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."
13244 </info>
13245 <glossdef>
13246 <para role="glossdeffirst">
13247<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13248 A list of recipe dependencies that should not be used to
13249 determine signatures of tasks from one recipe when they
13250 depend on tasks from another recipe.
13251 For example:
13252 <literallayout class='monospaced'>
13253 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
13254 </literallayout>
13255 </para>
13256
13257 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013258 In the previous example, <filename>intone</filename>
13259 depends on <filename>mplayer2</filename>.
13260 </para>
13261
13262 <para>
13263 You can use the special token <filename>"*"</filename> on
13264 the left-hand side of the dependency to match all
13265 recipes except the one on the right-hand side.
13266 Here is an example:
13267 <literallayout class='monospaced'>
13268 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
13269 </literallayout>
13270 </para>
13271
13272 <para>
13273 In the previous example, all recipes except
13274 <filename>quilt-native</filename> ignore task
13275 signatures from the <filename>quilt-native</filename>
13276 recipe when determining their task signatures.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013277 </para>
13278
13279 <para>
13280 Use of this variable is one mechanism to remove dependencies
13281 that affect task signatures and thus force rebuilds when a
13282 recipe changes.
13283 <note><title>Caution</title>
13284 If you add an inappropriate dependency for a recipe
13285 relationship, the software might break during
13286 runtime if the interface of the second recipe was
13287 changed after the first recipe had been built.
13288 </note>
13289 </para>
13290 </glossdef>
13291 </glossentry>
13292
13293 <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
13294 <info>
13295 SIGGEN_EXCLUDERECIPES_ABISAFE[doc] = "A list of recipes that are completely stable and will never change."
13296 </info>
13297 <glossdef>
13298 <para role="glossdeffirst">
13299<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13300 A list of recipes that are completely stable and will
13301 never change.
13302 The ABI for the recipes in the list are presented by
13303 output from the tasks run to build the recipe.
13304 Use of this variable is one way to remove dependencies from
13305 one recipe on another that affect task signatures and
13306 thus force rebuilds when the recipe changes.
13307 <note><title>Caution</title>
13308 If you add an inappropriate variable to this list,
13309 the software might break at runtime if the
13310 interface of the recipe was changed after the other
13311 had been built.
13312 </note>
13313 </para>
13314 </glossdef>
13315 </glossentry>
13316
13317 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
13318 <info>
13319 SITEINFO_BITS[doc] = "Specifies the number of bits for the target system CPU."
13320 </info>
13321 <glossdef>
13322 <para role="glossdeffirst">
13323<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13324 Specifies the number of bits for the target system CPU.
13325 The value should be either "32" or "64".
13326 </para>
13327 </glossdef>
13328 </glossentry>
13329
13330 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
13331 <info>
13332 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'."
13333 </info>
13334 <glossdef>
13335 <para role="glossdeffirst">
13336<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13337 Specifies the endian byte order of the target system.
13338 The value should be either "le" for little-endian or "be" for big-endian.
13339 </para>
13340 </glossdef>
13341 </glossentry>
13342
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013343 <glossentry id='var-SKIP_FILEDEPS'><glossterm>SKIP_FILEDEPS</glossterm>
13344 <info>
13345 SKIP_FILEDEPS[doc] = "Enables you to remove all files from
13346 the "Provides" section of an RPM package."
13347 </info>
13348 <glossdef>
13349 <para role="glossdeffirst">
13350<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13351 Enables removal of all files from the "Provides" section of
13352 an RPM package.
13353 Removal of these files is required for packages containing
13354 prebuilt binaries and libraries such as
13355 <filename>libstdc++</filename> and
13356 <filename>glibc</filename>.
13357 </para>
13358
13359 <para>
13360 To enable file removal, set the variable to "1" in your
13361 <filename>conf/local.conf</filename> configuration file
13362 in your:
Brad Bishopd7bf8c12018-02-25 22:55:05 -050013363 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013364 <literallayout class='monospaced'>
13365 SKIP_FILEDEPS = "1"
13366 </literallayout>
13367 </para>
13368 </glossdef>
13369 </glossentry>
13370
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013371 <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
13372 <info>
13373 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."
13374 </info>
13375 <glossdef>
13376 <para role="glossdeffirst">
13377<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13378 Groups together machines based upon the same family
13379 of SOC (System On Chip).
13380 You typically set this variable in a common
13381 <filename>.inc</filename> file that you include in the
13382 configuration files of all the machines.
13383 <note>
13384 You must include
13385 <filename>conf/machine/include/soc-family.inc</filename>
13386 for this variable to appear in
13387 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
13388 </note>
13389 </para>
13390 </glossdef>
13391 </glossentry>
13392
13393 <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
13394 <info>
13395 SOLIBS[doc] = "Defines the suffix for shared libraries used on the target platform."
13396 </info>
13397 <glossdef>
13398 <para role="glossdeffirst">
13399<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13400 Defines the suffix for shared libraries used on the
13401 target platform.
13402 By default, this suffix is ".so.*" for all Linux-based
13403 systems and is defined in the
13404 <filename>meta/conf/bitbake.conf</filename> configuration
13405 file.
13406 </para>
13407
13408 <para>
13409 You will see this variable referenced in the default values
13410 of <filename>FILES_${PN}</filename>.
13411 </para>
13412 </glossdef>
13413 </glossentry>
13414
13415 <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
13416 <info>
13417 SOLIBSDEV[doc] = "Defines the suffix for the development symbolic link (symlink) for shared libraries on the target platform."
13418 </info>
13419 <glossdef>
13420 <para role="glossdeffirst">
13421<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13422 Defines the suffix for the development symbolic link
13423 (symlink) for shared libraries on the target platform.
13424 By default, this suffix is ".so" for Linux-based
13425 systems and is defined in the
13426 <filename>meta/conf/bitbake.conf</filename> configuration
13427 file.
13428 </para>
13429
13430 <para>
13431 You will see this variable referenced in the default values
13432 of <filename>FILES_${PN}-dev</filename>.
13433 </para>
13434 </glossdef>
13435 </glossentry>
13436
13437 <glossentry id='var-SOURCE_MIRROR_FETCH'><glossterm>SOURCE_MIRROR_FETCH</glossterm>
13438 <info>
13439 SOURCE_MIRROR_FETCH[doc] = "Set as part of a source mirror generation script to skip COMPATIBLE_MACHINE and COMPATIBLE_HOST checks."
13440 </info>
13441 <glossdef>
13442 <para role="glossdeffirst">
13443<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13444 When you are fetching files to create a mirror of sources
13445 (i.e. creating a source mirror), setting
13446 <filename>SOURCE_MIRROR_FETCH</filename> to "1" in your
13447 <filename>local.conf</filename> configuration file ensures
13448 the source for all recipes are fetched regardless of
13449 whether or not a recipe is compatible with the
13450 configuration.
13451 A recipe is considered incompatible with the currently
13452 configured machine when either or both the
13453 <link linkend='var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></link>
13454 variable and
13455 <link linkend='var-COMPATIBLE_HOST'><filename>COMPATIBLE_HOST</filename></link>
13456 variables specify compatibility with a machine other
13457 than that of the current machine or host.
13458 <note><title>Warning</title>
13459 Do not set the
13460 <filename>SOURCE_MIRROR_FETCH</filename> variable
13461 unless you are creating a source mirror.
13462 In other words, do not set the variable during a
13463 normal build.
13464 </note>
13465 </para>
13466 </glossdef>
13467 </glossentry>
13468
13469 <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm>
13470 <info>
13471 SOURCE_MIRROR_URL[doc] = "URL to source mirror that will be used before fetching from original SRC_URI."
13472 </info>
13473 <glossdef>
13474 <para role="glossdeffirst">
13475<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13476 Defines your own
13477 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
13478 from which to first fetch source before attempting to fetch
13479 from the upstream specified in
13480 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
13481 </para>
13482
13483 <para>
13484 To use this variable, you must globally inherit the
13485 <link linkend='ref-classes-own-mirrors'><filename>own-mirrors</filename></link>
13486 class and then provide the URL to your mirrors.
13487 Here is the general syntax:
13488 <literallayout class='monospaced'>
13489 INHERIT += "own-mirrors"
13490 SOURCE_MIRROR_URL = "http://<replaceable>example</replaceable>.com/<replaceable>my_source_mirror</replaceable>"
13491 </literallayout>
13492 <note>
13493 You can specify only a single URL in
13494 <filename>SOURCE_MIRROR_URL</filename>.
13495 </note>
13496 </para>
13497 </glossdef>
13498 </glossentry>
13499
13500 <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>
13501 <info>
13502 SPDXLICENSEMAP[doc] = "Maps commonly used license names to their SPDX counterparts found in meta/files/common-licenses/."
13503 </info>
13504 <glossdef>
13505 <para role="glossdeffirst">
13506<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13507 Maps commonly used license names to their SPDX counterparts
13508 found in <filename>meta/files/common-licenses/</filename>.
13509 For the default <filename>SPDXLICENSEMAP</filename>
13510 mappings, see the
13511 <filename>meta/conf/licenses.conf</filename> file.
13512 </para>
13513
13514 <para>
13515 For additional information, see the
13516 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
13517 variable.
13518 </para>
13519 </glossdef>
13520 </glossentry>
13521
13522 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
13523 <info>
13524 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."
13525 </info>
13526 <glossdef>
13527 <para role="glossdeffirst">
13528<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13529 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
13530 OpenEmbedded build system to create variants of recipes or packages.
13531 The list specifies the prefixes to strip off during certain circumstances
13532 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
13533 </para>
13534 </glossdef>
13535 </glossentry>
13536
Brad Bishop316dfdd2018-06-25 12:45:53 -040013537 <glossentry id='var-SPL_BINARY'><glossterm>SPL_BINARY</glossterm>
13538 <info>
13539 SPL_BINARY[doc] = "The file type of the Secondary Program Loader (SPL)."
13540 </info>
13541 <glossdef>
13542 <para role="glossdeffirst">
13543<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13544 The file type for the Secondary Program Loader (SPL).
13545 Some devices use an SPL from which to boot (e.g. the
13546 BeagleBone development board).
13547 For such cases, you can declare the file type of the
13548 SPL binary in the <filename>u-boot.inc</filename> include
13549 file, which is used in the U-Boot recipe.
13550 </para>
13551
13552 <para>
13553 The SPL file type is set to "null" by default in the
13554 <filename>u-boot.inc</filename> file as follows:
13555 <literallayout class='monospaced'>
13556 # Some versions of u-boot build an SPL (Second Program Loader) image that
13557 # should be packaged along with the u-boot binary as well as placed in the
13558 # deploy directory. For those versions they can set the following variables
13559 # to allow packaging the SPL.
13560 SPL_BINARY ?= ""
13561 SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"
13562 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
13563 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"
13564 </literallayout>
13565 The <filename>SPL_BINARY</filename> variable helps form
13566 various <filename>SPL_*</filename> variables used by
13567 the OpenEmbedded build system.
13568 </para>
13569
13570 <para>
13571 See the BeagleBone machine configuration example in the
13572 "<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>"
13573 section in the Yocto Project Board Support Package
13574 Developer's Guide for additional information.
13575 </para>
13576 </glossdef>
13577 </glossentry>
13578
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013579 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
13580 <info>
13581 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."
13582 </info>
13583 <glossdef>
13584 <para role="glossdeffirst">
13585<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13586 The list of source files - local or remote.
13587 This variable tells the OpenEmbedded build system which bits
13588 to pull in for the build and how to pull them in.
13589 For example, if the recipe or append file only needs to
13590 fetch a tarball from the Internet, the recipe or
13591 append file uses a single <filename>SRC_URI</filename>
13592 entry.
13593 On the other hand, if the recipe or append file needs to
13594 fetch a tarball, apply two patches, and include a custom
13595 file, the recipe or append file would include four
13596 instances of the variable.
13597 </para>
13598
13599 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013600 The following list explains the available URI protocols.
13601 URI protocols are highly dependent on particular BitBake
13602 Fetcher submodules.
13603 Depending on the fetcher BitBake uses, various URL
13604 parameters are employed.
13605 For specifics on the supported Fetchers, see the
13606 "<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"
13607 section in the BitBake User Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013608 <itemizedlist>
13609 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
13610 Fetches files, which are usually files shipped with
13611 the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050013612 <link linkend='metadata'>Metadata</link>,
Brad Bishop316dfdd2018-06-25 12:45:53 -040013613 from the local machine (e.g.
13614 <ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>patch</ulink>
13615 files).
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013616 The path is relative to the
13617 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
13618 variable.
13619 Thus, the build system searches, in order, from the
13620 following directories, which are assumed to be a
13621 subdirectories of the directory in which the
13622 recipe file (<filename>.bb</filename>) or
13623 append file (<filename>.bbappend</filename>)
13624 resides:
13625 <itemizedlist>
13626 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
13627 The base recipe name without any special
13628 suffix or version numbers.
13629 </para></listitem>
13630 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
13631 <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
13632 The base recipe name and version but without
13633 any special package name suffix.
13634 </para></listitem>
13635 <listitem><para><emphasis>files -</emphasis>
13636 Files within a directory, which is named
13637 <filename>files</filename> and is also
13638 alongside the recipe or append file.
13639 </para></listitem>
13640 </itemizedlist>
13641 <note>
13642 If you want the build system to pick up files
13643 specified through a
13644 <filename>SRC_URI</filename>
13645 statement from your append file, you need to be
13646 sure to extend the
13647 <filename>FILESPATH</filename>
13648 variable by also using the
13649 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
13650 variable from within your append file.
13651 </note>
13652 </para></listitem>
13653 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
13654 Bazaar revision control repository.</para></listitem>
13655 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
13656 Git revision control repository.</para></listitem>
13657 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
13658 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
13659 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
13660 a repo (Git) repository.</para></listitem>
13661 <listitem><para><emphasis><filename>ccrc://</filename> -</emphasis>
13662 Fetches files from a ClearCase repository.
13663 </para></listitem>
13664 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
13665 the Internet using <filename>http</filename>.</para></listitem>
13666 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
13667 from the Internet using <filename>https</filename>.</para></listitem>
13668 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
13669 from the Internet using <filename>ftp</filename>.</para></listitem>
13670 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
13671 a CVS revision control repository.</para></listitem>
13672 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
13673 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
13674 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
13675 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
13676 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
13677 a secure shell.</para></listitem>
13678 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
13679 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
13680 </itemizedlist>
13681 </para>
13682
13683 <para>
13684 Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
13685 Here are standard options:
13686 <itemizedlist>
13687 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
13688 the patch or not.
13689 The default action is to apply the patch.</para></listitem>
13690 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
13691 striplevel to use when applying the patch.
13692 The default level is 1.</para></listitem>
13693 <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
13694 the directory in which the patch should be applied.
13695 The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
13696 </para></listitem>
13697 </itemizedlist>
13698 </para>
13699
13700 <para>
13701 Here are options specific to recipes building code from a revision control system:
13702 <itemizedlist>
13703 <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
13704 Apply the patch only if
13705 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
13706 is equal to or greater than <filename>mindate</filename>.
13707 </para></listitem>
13708 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
13709 Apply the patch only if <filename>SRCDATE</filename>
Andrew Geissler5fa08482019-03-20 15:58:14 -050013710 is not later than <filename>maxdate</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013711 </para></listitem>
13712 <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
13713 Apply the patch only if <filename>SRCREV</filename>
13714 is equal to or greater than <filename>minrev</filename>.
13715 </para></listitem>
13716 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
13717 Apply the patch only if <filename>SRCREV</filename>
13718 is not later than <filename>maxrev</filename>.
13719 </para></listitem>
13720 <listitem><para><emphasis><filename>rev</filename> -</emphasis>
13721 Apply the patch only if <filename>SRCREV</filename>
13722 is equal to <filename>rev</filename>.
13723 </para></listitem>
13724 <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
13725 Apply the patch only if <filename>SRCREV</filename>
13726 is not equal to <filename>rev</filename>.
13727 </para></listitem>
13728 </itemizedlist>
13729 </para>
13730
13731 <para>
13732 Here are some additional options worth mentioning:
13733 <itemizedlist>
13734 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
13735 whether or not to unpack the file if it is an archive.
13736 The default action is to unpack the file.</para></listitem>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013737 <listitem><para><emphasis><filename>destsuffix</filename> -</emphasis> Places the file
13738 (or extracts its contents) into the specified
13739 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
13740 when the Git fetcher is used.
13741 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013742 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
13743 (or extracts its contents) into the specified
Brad Bishop316dfdd2018-06-25 12:45:53 -040013744 subdirectory of <filename>WORKDIR</filename>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013745 when the local (<filename>file://</filename>)
13746 fetcher is used.
13747 </para></listitem>
13748 <listitem><para><emphasis><filename>localdir</filename> -</emphasis> Places the file
13749 (or extracts its contents) into the specified
Brad Bishop316dfdd2018-06-25 12:45:53 -040013750 subdirectory of <filename>WORKDIR</filename> when
13751 the CVS fetcher is used.
Patrick Williamsf1e5d692016-03-30 15:21:19 -050013752 </para></listitem>
13753 <listitem><para><emphasis><filename>subpath</filename> -</emphasis>
13754 Limits the checkout to a specific subpath of the
13755 tree when using the Git fetcher is used.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013756 </para></listitem>
13757 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
13758 name to be used for association with <filename>SRC_URI</filename> checksums
13759 when you have more than one file specified in <filename>SRC_URI</filename>.
13760 </para></listitem>
13761 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
13762 the filename used when storing the downloaded file.</para></listitem>
13763 </itemizedlist>
13764 </para>
13765 </glossdef>
13766 </glossentry>
13767
13768 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
13769 <info>
13770 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."
13771 </info>
13772 <glossdef>
13773 <para role="glossdeffirst">
13774<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13775 By default, the OpenEmbedded build system automatically detects whether
13776 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
13777 contains files that are machine-specific.
13778 If so, the build system automatically changes
13779 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
13780 Setting this variable to "0" disables this behavior.
13781 </para>
13782 </glossdef>
13783 </glossentry>
13784
13785 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
13786 <info>
13787 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)."
13788 </info>
13789 <glossdef>
13790 <para role="glossdeffirst">
13791<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13792 The date of the source code used to build the package.
13793 This variable applies only if the source was fetched from a Source Code Manager (SCM).
13794 </para>
13795 </glossdef>
13796 </glossentry>
13797
13798 <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
13799 <info>
13800 SRCPV[doc] = "Returns the version string of the current package. This string is used to help define the value of PV."
13801 </info>
13802 <glossdef>
13803 <para role="glossdeffirst">
13804<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13805 Returns the version string of the current package.
13806 This string is used to help define the value of
13807 <link linkend='var-PV'><filename>PV</filename></link>.
13808 </para>
13809
13810 <para>
13811 The <filename>SRCPV</filename> variable is defined in the
13812 <filename>meta/conf/bitbake.conf</filename> configuration
13813 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050013814 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013815 as follows:
13816 <literallayout class='monospaced'>
13817 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
13818 </literallayout>
13819 </para>
13820
13821 <para>
13822 Recipes that need to define <filename>PV</filename> do so
13823 with the help of the <filename>SRCPV</filename>.
13824 For example, the <filename>ofono</filename> recipe
13825 (<filename>ofono_git.bb</filename>) located in
13826 <filename>meta/recipes-connectivity</filename> in the
13827 Source Directory defines <filename>PV</filename> as
13828 follows:
13829 <literallayout class='monospaced'>
13830 PV = "0.12-git${SRCPV}"
13831 </literallayout>
13832 </para>
13833 </glossdef>
13834 </glossentry>
13835
13836 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
13837 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013838 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 -050013839 </info>
13840 <glossdef>
13841 <para role="glossdeffirst">
13842<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13843 The revision of the source code used to build the package.
Brad Bishop316dfdd2018-06-25 12:45:53 -040013844 This variable applies to Subversion, Git, Mercurial, and
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013845 Bazaar only.
13846 Note that if you want to build a fixed revision and you
13847 want to avoid performing a query on the remote repository
13848 every time BitBake parses your recipe, you should specify
13849 a <filename>SRCREV</filename> that is a
13850 full revision identifier and not just a tag.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050013851 <note>
13852 For information on limitations when inheriting the
13853 latest revision of software using
13854 <filename>SRCREV</filename>, see the
13855 <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link>
13856 variable description and the
13857 "<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 -050013858 section, which is in the Yocto Project Development
13859 Tasks Manual.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050013860 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013861 </para>
13862
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013863 </glossdef>
13864 </glossentry>
13865
13866 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
13867 <info>
13868 SSTATE_DIR[doc] = "The directory for the shared state cache."
13869 </info>
13870 <glossdef>
13871 <para role="glossdeffirst">
13872<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13873 The directory for the shared state cache.
13874 </para>
13875 </glossdef>
13876 </glossentry>
13877
13878 <glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm>
13879 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013880 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 -050013881 </info>
13882 <glossdef>
13883 <para role="glossdeffirst">
13884<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13885 If set to "1", allows fetches from
13886 mirrors that are specified in
13887 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040013888 to work even when fetching from the network is
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013889 disabled by setting <filename>BB_NO_NETWORK</filename>
13890 to "1".
13891 Using the
13892 <filename>SSTATE_MIRROR_ALLOW_NETWORK</filename>
13893 variable is useful if you have set
13894 <filename>SSTATE_MIRRORS</filename> to point to an
13895 internal server for your shared state cache, but
13896 you want to disable any other fetching from the network.
13897 </para>
13898 </glossdef>
13899 </glossentry>
13900
13901 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
13902 <info>
13903 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."
13904 </info>
13905 <glossdef>
13906 <para role="glossdeffirst">
13907<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13908 Configures the OpenEmbedded build system to search other
13909 mirror locations for prebuilt cache data objects before
13910 building out the data.
13911 This variable works like fetcher
13912 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
13913 and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
13914 and points to the cache locations to check for the shared
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080013915 state (sstate) objects.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013916 </para>
13917
13918 <para>
13919 You can specify a filesystem directory or a remote URL such
13920 as HTTP or FTP.
13921 The locations you specify need to contain the shared state
13922 cache (sstate-cache) results from previous builds.
13923 The sstate-cache you point to can also be from builds on
13924 other machines.
13925 </para>
13926
13927 <para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080013928 When pointing to sstate build artifacts on another machine
13929 that uses a different GCC version for native builds,
13930 you must configure <filename>SSTATE_MIRROR</filename>
13931 with a regular expression that maps local search paths
13932 to server paths.
13933 The paths need to take into account
13934 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
13935 set by the
13936 <link linkend='ref-classes-uninative'><filename>uninative</filename></link>
13937 class.
13938 For example, the following maps the local search path
13939 <filename>universal-4.9</filename> to the server-provided
13940 path <replaceable>server_url_sstate_path</replaceable>:
13941 <literallayout class='monospaced'>
13942 SSTATE_MIRRORS ?= file://universal-4.9/(.*) http://<replaceable>server_url_sstate_path</replaceable>/universal-4.8/\1 \n
13943 </literallayout>
13944 </para>
13945
13946 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013947 If a mirror uses the same structure as
13948 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
13949 you need to add
13950 "PATH" at the end as shown in the examples below.
13951 The build system substitutes the correct path within the
13952 directory structure.
13953 <literallayout class='monospaced'>
13954 SSTATE_MIRRORS ?= "\
Patrick Williamsc0f7c042017-02-23 20:41:17 -060013955 file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH;downloadfilename=PATH \n \
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013956 file://.* file:///<replaceable>some-local-dir</replaceable>/sstate/PATH"
13957 </literallayout>
13958 </para>
13959 </glossdef>
13960 </glossentry>
13961
Brad Bishop6e60e8b2018-02-01 10:27:11 -050013962 <glossentry id='var-SSTATE_SCAN_FILES'><glossterm>SSTATE_SCAN_FILES</glossterm>
13963 <info>
13964 SSTATE_SCAN_FILES[doc] = "Controls the list of files the OpenEmbedded build system scans for hardcoded installation paths."
13965 </info>
13966 <glossdef>
13967 <para role="glossdeffirst">
13968<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
13969 Controls the list of files the OpenEmbedded build system
13970 scans for hardcoded installation paths. The variable uses a
13971 space-separated list of filenames (not paths) with standard
13972 wildcard characters allowed.
13973 </para>
13974
13975 <para>
13976 During a build, the OpenEmbedded build system creates a
13977 shared state (sstate) object during the first stage of
13978 preparing the sysroots. That object is scanned for
13979 hardcoded paths for original installation locations.
13980 The list of files that are scanned for paths is controlled
13981 by the <filename>SSTATE_SCAN_FILES</filename> variable.
13982 Typically, recipes add files they want to be scanned to the
13983 value of <filename>SSTATE_SCAN_FILES</filename> rather than
13984 the variable being comprehensively set. The
13985 <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
13986 class specifies the default list of files.
13987 </para>
13988
13989 <para>
13990 For details on the process, see the
13991 <link linkend='ref-classes-staging'><filename>staging</filename></link>
13992 class.
13993 </para>
13994 </glossdef>
13995 </glossentry>
13996
Patrick Williamsc124f4f2015-09-15 14:41:29 -050013997 <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm>
13998 <info>
13999 STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host."
14000 </info>
14001 <glossdef>
14002 <para role="glossdeffirst">
14003<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14004 Specifies the path to the <filename>/lib</filename>
14005 subdirectory of the sysroot directory for the
14006 build host.
14007 </para>
14008 </glossdef>
14009 </glossentry>
14010
14011 <glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm>
14012 <info>
14013 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)."
14014 </info>
14015 <glossdef>
14016 <para role="glossdeffirst">
14017<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14018 Specifies the path to the <filename>/lib</filename>
14019 subdirectory of the sysroot directory for the target
14020 for which the current recipe is being built
14021 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14022 </para>
14023 </glossdef>
14024 </glossentry>
14025
14026 <glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm>
14027 <info>
14028 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)."
14029 </info>
14030 <glossdef>
14031 <para role="glossdeffirst">
14032<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14033 Specifies the path to the
14034 <filename>/usr/bin</filename> subdirectory of the
14035 sysroot directory for the target for which the current
14036 recipe is being built
14037 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14038 </para>
14039 </glossdef>
14040 </glossentry>
14041
14042 <glossentry id='var-STAGING_BINDIR_CROSS'><glossterm>STAGING_BINDIR_CROSS</glossterm>
14043 <info>
14044 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."
14045 </info>
14046 <glossdef>
14047 <para role="glossdeffirst">
14048<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14049 Specifies the path to the directory containing binary
14050 configuration scripts.
14051 These scripts provide configuration information for
14052 other software that wants to make use of libraries or
14053 include files provided by the software associated with
14054 the script.
14055 <note>
14056 This style of build configuration has been largely
14057 replaced by <filename>pkg-config</filename>.
14058 Consequently, if <filename>pkg-config</filename>
14059 is supported by the library to which you are linking,
14060 it is recommended you use
14061 <filename>pkg-config</filename> instead of a
14062 provided configuration script.
14063 </note>
14064 </para>
14065 </glossdef>
14066 </glossentry>
14067
14068 <glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm>
14069 <info>
14070 STAGING_BINDIR_NATIVE[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the build host."
14071 </info>
14072 <glossdef>
14073 <para role="glossdeffirst">
14074<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14075 Specifies the path to the
14076 <filename>/usr/bin</filename> subdirectory of the
14077 sysroot directory for the build host.
14078 </para>
14079 </glossdef>
14080 </glossentry>
14081
14082 <glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm>
14083 <info>
14084 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)."
14085 </info>
14086 <glossdef>
14087 <para role="glossdeffirst">
14088<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14089 Specifies the path to the <filename>/usr/share</filename>
14090 subdirectory of the sysroot directory for the target
14091 for which the current recipe is being built
14092 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14093 </para>
14094 </glossdef>
14095 </glossentry>
14096
14097 <glossentry id='var-STAGING_DATADIR_NATIVE'><glossterm>STAGING_DATADIR_NATIVE</glossterm>
14098 <info>
14099 STAGING_DATADIR_NATIVE[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the build host."
14100 </info>
14101 <glossdef>
14102 <para role="glossdeffirst">
14103<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14104 Specifies the path to the <filename>/usr/share</filename>
14105 subdirectory of the sysroot directory for the build host.
14106 </para>
14107 </glossdef>
14108 </glossentry>
14109
14110 <glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm>
14111 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014112 STAGING_DIR[doc] = "Helps construct the recipe-sysroots directory, which is used during packaging."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014113 </info>
14114 <glossdef>
14115 <para role="glossdeffirst">
14116<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Brad Bishop316dfdd2018-06-25 12:45:53 -040014117 Helps construct the <filename>recipe-sysroots</filename>
14118 directory, which is used during packaging.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014119 </para>
14120
14121 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014122 For information on how staging for recipe-specific
14123 sysroots occurs, see the
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014124 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014125 task, the
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014126 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-sharing-files-between-recipes'>Sharing Files Between Recipes</ulink>"
Brad Bishop316dfdd2018-06-25 12:45:53 -040014127 section in the Yocto Project Development Tasks Manual, the
14128 "<ulink url='&YOCTO_DOCS_OM_URL;#configuration-compilation-and-staging-dev-environment'>Configuration, Compilation, and Staging</ulink>"
14129 section in the Yocto Project Overview and Concepts Manual,
14130 and the
14131 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
14132 variable.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014133 <note>
14134 Recipes should never write files directly under
Brad Bishop37a0e4d2017-12-04 01:01:44 -050014135 the <filename>STAGING_DIR</filename> directory because
14136 the OpenEmbedded build system
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014137 manages the directory automatically.
14138 Instead, files should be installed to
14139 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
14140 within your recipe's
14141 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
14142 task and then the OpenEmbedded build system will
14143 stage a subset of those files into the sysroot.
14144 </note>
14145 </para>
14146 </glossdef>
14147 </glossentry>
14148
14149 <glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm>
14150 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014151 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 -050014152 </info>
14153 <glossdef>
14154 <para role="glossdeffirst">
14155<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014156 Specifies the path to the sysroot directory for the system
Brad Bishop316dfdd2018-06-25 12:45:53 -040014157 on which the component is built to run (the system that
14158 hosts the component).
14159 For most recipes, this sysroot is the one in which that
14160 recipe's
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014161 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014162 task copies files.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014163 Exceptions include <filename>-native</filename> recipes,
14164 where the <filename>do_populate_sysroot</filename> task
14165 instead uses
14166 <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>.
14167 Depending on the type of recipe and the build target,
14168 <filename>STAGING_DIR_HOST</filename> can have the
14169 following values:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014170 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014171 <listitem><para>
14172 For recipes building for the target machine, the
14173 value is
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014174 "${<link linkend='var-STAGING_DIR'>STAGING_DIR</link>}/${<link linkend='var-MACHINE'>MACHINE</link>}".
14175 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014176 <listitem><para>
14177 For native recipes building for the build host, the
14178 value is empty given the assumption that when
14179 building for the build host, the build host's own
14180 directories should be used.
14181 <note>
14182 <para><filename>-native</filename> recipes are
14183 not installed into host paths like such as
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014184 <filename>/usr</filename>.
14185 Rather, these recipes are installed into
14186 <filename>STAGING_DIR_NATIVE</filename>.
14187 When compiling <filename>-native</filename>
14188 recipes, standard build environment variables
14189 such as
14190 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
14191 and
14192 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
14193 are set up so that both host paths and
14194 <filename>STAGING_DIR_NATIVE</filename> are
14195 searched for libraries and headers using, for
14196 example, GCC's <filename>-isystem</filename>
14197 option.</para>
14198
Brad Bishop316dfdd2018-06-25 12:45:53 -040014199 <para>Thus, the emphasis is that the
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014200 <filename>STAGING_DIR*</filename> variables
14201 should be viewed as input variables by tasks
14202 such as
14203 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>,
14204 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
14205 and
14206 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
14207 Having the real system root correspond to
14208 <filename>STAGING_DIR_HOST</filename> makes
14209 conceptual sense for
14210 <filename>-native</filename> recipes, as
14211 they make use of host headers and libraries.
14212 </para>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014213 </note>
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014214 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014215 </itemizedlist>
14216 </para>
14217 </glossdef>
14218 </glossentry>
14219
14220 <glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm>
14221 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014222 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 -050014223 </info>
14224 <glossdef>
14225 <para role="glossdeffirst">
14226<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014227 Specifies the path to the sysroot directory used when
14228 building components that run on the build host itself.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014229 </para>
14230 </glossdef>
14231 </glossentry>
14232
14233 <glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm>
14234 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014235 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 -050014236 </info>
14237 <glossdef>
14238 <para role="glossdeffirst">
14239<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014240 Specifies the path to the sysroot used for the system for
14241 which the component generates code.
14242 For components that do not generate code, which is the
14243 majority, <filename>STAGING_DIR_TARGET</filename> is set
14244 to match
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014245 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
14246 </para>
14247
14248 <para>
14249 Some recipes build binaries that can run on the target
14250 system but those binaries in turn generate code for
14251 another different system (e.g. cross-canadian recipes).
14252 Using terminology from GNU, the primary system is referred
14253 to as the "HOST" and the secondary, or different, system is
14254 referred to as the "TARGET".
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014255 Thus, the binaries run on the "HOST" system
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014256 and generate binaries for the "TARGET" system.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014257 The <filename>STAGING_DIR_HOST</filename> variable points
14258 to the sysroot used for the "HOST" system, while
14259 <filename>STAGING_DIR_TARGET</filename>
14260 points to the sysroot used for the "TARGET" system.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014261 </para>
14262 </glossdef>
14263 </glossentry>
14264
14265 <glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm>STAGING_ETCDIR_NATIVE</glossterm>
14266 <info>
14267 STAGING_ETCDIR_NATIVE[doc] = "Specifies the path to the /etc subdirectory of the sysroot directory for the build host."
14268 </info>
14269 <glossdef>
14270 <para role="glossdeffirst">
14271<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14272 Specifies the path to the <filename>/etc</filename>
14273 subdirectory of the sysroot directory for the
14274 build host.
14275 </para>
14276 </glossdef>
14277 </glossentry>
14278
14279 <glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm>
14280 <info>
14281 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)."
14282 </info>
14283 <glossdef>
14284 <para role="glossdeffirst">
14285<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14286 Specifies the path to the <filename>/usr</filename>
14287 subdirectory of the sysroot directory for the target
14288 for which the current recipe is being built
14289 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14290 </para>
14291 </glossdef>
14292 </glossentry>
14293
14294 <glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm>
14295 <info>
14296 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)."
14297 </info>
14298 <glossdef>
14299 <para role="glossdeffirst">
14300<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14301 Specifies the path to the
14302 <filename>/usr/include</filename> subdirectory of the
14303 sysroot directory for the target for which the current
14304 recipe being built
14305 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14306 </para>
14307 </glossdef>
14308 </glossentry>
14309
14310 <glossentry id='var-STAGING_INCDIR_NATIVE'><glossterm>STAGING_INCDIR_NATIVE</glossterm>
14311 <info>
14312 STAGING_INCDIR_NATIVE[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the build host."
14313 </info>
14314 <glossdef>
14315 <para role="glossdeffirst">
14316<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14317 Specifies the path to the <filename>/usr/include</filename>
14318 subdirectory of the sysroot directory for the build host.
14319 </para>
14320 </glossdef>
14321 </glossentry>
14322
Patrick Williamsf1e5d692016-03-30 15:21:19 -050014323 <glossentry id='var-STAGING_KERNEL_BUILDDIR'><glossterm>STAGING_KERNEL_BUILDDIR</glossterm>
14324 <info>
14325 STAGING_KERNEL_BUILDDIR[doc] = "Points to the directory containing the kernel build artifacts."
14326 </info>
14327 <glossdef>
14328 <para role="glossdeffirst">
14329<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14330 Points to the directory containing the kernel build
14331 artifacts.
14332 Recipes building software that needs to access kernel
14333 build artifacts
14334 (e.g. <filename>systemtap-uprobes</filename>) can look in
14335 the directory specified with the
14336 <filename>STAGING_KERNEL_BUILDDIR</filename> variable to
14337 find these artifacts after the kernel has been built.
14338 </para>
14339 </glossdef>
14340 </glossentry>
14341
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014342 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
14343 <info>
14344 STAGING_KERNEL_DIR[doc] = "The directory with kernel headers that are required to build out-of-tree modules."
14345 </info>
14346 <glossdef>
14347 <para role="glossdeffirst">
14348<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14349 The directory with kernel headers that are required to build out-of-tree
14350 modules.
14351 </para>
14352 </glossdef>
14353 </glossentry>
14354
14355 <glossentry id='var-STAGING_LIBDIR'><glossterm>STAGING_LIBDIR</glossterm>
14356 <info>
14357 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)."
14358 </info>
14359 <glossdef>
14360 <para role="glossdeffirst">
14361<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14362 Specifies the path to the <filename>/usr/lib</filename>
14363 subdirectory of the sysroot directory for the target for
14364 which the current recipe is being built
14365 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14366 </para>
14367 </glossdef>
14368 </glossentry>
14369
14370 <glossentry id='var-STAGING_LIBDIR_NATIVE'><glossterm>STAGING_LIBDIR_NATIVE</glossterm>
14371 <info>
14372 STAGING_LIBDIR_NATIVE[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the build host."
14373 </info>
14374 <glossdef>
14375 <para role="glossdeffirst">
14376<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14377 Specifies the path to the <filename>/usr/lib</filename>
14378 subdirectory of the sysroot directory for the build host.
14379 </para>
14380 </glossdef>
14381 </glossentry>
14382
14383 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
14384 <info>
14385 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."
14386 </info>
14387 <glossdef>
14388 <para role="glossdeffirst">
14389<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14390 Specifies the base path used to create recipe stamp files.
14391 The path to an actual stamp file is constructed by evaluating this
14392 string and then appending additional information.
14393 Currently, the default assignment for <filename>STAMP</filename>
14394 as set in the <filename>meta/conf/bitbake.conf</filename> file
14395 is:
14396 <literallayout class='monospaced'>
14397 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
14398 </literallayout>
14399 </para>
14400
14401 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014402 For information on how BitBake uses stamp files to determine
14403 if a task should be rerun, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040014404 "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
14405 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014406 </para>
14407
14408 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014409 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
14410 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
14411 <link linkend='var-PN'><filename>PN</filename></link>,
14412 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
14413 <link linkend='var-PV'><filename>PV</filename></link>, and
14414 <link linkend='var-PR'><filename>PR</filename></link> for related variable
14415 information.
14416 </para>
14417 </glossdef>
14418 </glossentry>
14419
14420 <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
14421 <info>
14422 STAMPS_DIR[doc] = "Specifies the base directory in which the OpenEmbedded build system places stamps."
14423 </info>
14424 <glossdef>
14425 <para role="glossdeffirst">
14426<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14427 Specifies the base directory in which the OpenEmbedded
14428 build system places stamps.
14429 The default directory is
14430 <filename>${TMPDIR}/stamps</filename>.
14431 </para>
14432 </glossdef>
14433 </glossentry>
14434
14435 <glossentry id='var-STRIP'><glossterm>STRIP</glossterm>
14436 <info>
14437 STRIP[doc] = "Minimal command and arguments to run 'strip' (strip symbols)."
14438 </info>
14439 <glossdef>
14440 <para role="glossdeffirst">
14441<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14442 The minimal command and arguments to run
14443 <filename>strip</filename>, which is used to strip
14444 symbols.
14445 </para>
14446 </glossdef>
14447 </glossentry>
14448
14449 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
14450 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014451 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 -050014452 </info>
14453 <glossdef>
14454 <para role="glossdeffirst">
14455<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14456 The short (72 characters or less) summary of the binary package for packaging
Brad Bishop316dfdd2018-06-25 12:45:53 -040014457 systems such as <filename>opkg</filename>, <filename>rpm</filename>, or
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014458 <filename>dpkg</filename>.
14459 By default, <filename>SUMMARY</filename> is used to define
14460 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
14461 variable if <filename>DESCRIPTION</filename> is not set
14462 in the recipe.
14463 </para>
14464 </glossdef>
14465 </glossentry>
14466
14467 <glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm>
14468 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014469 SVNDIR[doc] = "The directory where Subversion checkouts are stored."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014470 </info>
14471 <glossdef>
14472 <para role="glossdeffirst">
14473<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14474 The directory in which files checked out of a Subversion
14475 system are stored.
14476 </para>
14477 </glossdef>
14478 </glossentry>
14479
14480 <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm>
14481 <info>
14482 SYSLINUX_DEFAULT_CONSOLE[doc] = "Specifies the kernel boot default console."
14483 </info>
14484 <glossdef>
14485 <para role="glossdeffirst">
14486<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14487 Specifies the kernel boot default console.
14488 If you want to use a console other than the default,
14489 set this variable in your recipe as follows where "X" is
14490 the console number you want to use:
14491 <literallayout class='monospaced'>
14492 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
14493 </literallayout>
14494 </para>
14495
14496 <para>
14497 The
14498 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14499 class initially sets this variable to null but then checks
14500 for a value later.
14501 </para>
14502 </glossdef>
14503 </glossentry>
14504
14505 <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm>
14506 <info>
14507 SYSLINUX_OPTS[doc] = "Lists additional options to add to the syslinux file."
14508 </info>
14509 <glossdef>
14510 <para role="glossdeffirst">
14511<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14512 Lists additional options to add to the syslinux file.
14513 You need to set this variable in your recipe.
14514 If you want to list multiple options, separate the options
14515 with a semicolon character (<filename>;</filename>).
14516 </para>
14517
14518 <para>
14519 The
14520 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14521 class uses this variable to create a set of options.
14522 </para>
14523 </glossdef>
14524 </glossentry>
14525
14526 <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm>
14527 <info>
14528 SYSLINUX_SERIAL[doc] = "Specifies the alternate serial port or turns it off."
14529 </info>
14530 <glossdef>
14531 <para role="glossdeffirst">
14532<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14533 Specifies the alternate serial port or turns it off.
14534 To turn off serial, set this variable to an empty string
14535 in your recipe.
14536 The variable's default value is set in the
14537 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014538 class as follows:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014539 <literallayout class='monospaced'>
14540 SYSLINUX_SERIAL ?= "0 115200"
14541 </literallayout>
14542 </para>
14543
14544 <para>
14545 The class checks for and uses the variable as needed.
14546 </para>
14547 </glossdef>
14548 </glossentry>
14549
14550 <glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm>
14551 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014552 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 -050014553 </info>
14554 <glossdef>
14555 <para role="glossdeffirst">
14556<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14557 An <filename>.LSS</filename> file used as the background
Brad Bishop316dfdd2018-06-25 12:45:53 -040014558 for the VGA boot menu when you use the boot menu.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014559 You need to set this variable in your recipe.
14560 </para>
14561
14562 <para>
14563 The
14564 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14565 class checks for this variable and if found, the
14566 OpenEmbedded build system installs the splash screen.
14567 </para>
14568 </glossdef>
14569 </glossentry>
14570
14571 <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>
14572 <info>
14573 SYSLINUX_SERIAL_TTY[doc] = "Specifies the alternate console=tty... kernel boot argument."
14574 </info>
14575 <glossdef>
14576 <para role="glossdeffirst">
14577<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14578 Specifies the alternate console=tty... kernel boot argument.
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_TTY ?= "console=ttyS0,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
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014593 <glossentry id='var-SYSROOT_DESTDIR'><glossterm>SYSROOT_DESTDIR</glossterm>
14594 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014595 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 -050014596 </info>
14597 <glossdef>
14598 <para role="glossdeffirst">
14599<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14600 Points to the temporary directory under the work directory
14601 (default
Brad Bishopd7bf8c12018-02-25 22:55:05 -050014602 "<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/sysroot-destdir</filename>")
Brad Bishop316dfdd2018-06-25 12:45:53 -040014603 where the files populated into the sysroot are assembled
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014604 during the
14605 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14606 task.
Brad Bishop6e60e8b2018-02-01 10:27:11 -050014607 </para>
14608 </glossdef>
14609 </glossentry>
14610
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014611 <glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm>
14612 <info>
14613 SYSROOT_DIRS[doc] = "Directories that are staged into the sysroot by the do_populate_sysroot task."
14614 </info>
14615 <glossdef>
14616 <para role="glossdeffirst">
14617<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14618 Directories that are staged into the sysroot by the
14619 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14620 task.
14621 By default, the following directories are staged:
14622 <literallayout class='monospaced'>
14623 SYSROOT_DIRS = " \
14624 ${includedir} \
14625 ${libdir} \
14626 ${base_libdir} \
14627 ${nonarch_base_libdir} \
14628 ${datadir} \
14629 "
14630 </literallayout>
14631 </para>
14632 </glossdef>
14633 </glossentry>
14634
14635 <glossentry id='var-SYSROOT_DIRS_BLACKLIST'><glossterm>SYSROOT_DIRS_BLACKLIST</glossterm>
14636 <info>
14637 SYSROOT_DIRS_BLACKLIST[doc] = "Directories that are not staged into the sysroot by the do_populate_sysroot task."
14638 </info>
14639 <glossdef>
14640 <para role="glossdeffirst">
14641<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14642 Directories that are not staged into the sysroot by the
14643 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14644 task.
14645 You can use this variable to exclude certain subdirectories
14646 of directories listed in
14647 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
14648 from staging.
14649 By default, the following directories are not staged:
14650 <literallayout class='monospaced'>
14651 SYSROOT_DIRS_BLACKLIST = " \
14652 ${mandir} \
14653 ${docdir} \
14654 ${infodir} \
14655 ${datadir}/locale \
14656 ${datadir}/applications \
14657 ${datadir}/fonts \
14658 ${datadir}/pixmaps \
14659 "
14660 </literallayout>
14661 </para>
14662 </glossdef>
14663 </glossentry>
14664
14665 <glossentry id='var-SYSROOT_DIRS_NATIVE'><glossterm>SYSROOT_DIRS_NATIVE</glossterm>
14666 <info>
14667 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."
14668 </info>
14669 <glossdef>
14670 <para role="glossdeffirst">
14671<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14672 Extra directories staged into the sysroot by the
14673 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14674 task for <filename>-native</filename> recipes, in addition
14675 to those specified in
14676 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>.
14677 By default, the following extra directories are staged:
14678 <literallayout class='monospaced'>
14679 SYSROOT_DIRS_NATIVE = " \
14680 ${bindir} \
14681 ${sbindir} \
14682 ${base_bindir} \
14683 ${base_sbindir} \
14684 ${libexecdir} \
14685 ${sysconfdir} \
14686 ${localstatedir} \
14687 "
14688 </literallayout>
14689 <note>
14690 Programs built by <filename>-native</filename> recipes
14691 run directly from the sysroot
14692 (<link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>),
14693 which is why additional directories containing program
14694 executables and supporting files need to be staged.
14695 </note>
14696 </para>
14697 </glossdef>
14698 </glossentry>
14699
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014700 <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
14701 <info>
14702 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."
14703 </info>
14704 <glossdef>
14705 <para role="glossdeffirst">
14706<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14707 A list of functions to execute after files are staged into
14708 the sysroot.
14709 These functions are usually used to apply additional
14710 processing on the staged files, or to stage additional
14711 files.
14712 </para>
14713 </glossdef>
14714 </glossentry>
14715
14716 <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>
14717 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014718 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 -050014719 </info>
14720 <glossdef>
14721 <para role="glossdeffirst">
14722<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14723 When inheriting the
14724 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014725 class, this variable specifies whether the specified service
14726 in
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014727 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014728 should start automatically or not.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014729 By default, the service is enabled to automatically start
14730 at boot time.
14731 The default setting is in the
14732 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14733 class as follows:
14734 <literallayout class='monospaced'>
14735 SYSTEMD_AUTO_ENABLE ??= "enable"
14736 </literallayout>
14737 </para>
14738
14739 <para>
14740 You can disable the service by setting the variable to
14741 "disable".
14742 </para>
14743 </glossdef>
14744 </glossentry>
14745
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014746 <glossentry id='var-SYSTEMD_BOOT_CFG'><glossterm>SYSTEMD_BOOT_CFG</glossterm>
14747 <info>
14748 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."
14749 </info>
14750 <glossdef>
14751 <para role="glossdeffirst">
14752<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14753 When
14754 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14755 is set to "systemd-boot", the
14756 <filename>SYSTEMD_BOOT_CFG</filename> variable specifies the
14757 configuration file that should be used.
14758 By default, the
14759 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14760 class sets the <filename>SYSTEMD_BOOT_CFG</filename> as
14761 follows:
14762 <literallayout class='monospaced'>
14763 SYSTEMD_BOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf"
14764 </literallayout>
14765 </para>
14766
14767 <para>
14768 For information on Systemd-boot, see the
14769 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14770 </para>
14771 </glossdef>
14772 </glossentry>
14773
14774 <glossentry id='var-SYSTEMD_BOOT_ENTRIES'><glossterm>SYSTEMD_BOOT_ENTRIES</glossterm>
14775 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014776 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 -060014777 </info>
14778 <glossdef>
14779 <para role="glossdeffirst">
14780<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14781 When
14782 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14783 is set to "systemd-boot", the
14784 <filename>SYSTEMD_BOOT_ENTRIES</filename> variable specifies
14785 a list of entry files
Brad Bishop316dfdd2018-06-25 12:45:53 -040014786 (<filename>*.conf</filename>) to install that contain
14787 one boot entry per file.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060014788 By default, the
14789 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14790 class sets the <filename>SYSTEMD_BOOT_ENTRIES</filename> as
14791 follows:
14792 <literallayout class='monospaced'>
14793 SYSTEMD_BOOT_ENTRIES ?= ""
14794 </literallayout>
14795 </para>
14796
14797 <para>
14798 For information on Systemd-boot, see the
14799 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14800 </para>
14801 </glossdef>
14802 </glossentry>
14803
14804 <glossentry id='var-SYSTEMD_BOOT_TIMEOUT'><glossterm>SYSTEMD_BOOT_TIMEOUT</glossterm>
14805 <info>
14806 SYSTEMD_BOOT_TIMEOUT[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_TIMEOUT variable specifies the boot menu timeout in seconds."
14807 </info>
14808 <glossdef>
14809 <para role="glossdeffirst">
14810<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14811 When
14812 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14813 is set to "systemd-boot", the
14814 <filename>SYSTEMD_BOOT_TIMEOUT</filename> variable specifies
14815 the boot menu timeout in seconds.
14816 By default, the
14817 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14818 class sets the <filename>SYSTEMD_BOOT_TIMEOUT</filename> as
14819 follows:
14820 <literallayout class='monospaced'>
14821 SYSTEMD_BOOT_TIMEOUT ?= "10"
14822 </literallayout>
14823 </para>
14824
14825 <para>
14826 For information on Systemd-boot, see the
14827 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14828 </para>
14829 </glossdef>
14830 </glossentry>
14831
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014832 <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>
14833 <info>
14834 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."
14835 </info>
14836 <glossdef>
14837 <para role="glossdeffirst">
14838<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14839 When inheriting the
14840 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14841 class, this variable locates the systemd unit files when
14842 they are not found in the main recipe's package.
14843 By default, the
14844 <filename>SYSTEMD_PACKAGES</filename> variable is set
14845 such that the systemd unit files are assumed to reside in
14846 the recipes main package:
14847 <literallayout class='monospaced'>
14848 SYSTEMD_PACKAGES ?= "${PN}"
14849 </literallayout>
14850 </para>
14851
14852 <para>
14853 If these unit files are not in this recipe's main
14854 package, you need to use
14855 <filename>SYSTEMD_PACKAGES</filename> to list the package
14856 or packages in which the build system can find the systemd
14857 unit files.
14858 </para>
14859 </glossdef>
14860 </glossentry>
14861
14862 <glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm>
14863 <info>
14864 SYSTEMD_SERVICE[doc] = "For recipes that inherit the systemd class, this variable specifies the systemd service name for a package."
14865 </info>
14866 <glossdef>
14867 <para role="glossdeffirst">
14868<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14869 When inheriting the
14870 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14871 class, this variable specifies the systemd service name for
14872 a package.
14873 </para>
14874
14875 <para>
14876 When you specify this file in your recipe, use a package
14877 name override to indicate the package to which the value
14878 applies.
14879 Here is an example from the connman recipe:
14880 <literallayout class='monospaced'>
14881 SYSTEMD_SERVICE_${PN} = "connman.service"
14882 </literallayout>
14883 </para>
14884 </glossdef>
14885 </glossentry>
14886
14887 <glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>SYSVINIT_ENABLED_GETTYS</glossterm>
14888 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040014889 SYSVINIT_ENABLED_GETTYS[doc] = "Specifies which virtual terminals should run a getty, the default is '1'."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014890 </info>
14891 <glossdef>
14892 <para role="glossdeffirst">
14893<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14894 When using
14895 <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
14896 specifies a space-separated list of the virtual terminals
Brad Bishop316dfdd2018-06-25 12:45:53 -040014897 that should run a
Patrick Williamsc124f4f2015-09-15 14:41:29 -050014898 <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
14899 (allowing login), assuming
14900 <link linkend='var-USE_VT'><filename>USE_VT</filename></link>
14901 is not set to "0".
14902 </para>
14903
14904 <para>
14905 The default value for
14906 <filename>SYSVINIT_ENABLED_GETTYS</filename> is "1"
14907 (i.e. only run a getty on the first virtual terminal).
14908 </para>
14909 </glossdef>
14910 </glossentry>
14911
14912 </glossdiv>
14913
14914 <glossdiv id='var-glossary-t'><title>T</title>
14915
14916 <glossentry id='var-T'><glossterm>T</glossterm>
14917 <info>
14918 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."
14919 </info>
14920 <glossdef>
14921 <para role="glossdeffirst">
14922<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14923 This variable points to a directory were BitBake places
14924 temporary files, which consist mostly of task logs and
14925 scripts, when building a particular recipe.
14926 The variable is typically set as follows:
14927 <literallayout class='monospaced'>
14928 T = "${WORKDIR}/temp"
14929 </literallayout>
14930 </para>
14931
14932 <para>
14933 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
14934 is the directory into which BitBake unpacks and builds the
14935 recipe.
14936 The default <filename>bitbake.conf</filename> file sets this variable.</para>
14937 <para>The <filename>T</filename> variable is not to be confused with
14938 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
14939 which points to the root of the directory tree where BitBake
14940 places the output of an entire build.
14941 </para>
14942 </glossdef>
14943 </glossentry>
14944
14945 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
14946 <info>
14947 TARGET_ARCH[doc] = "The architecture of the device being built. The OpenEmbedded build system supports the following architectures: arm, mips, ppc, x86, x86-64."
14948 </info>
14949 <glossdef>
14950 <para role="glossdeffirst">
14951<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14952 The target machine's architecture.
14953 The OpenEmbedded build system supports many
14954 architectures.
14955 Here is an example list of architectures supported.
14956 This list is by no means complete as the architecture
14957 is configurable:
14958 <literallayout class='monospaced'>
14959 arm
14960 i586
14961 x86_64
14962 powerpc
14963 powerpc64
14964 mips
14965 mipsel
14966 </literallayout>
14967 </para>
14968
14969 <para>
14970 For additional information on machine architectures, see
14971 the
14972 <link linkend='var-TUNE_ARCH'><filename>TUNE_ARCH</filename></link>
14973 variable.
14974 </para>
14975 </glossdef>
14976 </glossentry>
14977
14978 <glossentry id='var-TARGET_AS_ARCH'><glossterm>TARGET_AS_ARCH</glossterm>
14979 <info>
14980 TARGET_AS_ARCH[doc] = "Specifies architecture-specific assembler flags for the target system."
14981 </info>
14982 <glossdef>
14983 <para role="glossdeffirst">
14984<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
14985 Specifies architecture-specific assembler flags for the
14986 target system.
14987 <filename>TARGET_AS_ARCH</filename> is initialized from
14988 <link linkend='var-TUNE_ASARGS'><filename>TUNE_ASARGS</filename></link>
14989 by default in the BitBake configuration file
14990 (<filename>meta/conf/bitbake.conf</filename>):
14991 <literallayout class='monospaced'>
14992 TARGET_AS_ARCH = "${TUNE_ASARGS}"
14993 </literallayout>
14994 </para>
14995 </glossdef>
14996 </glossentry>
14997
14998 <glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm>
14999 <info>
15000 TARGET_CC_ARCH[doc] = "Specifies architecture-specific C compiler flags for the target system."
15001 </info>
15002 <glossdef>
15003 <para role="glossdeffirst">
15004<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15005 Specifies architecture-specific C compiler flags for the
15006 target system.
15007 <filename>TARGET_CC_ARCH</filename> is initialized from
15008 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
15009 by default.
15010 <note>
15011 It is a common workaround to append
15012 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
15013 to <filename>TARGET_CC_ARCH</filename>
15014 in recipes that build software for the target that
15015 would not otherwise respect the exported
15016 <filename>LDFLAGS</filename> variable.
15017 </note>
15018 </para>
15019 </glossdef>
15020 </glossentry>
15021
15022 <glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm>
15023 <info>
15024 TARGET_CC_KERNEL_ARCH[doc] = "This is a specific kernel compiler flag for a CPU or Application Binary Interface (ABI) tune."
15025 </info>
15026 <glossdef>
15027 <para role="glossdeffirst">
15028<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15029 This is a specific kernel compiler flag for a CPU or
15030 Application Binary Interface (ABI) tune.
15031 The flag is used rarely and only for cases where a
15032 userspace
15033 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
15034 is not compatible with the kernel compilation.
15035 The <filename>TARGET_CC_KERNEL_ARCH</filename> variable
15036 allows the kernel (and associated modules) to use a
15037 different configuration.
15038 See the
15039 <filename>meta/conf/machine/include/arm/feature-arm-thumb.inc</filename>
15040 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015041 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015042 for an example.
15043 </para>
15044 </glossdef>
15045 </glossentry>
15046
15047 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
15048 <info>
15049 TARGET_CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as CFLAGS."
15050 </info>
15051 <glossdef>
15052 <para role="glossdeffirst">
15053<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15054 Specifies the flags to pass to the C compiler when building
15055 for the target.
15056 When building in the target context,
15057 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
15058 is set to the value of this variable by default.
15059 </para>
15060
15061 <para>
15062 Additionally, the SDK's environment setup script sets
Brad Bishop316dfdd2018-06-25 12:45:53 -040015063 the <filename>CFLAGS</filename> variable in the environment
15064 to the <filename>TARGET_CFLAGS</filename> value so that
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015065 executables built using the SDK also have the flags
15066 applied.
15067 </para>
15068 </glossdef>
15069 </glossentry>
15070
15071 <glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm>
15072 <info>
15073 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."
15074 </info>
15075 <glossdef>
15076 <para role="glossdeffirst">
15077<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15078 Specifies the flags to pass to the C pre-processor
15079 (i.e. to both the C and the C++ compilers) when building
15080 for the target.
15081 When building in the target context,
15082 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
15083 is set to the value of this variable by default.
15084 </para>
15085
15086 <para>
15087 Additionally, the SDK's environment setup script sets
Brad Bishop316dfdd2018-06-25 12:45:53 -040015088 the <filename>CPPFLAGS</filename> variable in the
15089 environment to the <filename>TARGET_CPPFLAGS</filename>
15090 value so that executables built using the SDK also have
15091 the flags applied.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015092 </para>
15093 </glossdef>
15094 </glossentry>
15095
15096 <glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm>
15097 <info>
15098 TARGET_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the target."
15099 </info>
15100 <glossdef>
15101 <para role="glossdeffirst">
15102<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15103 Specifies the flags to pass to the C++ compiler when
15104 building for the target.
15105 When building in the target context,
15106 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
15107 is set to the value of this variable by default.
15108 </para>
15109
15110 <para>
15111 Additionally, the SDK's environment setup script sets
Brad Bishop316dfdd2018-06-25 12:45:53 -040015112 the <filename>CXXFLAGS</filename> variable in the
15113 environment to the <filename>TARGET_CXXFLAGS</filename>
15114 value so that executables built using the SDK also have
15115 the flags applied.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015116 </para>
15117 </glossdef>
15118 </glossentry>
15119
15120 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
15121 <info>
15122 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."
15123 </info>
15124 <glossdef>
15125 <para role="glossdeffirst">
15126<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15127 Specifies the method for handling FPU code.
15128 For FPU-less targets, which include most ARM CPUs, the variable must be
15129 set to "soft".
15130 If not, the kernel emulation gets used, which results in a performance penalty.
15131 </para>
15132 </glossdef>
15133 </glossentry>
15134
15135 <glossentry id='var-TARGET_LD_ARCH'><glossterm>TARGET_LD_ARCH</glossterm>
15136 <info>
15137 TARGET_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the target system."
15138 </info>
15139 <glossdef>
15140 <para role="glossdeffirst">
15141<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15142 Specifies architecture-specific linker flags for the
15143 target system.
15144 <filename>TARGET_LD_ARCH</filename> is initialized from
15145 <link linkend='var-TUNE_LDARGS'><filename>TUNE_LDARGS</filename></link>
15146 by default in the BitBake configuration file
15147 (<filename>meta/conf/bitbake.conf</filename>):
15148 <literallayout class='monospaced'>
15149 TARGET_LD_ARCH = "${TUNE_LDARGS}"
15150 </literallayout>
15151 </para>
15152 </glossdef>
15153 </glossentry>
15154
15155 <glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm>
15156 <info>
15157 TARGET_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the target."
15158 </info>
15159 <glossdef>
15160 <para role="glossdeffirst">
15161<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15162 Specifies the flags to pass to the linker when building
15163 for the target.
15164 When building in the target context,
15165 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
15166 is set to the value of this variable by default.
15167 </para>
15168
15169 <para>
15170 Additionally, the SDK's environment setup script sets
15171 the
15172 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
15173 variable in the environment to the
15174 <filename>TARGET_LDFLAGS</filename> value so that
15175 executables built using the SDK also have the flags
15176 applied.
15177 </para>
15178 </glossdef>
15179 </glossentry>
15180
15181 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
15182 <info>
15183 TARGET_OS[doc] = "Specifies the target's operating system."
15184 </info>
15185 <glossdef>
15186 <para role="glossdeffirst">
15187<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15188 Specifies the target's operating system.
Brad Bishop316dfdd2018-06-25 12:45:53 -040015189 The variable can be set to "linux" for glibc-based systems
15190 (GNU C Library) and to "linux-musl" for musl libc.
15191 For ARM/EABI targets, "linux-gnueabi" and "linux-musleabi"
15192 possible values exist.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015193 </para>
15194 </glossdef>
15195 </glossentry>
15196
15197 <glossentry id='var-TARGET_PREFIX'><glossterm>TARGET_PREFIX</glossterm>
15198 <info>
15199 TARGET_PREFIX[doc] = "The prefix used for the toolchain binary target tools."
15200 </info>
15201 <glossdef>
15202 <para role="glossdeffirst">
15203<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15204 Specifies the prefix used for the toolchain binary target
15205 tools.
15206 </para>
15207
15208 <para>
15209 Depending on the type of recipe and the build target,
15210 <filename>TARGET_PREFIX</filename> is set as follows:
15211 <itemizedlist>
15212 <listitem><para>
15213 For recipes building for the target machine,
15214 the value is
15215 "${<link linkend='var-TARGET_SYS'>TARGET_SYS</link>}-".
15216 </para></listitem>
15217 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015218 For native recipes, the build system sets the
15219 variable to the value of
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015220 <filename>BUILD_PREFIX</filename>.
15221 </para></listitem>
15222 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015223 For native SDK recipes
15224 (<filename>nativesdk</filename>), the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015225 build system sets the variable to the value of
15226 <filename>SDK_PREFIX</filename>.
15227 </para></listitem>
15228 </itemizedlist>
15229 </para>
15230 </glossdef>
15231 </glossentry>
15232
15233 <glossentry id='var-TARGET_SYS'><glossterm>TARGET_SYS</glossterm>
15234 <info>
15235 TARGET_SYS[doc] = "The target system is comprised of TARGET_ARCH,TARGET_VENDOR and TARGET_OS."
15236 </info>
15237 <glossdef>
15238 <para role="glossdeffirst">
15239<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15240 Specifies the system, including the architecture and the
15241 operating system, for which the build is occurring in
15242 the context of the current recipe.
15243 </para>
15244
15245 <para>
15246 The OpenEmbedded build system automatically sets this
15247 variable based on
15248 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
15249 <link linkend='var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></link>,
15250 and
15251 <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>
15252 variables.
15253 <note>
15254 You do not need to set the
15255 <filename>TARGET_SYS</filename> variable yourself.
15256 </note>
15257 </para>
15258
15259 <para>
15260 Consider these two examples:
15261 <itemizedlist>
15262 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015263 Given a native recipe on a 32-bit, x86 machine
15264 running Linux, the value is "i686-linux".
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015265 </para></listitem>
15266 <listitem><para>
15267 Given a recipe being built for a little-endian,
15268 MIPS target running Linux, the value might be
15269 "mipsel-linux".
15270 </para></listitem>
15271 </itemizedlist>
15272 </para>
15273 </glossdef>
15274 </glossentry>
15275
15276 <glossentry id='var-TARGET_VENDOR'><glossterm>TARGET_VENDOR</glossterm>
15277 <info>
15278 TARGET_VENDOR[doc] = "The name of the target vendor."
15279 </info>
15280 <glossdef>
15281 <para role="glossdeffirst">
15282<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15283 Specifies the name of the target vendor.
15284 </para>
15285 </glossdef>
15286 </glossentry>
15287
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015288 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
15289 <info>
15290 TCLIBC[doc] = "Specifies GNU standard C library (libc) variant to use during the build process. You can select 'glibc', 'musl' or "newlib."
15291 </info>
15292 <glossdef>
15293 <para role="glossdeffirst">
15294<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15295 Specifies the GNU standard C library
15296 (<filename>libc</filename>) variant to use during the
15297 build process.
15298 This variable replaces <filename>POKYLIBC</filename>,
15299 which is no longer supported.
15300 </para>
15301
15302 <para>
15303 You can select "glibc", "musl", "newlib", or "baremetal"
15304 </para>
15305 </glossdef>
15306 </glossentry>
15307
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015308 <glossentry id='var-TCLIBCAPPEND'><glossterm>TCLIBCAPPEND</glossterm>
15309 <info>
15310 TCLIBCAPPEND[doc] = "Specifies a suffix appended to TMPDIR that identifies the libc variant for the build."
15311 </info>
15312 <glossdef>
15313 <para role="glossdeffirst">
15314<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15315 Specifies a suffix to be appended onto the
15316 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
15317 value.
15318 The suffix identifies the <filename>libc</filename> variant
15319 for building.
15320 When you are building for multiple variants with the same
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015321 <link linkend='build-directory'>Build Directory</link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015322 this mechanism ensures that output for different
15323 <filename>libc</filename> variants is kept separate to
15324 avoid potential conflicts.
15325 </para>
15326
15327 <para>
15328 In the <filename>defaultsetup.conf</filename> file, the
15329 default value of <filename>TCLIBCAPPEND</filename> is
15330 "-${TCLIBC}".
15331 However, distros such as poky, which normally only support
15332 one <filename>libc</filename> variant, set
15333 <filename>TCLIBCAPPEND</filename> to "" in their distro
15334 configuration file resulting in no suffix being applied.
15335 </para>
15336 </glossdef>
15337 </glossentry>
15338
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015339 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
15340 <info>
15341 TCMODE[doc] = "Enables an external toolchain (where provided by an additional layer) if set to a value other than 'default'."
15342 </info>
15343 <glossdef>
15344 <para role="glossdeffirst">
15345<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15346 Specifies the toolchain selector.
15347 <filename>TCMODE</filename> controls the characteristics
15348 of the generated packages and images by telling the
15349 OpenEmbedded build system which toolchain profile to use.
15350 By default, the OpenEmbedded build system builds its own
15351 internal toolchain.
15352 The variable's default value is "default", which uses
15353 that internal toolchain.
15354 <note>
15355 If <filename>TCMODE</filename> is set to a value
15356 other than "default", then it is your responsibility
15357 to ensure that the toolchain is compatible with the
15358 default toolchain.
15359 Using older or newer versions of these components
15360 might cause build problems.
Brad Bishop316dfdd2018-06-25 12:45:53 -040015361 See the Release Notes for the Yocto Project release
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015362 for the specific components with which the toolchain
15363 must be compatible.
Brad Bishop316dfdd2018-06-25 12:45:53 -040015364 To access the Release Notes, go to the
15365 <ulink url='&YOCTO_HOME_URL;/software-overview/downloads/'>Downloads</ulink>
15366 page on the Yocto Project website and click on the
15367 "RELEASE INFORMATION" link for the appropriate
15368 release.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015369 </note>
15370 </para>
15371
15372 <para>
15373 The <filename>TCMODE</filename> variable is similar to
15374 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
15375 which controls the variant of the GNU standard C library
15376 (<filename>libc</filename>) used during the build process:
Brad Bishop37a0e4d2017-12-04 01:01:44 -050015377 <filename>glibc</filename> or <filename>musl</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015378 </para>
15379
15380 <para>
15381 With additional layers, it is possible to use a pre-compiled
15382 external toolchain.
15383 One example is the Sourcery G++ Toolchain.
15384 The support for this toolchain resides in the separate
15385 <trademark class='registered'>Mentor Graphics</trademark>
15386 <filename>meta-sourcery</filename> layer at
15387 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
15388 </para>
15389
15390 <para>
15391 The layer's <filename>README</filename> file contains
15392 information on how to use the Sourcery G++ Toolchain as
15393 an external toolchain.
15394 In summary, you must be sure to add the layer to your
15395 <filename>bblayers.conf</filename> file in front of the
15396 <filename>meta</filename> layer and then set the
15397 <filename>EXTERNAL_TOOLCHAIN</filename>
15398 variable in your <filename>local.conf</filename> file
15399 to the location in which you installed the toolchain.
15400 </para>
15401
15402 <para>
15403 The fundamentals used for this example apply to any
15404 external toolchain.
15405 You can use <filename>meta-sourcery</filename> as a
15406 template for adding support for other external toolchains.
15407 </para>
15408 </glossdef>
15409 </glossentry>
15410
15411 <glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>
15412 <info>
15413 TEST_EXPORT_DIR[doc] = "The location the OpenEmbedded build system uses to export tests when the TEST_EXPORT_ONLY variable is set to "1"."
15414 </info>
15415 <glossdef>
15416 <para role="glossdeffirst">
15417<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15418 The location the OpenEmbedded build system uses to export
15419 tests when the
15420 <link linkend='var-TEST_EXPORT_ONLY'><filename>TEST_EXPORT_ONLY</filename></link>
15421 variable is set to "1".
15422 </para>
15423
15424 <para>
15425 The <filename>TEST_EXPORT_DIR</filename> variable defaults
15426 to <filename>"${TMPDIR}/testimage/${PN}"</filename>.
15427 </para>
15428 </glossdef>
15429 </glossentry>
15430
15431 <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>
15432 <info>
15433 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."
15434 </info>
15435 <glossdef>
15436 <para role="glossdeffirst">
15437<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15438 Specifies to export the tests only.
15439 Set this variable to "1" if you do not want to run the
15440 tests but you want them to be exported in a manner that
15441 you to run them outside of the build system.
15442 </para>
15443 </glossdef>
15444 </glossentry>
15445
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015446 <glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm>
15447 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040015448 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 -050015449 </info>
15450 <glossdef>
15451 <para role="glossdeffirst">
15452<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15453 Holds the SSH log and the boot log for QEMU machines.
15454 The <filename>TEST_LOG_DIR</filename> variable defaults
15455 to <filename>"${WORKDIR}/testimage"</filename>.
15456 <note>
15457 Actual test results reside in the task log
15458 (<filename>log.do_testimage</filename>), which is in
15459 the <filename>${WORKDIR}/temp/</filename> directory.
15460 </note>
15461 </para>
15462 </glossdef>
15463 </glossentry>
15464
15465 <glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm>TEST_POWERCONTROL_CMD</glossterm>
15466 <info>
15467 TEST_POWERCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to control the power of the target machine under test"
15468 </info>
15469 <glossdef>
15470 <para role="glossdeffirst">
15471<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15472 For automated hardware testing, specifies the command to
15473 use to control the power of the target machine under test.
15474 Typically, this command would point to a script that
15475 performs the appropriate action (e.g. interacting
15476 with a web-enabled power strip).
15477 The specified command should expect to receive as the last
15478 argument "off", "on" or "cycle" specifying to power off,
15479 on, or cycle (power off and then power on) the device,
15480 respectively.
15481 </para>
15482 </glossdef>
15483 </glossentry>
15484
15485 <glossentry id='var-TEST_POWERCONTROL_EXTRA_ARGS'><glossterm>TEST_POWERCONTROL_EXTRA_ARGS</glossterm>
15486 <info>
15487 TEST_POWERCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_POWERCONTROL_CMD"
15488 </info>
15489 <glossdef>
15490 <para role="glossdeffirst">
15491<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15492 For automated hardware testing, specifies additional
15493 arguments to pass through to the command specified in
15494 <link linkend='var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></link>.
15495 Setting <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
15496 is optional.
15497 You can use it if you wish, for example, to separate the
15498 machine-specific and non-machine-specific parts of the
15499 arguments.
15500 </para>
15501 </glossdef>
15502 </glossentry>
15503
15504 <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
15505 <info>
15506 TEST_QEMUBOOT_TIMEOUT[doc] = "The time in seconds allowed for an image to boot before automated runtime tests begin to run against an image."
15507 </info>
15508 <glossdef>
15509 <para role="glossdeffirst">
15510<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15511 The time in seconds allowed for an image to boot before
15512 automated runtime tests begin to run against an
15513 image.
15514 The default timeout period to allow the boot process to
15515 reach the login prompt is 500 seconds.
15516 You can specify a different value in the
15517 <filename>local.conf</filename> file.
15518 </para>
15519
15520 <para>
15521 For more information on testing images, see the
15522 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015523 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015524 </para>
15525 </glossdef>
15526 </glossentry>
15527
15528 <glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm>TEST_SERIALCONTROL_CMD</glossterm>
15529 <info>
15530 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."
15531 </info>
15532 <glossdef>
15533 <para role="glossdeffirst">
15534<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15535 For automated hardware testing, specifies the command
15536 to use to connect to the serial console of the target
15537 machine under test.
15538 This command simply needs to connect to the serial console
15539 and forward that connection to standard input and output
15540 as any normal terminal program does.
15541 </para>
15542
15543 <para>
15544 For example, to use the Picocom terminal program on
15545 serial device <filename>/dev/ttyUSB0</filename> at
15546 115200bps, you would set the variable as follows:
15547 <literallayout class='monospaced'>
15548 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
15549 </literallayout>
15550 </para>
15551 </glossdef>
15552 </glossentry>
15553
15554 <glossentry id='var-TEST_SERIALCONTROL_EXTRA_ARGS'><glossterm>TEST_SERIALCONTROL_EXTRA_ARGS</glossterm>
15555 <info>
15556 TEST_SERIALCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_SERIALCONTROL_CMD."
15557 </info>
15558 <glossdef>
15559 <para role="glossdeffirst">
15560<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15561 For automated hardware testing, specifies additional
15562 arguments to pass through to the command specified in
15563 <link linkend='var-TEST_SERIALCONTROL_CMD'><filename>TEST_SERIALCONTROL_CMD</filename></link>.
15564 Setting <filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename>
15565 is optional.
15566 You can use it if you wish, for example, to separate the
15567 machine-specific and non-machine-specific parts of the
15568 command.
15569 </para>
15570 </glossdef>
15571 </glossentry>
15572
15573 <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>
15574 <info>
15575 TEST_SERVER_IP[doc] = "The IP address of the build machine (host machine). This IP address is usually automatically detected."
15576 </info>
15577 <glossdef>
15578 <para role="glossdeffirst">
15579<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15580 The IP address of the build machine (host machine).
15581 This IP address is usually automatically detected.
15582 However, if detection fails, this variable needs to be set
15583 to the IP address of the build machine (i.e. where
15584 the build is taking place).
15585 <note>
15586 The <filename>TEST_SERVER_IP</filename> variable
15587 is only used for a small number of tests such as
Brad Bishop6e60e8b2018-02-01 10:27:11 -050015588 the "dnf" test suite, which needs to download
15589 packages from
15590 <filename>WORKDIR/oe-rootfs-repo</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015591 </note>
15592 </para>
15593 </glossdef>
15594 </glossentry>
15595
15596 <glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>
15597 <info>
15598 TEST_TARGET[doc] = "For automated runtime testing, specifies the method of deploying the image and running tests on the target machine."
15599 </info>
15600 <glossdef>
15601 <para role="glossdeffirst">
15602<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15603 Specifies the target controller to use when running tests
15604 against a test image.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015605 The default controller to use is "QemuTarget":
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015606 <literallayout class='monospaced'>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015607 TEST_TARGET = "QemuTarget"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015608 </literallayout>
15609 </para>
15610
15611 <para>
15612 A target controller is a class that defines how an
15613 image gets deployed on a target and how a target is started.
15614 A layer can extend the controllers by adding a module
15615 in the layer's <filename>/lib/oeqa/controllers</filename>
15616 directory and by inheriting the
15617 <filename>BaseTarget</filename> class, which is an abstract
15618 class that cannot be used as a value of
15619 <filename>TEST_TARGET</filename>.
15620 </para>
15621
15622 <para>
15623 You can provide the following arguments with
15624 <filename>TEST_TARGET</filename>:
15625 <itemizedlist>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015626 <listitem><para><emphasis>"QemuTarget":</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015627 Boots a QEMU image and runs the tests.
15628 See the
15629 "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015630 section in the Yocto Project Development Tasks
15631 Manual for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015632 </para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015633 <listitem><para><emphasis>"SimpleRemoteTarget":</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015634 Runs the tests on target hardware that is already
15635 up and running.
15636 The hardware can be on the network or it can be
15637 a device running an image on QEMU.
15638 You must also set
15639 <link linkend='var-TEST_TARGET_IP'><filename>TEST_TARGET_IP</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015640 when you use "SimpleRemoteTarget".
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015641 <note>
15642 This argument is defined in
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015643 <filename>meta/lib/oeqa/controllers/simpleremote.py</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015644 </note>
15645 </para></listitem>
15646 </itemizedlist>
15647 </para>
15648
15649 <para>
15650 For information on running tests on hardware, see the
15651 "<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015652 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015653 </para>
15654 </glossdef>
15655 </glossentry>
15656
15657 <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>
15658 <info>
15659 TEST_TARGET_IP[doc] = "The IP address of your hardware under test."
15660 </info>
15661 <glossdef>
15662 <para role="glossdeffirst">
15663<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15664 The IP address of your hardware under test.
15665 The <filename>TEST_TARGET_IP</filename> variable has no
15666 effect when
15667 <link linkend='var-TEST_TARGET'><filename>TEST_TARGET</filename></link>
15668 is set to "qemu".
15669 </para>
15670
15671 <para>
15672 When you specify the IP address, you can also include a
15673 port.
15674 Here is an example:
15675 <literallayout class='monospaced'>
15676 TEST_TARGET_IP = "192.168.1.4:2201"
15677 </literallayout>
15678 Specifying a port is useful when SSH is started on a
15679 non-standard port or in cases when your hardware under test
15680 is behind a firewall or network that is not directly
15681 accessible from your host and you need to do port address
15682 translation.
15683 </para>
15684 </glossdef>
15685 </glossentry>
15686
15687 <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
15688 <info>
15689 TEST_SUITES[doc] = "An ordered list of tests (modules) to run against an image when performing automated runtime testing."
15690 </info>
15691 <glossdef>
15692 <para role="glossdeffirst">
15693<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15694 An ordered list of tests (modules) to run against
15695 an image when performing automated runtime testing.
15696 </para>
15697
15698 <para>
15699 The OpenEmbedded build system provides a core set of tests
15700 that can be used against images.
15701 <note>
15702 Currently, there is only support for running these tests
15703 under QEMU.
15704 </note>
15705 Tests include <filename>ping</filename>,
15706 <filename>ssh</filename>, <filename>df</filename> among
15707 others.
15708 You can add your own tests to the list of tests by
15709 appending <filename>TEST_SUITES</filename> as follows:
15710 <literallayout class='monospaced'>
15711 TEST_SUITES_append = " <replaceable>mytest</replaceable>"
15712 </literallayout>
15713 Alternatively, you can provide the "auto" option to
15714 have all applicable tests run against the image.
15715 <literallayout class='monospaced'>
15716 TEST_SUITES_append = " auto"
15717 </literallayout>
15718 Using this option causes the build system to automatically
15719 run tests that are applicable to the image.
15720 Tests that are not applicable are skipped.
15721 </para>
15722
15723 <para>
15724 The order in which tests are run is important.
15725 Tests that depend on another test must appear later in the
15726 list than the test on which they depend.
15727 For example, if you append the list of tests with two
15728 tests (<filename>test_A</filename> and
15729 <filename>test_B</filename>) where
15730 <filename>test_B</filename> is dependent on
15731 <filename>test_A</filename>, then you must order the tests
15732 as follows:
15733 <literallayout class='monospaced'>
15734 TEST_SUITES = " test_A test_B"
15735 </literallayout>
15736 </para>
15737
15738 <para>
15739 For more information on testing images, see the
15740 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015741 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015742 </para>
15743 </glossdef>
15744 </glossentry>
15745
Brad Bishop1a4b7ee2018-12-16 17:11:34 -080015746 <glossentry id='var-TESTIMAGE_AUTO'><glossterm>TESTIMAGE_AUTO</glossterm>
15747 <info>
15748 TESTIMAGE_AUTO[doc] = "Enables automatic testing of an image once it is built."
15749 </info>
15750 <glossdef>
15751 <para role="glossdeffirst">
15752<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15753 Automatically runs the series of automated tests for
15754 images when an image is successfully built.
15755 Setting <filename>TESTIMAGE_AUTO</filename> to "1"
15756 causes any image that successfully builds to automatically
15757 boot under QEMU.
15758 Using the variable also adds in dependencies so that any
15759 SDK for which testing is requested is automatically built
15760 first.
15761 </para>
15762
15763 <para>
15764 These tests are written in Python making use of the
15765 <filename>unittest</filename> module, and the majority of
15766 them run commands on the target system over
15767 <filename>ssh</filename>.
15768 You can set this variable to "1" in your
15769 <filename>local.conf</filename> file in the
15770 <link linkend='build-directory'>Build Directory</link>
15771 to have the OpenEmbedded build system automatically run
15772 these tests after an image successfully builds:
15773 <literallayout class='monospaced'>
15774 TESTIMAGE_AUTO = "1"
15775 </literallayout>
15776 For more information on enabling, running, and writing
15777 these tests, see the
15778 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
15779 section in the Yocto Project Development Tasks Manual and
15780 the
15781 "<link linkend='ref-classes-testimage*'><filename>testimage*.bbclass</filename></link>"
15782 section.
15783 </para>
15784 </glossdef>
15785 </glossentry>
15786
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015787 <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
15788 <info>
15789 THISDIR[doc] = "The directory in which the file BitBake is currently parsing is located."
15790 </info>
15791 <glossdef>
15792 <para role="glossdeffirst">
15793<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15794 The directory in which the file BitBake is currently
15795 parsing is located.
15796 Do not manually set this variable.
15797 </para>
15798 </glossdef>
15799 </glossentry>
15800
15801 <glossentry id='var-TIME'><glossterm>TIME</glossterm>
15802 <info>
15803 TIME[doc] = "The time the build was started using HMS format."
15804 </info>
15805 <glossdef>
15806 <para role="glossdeffirst">
15807<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15808 The time the build was started.
15809 Times appear using the hour, minute, and second (HMS)
15810 format (e.g. "140159" for one minute and fifty-nine
15811 seconds past 1400 hours).
15812 </para>
15813 </glossdef>
15814 </glossentry>
15815
15816 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
15817 <info>
15818 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."
15819 </info>
15820 <glossdef>
15821 <para role="glossdeffirst">
15822<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15823 This variable is the base directory the OpenEmbedded
15824 build system uses for all build output and intermediate
15825 files (other than the shared state cache).
15826 By default, the <filename>TMPDIR</filename> variable points
15827 to <filename>tmp</filename> within the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015828 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015829 </para>
15830
15831 <para>
15832 If you want to establish this directory in a location other
15833 than the default, you can uncomment and edit the following
15834 statement in the
15835 <filename>conf/local.conf</filename> file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015836 <link linkend='source-directory'>Source Directory</link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015837 <literallayout class='monospaced'>
15838 #TMPDIR = "${TOPDIR}/tmp"
15839 </literallayout>
15840 An example use for this scenario is to set
15841 <filename>TMPDIR</filename> to a local disk, which does
15842 not use NFS, while having the Build Directory use NFS.
15843 </para>
15844
15845 <para>
15846 The filesystem used by <filename>TMPDIR</filename> must
15847 have standard filesystem semantics (i.e. mixed-case files
15848 are unique, POSIX file locking, and persistent inodes).
15849 Due to various issues with NFS and bugs in some
15850 implementations, NFS does not meet this minimum
15851 requirement.
15852 Consequently, <filename>TMPDIR</filename> cannot be on
15853 NFS.
15854 </para>
15855 </glossdef>
15856 </glossentry>
15857
15858 <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
15859 <info>
15860 TOOLCHAIN_HOST_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when building an SDK, which contains a cross-development environment."
15861 </info>
15862 <glossdef>
15863 <para role="glossdeffirst">
15864<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15865 This variable lists packages the OpenEmbedded build system
15866 uses when building an SDK, which contains a
15867 cross-development environment.
15868 The packages specified by this variable are part of the
15869 toolchain set that runs on the
15870 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
15871 and each package should usually have the prefix
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050015872 <filename>nativesdk-</filename>.
15873 For example, consider the following command when
15874 building an SDK:
15875 <literallayout class='monospaced'>
15876 $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
15877 </literallayout>
15878 In this case, a default list of packages is set in this
15879 variable, but you can add additional packages to the list.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050015880 See the
15881 "<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 -050015882 section in the Yocto Project Application Development and
15883 the Extensible Software Development Kit (eSDK) manual
15884 for more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015885 </para>
15886
15887 <para>
15888 For background information on cross-development toolchains
15889 in the Yocto Project development environment, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040015890 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
15891 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015892 For information on setting up a cross-development
15893 environment, see the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015894 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
15895 manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015896 </para>
15897 </glossdef>
15898 </glossentry>
15899
15900 <glossentry id='var-TOOLCHAIN_OUTPUTNAME'><glossterm>TOOLCHAIN_OUTPUTNAME</glossterm>
15901 <info>
15902 TOOLCHAIN_OUTPUTNAME[doc] = "Defines the name used for the toolchain output."
15903 </info>
15904 <glossdef>
15905 <para role="glossdeffirst">
15906<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15907 This variable defines the name used for the toolchain
15908 output.
15909 The
15910 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
15911 class sets the
15912 <filename>TOOLCHAIN_OUTPUTNAME</filename> variable as
15913 follows:
15914 <literallayout class='monospaced'>
15915 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"
15916 </literallayout>
15917 See the
15918 <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
15919 and
15920 <link linkend='var-SDK_VERSION'><filename>SDK_VERSION</filename></link>
15921 variables for additional information.
15922 </para>
15923 </glossdef>
15924 </glossentry>
15925
15926 <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
15927 <info>
15928 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."
15929 </info>
15930 <glossdef>
15931 <para role="glossdeffirst">
15932<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15933 This variable lists packages the OpenEmbedded build system
15934 uses when it creates the target part of an SDK
15935 (i.e. the part built for the target hardware), which
15936 includes libraries and headers.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050015937 Use this variable to add individual packages to the
15938 part of the SDK that runs on the target.
15939 See the
15940 "<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 -050015941 section in the Yocto Project Application Development and
15942 the Extensible Software Development Kit (eSDK) manual for
15943 more information.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015944 </para>
15945
15946 <para>
15947 For background information on cross-development toolchains
15948 in the Yocto Project development environment, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040015949 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
15950 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015951 For information on setting up a cross-development
15952 environment, see the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015953 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
15954 manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015955 </para>
15956 </glossdef>
15957 </glossentry>
15958
15959 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
15960 <info>
15961 TOPDIR[doc] = "The Build Directory. BitBake automatically sets this variable. The OpenEmbedded build system uses the Build Directory when building images."
15962 </info>
15963 <glossdef>
15964 <para role="glossdeffirst">
15965<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15966 The top-level
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015967 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015968 BitBake automatically sets this variable when you
Brad Bishopd7bf8c12018-02-25 22:55:05 -050015969 initialize your build environment using
15970 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015971 </para>
15972 </glossdef>
15973 </glossentry>
15974
15975 <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
15976 <info>
15977 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."
15978 </info>
15979 <glossdef>
15980 <para role="glossdeffirst">
15981<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
15982 A sanitized version of
15983 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
15984 This variable is used where the architecture is needed in
15985 a value where underscores are not allowed, for example
15986 within package filenames.
15987 In this case, dash characters replace any underscore
Brad Bishop316dfdd2018-06-25 12:45:53 -040015988 characters used in <filename>TARGET_ARCH</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050015989 </para>
15990
15991 <para>
15992 Do not edit this variable.
15993 </para>
15994 </glossdef>
15995 </glossentry>
15996
15997 <glossentry id='var-TUNE_ARCH'><glossterm>TUNE_ARCH</glossterm>
15998 <info>
15999 TUNE_ARCH[doc] = "The GNU canonical architecture for a specific architecture (i.e. arm, armeb, mips, mips64, and so forth)."
16000 </info>
16001 <glossdef>
16002 <para role="glossdeffirst">
16003<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16004 The GNU canonical architecture for a specific architecture
16005 (i.e. <filename>arm</filename>,
16006 <filename>armeb</filename>,
16007 <filename>mips</filename>,
16008 <filename>mips64</filename>, and so forth).
16009 BitBake uses this value to setup configuration.
16010 </para>
16011
16012 <para>
16013 <filename>TUNE_ARCH</filename> definitions are specific to
16014 a given architecture.
16015 The definitions can be a single static definition, or
16016 can be dynamically adjusted.
16017 You can see details for a given CPU family by looking at
16018 the architecture's <filename>README</filename> file.
16019 For example, the
16020 <filename>meta/conf/machine/include/mips/README</filename>
16021 file in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016022 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016023 provides information for <filename>TUNE_ARCH</filename>
16024 specific to the <filename>mips</filename> architecture.
16025 </para>
16026
16027 <para>
16028 <filename>TUNE_ARCH</filename> is tied closely to
16029 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
16030 which defines the target machine's architecture.
16031 The BitBake configuration file
16032 (<filename>meta/conf/bitbake.conf</filename>) sets
16033 <filename>TARGET_ARCH</filename> as follows:
16034 <literallayout class='monospaced'>
16035 TARGET_ARCH = "${TUNE_ARCH}"
16036 </literallayout>
16037 </para>
16038
16039 <para>
16040 The following list, which is by no means complete since
16041 architectures are configurable, shows supported machine
16042 architectures:
16043 <literallayout class='monospaced'>
16044 arm
16045 i586
16046 x86_64
16047 powerpc
16048 powerpc64
16049 mips
16050 mipsel
16051 </literallayout>
16052 </para>
16053 </glossdef>
16054 </glossentry>
16055
16056 <glossentry id='var-TUNE_ASARGS'><glossterm>TUNE_ASARGS</glossterm>
16057 <info>
16058 TUNE_ASARGS[doc] = "Specifies architecture-specific assembler flags for the target system."
16059 </info>
16060 <glossdef>
16061 <para role="glossdeffirst">
16062<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16063 Specifies architecture-specific assembler flags for
16064 the target system.
16065 The set of flags is based on the selected tune features.
16066 <filename>TUNE_ASARGS</filename> is set using
16067 the tune include files, which are typically under
16068 <filename>meta/conf/machine/include/</filename> and are
16069 influenced through
16070 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
16071 For example, the
16072 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
16073 file defines the flags for the x86 architecture as follows:
16074 <literallayout class='monospaced'>
16075 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
16076 </literallayout>
16077 <note>
16078 Board Support Packages (BSPs) select the tune.
16079 The selected tune, in turn, affects the tune variables
16080 themselves (i.e. the tune can supply its own
16081 set of flags).
16082 </note>
16083 </para>
16084 </glossdef>
16085 </glossentry>
16086
16087 <glossentry id='var-TUNE_CCARGS'><glossterm>TUNE_CCARGS</glossterm>
16088 <info>
16089 TUNE_CCARGS[doc] = "Specifies architecture-specific C compiler flags for the target system."
16090 </info>
16091 <glossdef>
16092 <para role="glossdeffirst">
16093<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16094 Specifies architecture-specific C compiler flags for
16095 the target system.
16096 The set of flags is based on the selected tune features.
16097 <filename>TUNE_CCARGS</filename> is set using
16098 the tune include files, which are typically under
16099 <filename>meta/conf/machine/include/</filename> and are
16100 influenced through
16101 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
16102 <note>
16103 Board Support Packages (BSPs) select the tune.
16104 The selected tune, in turn, affects the tune variables
16105 themselves (i.e. the tune can supply its own
16106 set of flags).
16107 </note>
16108 </para>
16109 </glossdef>
16110 </glossentry>
16111
16112 <glossentry id='var-TUNE_LDARGS'><glossterm>TUNE_LDARGS</glossterm>
16113 <info>
16114 TUNE_LDARGS[doc] = "Specifies architecture-specific linker flags for the target system."
16115 </info>
16116 <glossdef>
16117 <para role="glossdeffirst">
16118<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16119 Specifies architecture-specific linker flags for
16120 the target system.
16121 The set of flags is based on the selected tune features.
16122 <filename>TUNE_LDARGS</filename> is set using
16123 the tune include files, which are typically under
16124 <filename>meta/conf/machine/include/</filename> and are
16125 influenced through
16126 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
16127 For example, the
16128 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
16129 file defines the flags for the x86 architecture as follows:
16130 <literallayout class='monospaced'>
16131 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
16132 </literallayout>
16133 <note>
16134 Board Support Packages (BSPs) select the tune.
16135 The selected tune, in turn, affects the tune variables
16136 themselves (i.e. the tune can supply its own
16137 set of flags).
16138 </note>
16139 </para>
16140 </glossdef>
16141 </glossentry>
16142
16143 <glossentry id='var-TUNE_FEATURES'><glossterm>TUNE_FEATURES</glossterm>
16144 <info>
16145 TUNE_FEATURES[doc] = "Features used to "tune" a compiler for optimal use given a specific processor."
16146 </info>
16147 <glossdef>
16148 <para role="glossdeffirst">
16149<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16150 Features used to "tune" a compiler for optimal use
16151 given a specific processor.
16152 The features are defined within the tune files and allow
16153 arguments (i.e. <filename>TUNE_*ARGS</filename>) to be
16154 dynamically generated based on the features.
16155 </para>
16156
16157 <para>
16158 The OpenEmbedded build system verifies the features
16159 to be sure they are not conflicting and that they are
16160 supported.
16161 </para>
16162
16163 <para>
16164 The BitBake configuration file
16165 (<filename>meta/conf/bitbake.conf</filename>) defines
16166 <filename>TUNE_FEATURES</filename> as follows:
16167 <literallayout class='monospaced'>
16168 TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}"
16169 </literallayout>
16170 See the
16171 <link linkend='var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></link>
16172 variable for more information.
16173 </para>
16174 </glossdef>
16175 </glossentry>
16176
16177 <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
16178 <info>
16179 TUNE_PKGARCH[doc] = "The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages."
16180 </info>
16181 <glossdef>
16182 <para role="glossdeffirst">
16183<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16184 The package architecture understood by the packaging
16185 system to define the architecture, ABI, and tuning of
16186 output packages.
16187 The specific tune is defined using the "_tune" override
16188 as follows:
16189 <literallayout class='monospaced'>
16190 TUNE_PKGARCH_tune-<replaceable>tune</replaceable> = "<replaceable>tune</replaceable>"
16191 </literallayout>
16192 </para>
16193
16194 <para>
16195 These tune-specific package architectures are defined in
16196 the machine include files.
16197 Here is an example of the "core2-32" tuning as used
16198 in the
16199 <filename>meta/conf/machine/include/tune-core2.inc</filename>
16200 file:
16201 <literallayout class='monospaced'>
16202 TUNE_PKGARCH_tune-core2-32 = "core2-32"
16203 </literallayout>
16204 </para>
16205 </glossdef>
16206 </glossentry>
16207
16208 <glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm>
16209 <info>
16210 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."
16211 </info>
16212 <glossdef>
16213 <para role="glossdeffirst">
16214<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16215 An underlying Application Binary Interface (ABI) used by
16216 a particular tuning in a given toolchain layer.
16217 Providers that use prebuilt libraries can use the
16218 <filename>TUNEABI</filename>,
16219 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
16220 and
16221 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
16222 variables to check compatibility of tunings against their
16223 selection of libraries.
16224 </para>
16225
16226 <para>
16227 If <filename>TUNEABI</filename> is undefined, then every
16228 tuning is allowed.
16229 See the
16230 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
16231 class to see how the variable is used.
16232 </para>
16233 </glossdef>
16234 </glossentry>
16235
16236 <glossentry id='var-TUNEABI_OVERRIDE'><glossterm>TUNEABI_OVERRIDE</glossterm>
16237 <info>
16238 TUNEABI_OVERRIDE[doc] = "If set, ignores TUNEABI_WHITELIST."
16239 </info>
16240 <glossdef>
16241 <para role="glossdeffirst">
16242<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16243 If set, the OpenEmbedded system ignores the
16244 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
16245 variable.
16246 Providers that use prebuilt libraries can use the
16247 <filename>TUNEABI_OVERRIDE</filename>,
16248 <filename>TUNEABI_WHITELIST</filename>,
16249 and
16250 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
16251 variables to check compatibility of a tuning against their
16252 selection of libraries.
16253 </para>
16254
16255 <para>
16256 See the
16257 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
16258 class to see how the variable is used.
16259 </para>
16260 </glossdef>
16261 </glossentry>
16262
16263 <glossentry id='var-TUNEABI_WHITELIST'><glossterm>TUNEABI_WHITELIST</glossterm>
16264 <info>
16265 TUNEABI_WHITELIST[doc] = "A whitelist of permissible TUNEABI values. If the variable is not set, all values are allowed."
16266 </info>
16267 <glossdef>
16268 <para role="glossdeffirst">
16269<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16270 A whitelist of permissible
16271 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
16272 values.
16273 If <filename>TUNEABI_WHITELIST</filename> is not set,
16274 all tunes are allowed.
16275 Providers that use prebuilt libraries can use the
16276 <filename>TUNEABI_WHITELIST</filename>,
16277 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
16278 and <filename>TUNEABI</filename> variables to check
16279 compatibility of a tuning against their selection of
16280 libraries.
16281 </para>
16282
16283 <para>
16284 See the
16285 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
16286 class to see how the variable is used.
16287 </para>
16288 </glossdef>
16289 </glossentry>
16290
16291 <glossentry id='var-TUNECONFLICTS'><glossterm>TUNECONFLICTS[<replaceable>feature</replaceable>]</glossterm>
16292 <info>
16293 TUNECONFLICTS[doc] = "Specifies CPU or Application Binary Interface (ABI) tuning features that conflict with specified feature."
16294 </info>
16295 <glossdef>
16296 <para role="glossdeffirst">
16297<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16298 Specifies CPU or Application Binary Interface (ABI)
16299 tuning features that conflict with <replaceable>feature</replaceable>.
16300 </para>
16301
16302 <para>
16303 Known tuning conflicts are specified in the machine include
16304 files in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016305 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016306 Here is an example from the
16307 <filename>meta/conf/machine/include/mips/arch-mips.inc</filename>
16308 include file that lists the "o32" and "n64" features as
16309 conflicting with the "n32" feature:
16310 <literallayout class='monospaced'>
16311 TUNECONFLICTS[n32] = "o32 n64"
16312 </literallayout>
16313 </para>
16314 </glossdef>
16315 </glossentry>
16316
16317 <glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[<replaceable>feature</replaceable>]</glossterm>
16318 <info>
16319 TUNEVALID[doc] = "Descriptions, stored as flags, of valid tuning features."
16320 </info>
16321 <glossdef>
16322 <para role="glossdeffirst">
16323<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16324 Specifies a valid CPU or Application Binary Interface (ABI)
16325 tuning feature.
16326 The specified feature is stored as a flag.
16327 Valid features are specified in the machine include files
16328 (e.g. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>).
16329 Here is an example from that file:
16330 <literallayout class='monospaced'>
16331 TUNEVALID[bigendian] = "Enable big-endian mode."
16332 </literallayout>
16333 </para>
16334
16335 <para>
16336 See the machine include files in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016337 <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016338 for these features.
16339 </para>
16340 </glossdef>
16341 </glossentry>
16342
16343 </glossdiv>
16344
16345 <glossdiv id='var-glossary-u'><title>U</title>
16346
16347 <glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm>
16348 <info>
16349 UBOOT_CONFIG[doc] = "Configures the UBOOT_MACHINE and can also define IMAGE_FSTYPES for individual cases."
16350 </info>
16351 <glossdef>
16352 <para role="glossdeffirst">
16353<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16354 Configures the
16355 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
16356 and can also define
16357 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
16358 for individual cases.
16359 </para>
16360
16361 <para>
16362 Following is an example from the
16363 <filename>meta-fsl-arm</filename> layer.
16364 <literallayout class='monospaced'>
16365 UBOOT_CONFIG ??= "sd"
16366 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
16367 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
16368 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
16369 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
16370 </literallayout>
16371 In this example, "sd" is selected as the configuration
16372 of the possible four for the
16373 <filename>UBOOT_MACHINE</filename>.
16374 The "sd" configuration defines "mx6qsabreauto_config"
16375 as the value for <filename>UBOOT_MACHINE</filename>, while
16376 the "sdcard" specifies the
16377 <filename>IMAGE_FSTYPES</filename> to use for the U-boot
16378 image.
16379 </para>
16380
16381 <para>
16382 For more information on how the
16383 <filename>UBOOT_CONFIG</filename> is handled, see the
16384 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass'><filename>uboot-config</filename></ulink>
16385 class.
16386 </para>
16387 </glossdef>
16388 </glossentry>
16389
16390 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
16391 <info>
16392 UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image."
16393 </info>
16394 <glossdef>
16395 <para role="glossdeffirst">
16396<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16397 Specifies the entry point for the U-Boot image.
16398 During U-Boot image creation, the
16399 <filename>UBOOT_ENTRYPOINT</filename> variable is passed
16400 as a command-line parameter to the
16401 <filename>uboot-mkimage</filename> utility.
16402 </para>
16403 </glossdef>
16404 </glossentry>
16405
16406 <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
16407 <info>
16408 UBOOT_LOADADDRESS[doc] = "Specifies the load address for the U-Boot image."
16409 </info>
16410 <glossdef>
16411 <para role="glossdeffirst">
16412<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16413 Specifies the load address for the U-Boot image.
16414 During U-Boot image creation, the
16415 <filename>UBOOT_LOADADDRESS</filename> variable is passed
16416 as a command-line parameter to the
16417 <filename>uboot-mkimage</filename> utility.
16418 </para>
16419 </glossdef>
16420 </glossentry>
16421
16422 <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>
16423 <info>
16424 UBOOT_LOCALVERSION[doc] = "Appends a string to the name of the local version of the U-Boot image."
16425 </info>
16426 <glossdef>
16427 <para role="glossdeffirst">
16428<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16429 Appends a string to the name of the local version of the
16430 U-Boot image.
16431 For example, assuming the version of the U-Boot image
16432 built was "2013.10, the full version string reported by
16433 U-Boot would be "2013.10-yocto" given the following
16434 statement:
16435 <literallayout class='monospaced'>
16436 UBOOT_LOCALVERSION = "-yocto"
16437 </literallayout>
16438 </para>
16439 </glossdef>
16440 </glossentry>
16441
16442 <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
16443 <info>
16444 UBOOT_MACHINE[doc] = "Specifies the value passed on the make command line when building a U-Boot image."
16445 </info>
16446 <glossdef>
16447 <para role="glossdeffirst">
16448<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16449 Specifies the value passed on the
16450 <filename>make</filename> command line when building
16451 a U-Boot image.
16452 The value indicates the target platform configuration.
16453 You typically set this variable from the machine
16454 configuration file (i.e.
16455 <filename>conf/machine/<replaceable>machine_name</replaceable>.conf</filename>).
16456 </para>
16457
16458 <para>
16459 Please see the "Selection of Processor Architecture and
16460 Board Type" section in the U-Boot README for valid values
16461 for this variable.
16462 </para>
16463 </glossdef>
16464 </glossentry>
16465
16466 <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm>
16467 <info>
16468 UBOOT_MAKE_TARGET[doc] = "Specifies the target called in the Makefile."
16469 </info>
16470 <glossdef>
16471 <para role="glossdeffirst">
16472<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16473 Specifies the target called in the
16474 <filename>Makefile</filename>.
16475 The default target is "all".
16476 </para>
16477 </glossdef>
16478 </glossentry>
16479
16480 <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>
16481 <info>
16482 UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension."
16483 </info>
16484 <glossdef>
16485 <para role="glossdeffirst">
16486<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16487 Points to the generated U-Boot extension.
16488 For example, <filename>u-boot.sb</filename> has a
16489 <filename>.sb</filename> extension.
16490 </para>
16491
16492 <para>
16493 The default U-Boot extension is
16494 <filename>.bin</filename>
16495 </para>
16496 </glossdef>
16497 </glossentry>
16498
16499 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
16500 <info>
16501 UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot."
16502 </info>
16503 <glossdef>
16504 <para role="glossdeffirst">
16505<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16506 Specifies the target used for building U-Boot.
16507 The target is passed directly as part of the "make" command
16508 (e.g. SPL and AIS).
16509 If you do not specifically set this variable, the
16510 OpenEmbedded build process passes and uses "all" for the
16511 target during the U-Boot building process.
16512 </para>
16513 </glossdef>
16514 </glossentry>
16515
16516 <glossentry id='var-UNKNOWN_CONFIGURE_WHITELIST'><glossterm>UNKNOWN_CONFIGURE_WHITELIST</glossterm>
16517 <info>
16518 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."
16519 </info>
16520 <glossdef>
16521 <para role="glossdeffirst">
16522<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16523 Specifies a list of options that, if reported by the
16524 configure script as being invalid, should not generate a
16525 warning during the
16526 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
16527 task.
16528 Normally, invalid configure options are simply not passed
16529 to the configure script (e.g. should be removed from
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016530 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
16531 or
16532 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>).
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016533 However, common options, for example, exist that are passed
16534 to all configure scripts at a class level that might not
16535 be valid for some configure scripts.
16536 It follows that no benefit exists in seeing a warning about
16537 these options.
16538 For these cases, the options are added to
16539 <filename>UNKNOWN_CONFIGURE_WHITELIST</filename>.
16540 </para>
16541
16542 <para>
16543 The configure arguments check that uses
16544 <filename>UNKNOWN_CONFIGURE_WHITELIST</filename> is part
16545 of the
16546 <link linkend='ref-classes-insane'><filename>insane</filename></link>
16547 class and is only enabled if the recipe inherits the
16548 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
16549 class.
16550 </para>
16551 </glossdef>
16552 </glossentry>
16553
16554 <glossentry id='var-UPDATERCPN'><glossterm>UPDATERCPN</glossterm>
16555 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040016556 UPDATERCPN[doc] = "Specifies the package that contains the initscript that is enabled."
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016557 </info>
16558 <glossdef>
16559 <para role="glossdeffirst">
16560<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16561 For recipes inheriting the
16562 <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
16563 class, <filename>UPDATERCPN</filename> specifies
Brad Bishop316dfdd2018-06-25 12:45:53 -040016564 the package that contains the initscript that is
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016565 enabled.
16566 </para>
16567
16568 <para>
16569 The default value is "${PN}".
16570 Given that almost all recipes that install initscripts
16571 package them in the main package for the recipe, you
16572 rarely need to set this variable in individual recipes.
16573 </para>
16574 </glossdef>
16575 </glossentry>
16576
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016577 <glossentry id='var-UPSTREAM_CHECK_GITTAGREGEX'><glossterm>UPSTREAM_CHECK_GITTAGREGEX</glossterm>
16578 <info>
16579 UPSTREAM_CHECK_GITTAGREGEX[doc] = "Filters relevant Git tags when fetching source from an upstream Git repository."
16580 </info>
16581 <glossdef>
16582 <para role="glossdeffirst">
16583<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16584 When the
16585 <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link>
16586 class is enabled globally, you can perform a per-recipe
16587 check for what the latest upstream source code version is
16588 by calling
16589 <filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.
16590 If the recipe source code is provided from Git
16591 repositories, the OpenEmbedded build system determines the
16592 latest upstream version by picking the latest tag from the
16593 list of all repository tags.
16594 You can use the
16595 <filename>UPSTREAM_CHECK_GITTAGREGEX</filename>
16596 variable to provide a regular expression to filter only the
16597 relevant tags should the default filter not work
16598 correctly.
16599 <literallayout class='monospaced'>
16600 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"
16601 </literallayout>
16602 </para>
16603 </glossdef>
16604 </glossentry>
16605
16606 <glossentry id='var-UPSTREAM_CHECK_REGEX'><glossterm>UPSTREAM_CHECK_REGEX</glossterm>
16607 <info>
16608 UPSTREAM_CHECK_REGEX[doc] = "The regular expression the package checking system uses to parse the page pointed to by UPSTREAM_CHECK_URI."
16609 </info>
16610 <glossdef>
16611 <para role="glossdeffirst">
16612<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16613 When the
16614 <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link>
16615 class is enabled globally, use the
16616 <filename>UPSTREAM_CHECK_REGEX</filename> variable to
16617 specify a different regular expression instead of the
16618 default one when the package checking system is parsing
16619 the page found using
16620 <link linkend='var-UPSTREAM_CHECK_URI'><filename>UPSTREAM_CHECK_URI</filename></link>.
16621 <literallayout class='monospaced'>
16622 UPSTREAM_CHECK_REGEX = "package_regex"
16623 </literallayout>
16624 </para>
16625 </glossdef>
16626 </glossentry>
16627
16628 <glossentry id='var-UPSTREAM_CHECK_URI'><glossterm>UPSTREAM_CHECK_URI</glossterm>
16629 <info>
16630 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."
16631 </info>
16632 <glossdef>
16633 <para role="glossdeffirst">
16634<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16635 When the
16636 <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link>
16637 class is enabled globally, you can perform a per-recipe
16638 check for what the latest upstream source code version is
16639 by calling <filename>bitbake -c checkpkg</filename>
16640 <replaceable>recipe</replaceable>.
16641 If the source code is provided from tarballs, the latest
16642 version is determined by fetching the directory listing
16643 where the tarball is and attempting to find a later tarball.
16644 When this approach does not work, you can use
16645 <filename>UPSTREAM_CHECK_URI</filename> to
16646 provide a different URI that contains the link to the
16647 latest tarball.
16648 <literallayout class='monospaced'>
16649 UPSTREAM_CHECK_URI = "recipe_url"
16650 </literallayout>
16651 </para>
16652 </glossdef>
16653 </glossentry>
16654
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016655 <glossentry id='var-USE_DEVFS'><glossterm>USE_DEVFS</glossterm>
16656 <info>
16657 USE_DEVFS[doc] = "Determines if devtmpfs is used for /dev population."
16658 </info>
16659 <glossdef>
16660 <para role="glossdeffirst">
16661<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16662 Determines if <filename>devtmpfs</filename> is used for
16663 <filename>/dev</filename> population.
16664 The default value used for <filename>USE_DEVFS</filename>
16665 is "1" when no value is specifically set.
16666 Typically, you would set <filename>USE_DEVFS</filename>
16667 to "0" for a statically populated <filename>/dev</filename>
16668 directory.
16669 </para>
16670
16671 <para>
16672 See the
16673 "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-dev-manager'>Selecting a Device Manager</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016674 section in the Yocto Project Development Tasks Manual for
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016675 information on how to use this variable.
16676 </para>
16677 </glossdef>
16678 </glossentry>
16679
16680 <glossentry id='var-USE_VT'><glossterm>USE_VT</glossterm>
16681 <info>
16682 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."
16683 </info>
16684 <glossdef>
16685 <para role="glossdeffirst">
16686<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16687 When using
16688 <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
16689 determines whether or not to run a
16690 <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
16691 on any virtual terminals in order to enable logging in
16692 through those terminals.
16693 </para>
16694
16695 <para>
16696 The default value used for <filename>USE_VT</filename>
16697 is "1" when no default value is specifically set.
16698 Typically, you would set <filename>USE_VT</filename>
16699 to "0" in the machine configuration file for machines
16700 that do not have a graphical display attached and
16701 therefore do not need virtual terminal functionality.
16702 </para>
16703 </glossdef>
16704 </glossentry>
16705
16706 <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
16707 <info>
16708 USER_CLASSES[doc] = "List of additional classes to use when building images that enable extra features."
16709 </info>
16710 <glossdef>
16711 <para role="glossdeffirst">
16712<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16713 A list of classes to globally inherit.
16714 These classes are used by the OpenEmbedded build system
16715 to enable extra features (e.g.
16716 <filename>buildstats</filename>,
16717 <filename>image-mklibs</filename>, and so forth).
16718 </para>
16719
16720 <para>
16721 The default list is set in your
16722 <filename>local.conf</filename> file:
16723 <literallayout class='monospaced'>
16724 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
16725 </literallayout>
16726 For more information, see
Patrick Williamsd8c66bc2016-06-20 12:57:21 -050016727 <filename>meta-poky/conf/local.conf.sample</filename> in
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016728 the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050016729 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016730 </para>
16731 </glossdef>
16732 </glossentry>
16733
16734 <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>
16735 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016736 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 -050016737 </info>
16738 <glossdef>
16739 <para role="glossdeffirst">
16740<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016741 If set to "error", forces the OpenEmbedded build system to
16742 produce an error if the user identification
16743 (<filename>uid</filename>) and group identification
16744 (<filename>gid</filename>) values are not defined
16745 in <filename>files/passwd</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016746 and <filename>files/group</filename> files.
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016747 If set to "warn", a warning will be issued instead.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016748 </para>
16749
16750 <para>
16751 The default behavior for the build system is to dynamically
16752 apply <filename>uid</filename> and
16753 <filename>gid</filename> values.
16754 Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>
16755 variable is by default not set.
16756 If you plan on using statically assigned
16757 <filename>gid</filename> and <filename>uid</filename>
16758 values, you should set
16759 the <filename>USERADD_ERROR_DYNAMIC</filename> variable in
16760 your <filename>local.conf</filename> file as
16761 follows:
16762 <literallayout class='monospaced'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016763 USERADD_ERROR_DYNAMIC = "error"
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016764 </literallayout>
16765 Overriding the default behavior implies you are going to
16766 also take steps to set static <filename>uid</filename> and
16767 <filename>gid</filename> values through use of the
16768 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
16769 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
16770 and
16771 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
16772 variables.
16773 </para>
16774 </glossdef>
16775 </glossentry>
16776
16777 <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>
16778 <info>
16779 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."
16780 </info>
16781 <glossdef>
16782 <para role="glossdeffirst">
16783<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16784 Specifies a password file to use for obtaining static
16785 group identification (<filename>gid</filename>) values
16786 when the OpenEmbedded build system adds a group to the
16787 system during package installation.
16788 </para>
16789
16790 <para>
16791 When applying static group identification
16792 (<filename>gid</filename>) values, the OpenEmbedded build
16793 system looks in
16794 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
16795 for a <filename>files/group</filename> file and then applies
16796 those <filename>uid</filename> values.
16797 Set the variable as follows in your
16798 <filename>local.conf</filename> file:
16799 <literallayout class='monospaced'>
16800 USERADD_GID_TABLES = "files/group"
16801 </literallayout>
16802 </para>
16803
16804 <note>
16805 Setting the
16806 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
16807 variable to "useradd-staticids" causes the build system
16808 to use static <filename>gid</filename> values.
16809 </note>
16810 </glossdef>
16811 </glossentry>
16812
16813 <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>
16814 <info>
16815 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."
16816 </info>
16817 <glossdef>
16818 <para role="glossdeffirst">
16819<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16820 When inheriting the
16821 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
16822 class, this variable
16823 specifies the individual packages within the recipe that
16824 require users and/or groups to be added.
16825 </para>
16826
16827 <para>
16828 You must set this variable if the recipe inherits the
16829 class.
16830 For example, the following enables adding a user for the
16831 main package in a recipe:
16832 <literallayout class='monospaced'>
16833 USERADD_PACKAGES = "${PN}"
16834 </literallayout>
16835 <note>
Andrew Geissler99467da2019-02-25 18:54:23 -060016836 It follows that if you are going to use the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016837 <filename>USERADD_PACKAGES</filename> variable,
16838 you need to set one or more of the
16839 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
16840 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
16841 or
16842 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
16843 variables.
16844 </note>
16845 </para>
16846
16847 </glossdef>
16848 </glossentry>
16849
16850 <glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>
16851 <info>
Brad Bishop316dfdd2018-06-25 12:45:53 -040016852 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 -050016853 </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
Brad Bishop316dfdd2018-06-25 12:45:53 -040016860 specifies for a package what parameters should pass
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016861 to the <filename>useradd</filename> command
Brad Bishop316dfdd2018-06-25 12:45:53 -040016862 if you add a user to the system when the package
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016863 is installed.
16864 </para>
16865
16866 <para>
16867 Here is an example from the <filename>dbus</filename>
16868 recipe:
16869 <literallayout class='monospaced'>
16870 USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \
16871 --no-create-home --shell /bin/false \
16872 --user-group messagebus"
16873 </literallayout>
16874 For information on the standard Linux shell command
16875 <filename>useradd</filename>, see
16876 <ulink url='http://linux.die.net/man/8/useradd'></ulink>.
16877 </para>
16878 </glossdef>
16879 </glossentry>
16880
16881 <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>
16882 <info>
16883 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."
16884 </info>
16885 <glossdef>
16886 <para role="glossdeffirst">
16887<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16888 Specifies a password file to use for obtaining static
16889 user identification (<filename>uid</filename>) values
16890 when the OpenEmbedded build system adds a user to the
16891 system during package installation.
16892 </para>
16893
16894 <para>
16895 When applying static user identification
16896 (<filename>uid</filename>) values, the OpenEmbedded build
16897 system looks in
16898 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
16899 for a <filename>files/passwd</filename> file and then applies
16900 those <filename>uid</filename> values.
16901 Set the variable as follows in your
16902 <filename>local.conf</filename> file:
16903 <literallayout class='monospaced'>
16904 USERADD_UID_TABLES = "files/passwd"
16905 </literallayout>
16906 </para>
16907
16908 <note>
16909 Setting the
16910 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
16911 variable to "useradd-staticids" causes the build system
16912 to use static <filename>uid</filename> values.
16913 </note>
16914 </glossdef>
16915 </glossentry>
16916
16917 <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>
16918 <info>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060016919 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 -050016920 </info>
16921 <glossdef>
16922 <para role="glossdeffirst">
16923<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16924 When set to "useradd-staticids", causes the
16925 OpenEmbedded build system to base all user and group
16926 additions on a static
16927 <filename>passwd</filename> and
16928 <filename>group</filename> files found in
16929 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
16930 </para>
16931
16932 <para>
16933 To use static user identification (<filename>uid</filename>)
16934 and group identification (<filename>gid</filename>)
16935 values, set the variable
16936 as follows in your <filename>local.conf</filename> file:
16937 <literallayout class='monospaced'>
16938 USERADDEXTENSION = "useradd-staticids"
16939 </literallayout>
16940 <note>
16941 Setting this variable to use static
16942 <filename>uid</filename> and <filename>gid</filename>
16943 values causes the OpenEmbedded build system to employ
16944 the
Patrick Williamsf1e5d692016-03-30 15:21:19 -050016945 <link linkend='ref-classes-useradd'><filename>useradd-staticids</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016946 class.
16947 </note>
16948 </para>
16949
16950 <para>
16951 If you use static <filename>uid</filename> and
16952 <filename>gid</filename> information, you must also
16953 specify the <filename>files/passwd</filename> and
16954 <filename>files/group</filename> files by setting the
16955 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
16956 and
16957 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
16958 variables.
16959 Additionally, you should also set the
16960 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
16961 variable.
16962 </para>
16963 </glossdef>
16964 </glossentry>
16965
16966 </glossdiv>
16967
Brad Bishop6e60e8b2018-02-01 10:27:11 -050016968 <glossdiv id='var-glossary-v'><title>V</title>
16969
16970 <glossentry id='var-VOLATILE_LOG_DIR'><glossterm>VOLATILE_LOG_DIR</glossterm>
16971 <info>
16972 VOLATILE_LOG_DIR[doc] = "Specifies the persistence of the target's /var/log directory, which is used to house postinstall target log files."
16973 </info>
16974 <glossdef>
16975 <para role="glossdeffirst">
16976<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
16977 Specifies the persistence of the target's
16978 <filename>/var/log</filename> directory, which is used to
16979 house postinstall target log files.
16980 </para>
16981
16982 <para>
16983 By default, <filename>VOLATILE_LOG_DIR</filename> is set
16984 to "yes", which means the file is not persistent.
16985 You can override this setting by setting the
16986 variable to "no" to make the log directory persistent.
16987 </para>
16988 </glossdef>
16989 </glossentry>
16990
16991 </glossdiv>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050016992
16993 <glossdiv id='var-glossary-w'><title>W</title>
16994
16995 <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
16996 <info>
16997 WARN_QA[doc] = "Specifies the quality assurance checks whose failures are reported as warnings by the OpenEmbedded build system."
16998 </info>
16999 <glossdef>
17000 <para role="glossdeffirst">
17001<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17002 Specifies the quality assurance checks whose failures are
17003 reported as warnings by the OpenEmbedded build system.
17004 You set this variable in your distribution configuration
17005 file.
17006 For a list of the checks you can control with this variable,
17007 see the
17008 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
17009 section.
17010 </para>
17011 </glossdef>
17012 </glossentry>
17013
Brad Bishop6e60e8b2018-02-01 10:27:11 -050017014 <glossentry id='var-WKS_FILE_DEPENDS'><glossterm>WKS_FILE_DEPENDS</glossterm>
17015 <info>
17016 WKS_FILE_DEPENDS[doc] = "Lists a recipe's build-time dependencies specific to Wic."
17017 </info>
17018 <glossdef>
17019 <para role="glossdeffirst">
17020 When placed in the recipe that builds your image, this
17021 variable lists build-time dependencies.
17022 The <filename>WKS_FILE_DEPENDS</filename> variable is only
17023 applicable when Wic images are active (i.e. when
17024 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
17025 contains entries related to Wic).
17026 If your recipe does not create Wic images, the variable
17027 has no effect.
17028 </para>
17029
17030 <para>
17031 The <filename>WKS_FILE_DEPENDS</filename> variable is
17032 similar to the
17033 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
17034 variable.
17035 When you use the variable in your recipe that builds the
17036 Wic image, dependencies you list in the
17037 <filename>WIC_FILE_DEPENDS</filename> variable are added to
17038 the <filename>DEPENDS</filename> variable.
17039 </para>
17040
17041 <para>
17042 With the <filename>WKS_FILE_DEPENDS</filename> variable,
17043 you have the possibility to specify a list of additional
17044 dependencies (e.g. native tools, bootloaders, and so forth),
17045 that are required to build Wic images.
17046 Following is an example:
17047 <literallayout class='monospaced'>
17048 WKS_FILE_DEPENDS = "<replaceable>some-native-tool</replaceable>"
17049 </literallayout>
17050 In the previous example,
17051 <replaceable>some-native-tool</replaceable> would be
17052 replaced with an actual native tool on which the build
17053 would depend.
17054 </para>
17055 </glossdef>
17056 </glossentry>
17057
Brad Bishop37a0e4d2017-12-04 01:01:44 -050017058 <glossentry id='var-WKS_FILE'><glossterm>WKS_FILE</glossterm>
17059 <info>
17060 WKS_FILE[doc] = "Specifies the name of the wic kickstart file."
17061 </info>
17062 <glossdef>
17063 <para role="glossdeffirst">
17064 Specifies the location of the Wic
17065 kickstart file that is used by the OpenEmbedded build
17066 system to create a partitioned image
17067 (<replaceable>image</replaceable><filename>.wic</filename>).
Brad Bishopd7bf8c12018-02-25 22:55:05 -050017068 For information on how to create a partitioned image, see
17069 the
17070 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
17071 section in the Yocto Project Development Tasks Manual.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050017072 For details on the kickstart file format, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -040017073 "<link linkend='ref-kickstart'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</link>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050017074 Chapter.
Brad Bishop37a0e4d2017-12-04 01:01:44 -050017075 </para>
17076 </glossdef>
17077 </glossentry>
17078
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017079 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
17080 <info>
17081 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."
17082 </info>
17083 <glossdef>
17084 <para role="glossdeffirst">
17085<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17086 The pathname of the work directory in which the OpenEmbedded
17087 build system builds a recipe.
17088 This directory is located within the
17089 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
17090 directory structure and is specific to the recipe being
17091 built and the system for which it is being built.
17092 </para>
17093
17094 <para>
17095 The <filename>WORKDIR</filename> directory is defined as
17096 follows:
17097 <literallayout class='monospaced'>
17098 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
17099 </literallayout>
17100 The actual directory depends on several things:
17101 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -040017102 <listitem><filename>TMPDIR</filename>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -050017103 The top-level build output directory</listitem>
17104 <listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>:
17105 The target system identifier</listitem>
17106 <listitem><link linkend='var-PN'><filename>PN</filename></link>:
17107 The recipe name</listitem>
17108 <listitem><link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>:
17109 The epoch - (if
17110 <link linkend='var-PE'><filename>PE</filename></link>
17111 is not specified, which is usually the case for most
17112 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
17113 <listitem><link linkend='var-PV'><filename>PV</filename></link>:
17114 The recipe version</listitem>
17115 <listitem><link linkend='var-PR'><filename>PR</filename></link>:
17116 The recipe revision</listitem>
17117 </itemizedlist>
17118 </para>
17119
17120 <para>
17121 As an example, assume a Source Directory top-level folder
17122 name <filename>poky</filename>, a default Build Directory at
17123 <filename>poky/build</filename>, and a
17124 <filename>qemux86-poky-linux</filename> machine target
17125 system.
17126 Furthermore, suppose your recipe is named
17127 <filename>foo_1.3.0-r0.bb</filename>.
17128 In this case, the work directory the build system uses to
17129 build the package would be as follows:
17130 <literallayout class='monospaced'>
17131 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
17132 </literallayout>
17133 </para>
17134 </glossdef>
17135 </glossentry>
17136
17137 </glossdiv>
17138
17139 <glossdiv id='var-glossary-x'><title>X</title>
17140
17141 <glossentry id='var-XSERVER'><glossterm>XSERVER</glossterm>
17142 <info>
17143 XSERVER[doc] = "Specifies the packages that should be installed
17144 to provide an X server and drivers for the current machine."
17145 </info>
17146 <glossdef>
17147 <para role="glossdeffirst">
17148<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
17149 Specifies the packages that should be installed to
17150 provide an X server and drivers for the current machine,
17151 assuming your image directly includes
17152 <filename>packagegroup-core-x11-xserver</filename> or,
17153 perhaps indirectly, includes "x11-base" in
17154 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
17155 </para>
17156
17157 <para>
17158 The default value of <filename>XSERVER</filename>, if not
17159 specified in the machine configuration, is
17160 "xserver-xorg xf86-video-fbdev xf86-input-evdev".
17161 </para>
17162 </glossdef>
17163 </glossentry>
17164
17165 </glossdiv>
17166
17167<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
17168<!-- </glossdiv>-->
17169
17170<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
17171<!-- </glossdiv>-->
17172
17173</glossary>
17174</chapter>
17175<!--
17176vim: expandtab tw=80 ts=4
17177-->