summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-variables.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/ref-variables.xml')
-rw-r--r--documentation/ref-manual/ref-variables.xml8419
1 files changed, 8419 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
new file mode 100644
index 0000000..4ff1a21
--- /dev/null
+++ b/documentation/ref-manual/ref-variables.xml
@@ -0,0 +1,8419 @@
1<!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-ALLOW_EMPTY'>A</link>
20 <link linkend='var-B'>B</link>
21 <link linkend='var-CFLAGS'>C</link>
22 <link linkend='var-D'>D</link>
23 <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link>
24 <link linkend='var-FEATURE_PACKAGES'>F</link>
25 <link linkend='var-GROUPADD_PARAM'>G</link>
26 <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>
32<!-- <link linkend='var-glossary-n'>N</link> -->
33 <link linkend='var-OE_BINCONFIG_EXTRA_MANGLE'>O</link>
34 <link linkend='var-P'>P</link>
35 <link linkend='var-QMAKE_PROFILES'>Q</link>
36 <link linkend='var-RCONFLICTS'>R</link>
37 <link linkend='var-S'>S</link>
38 <link linkend='var-T'>T</link>
39 <link linkend='var-UBOOT_CONFIG'>U</link>
40<!-- <link linkend='var-glossary-v'>V</link> -->
41 <link linkend='var-WARN_QA'>W</link>
42<!-- <link linkend='var-glossary-x'>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-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
50 <glossdef>
51 <para>
52 Specifies if an output package should still be produced if it is empty.
53 By default, BitBake does not produce empty packages.
54 This default behavior can cause issues when there is an
55 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
56 some other hard runtime requirement on the existence of the package.
57 </para>
58
59 <para>
60 Like all package-controlling variables, you must always use them in
61 conjunction with a package name override, as in:
62 <literallayout class='monospaced'>
63 ALLOW_EMPTY_${PN} = "1"
64 ALLOW_EMPTY_${PN}-dev = "1"
65 ALLOW_EMPTY_${PN}-staticdev = "1"
66 </literallayout>
67 </para>
68 </glossdef>
69 </glossentry>
70
71 <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
72 <glossdef>
73 <para>
74 Lists commands in a package that need an alternative
75 binary naming scheme.
76 Sometimes the same command is provided in multiple packages.
77 When this occurs, the OpenEmbedded build system needs to
78 use the alternatives system to create a different binary
79 naming scheme so the commands can co-exist.
80 </para>
81
82 <para>
83 To use the variable, list out the package's commands
84 that also exist as part of another package.
85 For example, if the <filename>busybox</filename> package
86 has four commands that also exist as part of another
87 package, you identify them as follows:
88 <literallayout class='monospaced'>
89 ALTERNATIVE_busybox = "sh sed test bracket"
90 </literallayout>
91 For more information on the alternatives system, see the
92 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
93 section.
94 </para>
95 </glossdef>
96 </glossentry>
97
98 <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
99 <glossdef>
100 <para>
101 Used by the alternatives system to map duplicated commands
102 to actual locations.
103 For example, if the <filename>bracket</filename> command
104 provided by the <filename>busybox</filename> package is
105 duplicated through another package, you must use the
106 <filename>ALTERNATIVE_LINK_NAME</filename> variable to
107 specify the actual location:
108 <literallayout class='monospaced'>
109 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
110 </literallayout>
111 In this example, the binary for the
112 <filename>bracket</filename> command (i.e.
113 <filename>[</filename>) from the
114 <filename>busybox</filename> package resides in
115 <filename>/usr/bin/</filename>.
116 <note>
117 If <filename>ALTERNATIVE_LINK_NAME</filename> is not
118 defined, it defaults to
119 <filename>${bindir}/&lt;name&gt;</filename>.
120 </note>
121 </para>
122
123 <para>
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_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
132 <glossdef>
133 <para>
134 Used by the alternatives system to create default
135 priorities for duplicated commands.
136 You can use the variable to create a single default
137 regardless of the command name or package, a default for
138 specific duplicated commands regardless of the package, or
139 a default for specific commands tied to particular packages.
140 Here are the available syntax forms:
141 <literallayout class='monospaced'>
142 ALTERNATIVE_PRIORITY = "&lt;priority&gt;"
143 ALTERNATIVE_PRIORITY[&lt;name&gt;] = "&lt;priority&gt;"
144 ALTERNATIVE_PRIORITY_&lt;pkg&gt;[&lt;name&gt;] = "&lt;priority&gt;"
145 </literallayout>
146 </para>
147
148 <para>
149 For more information on the alternatives system, see the
150 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
151 section.
152 </para>
153 </glossdef>
154 </glossentry>
155
156 <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
157 <glossdef>
158 <para>
159 Used by the alternatives system to create default link
160 locations for duplicated commands.
161 You can use the variable to create a single default
162 location for all duplicated commands regardless of the
163 command name or package, a default for
164 specific duplicated commands regardless of the package, or
165 a default for specific commands tied to particular packages.
166 Here are the available syntax forms:
167 <literallayout class='monospaced'>
168 ALTERNATIVE_TARGET = "&lt;target&gt;"
169 ALTERNATIVE_TARGET[&lt;name&gt;] = "&lt;target&gt;"
170 ALTERNATIVE_TARGET_&lt;pkg&gt;[&lt;name&gt;] = "&lt;target&gt;"
171 </literallayout>
172 <note>
173 <para>
174 If <filename>ALTERNATIVE_TARGET</filename> is not
175 defined, it inherits the value from the
176 <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
177 variable.
178 </para>
179
180 <para>
181 If <filename>ALTERNATIVE_LINK_NAME</filename> and
182 <filename>ALTERNATIVE_TARGET</filename> are the
183 same, the target for
184 <filename>ALTERNATIVE_TARGET</filename>
185 has "<filename>.{BPN}</filename>" appended to it.
186 </para>
187
188 <para>
189 Finally, if the file referenced has not been
190 renamed, the alternatives system will rename it to
191 avoid the need to rename alternative files in the
192 <filename>do_install</filename> task while
193 retaining support for the command if necessary.
194 </para>
195 </note>
196 </para>
197
198 <para>
199 For more information on the alternatives system, see the
200 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
201 section.
202 </para>
203 </glossdef>
204 </glossentry>
205
206 <glossentry id='var-APPEND'><glossterm>APPEND</glossterm>
207 <glossdef>
208 <para>
209 An override list of append strings for each
210 <link linkend='var-LABELS'><filename>LABEL</filename></link>.
211 </para>
212
213 <para>
214 See the
215 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
216 class for more information on how this variable is used.
217 </para>
218 </glossdef>
219 </glossentry>
220
221 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
222 <glossdef>
223 <para>The email address used to contact the original author
224 or authors in order to send patches and forward bugs.</para>
225 </glossdef>
226 </glossentry>
227
228 <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm>AUTO_SYSLINUXMENU</glossterm>
229 <glossdef>
230 <para>
231 Enables creating an automatic menu.
232 You must set this in your recipe.
233 The
234 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
235 class checks this variable.
236 </para>
237 </glossdef>
238 </glossentry>
239
240 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
241 <glossdef>
242 <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
243 is set to the value of this variable, it specifies to use the latest
244 source revision in the repository.
245 Here is an example:
246 <literallayout class='monospaced'>
247 SRCREV = "${AUTOREV}"
248 </literallayout>
249 </para>
250 </glossdef>
251 </glossentry>
252
253 </glossdiv>
254
255 <glossdiv id='var-glossary-b'><title>B</title>
256
257 <glossentry id='var-B'><glossterm>B</glossterm>
258 <glossdef>
259 <para>
260 The directory within the
261 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
262 in which the OpenEmbedded build system places generated
263 objects during a recipe's build process.
264 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
265 directory, which is defined as:
266 <literallayout class='monospaced'>
267 S = "${WORKDIR}/${BP}/"
268 </literallayout>
269 You can separate the (<filename>S</filename>) directory
270 and the directory pointed to by the <filename>B</filename>
271 variable.
272 Most Autotools-based recipes support separating these
273 directories.
274 The build system defaults to using separate directories for
275 <filename>gcc</filename> and some kernel recipes.
276 </para>
277 </glossdef>
278 </glossentry>
279
280 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
281 <glossdef>
282 <para>
283 Lists "recommended-only" packages to not install.
284 Recommended-only packages are packages installed only
285 through the
286 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
287 variable.
288 You can prevent any of these "recommended" packages from
289 being installed by listing them with the
290 <filename>BAD_RECOMMENDATIONS</filename> variable:
291 <literallayout class='monospaced'>
292 BAD_RECOMMENDATIONS = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
293 </literallayout>
294 You can set this variable globally in your
295 <filename>local.conf</filename> file or you can attach it to
296 a specific image recipe by using the recipe name override:
297 <literallayout class='monospaced'>
298 BAD_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
299 </literallayout>
300 </para>
301
302 <para>
303 It is important to realize that if you choose to not install
304 packages using this variable and some other packages are
305 dependent on them (i.e. listed in a recipe's
306 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
307 variable), the OpenEmbedded build system ignores your
308 request and will install the packages to avoid dependency
309 errors.
310 </para>
311
312 <para>
313 Support for this variable exists only when using the
314 IPK and RPM packaging backend.
315 Support does not exist for DEB.
316 </para>
317
318 <para>
319 See the
320 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
321 and the
322 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
323 variables for related information.
324 </para>
325 </glossdef>
326 </glossentry>
327
328 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
329 <glossdef>
330 <para>
331 Defines how BitBake handles situations where an append
332 file (<filename>.bbappend</filename>) has no
333 corresponding recipe file (<filename>.bb</filename>).
334 This condition often occurs when layers get out of sync
335 (e.g. <filename>oe-core</filename> bumps a
336 recipe version and the old recipe no longer exists and the
337 other layer has not been updated to the new version
338 of the recipe yet).
339 </para>
340
341 <para>
342 The default fatal behavior is safest because it is
343 the sane reaction given something is out of sync.
344 It is important to realize when your changes are no longer
345 being applied.
346 </para>
347
348 <para>
349 You can change the default behavior by setting this
350 variable to "1", "yes", or "true"
351 in your <filename>local.conf</filename> file, which is
352 located in the
353 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
354 Here is an example:
355 <literallayout class='monospaced'>
356 BB_DANGLINGAPPENDS_WARNONLY = "1"
357 </literallayout>
358 </para>
359 </glossdef>
360 </glossentry>
361
362 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
363 <glossdef>
364 <para>
365 Monitors disk space and available inodes during the build
366 and allows you to control the build based on these
367 parameters.
368 </para>
369
370 <para>
371 Disk space monitoring is disabled by default.
372 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
373 variable to your <filename>conf/local.conf</filename> file found in the
374 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
375 Use the following form:
376 <literallayout class='monospaced'>
377 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
378
379 where:
380
381 &lt;action&gt; is:
382 ABORT: Immediately abort the build when
383 a threshold is broken.
384 STOPTASKS: Stop the build after the currently
385 executing tasks have finished when
386 a threshold is broken.
387 WARN: Issue a warning but continue the
388 build when a threshold is broken.
389 Subsequent warnings are issued as
390 defined by the
391 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
392 which must be defined in the
393 conf/local.conf file.
394
395 &lt;dir&gt; is:
396 Any directory you choose. You can specify one or
397 more directories to monitor by separating the
398 groupings with a space. If two directories are
399 on the same device, only the first directory
400 is monitored.
401
402 &lt;threshold&gt; is:
403 Either the minimum available disk space,
404 the minimum number of free inodes, or
405 both. You must specify at least one. To
406 omit one or the other, simply omit the value.
407 Specify the threshold using G, M, K for Gbytes,
408 Mbytes, and Kbytes, respectively. If you do
409 not specify G, M, or K, Kbytes is assumed by
410 default. Do not use GB, MB, or KB.
411 </literallayout>
412 </para>
413
414 <para>
415 Here are some examples:
416 <literallayout class='monospaced'>
417 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
418 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
419 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
420 </literallayout>
421 The first example works only if you also provide
422 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
423 in the <filename>conf/local.conf</filename>.
424 This example causes the build system to immediately
425 abort when either the disk space in <filename>${TMPDIR}</filename> drops
426 below 1 Gbyte or the available free inodes drops below
427 100 Kbytes.
428 Because two directories are provided with the variable, the
429 build system also issue a
430 warning when the disk space in the
431 <filename>${SSTATE_DIR}</filename> directory drops
432 below 1 Gbyte or the number of free inodes drops
433 below 100 Kbytes.
434 Subsequent warnings are issued during intervals as
435 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
436 variable.
437 </para>
438
439 <para>
440 The second example stops the build after all currently
441 executing tasks complete when the minimum disk space
442 in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
443 directory drops below 1 Gbyte.
444 No disk monitoring occurs for the free inodes in this case.
445 </para>
446
447 <para>
448 The final example immediately aborts the build when the
449 number of free inodes in the <filename>${TMPDIR}</filename> directory
450 drops below 100 Kbytes.
451 No disk space monitoring for the directory itself occurs
452 in this case.
453 </para>
454 </glossdef>
455 </glossentry>
456
457 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
458 <glossdef>
459 <para>
460 Defines the disk space and free inode warning intervals.
461 To set these intervals, define the variable in your
462 <filename>conf/local.conf</filename> file in the
463 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
464 </para>
465
466 <para>
467 If you are going to use the
468 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
469 also use the
470 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
471 and define its action as "WARN".
472 During the build, subsequent warnings are issued each time
473 disk space or number of free inodes further reduces by
474 the respective interval.
475 </para>
476
477 <para>
478 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
479 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
480 the "WARN" action, the disk monitoring interval defaults to
481 the following:
482 <literallayout class='monospaced'>
483 BB_DISKMON_WARNINTERVAL = "50M,5K"
484 </literallayout>
485 </para>
486
487 <para>
488 When specifying the variable in your configuration file,
489 use the following form:
490 <literallayout class='monospaced'>
491 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
492
493 where:
494
495 &lt;disk_space_interval&gt; is:
496 An interval of memory expressed in either
497 G, M, or K for Gbytes, Mbytes, or Kbytes,
498 respectively. You cannot use GB, MB, or KB.
499
500 &lt;disk_inode_interval&gt; is:
501 An interval of free inodes expressed in either
502 G, M, or K for Gbytes, Mbytes, or Kbytes,
503 respectively. You cannot use GB, MB, or KB.
504 </literallayout>
505 </para>
506
507 <para>
508 Here is an example:
509 <literallayout class='monospaced'>
510 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
511 BB_DISKMON_WARNINTERVAL = "50M,5K"
512 </literallayout>
513 These variables cause the OpenEmbedded build system to
514 issue subsequent warnings each time the available
515 disk space further reduces by 50 Mbytes or the number
516 of free inodes further reduces by 5 Kbytes in the
517 <filename>${SSTATE_DIR}</filename> directory.
518 Subsequent warnings based on the interval occur each time
519 a respective interval is reached beyond the initial warning
520 (i.e. 1 Gbytes and 100 Kbytes).
521 </para>
522 </glossdef>
523 </glossentry>
524
525 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
526 <glossdef>
527 <para>
528 Causes tarballs of the Git repositories, including the
529 Git metadata, to be placed in the
530 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
531 directory.
532 </para>
533
534 <para>
535 For performance reasons, creating and placing tarballs of
536 the Git repositories is not the default action by the
537 OpenEmbedded build system.
538 <literallayout class='monospaced'>
539 BB_GENERATE_MIRROR_TARBALLS = "1"
540 </literallayout>
541 Set this variable in your <filename>local.conf</filename>
542 file in the
543 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
544 </para>
545 </glossdef>
546 </glossentry>
547
548 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
549 <glossdef>
550 <para>
551 The maximum number of tasks BitBake should run in parallel
552 at any one time.
553 If your host development system supports multiple cores,
554 a good rule of thumb is to set this variable to twice the
555 number of cores.
556 </para>
557
558 <para>
559 The default value for <filename>BB_NUMBER_THREADS</filename>
560 is equal to the number of cores your build system has.
561 </para>
562 </glossdef>
563 </glossentry>
564
565 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
566 <glossdef>
567 <para>
568 Allows you to extend a recipe so that it builds variants of the software.
569 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
570 which is a copy of Quilt built to run on the build system;
571 "crosses" such as <filename>gcc-cross</filename>,
572 which is a compiler built to run on the build machine but produces binaries
573 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
574 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
575 and "mulitlibs" in the form "<filename>multilib:&lt;multilib_name&gt;</filename>".
576 </para>
577
578 <para>
579 To build a different variant of the recipe with a minimal amount of code, it usually
580 is as simple as adding the following to your recipe:
581 <literallayout class='monospaced'>
582 BBCLASSEXTEND =+ "native nativesdk"
583 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
584 </literallayout>
585 </para>
586 </glossdef>
587 </glossentry>
588
589 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
590 <glossdef>
591 <para>Lists the names of configured layers.
592 These names are used to find the other <filename>BBFILE_*</filename>
593 variables.
594 Typically, each layer will append its name to this variable in its
595 <filename>conf/layer.conf</filename> file.
596 </para>
597 </glossdef>
598 </glossentry>
599
600 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
601 <glossdef>
602 <para>Variable that expands to match files from
603 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
604 in a particular layer.
605 This variable is used in the <filename>conf/layer.conf</filename> file and must
606 be suffixed with the name of the specific layer (e.g.
607 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
608 </glossdef>
609 </glossentry>
610
611 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
612 <glossdef>
613 <para>Assigns the priority for recipe files in each layer.</para>
614 <para>This variable is useful in situations where the same recipe appears in
615 more than one layer.
616 Setting this variable allows you to prioritize a
617 layer against other layers that contain the same recipe - effectively
618 letting you control the precedence for the multiple layers.
619 The precedence established through this variable stands regardless of a
620 recipe's version
621 (<link linkend='var-PV'><filename>PV</filename></link> variable).
622 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
623 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
624 lower precedence.</para>
625 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
626 precedence.
627 For example, the value 6 has a higher precedence than the value 5.
628 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
629 dependencies (see the
630 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
631 more information.
632 The default priority, if unspecified
633 for a layer with no dependencies, is the lowest defined priority + 1
634 (or 1 if no priorities are defined).</para>
635 <tip>
636 You can use the command <filename>bitbake-layers show-layers</filename> to list
637 all configured layers along with their priorities.
638 </tip>
639 </glossdef>
640 </glossentry>
641
642 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
643 <glossdef>
644 <para>List of recipe files used by BitBake to build software.</para>
645 </glossdef>
646 </glossentry>
647
648 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
649 <glossdef>
650 <para>Variable that controls how BitBake displays logs on build failure.</para>
651 </glossdef>
652 </glossentry>
653
654 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
655 <glossdef>
656 <para>Lists the layers to enable during the build.
657 This variable is defined in the <filename>bblayers.conf</filename> configuration
658 file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
659 Here is an example:
660 <literallayout class='monospaced'>
661 BBLAYERS = " \
662 /home/scottrif/poky/meta \
663 /home/scottrif/poky/meta-yocto \
664 /home/scottrif/poky/meta-yocto-bsp \
665 /home/scottrif/poky/meta-mykernel \
666 "
667
668 BBLAYERS_NON_REMOVABLE ?= " \
669 /home/scottrif/poky/meta \
670 /home/scottrif/poky/meta-yocto \
671 "
672 </literallayout>
673 This example enables four layers, one of which is a custom, user-defined layer
674 named <filename>meta-mykernel</filename>.
675 </para>
676 </glossdef>
677 </glossentry>
678
679 <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm>
680 <glossdef>
681 <para>Lists core layers that cannot be removed from the
682 <filename>bblayers.conf</filename> file during a build
683 using the
684 <ulink url='https://www.yoctoproject.org/tools-resources/projects/hob'>Hob</ulink>.
685 <note>
686 When building an image outside of Hob, this variable
687 is ignored.
688 </note>
689 In order for BitBake to build your image using Hob, your
690 <filename>bblayers.conf</filename> file must include the
691 <filename>meta</filename> and <filename>meta-yocto</filename>
692 core layers.
693 Here is an example that shows these two layers listed in
694 the <filename>BBLAYERS_NON_REMOVABLE</filename> statement:
695 <literallayout class='monospaced'>
696 BBLAYERS = " \
697 /home/scottrif/poky/meta \
698 /home/scottrif/poky/meta-yocto \
699 /home/scottrif/poky/meta-yocto-bsp \
700 /home/scottrif/poky/meta-mykernel \
701 "
702
703 BBLAYERS_NON_REMOVABLE ?= " \
704 /home/scottrif/poky/meta \
705 /home/scottrif/poky/meta-yocto \
706 "
707 </literallayout>
708 </para>
709 </glossdef>
710 </glossentry>
711
712 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
713 <glossdef>
714 <para>
715 Prevents BitBake from processing recipes and recipe
716 append files.
717 Use the <filename>BBMASK</filename> variable from within the
718 <filename>conf/local.conf</filename> file found
719 in the
720 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
721 </para>
722
723 <para>
724 You can use the <filename>BBMASK</filename> variable
725 to "hide" these <filename>.bb</filename> and
726 <filename>.bbappend</filename> files.
727 BitBake ignores any recipe or recipe append files that
728 match the expression.
729 It is as if BitBake does not see them at all.
730 Consequently, matching files are not parsed or otherwise
731 used by BitBake.</para>
732 <para>
733 The value you provide is passed to Python's regular
734 expression compiler.
735 The expression is compared against the full paths to
736 the files.
737 For complete syntax information, see Python's
738 documentation at
739 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
740 </para>
741
742 <para>
743 The following example uses a complete regular expression
744 to tell BitBake to ignore all recipe and recipe append
745 files in the <filename>meta-ti/recipes-misc/</filename>
746 directory:
747 <literallayout class='monospaced'>
748 BBMASK = "meta-ti/recipes-misc/"
749 </literallayout>
750 If you want to mask out multiple directories or recipes,
751 use the vertical bar to separate the regular expression
752 fragments.
753 This next example masks out multiple directories and
754 individual recipes:
755 <literallayout class='monospaced'>
756 BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/"
757 BBMASK .= "|.*meta-oe/recipes-support/"
758 BBMASK .= "|.*openldap"
759 BBMASK .= "|.*opencv"
760 BBMASK .= "|.*lzma"
761 </literallayout>
762 Notice how the vertical bar is used to append the fragments.
763 <note>
764 When specifying a directory name, use the trailing
765 slash character to ensure you match just that directory
766 name.
767 </note>
768 </para>
769 </glossdef>
770 </glossentry>
771
772 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
773 <glossdef>
774 <para>
775 Used by BitBake to locate
776 <filename>.bbclass</filename> and configuration files.
777 This variable is analogous to the
778 <filename>PATH</filename> variable.
779 <note>
780 If you run BitBake from a directory outside of the
781 <ulink url='&YOCTO_DOCS_DEV_URL;build-directory'>Build Directory</ulink>,
782 you must be sure to set
783 <filename>BBPATH</filename> to point to the
784 Build Directory.
785 Set the variable as you would any environment variable
786 and then run BitBake:
787 <literallayout class='monospaced'>
788 $ BBPATH = "&lt;build_directory&gt;"
789 $ export BBPATH
790 $ bitbake &lt;target&gt;
791 </literallayout>
792 </note>
793 </para>
794 </glossdef>
795 </glossentry>
796
797 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
798 <glossdef>
799 <para>
800 Points to the server that runs memory-resident BitBake.
801 This variable is set by the
802 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
803 setup script and should not be hand-edited.
804 The variable is only used when you employ memory-resident
805 BitBake.
806 The setup script exports the value as follows:
807 <literallayout class='monospaced'>
808 export BBSERVER=localhost:$port
809 </literallayout>
810 For more information on how the
811 <filename>BBSERVER</filename> is used, see the
812 <filename>oe-init-build-env-memres</filename> script, which
813 is located in the
814 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
815 </para>
816 </glossdef>
817 </glossentry>
818
819 <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
820 <glossdef>
821 <para>
822 When inheriting <filename>binconfig.bbclass</filename>
823 from a recipe, this variable specifies a wildcard for
824 configuration scripts that need editing.
825 The scripts are edited to correct any paths that have been
826 set up during compilation so that they are correct for
827 use when installed into the sysroot and called by the
828 build processes of other recipes.
829 </para>
830
831 <para>
832 For more information on how this variable works, see
833 <filename>meta/classes/binconfig.bbclass</filename> in the
834 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
835 You can also find general information on the class in the
836 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
837 section.
838 </para>
839 </glossdef>
840 </glossentry>
841
842 <glossentry id='var-BP'><glossterm>BP</glossterm>
843 <glossdef>
844 <para>The base recipe name and version but without any special
845 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
846 and so forth).
847 <filename>BP</filename> is comprised of the following:
848 <literallayout class="monospaced">
849 ${BPN}-${PV}
850 </literallayout></para>
851 </glossdef>
852 </glossentry>
853
854 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
855 <glossdef>
856 <para>The bare name of the recipe.
857 This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable
858 but removes common suffixes such as "-native" and "-cross" as well
859 as removes common prefixes such as multilib's "lib64-" and "lib32-".
860 The exact list of suffixes removed is specified by the
861 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable.
862 The exact list of prefixes removed is specified by the
863 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable.
864 Prefixes are removed for <filename>multilib</filename>
865 and <filename>nativesdk</filename> cases.</para>
866 </glossdef>
867 </glossentry>
868
869 <glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm>
870 <glossdef>
871 <para>
872 Specifies a URL for an upstream bug tracking website for
873 a recipe.
874 The OpenEmbedded build system does not use this variable.
875 Rather, the variable is a useful pointer in case a bug
876 in the software being built needs to be manually reported.
877 </para>
878 </glossdef>
879 </glossentry>
880
881 <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
882 <glossdef>
883 <para>
884 Points to the location of the
885 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
886 You can define this directory indirectly through the
887 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
888 and
889 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
890 scripts by passing in a Build Directory path when you run
891 the scripts.
892 If you run the scripts and do not provide a Build Directory
893 path, the <filename>BUILDDIR</filename> defaults to
894 <filename>build</filename> in the current directory.
895 </para>
896 </glossdef>
897 </glossentry>
898
899 <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>BUILDHISTORY_COMMIT</glossterm>
900 <glossdef>
901 <para>
902 When inheriting the
903 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
904 class, specifies whether or not to commit the build
905 history output in a local Git repository.
906 If set to "1", this local repository will be maintained
907 automatically by the
908 <filename>buildhistory</filename>
909 class and a commit will be created on every
910 build for changes to each top-level subdirectory of the
911 build history output (images, packages, and sdk).
912 If you want to track changes to build history over
913 time, you should set this value to "1".
914 </para>
915
916 <para>
917 By default, the <filename>buildhistory</filename> class
918 does not commit the build history output in a local
919 Git repository:
920 <literallayout class='monospaced'>
921 BUILDHISTORY_COMMIT ?= "0"
922 </literallayout>
923 </para>
924 </glossdef>
925 </glossentry>
926
927 <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>BUILDHISTORY_COMMIT_AUTHOR</glossterm>
928 <glossdef>
929 <para>
930 When inheriting the
931 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
932 class, specifies the author to use for each Git commit.
933 In order for the <filename>BUILDHISTORY_COMMIT_AUTHOR</filename>
934 variable to work, the
935 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
936 variable must be set to "1".
937 </para>
938
939 <para>
940 Git requires that the value you provide for the
941 <filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable
942 takes the form of "name &lt;email@host&gt;".
943 Providing an email address or host that is not valid does
944 not produce an error.
945 </para>
946
947 <para>
948 By default, the <filename>buildhistory</filename> class
949 sets the variable as follows:
950 <literallayout class='monospaced'>
951 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory &lt;buildhistory@${DISTRO}&gt;"
952 </literallayout>
953 </para>
954 </glossdef>
955 </glossentry>
956
957 <glossentry id='var-BUILDHISTORY_DIR'><glossterm>BUILDHISTORY_DIR</glossterm>
958 <glossdef>
959 <para>
960 When inheriting the
961 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
962 class, specifies the directory in which build history
963 information is kept.
964 For more information on how the variable works, see the
965 <filename>buildhistory.class</filename>.
966 </para>
967
968 <para>
969 By default, the <filename>buildhistory</filename> class
970 sets the directory as follows:
971 <literallayout class='monospaced'>
972 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
973 </literallayout>
974 </para>
975 </glossdef>
976 </glossentry>
977
978 <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>BUILDHISTORY_FEATURES</glossterm>
979 <glossdef>
980 <para>
981 When inheriting the
982 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
983 class, specifies the build history features to be enabled.
984 For more information on how build history works, see the
985 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
986 section.
987 </para>
988
989 <para>
990 You can specify three features in the form of a
991 space-separated list:
992 <itemizedlist>
993 <listitem><para><emphasis>image:</emphasis>
994 Analysis of the contents of images, which
995 includes the list of installed packages among other
996 things.
997 </para></listitem>
998 <listitem><para><emphasis>package:</emphasis>
999 Analysis of the contents of individual packages.
1000 </para></listitem>
1001 <listitem><para><emphasis>sdk:</emphasis>
1002 Analysis of the contents of the software
1003 development kit (SDK).
1004 </para></listitem>
1005 </itemizedlist>
1006 </para>
1007
1008 <para>
1009 By default, the <filename>buildhistory</filename> class
1010 enables all three features:
1011 <literallayout class='monospaced'>
1012 BUILDHISTORY_FEATURES ?= "image package sdk"
1013 </literallayout>
1014 </para>
1015 </glossdef>
1016 </glossentry>
1017
1018 <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>BUILDHISTORY_IMAGE_FILES</glossterm>
1019 <glossdef>
1020 <para>
1021 When inheriting the
1022 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1023 class, specifies a list of paths to files copied from the
1024 image contents into the build history directory under
1025 an "image-files" directory in the directory for
1026 the image, so that you can track the contents of each file.
1027 The default is to copy <filename>/etc/passwd</filename>
1028 and <filename>/etc/group</filename>, which allows you to
1029 monitor for changes in user and group entries.
1030 You can modify the list to include any file.
1031 Specifying an invalid path does not produce an error.
1032 Consequently, you can include files that might
1033 not always be present.
1034 </para>
1035
1036 <para>
1037 By default, the <filename>buildhistory</filename> class
1038 provides paths to the following files:
1039 <literallayout class='monospaced'>
1040 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
1041 </literallayout>
1042 </para>
1043 </glossdef>
1044 </glossentry>
1045
1046 <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>BUILDHISTORY_PUSH_REPO</glossterm>
1047 <glossdef>
1048 <para>
1049 When inheriting the
1050 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1051 class, optionally specifies a remote repository
1052 to which build history pushes Git changes.
1053 In order for <filename>BUILDHISTORY_PUSH_REPO</filename>
1054 to work,
1055 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
1056 must be set to "1".
1057 </para>
1058
1059 <para>
1060 The repository should correspond to a remote
1061 address that specifies a repository as understood by
1062 Git, or alternatively to a remote name that you have
1063 set up manually using <filename>git remote</filename>
1064 within the local repository.
1065 </para>
1066
1067 <para>
1068 By default, the <filename>buildhistory</filename> class
1069 sets the variable as follows:
1070 <literallayout class='monospaced'>
1071 BUILDHISTORY_PUSH_REPO ?= ""
1072 </literallayout>
1073 </para>
1074 </glossdef>
1075 </glossentry>
1076
1077 <glossentry id='var-BUILDSTATS_BASE'><glossterm>BUILDSTATS_BASE</glossterm>
1078 <glossdef>
1079 <para>
1080 Points to the location of the directory that holds build
1081 statistics when you use and enable the
1082 <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link>
1083 class.
1084 The <filename>BUILDSTATS_BASE</filename> directory defaults
1085 to
1086 <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/buildstats/</filename>.
1087 </para>
1088 </glossdef>
1089 </glossentry>
1090
1091 <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
1092 <glossdef>
1093 <para>
1094 For the BusyBox recipe, specifies whether to split the
1095 output executable file into two parts: one for features
1096 that require <filename>setuid root</filename>, and one for
1097 the remaining features (i.e. those that do not require
1098 <filename>setuid root</filename>).
1099 </para>
1100
1101 <para>
1102 The <filename>BUSYBOX_SPLIT_SUID</filename> variable
1103 defaults to "1", which results in a single output
1104 executable file.
1105 Set the variable to "0" to split the output file.
1106 </para>
1107 </glossdef>
1108 </glossentry>
1109
1110 </glossdiv>
1111
1112 <glossdiv id='var-glossary-c'><title>C</title>
1113
1114 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
1115 <glossdef>
1116 <para>
1117 Flags passed to the C compiler for the target system.
1118 This variable evaluates to the same as
1119 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>.
1120 </para>
1121
1122 <para>
1123 For information on flags that help with creating more
1124 secure code, see the
1125 "<ulink url='&YOCTO_DOCS_DEV_URL;#making-images-more-secure'>Making Images More Secure</ulink>"
1126 section in the Yocto Project Development Manual.
1127 </para>
1128 </glossdef>
1129 </glossentry>
1130
1131 <glossentry id='var-CLASSOVERRIDE'><glossterm>CLASSOVERRIDE</glossterm>
1132 <glossdef>
1133 <para>
1134 An internal variable specifying the special class override
1135 that should currently apply (e.g. "class-target",
1136 "class-native", and so forth).
1137 The classes that use this variable set it to
1138 appropriate values.
1139 </para>
1140
1141 <para>
1142 You do not normally directly interact with this variable.
1143 The value for the <filename>CLASSOVERRIDE</filename>
1144 variable goes into
1145 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1146 and then can be used as an override.
1147 Here is an example where "python-native" is added to
1148 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1149 only when building for the native case:
1150 <literallayout class='monospaced'>
1151 DEPENDS_append_class-native = " python-native"
1152 </literallayout>
1153 </para>
1154 </glossdef>
1155 </glossentry>
1156
1157 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
1158 <glossdef>
1159 <para>
1160 Provides a list of hardware features that are enabled in
1161 both
1162 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
1163 and
1164 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
1165 This select list of features contains features that make
1166 sense to be controlled both at the machine and distribution
1167 configuration level.
1168 For example, the "bluetooth" feature requires hardware
1169 support but should also be optional at the distribution
1170 level, in case the hardware supports Bluetooth but you
1171 do not ever intend to use it.
1172 </para>
1173
1174 <para>
1175 For more information, see the
1176 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
1177 and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
1178 variables.
1179 </para>
1180 </glossdef>
1181 </glossentry>
1182
1183 <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
1184 <glossdef>
1185 <para>
1186 Points to <filename>meta/files/common-licenses</filename>
1187 in the
1188 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
1189 which is where generic license files reside.
1190 </para>
1191 </glossdef>
1192 </glossentry>
1193
1194 <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
1195 <glossdef>
1196 <para>A regular expression that resolves to one or more hosts
1197 (when the recipe is native) or one or more targets (when
1198 the recipe is non-native) with which a recipe is compatible.
1199 The regular expression is matched against
1200 <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
1201 You can use the variable to stop recipes from being built
1202 for classes of systems with which the recipes are not
1203 compatible.
1204 Stopping these builds is particularly useful with kernels.
1205 The variable also helps to increase parsing speed
1206 since the build system skips parsing recipes not
1207 compatible with the current system.</para>
1208 </glossdef>
1209 </glossentry>
1210
1211 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
1212 <glossdef>
1213 <para>A regular expression that resolves to one or more
1214 target machines with which a recipe is compatible.
1215 The regular expression is matched against
1216 <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
1217 You can use the variable to stop recipes from being built
1218 for machines with which the recipes are not compatible.
1219 Stopping these builds is particularly useful with kernels.
1220 The variable also helps to increase parsing speed
1221 since the build system skips parsing recipes not
1222 compatible with the current machine.</para>
1223 </glossdef>
1224 </glossentry>
1225
1226 <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
1227 <glossdef>
1228 <para>
1229 Defines wildcards to match when installing a list of
1230 complementary packages for all the packages explicitly
1231 (or implicitly) installed in an image.
1232 The resulting list of complementary packages is associated
1233 with an item that can be added to
1234 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
1235 An example usage of this is the "dev-pkgs" item that when
1236 added to <filename>IMAGE_FEATURES</filename> will
1237 install -dev packages (containing headers and other
1238 development files) for every package in the image.
1239 </para>
1240
1241 <para>
1242 To add a new feature item pointing to a wildcard, use a
1243 variable flag to specify the feature item name and
1244 use the value to specify the wildcard.
1245 Here is an example:
1246 <literallayout class='monospaced'>
1247 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
1248 </literallayout>
1249 </para>
1250 </glossdef>
1251 </glossentry>
1252
1253 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
1254 <glossdef>
1255 <para>
1256 Identifies editable or configurable files that are part of a package.
1257 If the Package Management System (PMS) is being used to update
1258 packages on the target system, it is possible that
1259 configuration files you have changed after the original installation
1260 and that you now want to remain unchanged are overwritten.
1261 In other words, editable files might exist in the package that you do not
1262 want reset as part of the package update process.
1263 You can use the <filename>CONFFILES</filename> variable to list the files in the
1264 package that you wish to prevent the PMS from overwriting during this update process.
1265 </para>
1266
1267 <para>
1268 To use the <filename>CONFFILES</filename> variable, provide a package name
1269 override that identifies the resulting package.
1270 Then, provide a space-separated list of files.
1271 Here is an example:
1272 <literallayout class='monospaced'>
1273 CONFFILES_${PN} += "${sysconfdir}/file1 \
1274 ${sysconfdir}/file2 ${sysconfdir}/file3"
1275 </literallayout>
1276 </para>
1277
1278 <para>
1279 A relationship exists between the <filename>CONFFILES</filename> and
1280 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
1281 The files listed within <filename>CONFFILES</filename> must be a subset of
1282 the files listed within <filename>FILES</filename>.
1283 Because the configuration files you provide with <filename>CONFFILES</filename>
1284 are simply being identified so that the PMS will not overwrite them,
1285 it makes sense that
1286 the files must already be included as part of the package through the
1287 <filename>FILES</filename> variable.
1288 </para>
1289
1290 <note>
1291 When specifying paths as part of the <filename>CONFFILES</filename> variable,
1292 it is good practice to use appropriate path variables.
1293 For example, <filename>${sysconfdir}</filename> rather than
1294 <filename>/etc</filename> or <filename>${bindir}</filename> rather
1295 than <filename>/usr/bin</filename>.
1296 You can find a list of these variables at the top of the
1297 <filename>meta/conf/bitbake.conf</filename> file in the
1298 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1299 </note>
1300 </glossdef>
1301 </glossentry>
1302
1303 <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>
1304 <glossdef>
1305 <para>
1306 Identifies the initial RAM disk (initramfs) source files.
1307 The OpenEmbedded build system receives and uses
1308 this kernel Kconfig variable as an environment variable.
1309 By default, the variable is set to null ("").
1310 </para>
1311
1312 <para>
1313 The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be
1314 either a single cpio archive with a
1315 <filename>.cpio</filename> suffix or a
1316 space-separated list of directories and files for building
1317 the initramfs image.
1318 A cpio archive should contain a filesystem archive
1319 to be used as an initramfs image.
1320 Directories should contain a filesystem layout to be
1321 included in the initramfs image.
1322 Files should contain entries according to the format
1323 described by the
1324 <filename>usr/gen_init_cpio</filename> program in the
1325 kernel tree.
1326 </para>
1327
1328 <para>
1329 If you specify multiple directories and files, the
1330 initramfs image will be the aggregate of all of them.
1331 </para>
1332 </glossdef>
1333 </glossentry>
1334
1335 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
1336 <glossdef>
1337 <para>
1338 A list of files that contains <filename>autoconf</filename> test results relevant
1339 to the current build.
1340 This variable is used by the Autotools utilities when running
1341 <filename>configure</filename>.
1342 </para>
1343 </glossdef>
1344 </glossentry>
1345
1346 <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>CONFLICT_DISTRO_FEATURES</glossterm>
1347 <glossdef>
1348 <para>
1349 When a recipe inherits the
1350 <filename>distro_features_check</filename> class, this
1351 variable identifies distribution features that would
1352 be in conflict should the recipe
1353 be built.
1354 In other words, if the
1355 <filename>CONFLICT_DISTRO_FEATURES</filename> variable
1356 lists a feature that also appears in
1357 <filename>DISTRO_FEATURES</filename> within the
1358 current configuration, an error occurs and the
1359 build stops.
1360 </para>
1361 </glossdef>
1362 </glossentry>
1363
1364 <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm>
1365 <glossdef>
1366 <para>
1367 If set to "1" along with the
1368 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
1369 variable, the OpenEmbedded build system copies
1370 into the image the license files, which are located in
1371 <filename>/usr/share/common-licenses</filename>,
1372 for each package.
1373 The license files are placed
1374 in directories within the image itself.
1375 </para>
1376 </glossdef>
1377 </glossentry>
1378
1379 <glossentry id='var-COPY_LIC_MANIFEST'><glossterm>COPY_LIC_MANIFEST</glossterm>
1380 <glossdef>
1381 <para>
1382 If set to "1", the OpenEmbedded build system copies
1383 the license manifest for the image to
1384 <filename>/usr/share/common-licenses/license.manifest</filename>
1385 within the image itself.
1386 </para>
1387 </glossdef>
1388 </glossentry>
1389
1390 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
1391 <glossdef>
1392 <para>
1393 Specifies the list of packages to be added to the image.
1394 You should only set this variable in the
1395 <filename>local.conf</filename> configuration file found
1396 in the
1397 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1398 </para>
1399
1400 <para>
1401 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
1402 </para>
1403 </glossdef>
1404 </glossentry>
1405
1406 <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
1407 <glossdef>
1408 <para>
1409 Specifies the parent directory of the OpenEmbedded
1410 Core Metadata layer (i.e. <filename>meta</filename>).
1411 </para>
1412
1413 <para>
1414 It is an important distinction that
1415 <filename>COREBASE</filename> points to the parent of this
1416 layer and not the layer itself.
1417 Consider an example where you have cloned the Poky Git
1418 repository and retained the <filename>poky</filename>
1419 name for your local copy of the repository.
1420 In this case, <filename>COREBASE</filename> points to
1421 the <filename>poky</filename> folder because it is the
1422 parent directory of the <filename>poky/meta</filename>
1423 layer.
1424 </para>
1425 </glossdef>
1426 </glossentry>
1427
1428 </glossdiv>
1429
1430 <glossdiv id='var-glossary-d'><title>D</title>
1431
1432 <glossentry id='var-D'><glossterm>D</glossterm>
1433 <glossdef>
1434 <para>
1435 The destination directory.
1436 The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1437 where components are installed by the <filename>do_install</filename> task.
1438 This location defaults to:
1439 <literallayout class='monospaced'>
1440 ${WORKDIR}/image
1441 </literallayout>
1442 </para>
1443 </glossdef>
1444 </glossentry>
1445
1446 <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
1447 <glossdef>
1448 <para>
1449 The date and time on which the current build started.
1450 The format is suitable for timestamps.
1451 </para>
1452 </glossdef>
1453 </glossentry>
1454
1455 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
1456 <glossdef>
1457 <para>
1458 Specifies to build packages with debugging information.
1459 This influences the value of the
1460 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
1461 variable.
1462 </para>
1463 </glossdef>
1464 </glossentry>
1465
1466 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
1467 <glossdef>
1468 <para>
1469 The options to pass in
1470 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1471 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
1472 a system for debugging.
1473 This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
1474 </para>
1475 </glossdef>
1476 </glossentry>
1477
1478 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
1479 <glossdef>
1480 <para>
1481 Specifies a weak bias for recipe selection priority.
1482 </para>
1483 <para>
1484 The most common usage of this is variable is to set
1485 it to "-1" within a recipe for a development version of a
1486 piece of software.
1487 Using the variable in this way causes the stable version
1488 of the recipe to build by default in the absence of
1489 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
1490 being used to build the development version.
1491 </para>
1492 <note>
1493 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
1494 is weak and is overridden by
1495 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
1496 if that variable is different between two layers
1497 that contain different versions of the same recipe.
1498 </note>
1499 </glossdef>
1500 </glossentry>
1501
1502 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
1503 <glossdef>
1504 <para>
1505 Lists a recipe's build-time dependencies
1506 (i.e. other recipe files).
1507 The system ensures that all the dependencies listed
1508 have been built and have their contents in the appropriate
1509 sysroots before the recipe's configure task is executed.
1510 </para>
1511
1512 <para>
1513 Consider this simple example for two recipes named "a" and
1514 "b" that produce similarly named packages.
1515 In this example, the <filename>DEPENDS</filename>
1516 statement appears in the "a" recipe:
1517 <literallayout class='monospaced'>
1518 DEPENDS = "b"
1519 </literallayout>
1520 Here, the dependency is such that the
1521 <filename>do_configure</filename> task for recipe "a"
1522 depends on the <filename>do_populate_sysroot</filename>
1523 task of recipe "b".
1524 This means anything that recipe "b" puts into sysroot
1525 is available when recipe "a" is configuring itself.
1526 </para>
1527
1528 <para>
1529 For information on runtime dependencies, see the
1530 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1531 variable.
1532 </para>
1533 </glossdef>
1534 </glossentry>
1535
1536 <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
1537 <glossdef>
1538 <para>
1539 Points to the general area that the OpenEmbedded build
1540 system uses to place images, packages, SDKs and other output
1541 files that are ready to be used outside of the build system.
1542 By default, this directory resides within the
1543 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1544 as <filename>${TMPDIR}/deploy</filename>.
1545 </para>
1546
1547 <para>
1548 For more information on the structure of the Build
1549 Directory, see
1550 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1551 section.
1552 For more detail on the contents of the
1553 <filename>deploy</filename> directory, see the
1554 "<link linkend='images-dev-environment'>Images</link>" and
1555 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1556 sections.
1557 </para>
1558 </glossdef>
1559 </glossentry>
1560
1561 <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
1562 <glossdef>
1563 <para>
1564 Points to the area that the OpenEmbedded build system uses
1565 to place images and other associated output files that are
1566 ready to be deployed onto the target machine.
1567 The directory is machine-specific as it contains the
1568 <filename>${MACHINE}</filename> name.
1569 By default, this directory resides within the
1570 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1571 as <filename>${DEPLOY_DIR}/images/${MACHINE}/</filename>.
1572 </para>
1573
1574 <para>
1575 For more information on the structure of the Build
1576 Directory, see
1577 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1578 section.
1579 For more detail on the contents of the
1580 <filename>deploy</filename> directory, see the
1581 "<link linkend='images-dev-environment'>Images</link>" and
1582 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1583 sections.
1584 </para>
1585 </glossdef>
1586 </glossentry>
1587
1588 <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm>
1589 <glossdef>
1590 <para>
1591 For recipes that inherit the
1592 <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
1593 class, the <filename>DEPLOYDIR</filename> points to a
1594 temporary work area for deployed files that is set in the
1595 <filename>deploy</filename> class as follows:
1596 <literallayout class='monospaced'>
1597 DEPLOYDIR = "${WORKDIR}/deploy-${<link linkend='var-PN'><filename>PN</filename></link>}"
1598 </literallayout>
1599 Recipes inheriting the <filename>deploy</filename> class
1600 should copy files to be deployed into
1601 <filename>DEPLOYDIR</filename>, and the class will take
1602 care of copying them into
1603 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
1604 afterwards.
1605 </para>
1606 </glossdef>
1607 </glossentry>
1608
1609 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
1610 <glossdef>
1611 <para>The package description used by package managers.
1612 If not set, <filename>DESCRIPTION</filename> takes
1613 the value of the
1614 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
1615 variable.
1616 </para>
1617 </glossdef>
1618 </glossentry>
1619
1620 <glossentry id='var-DISK_SIGNATURE'><glossterm>DISK_SIGNATURE</glossterm>
1621 <glossdef>
1622 <para>
1623 A 32-bit MBR disk signature used by
1624 <filename>directdisk</filename> images.
1625 </para>
1626
1627 <para>
1628 By default, the signature is set to an automatically
1629 generated random value that allows the OpenEmbedded
1630 build system to create a boot loader.
1631 You can override the signature in the image recipe
1632 by setting <filename>DISK_SIGNATURE</filename> to an
1633 8-digit hex string.
1634 You might want to override
1635 <filename>DISK_SIGNATURE</filename> if you want the disk
1636 signature to remain constant between image builds.
1637 </para>
1638
1639 <para>
1640 When using Linux 3.8 or later, you can use
1641 <filename>DISK_SIGNATURE</filename> to specify the root
1642 by UUID to allow the kernel to locate the root device
1643 even if the device name changes due to differences in
1644 hardware configuration.
1645 By default, <filename>SYSLINUX_ROOT</filename> is set
1646 as follows:
1647 <literallayout class='monospaced'>
1648 SYSLINUX_ROOT = "root=/dev/sda2"
1649 </literallayout>
1650 However, you can change this to locate the root device
1651 using the disk signature instead:
1652 <literallayout class='monospaced'>
1653 SYSLINUX_ROOT = "root=PARTUUID=${DISK_SIGNATURE}-02"
1654 </literallayout>
1655 </para>
1656
1657 <para>
1658 As previously mentioned, it is possible to set the
1659 <filename>DISK_SIGNATURE</filename> variable in your
1660 <filename>local.conf</filename> file to a fixed
1661 value if you do not want <filename>syslinux.cfg</filename>
1662 changing for each build.
1663 You might find this useful when you want to upgrade the
1664 root filesystem on a device without having to recreate or
1665 modify the master boot record.
1666 </para>
1667 </glossdef>
1668 </glossentry>
1669
1670 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
1671 <glossdef>
1672 <para>
1673 The short name of the distribution.
1674 This variable corresponds to a distribution
1675 configuration file whose root name is the same as the
1676 variable's argument and whose filename extension is
1677 <filename>.conf</filename>.
1678 For example, the distribution configuration file for the
1679 Poky distribution is named <filename>poky.conf</filename>
1680 and resides in the
1681 <filename>meta-yocto/conf/distro</filename> directory of
1682 the
1683 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1684 </para>
1685
1686 <para>
1687 Within that <filename>poky.conf</filename> file, the
1688 <filename>DISTRO</filename> variable is set as follows:
1689 <literallayout class='monospaced'>
1690 DISTRO = "poky"
1691 </literallayout>
1692 </para>
1693
1694 <para>
1695 Distribution configuration files are located in a
1696 <filename>conf/distro</filename> directory within the
1697 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
1698 that contains the distribution configuration.
1699 The value for <filename>DISTRO</filename> must not contain
1700 spaces, and is typically all lower-case.
1701 <note>
1702 If the <filename>DISTRO</filename> variable is blank, a set
1703 of default configurations are used, which are specified
1704 within
1705 <filename>meta/conf/distro/defaultsetup.conf</filename>
1706 also in the Source Directory.
1707 </note>
1708 </para>
1709 </glossdef>
1710 </glossentry>
1711
1712 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
1713 <glossdef>
1714 <para>
1715 Specifies a list of distro-specific packages to add to all images.
1716 This variable takes affect through
1717 <filename>packagegroup-base</filename> so the
1718 variable only really applies to the more full-featured
1719 images that include <filename>packagegroup-base</filename>.
1720 You can use this variable to keep distro policy out of
1721 generic images.
1722 As with all other distro variables, you set this variable
1723 in the distro <filename>.conf</filename> file.
1724 </para>
1725 </glossdef>
1726 </glossentry>
1727
1728 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
1729 <glossdef>
1730 <para>
1731 Specifies a list of distro-specific packages to add to all images
1732 if the packages exist.
1733 The packages might not exist or be empty (e.g. kernel modules).
1734 The list of packages are automatically installed but you can
1735 remove them.
1736 </para>
1737 </glossdef>
1738 </glossentry>
1739
1740 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
1741 <glossdef>
1742 <para>
1743 The software support you want in your distribution for
1744 various features.
1745 You define your distribution features in the distribution
1746 configuration file.
1747 </para>
1748
1749 <para>
1750 In most cases, the presence or absence of a feature in
1751 <filename>DISTRO_FEATURES</filename> is translated to the
1752 appropriate option supplied to the configure script
1753 during <filename>do_configure</filename> for recipes that
1754 optionally support the feature.
1755 For example, specifying "x11" in
1756 <filename>DISTRO_FEATURES</filename>, causes
1757 every piece of software built for the target that can
1758 optionally support X11 to have its X11 support enabled.
1759 </para>
1760
1761 <para>
1762 Two more examples are Bluetooth and NFS support.
1763 For a more complete list of features that ships with the
1764 Yocto Project and that you can provide with this variable,
1765 see the
1766 "<link linkend='ref-features-distro'>Distro Features</link>"
1767 section.
1768 </para>
1769 </glossdef>
1770 </glossentry>
1771
1772 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
1773 <glossdef>
1774 <para>Features to be added to
1775 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
1776 if not also present in
1777 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
1778 </para>
1779
1780 <para>
1781 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
1782 It is not intended to be user-configurable.
1783 It is best to just reference the variable to see which distro features are
1784 being backfilled for all distro configurations.
1785 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1786 more information.
1787 </para>
1788 </glossdef>
1789 </glossentry>
1790
1791 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
1792 <glossdef>
1793 <para>Features from
1794 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
1795 that should not be backfilled (i.e. added to
1796 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
1797 during the build.
1798 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
1799 more information.
1800 </para>
1801 </glossdef>
1802 </glossentry>
1803
1804 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
1805 <glossdef>
1806 <para>The long name of the distribution.</para>
1807 </glossdef>
1808 </glossentry>
1809
1810 <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
1811 <glossdef>
1812 <para>Alias names used for the recipe in various Linux distributions.</para>
1813 <para>See the
1814 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling
1815 a Package Name Alias</ulink>" section in the Yocto Project Development
1816 Manual for more information.</para>
1817 </glossdef>
1818 </glossentry>
1819
1820 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
1821 <glossdef>
1822 <para>The version of the distribution.</para>
1823 </glossdef>
1824 </glossentry>
1825
1826 <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
1827 <glossdef>
1828 <para>
1829 This variable lists overrides specific to the current
1830 distribution.
1831 By default, the variable list includes the value of the
1832 <filename><link linkend='var-DISTRO'>DISTRO</link></filename>
1833 variable.
1834 You can extend the variable to apply any variable overrides
1835 you want as part of the distribution and are not
1836 already in <filename>OVERRIDES</filename> through
1837 some other means.
1838 </para>
1839 </glossdef>
1840 </glossentry>
1841
1842 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
1843 <glossdef>
1844 <para>
1845 The central download directory used by the build process to
1846 store downloads.
1847 By default, <filename>DL_DIR</filename> gets files
1848 suitable for mirroring for everything except Git
1849 repositories.
1850 If you want tarballs of Git repositories, use the
1851 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
1852 variable.
1853 </para>
1854
1855 <para>
1856 You can set this directory by defining the
1857 <filename>DL_DIR</filename> variable in the
1858 <filename>conf/local.conf</filename> file.
1859 This directory is self-maintaining and you should not have
1860 to touch it.
1861 By default, the directory is <filename>downloads</filename>
1862 in the
1863 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1864 <literallayout class='monospaced'>
1865 #DL_DIR ?= "${TOPDIR}/downloads"
1866 </literallayout>
1867 To specify a different download directory, simply remove
1868 the comment from the line and provide your directory.
1869 </para>
1870
1871 <para>
1872 During a first build, the system downloads many different
1873 source code tarballs from various upstream projects.
1874 Downloading can take a while, particularly if your network
1875 connection is slow.
1876 Tarballs are all stored in the directory defined by
1877 <filename>DL_DIR</filename> and the build system looks there
1878 first to find source tarballs.
1879 <note>
1880 When wiping and rebuilding, you can preserve this
1881 directory to speed up this part of subsequent
1882 builds.
1883 </note>
1884 </para>
1885
1886 <para>
1887 You can safely share this directory between multiple builds
1888 on the same development machine.
1889 For additional information on how the build process gets
1890 source files when working behind a firewall or proxy server,
1891 see this specific question in the
1892 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
1893 chapter.
1894 </para>
1895 </glossdef>
1896
1897 </glossentry>
1898 </glossdiv>
1899
1900 <glossdiv id='var-glossary-e'><title>E</title>
1901
1902 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
1903 <glossdef>
1904 <para></para>
1905 <para>Variable that controls which locales for
1906 <filename>eglibc</filename> are generated during the
1907 build (useful if the target device has 64Mbytes
1908 of RAM or less).</para>
1909 </glossdef>
1910 </glossentry>
1911
1912 <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
1913 <glossdef>
1914 <para>
1915 Specifies the quality assurance checks whose failures are
1916 reported as errors by the OpenEmbedded build system.
1917 You set this variable in your distribution configuration
1918 file.
1919 For a list of the checks you can control with this variable,
1920 see the
1921 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
1922 section.
1923 </para>
1924 </glossdef>
1925 </glossentry>
1926
1927 <glossentry id='var-ERR_REPORT_DIR'><glossterm>ERR_REPORT_DIR</glossterm>
1928 <glossdef>
1929 <para>
1930 When used with the
1931 <link linkend='ref-classes-report-error'><filename>report-error</filename></link>
1932 class, specifies the path used for storing the debug files
1933 created by the
1934 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
1935 which allows you to submit build errors you encounter to a
1936 central database.
1937 By default, the value of this variable is
1938 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
1939 </para>
1940
1941 <para>
1942 You can set <filename>ERR_REPORT_DIR</filename> to the path
1943 you want the error reporting tool to store the debug files
1944 as follows in your <filename>local.conf</filename> file:
1945 <literallayout class='monospaced'>
1946 ERR_REPORT_DIR = "path"
1947 </literallayout>
1948 </para>
1949 </glossdef>
1950 </glossentry>
1951
1952 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
1953 <glossdef>
1954 <para>
1955 Directs BitBake to exclude a recipe from world builds (i.e.
1956 <filename>bitbake world</filename>).
1957 During world builds, BitBake locates, parses and builds all
1958 recipes found in every layer exposed in the
1959 <filename>bblayers.conf</filename> configuration file.
1960 </para>
1961
1962 <para>
1963 To exclude a recipe from a world build using this variable,
1964 set the variable to "1" in the recipe.
1965 </para>
1966
1967 <note>
1968 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
1969 may still be built during a world build in order to satisfy
1970 dependencies of other recipes.
1971 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
1972 only ensures that the recipe is not explicitly added
1973 to the list of build targets in a world build.
1974 </note>
1975 </glossdef>
1976 </glossentry>
1977
1978 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
1979 <glossdef>
1980 <para>
1981 Used with file and pathnames to create a prefix for a recipe's
1982 version based on the recipe's
1983 <link linkend='var-PE'><filename>PE</filename></link> value.
1984 If <filename>PE</filename> is set and greater than zero for a recipe,
1985 <filename>EXTENDPE</filename> becomes that value (e.g if
1986 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
1987 becomes "1_").
1988 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
1989 zero, <filename>EXTENDPE</filename> becomes "".</para>
1990 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
1991 variable for an example.
1992 </para>
1993 </glossdef>
1994 </glossentry>
1995
1996 <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
1997 <glossdef>
1998 <para>
1999 The full package version specification as it appears on the
2000 final packages produced by a recipe.
2001 The variable's value is normally used to fix a runtime
2002 dependency to the exact same version of another package
2003 in the same recipe:
2004 <literallayout class='monospaced'>
2005 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
2006 </literallayout>
2007 </para>
2008
2009 <para>
2010 The dependency relationships are intended to force the
2011 package manager to upgrade these types of packages in
2012 lock-step.
2013 </para>
2014 </glossdef>
2015 </glossentry>
2016
2017 <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
2018 <glossdef>
2019 <para>
2020 If <filename>externalsrc.bbclass</filename> is inherited,
2021 this variable points to the source tree, which is
2022 outside of the OpenEmbedded build system.
2023 When set, this variable sets the
2024 <link linkend='var-S'><filename>S</filename></link>
2025 variable, which is what the OpenEmbedded build system uses
2026 to locate unpacked recipe source code.
2027 </para>
2028
2029 <para>
2030 For more information on
2031 <filename>externalsrc.bbclass</filename>, see the
2032 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
2033 section.
2034 You can also find information on how to use this variable
2035 in the
2036 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
2037 section in the Yocto Project Development Manual.
2038 </para>
2039 </glossdef>
2040 </glossentry>
2041
2042 <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
2043 <glossdef>
2044 <para>
2045 If <filename>externalsrc.bbclass</filename> is inherited,
2046 this variable points to the directory in which the recipe's
2047 source code is built,
2048 which is outside of the OpenEmbedded build system.
2049 When set, this variable sets the
2050 <link linkend='var-B'><filename>B</filename></link>
2051 variable, which is what the OpenEmbedded build system uses
2052 to locate the Build Directory.
2053 </para>
2054
2055 <para>
2056 For more information on
2057 <filename>externalsrc.bbclass</filename>, see the
2058 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
2059 section.
2060 You can also find information on how to use this variable
2061 in the
2062 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
2063 section in the Yocto Project Development Manual.
2064 </para>
2065 </glossdef>
2066 </glossentry>
2067
2068 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
2069 <glossdef>
2070 <para>
2071 The list of additional features to include in an image.
2072 Typically, you configure this variable in your
2073 <filename>local.conf</filename> file, which is found in the
2074 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2075 Although you can use this variable from within a recipe,
2076 best practices dictate that you do not.
2077 <note>
2078 To enable primary features from within the image
2079 recipe, use the
2080 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
2081 variable.
2082 </note>
2083 </para>
2084
2085 <para>
2086 Here are some examples of features you can add:
2087 <literallayout class='monospaced'>
2088"dbg-pkgs" - Adds -dbg packages for all installed packages
2089 including symbol information for debugging and
2090 profiling.
2091
2092"debug-tweaks" - Makes an image suitable for development.
2093 For example, ssh root access has a blank
2094 password. You should remove this feature
2095 before you produce a production image.
2096
2097"dev-pkgs" - Adds -dev packages for all installed packages.
2098 This is useful if you want to develop against
2099 the libraries in the image.
2100
2101"read-only-rootfs" - Creates an image whose root
2102 filesystem is read-only. See the
2103 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
2104 section in the Yocto Project
2105 Development Manual for more
2106 information
2107
2108"tools-debug" - Adds debugging tools such as gdb and
2109 strace.
2110
2111"tools-profile" - Adds profiling tools such as oprofile,
2112 exmap, lttng and valgrind (x86 only).
2113
2114"tools-sdk" - Adds development tools such as gcc, make,
2115 pkgconfig and so forth.
2116
2117"tools-testapps" - Adds useful testing tools such as
2118 ts_print, aplay, arecord and so
2119 forth.
2120
2121 </literallayout>
2122 </para>
2123
2124 <para>
2125 For a complete list of image features that ships with the
2126 Yocto Project, see the
2127 "<link linkend="ref-features-image">Image Features</link>"
2128 section.
2129 </para>
2130
2131 <para>
2132 For an example that shows how to customize your image by
2133 using this variable, see the
2134 "<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>"
2135 section in the Yocto Project Development Manual.
2136 </para>
2137 </glossdef>
2138 </glossentry>
2139
2140 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
2141 <glossdef>
2142 <para>A list of recipes to build that do not provide packages
2143 for installing into the root filesystem.
2144 </para>
2145 <para>Sometimes a recipe is required to build the final image but is not
2146 needed in the root filesystem.
2147 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
2148 list these recipes and thus specify the dependencies.
2149 A typical example is a required bootloader in a machine configuration.
2150 </para>
2151 <note>
2152 To add packages to the root filesystem, see the various
2153 <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
2154 and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
2155 variables.
2156 </note>
2157 </glossdef>
2158 </glossentry>
2159
2160 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
2161 <glossdef>
2162 <para>Additional <filename>cmake</filename> options.</para>
2163 </glossdef>
2164 </glossentry>
2165
2166 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
2167 <glossdef>
2168 <para>Additional <filename>configure</filename> script options.</para>
2169 </glossdef>
2170 </glossentry>
2171
2172 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
2173 <glossdef>
2174 <para>Additional GNU <filename>make</filename> options.</para>
2175 </glossdef>
2176 </glossentry>
2177
2178 <glossentry id='var-EXTRA_OESCONS'><glossterm>EXTRA_OESCONS</glossterm>
2179 <glossdef>
2180 <para>
2181 When a recipe inherits the
2182 <link linkend='ref-classes-scons'><filename>scons</filename></link>
2183 class, this variable specifies additional configuration
2184 options you want to pass to the
2185 <filename>scons</filename> command line.
2186 </para>
2187 </glossdef>
2188 </glossentry>
2189
2190 <glossentry id='var-EXTRA_QMAKEVARS_POST'><glossterm>EXTRA_QMAKEVARS_POST</glossterm>
2191 <glossdef>
2192 <para>
2193 Configuration variables or options you want to pass to
2194 <filename>qmake</filename>.
2195 Use this variable when the arguments need to be after the
2196 <filename>.pro</filename> file list on the command line.
2197 </para>
2198
2199 <para>
2200 This variable is used with recipes that inherit the
2201 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
2202 class or other classes that inherit
2203 <filename>qmake_base</filename>.
2204 </para>
2205 </glossdef>
2206 </glossentry>
2207
2208 <glossentry id='var-EXTRA_QMAKEVARS_PRE'><glossterm>EXTRA_QMAKEVARS_PRE</glossterm>
2209 <glossdef>
2210 <para>
2211 Configuration variables or options you want to pass to
2212 <filename>qmake</filename>.
2213 Use this variable when the arguments need to be before the
2214 <filename>.pro</filename> file list on the command line.
2215 </para>
2216
2217 <para>
2218 This variable is used with recipes that inherit the
2219 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
2220 class or other classes that inherit
2221 <filename>qmake_base</filename>.
2222 </para>
2223 </glossdef>
2224 </glossentry>
2225
2226 <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm>
2227 <glossdef>
2228 <para>
2229 When a recipe inherits the
2230 <link linkend='ref-classes-extrausers'><filename>extrausers</filename></link>
2231 class, this variable provides image level user and group
2232 operations.
2233 This is a more global method of providing user and group
2234 configuration as compared to using the
2235 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
2236 class, which ties user and group configurations to a
2237 specific recipe.
2238 </para>
2239
2240 <para>
2241 The set list of commands you can configure using the
2242 <filename>EXTRA_USERS_PARAMS</filename> is shown in the
2243 <filename>extrausers</filename> class.
2244 These commands map to the normal Unix commands of the same
2245 names:
2246 <literallayout class='monospaced'>
2247 # EXTRA_USERS_PARAMS = "\
2248 # useradd -p '' tester; \
2249 # groupadd developers; \
2250 # userdel nobody; \
2251 # groupdel -g video; \
2252 # groupmod -g 1020 developers; \
2253 # usermod -s /bin/sh tester; \
2254 # "
2255 </literallayout>
2256 </para>
2257 </glossdef>
2258 </glossentry>
2259
2260 </glossdiv>
2261
2262 <glossdiv id='var-glossary-f'><title>F</title>
2263
2264 <glossentry id='var-FEATURE_PACKAGES'><glossterm>FEATURE_PACKAGES</glossterm>
2265 <glossdef>
2266 <para>
2267 Defines one or more packages to include in an image when
2268 a specific item is included in
2269 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
2270 When setting the value, <filename>FEATURE_PACKAGES</filename>
2271 should have the name of the feature item as an override.
2272 Here is an example:
2273 <literallayout class='monospaced'>
2274 FEATURE_PACKAGES_widget = "package1 package2"
2275 </literallayout>
2276 In this example, if "widget" were added to
2277 <filename>IMAGE_FEATURES</filename>, "package1" and
2278 "package2" would be included in the image.
2279 <note>
2280 Packages installed by features defined through
2281 <filename>FEATURE_PACKAGES</filename> are often package
2282 groups.
2283 While similarly named, you should not confuse the
2284 <filename>FEATURE_PACKAGES</filename> variable with
2285 package groups, which are discussed elsewhere in the
2286 documentation.
2287 </note>
2288 </para>
2289 </glossdef>
2290 </glossentry>
2291
2292 <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm>
2293 <glossdef>
2294 <para>
2295 Points to the base URL of the server and location within
2296 the document-root that provides the metadata and
2297 packages required by OPKG to support runtime package
2298 management of IPK packages.
2299 You set this variable in your
2300 <filename>local.conf</filename> file.
2301 </para>
2302
2303 <para>
2304 Consider the following example:
2305 <literallayout class='monospaced'>
2306 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
2307 </literallayout>
2308 This example assumes you are serving your packages over
2309 HTTP and your databases are located in a directory
2310 named <filename>BOARD-dir</filename>, which is underneath
2311 your HTTP server's document-root.
2312 In this case, the OpenEmbedded build system generates a set
2313 of configuration files for you in your target that work
2314 with the feed.
2315 </para>
2316 </glossdef>
2317 </glossentry>
2318
2319 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
2320 <glossdef>
2321 <para>
2322 The list of directories or files that are placed in packages.
2323 </para>
2324
2325 <para>
2326 To use the <filename>FILES</filename> variable, provide a package name
2327 override that identifies the resulting package.
2328 Then, provide a space-separated list of files or paths that identifies the
2329 files you want included as part of the resulting package.
2330 Here is an example:
2331 <literallayout class='monospaced'>
2332 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
2333 </literallayout>
2334 </para>
2335
2336 <note>
2337 When specifying paths as part of the <filename>FILES</filename> variable,
2338 it is good practice to use appropriate path variables.
2339 For example, use <filename>${sysconfdir}</filename> rather than
2340 <filename>/etc</filename>, or <filename>${bindir}</filename> rather
2341 than <filename>/usr/bin</filename>.
2342 You can find a list of these variables at the top of the
2343 <filename>meta/conf/bitbake.conf</filename> file in the
2344 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2345 </note>
2346
2347 <para>
2348 If some of the files you provide with the <filename>FILES</filename> variable
2349 are editable and you know they should not be
2350 overwritten during the package update process by the Package Management
2351 System (PMS), you can identify these files so that the PMS will not
2352 overwrite them.
2353 See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename>
2354 variable for information on how to identify these files to the PMS.
2355 </para>
2356
2357 </glossdef>
2358 </glossentry>
2359
2360 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
2361 <glossdef>
2362 <para>
2363 Extends the search path the OpenEmbedded build system uses
2364 when looking for files and patches as it processes recipes
2365 and append files.
2366 The default directories BitBake uses when it processes
2367 recipes are initially defined by the
2368 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
2369 variable.
2370 You can extend <filename>FILESPATH</filename> variable
2371 by using <filename>FILESEXTRAPATHS</filename>.
2372 </para>
2373
2374 <para>
2375 Best practices dictate that you accomplish this by using
2376 <filename>FILESEXTRAPATHS</filename> from within a
2377 <filename>.bbappend</filename> file and that you prepend
2378 paths as follows:
2379 <literallayout class='monospaced'>
2380 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
2381 </literallayout>
2382 In the above example, the build system first looks for files
2383 in a directory that has the same name as the corresponding
2384 append file.
2385 <note>
2386 <para>When extending <filename>FILESEXTRAPATHS</filename>,
2387 be sure to use the immediate expansion
2388 (<filename>:=</filename>) operator.
2389 Immediate expansion makes sure that BitBake evaluates
2390 <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
2391 at the time the directive is encountered rather than at
2392 some later time when expansion might result in a
2393 directory that does not contain the files you need.
2394 </para>
2395 <para>Also, include the trailing separating colon
2396 character if you are prepending.
2397 The trailing colon character is necessary because you
2398 are directing BitBake to extend the path by prepending
2399 directories to the search path.</para>
2400 </note>
2401 Here is another common use:
2402 <literallayout class='monospaced'>
2403 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
2404 </literallayout>
2405 In this example, the build system extends the
2406 <filename>FILESPATH</filename> variable to include a
2407 directory named <filename>files</filename> that is in the
2408 same directory as the corresponding append file.
2409 </para>
2410
2411 <para>
2412 Here is a final example that specifically adds three paths:
2413 <literallayout class='monospaced'>
2414 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
2415 </literallayout>
2416 </para>
2417
2418 <para>
2419 By prepending paths in <filename>.bbappend</filename>
2420 files, you allow multiple append files that reside in
2421 different layers but are used for the same recipe to
2422 correctly extend the path.
2423 </para>
2424 </glossdef>
2425 </glossentry>
2426
2427 <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
2428 <glossdef>
2429 <para>
2430 A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
2431 used by the OpenEmbedded build system for creating
2432 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
2433 You can find more information on how overrides are handled
2434 in the BitBake Manual that is located at
2435 <filename>bitbake/doc/manual</filename> in the
2436 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2437 </para>
2438
2439 <para>
2440 By default, the <filename>FILESOVERRIDES</filename>
2441 variable is defined as:
2442 <literallayout class='monospaced'>
2443 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
2444 </literallayout>
2445
2446 <note>
2447 Do not hand-edit the <filename>FILESOVERRIDES</filename>
2448 variable.
2449 The values match up with expected overrides and are
2450 used in an expected manner by the build system.
2451 </note>
2452 </para>
2453 </glossdef>
2454 </glossentry>
2455
2456 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
2457 <glossdef>
2458 <para>
2459 The default set of directories the OpenEmbedded build system
2460 uses when searching for patches and files.
2461 During the build process, BitBake searches each directory in
2462 <filename>FILESPATH</filename> in the specified order when
2463 looking for files and patches specified by each
2464 <filename>file://</filename> URI in a recipe.
2465 </para>
2466
2467 <para>
2468 The default value for the <filename>FILESPATH</filename>
2469 variable is defined in the <filename>base.bbclass</filename>
2470 class found in <filename>meta/classes</filename> in the
2471 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
2472 <literallayout class='monospaced'>
2473 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
2474 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
2475 </literallayout>
2476 <note>
2477 Do not hand-edit the <filename>FILESPATH</filename>
2478 variable.
2479 If you want the build system to look in directories
2480 other than the defaults, extend the
2481 <filename>FILESPATH</filename> variable by using the
2482 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
2483 variable.
2484 </note>
2485 Be aware that the default <filename>FILESPATH</filename>
2486 directories do not map to directories in custom layers
2487 where append files (<filename>.bbappend</filename>)
2488 are used.
2489 If you want the build system to find patches or files
2490 that reside with your append files, you need to extend
2491 the <filename>FILESPATH</filename> variable by using
2492 the
2493 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
2494 variable.
2495 </para>
2496 </glossdef>
2497 </glossentry>
2498
2499 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
2500 <glossdef>
2501 <para>Allows you to define your own file permissions settings table as part of
2502 your configuration for the packaging process.
2503 For example, suppose you need a consistent set of custom permissions for
2504 a set of groups and users across an entire work project.
2505 It is best to do this in the packages themselves but this is not always
2506 possible.
2507 </para>
2508 <para>
2509 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
2510 is located in the <filename>meta/files</filename> folder in the
2511 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2512 If you create your own file permissions setting table, you should place it in your
2513 layer or the distro's layer.
2514 </para>
2515 <para>
2516 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
2517 <filename>conf/local.conf</filename> file, which is found in the
2518 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to
2519 point to your custom <filename>fs-perms.txt</filename>.
2520 You can specify more than a single file permissions setting table.
2521 The paths you specify to these files must be defined within the
2522 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
2523 </para>
2524 <para>
2525 For guidance on how to create your own file permissions settings table file,
2526 examine the existing <filename>fs-perms.txt</filename>.
2527 </para>
2528 </glossdef>
2529 </glossentry>
2530
2531 <glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm>
2532 <glossdef>
2533 <para>
2534 When a recipe inherits the
2535 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
2536 class, this variable identifies packages containing font
2537 files that need to be cached by Fontconfig.
2538 By default, the <filename>fontcache</filename> class assumes
2539 that fonts are in the recipe's main package
2540 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
2541 Use this variable if fonts you need are in a package
2542 other than that main package.
2543 </para>
2544 </glossdef>
2545 </glossentry>
2546
2547 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
2548 <glossdef>
2549 <para>
2550 The options to pass in
2551 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
2552 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
2553 when compiling an optimized system.
2554 This variable defaults to
2555 "-O2 -pipe ${DEBUG_FLAGS}".
2556 </para>
2557 </glossdef>
2558 </glossentry>
2559 </glossdiv>
2560
2561 <glossdiv id='var-glossary-g'><title>G</title>
2562
2563 <glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm>
2564 <glossdef>
2565 <para>
2566 When a recipe inherits the
2567 <filename>useradd</filename> class, this variable
2568 specifies for a package what parameters should be passed
2569 to the <filename>groupadd</filename> command
2570 if you wish to add a group to the system when the package
2571 is installed.
2572 </para>
2573
2574 <para>
2575 Here is an example from the <filename>dbus</filename>
2576 recipe:
2577 <literallayout class='monospaced'>
2578 GROUPADD_PARAM_${PN} = "-r netdev"
2579 </literallayout>
2580 For information on the standard Linux shell command
2581 <filename>groupadd</filename>, see
2582 <ulink url='http://linux.die.net/man/8/groupadd'></ulink>.
2583 </para>
2584 </glossdef>
2585 </glossentry>
2586
2587 <glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm>
2588 <glossdef>
2589 <para>
2590 When a recipe inherits the
2591 <filename>useradd</filename> class, this variable
2592 specifies for a package what parameters should be passed
2593 to the <filename>groupmems</filename> command
2594 if you wish to modify the members of a group when the
2595 package is installed.
2596 </para>
2597
2598 <para>
2599 For information on the standard Linux shell command
2600 <filename>groupmems</filename>, see
2601 <ulink url='http://linux.die.net/man/8/groupmems'></ulink>.
2602 </para>
2603 </glossdef>
2604 </glossentry>
2605
2606 <glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm>
2607 <glossdef>
2608 <para>
2609 Configures the GNU GRand Unified Bootloader (GRUB) to have
2610 graphics and serial in the boot menu.
2611 Set this variable to "1" in your
2612 <filename>local.conf</filename> or distribution
2613 configuration file to enable graphics and serial
2614 in the menu.
2615 </para>
2616
2617 <para>
2618 See the
2619 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2620 class for more information on how this variable is used.
2621 </para>
2622 </glossdef>
2623 </glossentry>
2624
2625 <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm>
2626 <glossdef>
2627 <para>
2628 Additional options to add to the GNU GRand Unified
2629 Bootloader (GRUB) configuration.
2630 Use a semi-colon character (<filename>;</filename>) to
2631 separate multiple options.
2632 </para>
2633
2634 <para>
2635 The <filename>GRUB_OPTS</filename> variable is optional.
2636 See the
2637 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2638 class for more information on how this variable is used.
2639 </para>
2640 </glossdef>
2641 </glossentry>
2642
2643 <glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm>
2644 <glossdef>
2645 <para>
2646 Specifies the timeout before executing the default
2647 <filename>LABEL</filename> in the GNU GRand Unified
2648 Bootloader (GRUB).
2649 </para>
2650
2651 <para>
2652 The <filename>GRUB_TIMEOUT</filename> variable is optional.
2653 See the
2654 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2655 class for more information on how this variable is used.
2656 </para>
2657 </glossdef>
2658 </glossentry>
2659
2660 <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm>
2661 <glossdef>
2662 <para>
2663 For recipes that inherit the
2664 <link linkend='ref-classes-gtk-immodules-cache'><filename>gtk-immodules-cache</filename></link>
2665 class, this variable specifies the packages that contain the
2666 GTK+ input method modules being installed when the modules
2667 are in packages other than the main package.
2668 </para>
2669 </glossdef>
2670 </glossentry>
2671
2672 </glossdiv>
2673
2674 <glossdiv id='var-glossary-h'><title>H</title>
2675
2676 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
2677 <glossdef>
2678 <para>Website where more information about the software the recipe is building
2679 can be found.</para>
2680 </glossdef>
2681 </glossentry>
2682
2683 <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
2684 <glossdef>
2685 <para>
2686 Specifies the system, including the architecture and the
2687 operating system, for with the build is occurring
2688 in the context of the current
2689 recipe.
2690 The OpenEmbedded build system automatically sets this
2691 variable.
2692 You do not need to set the variable yourself.
2693 </para>
2694
2695 <para>
2696 Here are two examples:
2697 <itemizedlist>
2698 <listitem><para>Given a native recipe on a 32-bit
2699 x86 machine running Linux, the value is
2700 "i686-linux".
2701 </para></listitem>
2702 <listitem><para>Given a recipe being built for a
2703 little-endian MIPS target running Linux,
2704 the value might be "mipsel-linux".
2705 </para></listitem>
2706 </itemizedlist>
2707 </para>
2708 </glossdef>
2709 </glossentry>
2710
2711 </glossdiv>
2712
2713 <glossdiv id='var-glossary-i'><title>I</title>
2714
2715 <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm>
2716 <glossdef>
2717 <para>
2718 Disables or enables the <filename>icecc</filename>
2719 (Icecream) function.
2720 For more information on this function and best practices
2721 for using this variable, see the
2722 "<link linkend='ref-classes-icecc'><filename>icecc.bbclass</filename></link>"
2723 section.
2724 </para>
2725
2726 <para>
2727 Setting this variable to "1" in your
2728 <filename>local.conf</filename> disables the function:
2729 <literallayout class='monospaced'>
2730 ICECC_DISABLED ??= "1"
2731 </literallayout>
2732 To enable the function, set the variable as follows:
2733 <literallayout class='monospaced'>
2734 ICECC_DISABLED = ""
2735 </literallayout>
2736 </para>
2737 </glossdef>
2738 </glossentry>
2739
2740 <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm>
2741 <glossdef>
2742 <para>
2743 Points to the <filename>icecc-create-env</filename> script
2744 that you provide.
2745 This variable is used by the
2746 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2747 class.
2748 You set this variable in your
2749 <filename>local.conf</filename> file.
2750 </para>
2751
2752 <para>
2753 If you do not point to a script that you provide, the
2754 OpenEmbedded build system uses the default script provided
2755 by the <filename>icecc-create-env.bb</filename> recipe,
2756 which is a modified version and not the one that comes with
2757 <filename>icecc</filename>.
2758 </para>
2759 </glossdef>
2760 </glossentry>
2761
2762 <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm>
2763 <glossdef>
2764 <para>
2765 Extra options passed to the <filename>make</filename>
2766 command during the <filename>do_compile</filename> task
2767 that specify parallel compilation.
2768 This variable usually takes the form of
2769 <filename>-j 4</filename>, where the number
2770 represents the maximum number of parallel threads
2771 <filename>make</filename> can run.
2772 <note>
2773 The options passed affect builds on all enabled
2774 machines on the network, which are machines running the
2775 <filename>iceccd</filename> daemon.
2776 </note>
2777 </para>
2778
2779 <para>
2780 If your enabled machines support multiple cores,
2781 coming up with the maximum number of parallel threads
2782 that gives you the best performance could take some
2783 experimentation since machine speed, network lag,
2784 available memory, and existing machine loads can all
2785 affect build time.
2786 Consequently, unlike the
2787 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
2788 variable, there is no rule-of-thumb for setting
2789 <filename>ICECC_PARALLEL_MAKE</filename> to achieve
2790 optimal performance.
2791 </para>
2792
2793 <para>
2794 If you do not set <filename>ICECC_PARALLEL_MAKE</filename>,
2795 the build system does not use it (i.e. the system does
2796 not detect and assign the number of cores as is done with
2797 <filename>PARALLEL_MAKE</filename>).
2798 </para>
2799 </glossdef>
2800 </glossentry>
2801
2802 <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm>
2803 <glossdef>
2804 <para>
2805 The location of the <filename>icecc</filename> binary.
2806 You can set this variable in your
2807 <filename>local.conf</filename> file.
2808 If your <filename>local.conf</filename> file does not define
2809 this variable, the
2810 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2811 class attempts to define it by locating
2812 <filename>icecc</filename> using <filename>which</filename>.
2813 </para>
2814 </glossdef>
2815 </glossentry>
2816
2817 <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm>
2818 <glossdef>
2819 <para>
2820 Identifies user classes that you do not want the
2821 Icecream distributed compile support to consider.
2822 This variable is used by the
2823 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2824 class.
2825 You set this variable in your
2826 <filename>local.conf</filename> file.
2827 </para>
2828
2829 <para>
2830 When you list classes using this variable, you are
2831 "blacklisting" them from distributed compilation across
2832 remote hosts.
2833 Any classes you list will be distributed and compiled
2834 locally.
2835 </para>
2836 </glossdef>
2837 </glossentry>
2838
2839 <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm>
2840 <glossdef>
2841 <para>
2842 Identifies user recipes that you do not want the
2843 Icecream distributed compile support to consider.
2844 This variable is used by the
2845 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2846 class.
2847 You set this variable in your
2848 <filename>local.conf</filename> file.
2849 </para>
2850
2851 <para>
2852 When you list packages using this variable, you are
2853 "blacklisting" them from distributed compilation across
2854 remote hosts.
2855 Any packages you list will be distributed and compiled
2856 locally.
2857 </para>
2858 </glossdef>
2859 </glossentry>
2860
2861 <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm>
2862 <glossdef>
2863 <para>
2864 Identifies user recipes that use an empty
2865 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
2866 variable that you want to force remote distributed
2867 compilation on using the Icecream distributed compile
2868 support.
2869 This variable is used by the
2870 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2871 class.
2872 You set this variable in your
2873 <filename>local.conf</filename> file.
2874 </para>
2875 </glossdef>
2876 </glossentry>
2877
2878 <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
2879 <glossdef>
2880 <para>
2881 The base name of image output files.
2882 This variable defaults to the recipe name
2883 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
2884 </para>
2885 </glossdef>
2886 </glossentry>
2887
2888 <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
2889 <glossdef>
2890 <para>
2891 A list of classes that all images should inherit.
2892 You typically use this variable to specify the list of
2893 classes that register the different types of images
2894 the OpenEmbedded build system creates.
2895 </para>
2896
2897 <para>
2898 The default value for <filename>IMAGE_CLASSES</filename> is
2899 <filename>image_types</filename>.
2900 You can set this variable in your
2901 <filename>local.conf</filename> or in a distribution
2902 configuration file.
2903 </para>
2904
2905 <para>
2906 For more information, see
2907 <filename>meta/classes/image_types.bbclass</filename> in the
2908 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2909 </para>
2910 </glossdef>
2911 </glossentry>
2912
2913 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
2914 <glossdef>
2915 <para>
2916 The primary list of features to include in an image.
2917 Typically, you configure this variable in an image recipe.
2918 Although you can use this variable from your
2919 <filename>local.conf</filename> file, which is found in the
2920 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
2921 best practices dictate that you do not.
2922 <note>
2923 To enable extra features from outside the image recipe,
2924 use the
2925 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
2926 </note>
2927 For a list of image features that ships with the Yocto
2928 Project, see the
2929 "<link linkend="ref-features-image">Image Features</link>"
2930 section.
2931 </para>
2932
2933 <para>
2934 For an example that shows how to customize your image by
2935 using this variable, see the
2936 "<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>"
2937 section in the Yocto Project Development Manual.
2938 </para>
2939 </glossdef>
2940 </glossentry>
2941
2942 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
2943 <glossdef>
2944 <para>
2945 Specifies the formats the OpenEmbedded build system uses
2946 during the build when creating the root filesystem.
2947 For example, setting <filename>IMAGE_FSTYPES</filename>
2948 as follows causes the build system to create root
2949 filesystems using two formats: <filename>.ext3</filename>
2950 and <filename>.tar.bz2</filename>:
2951 <literallayout class='monospaced'>
2952 IMAGE_FSTYPES = "ext3 tar.bz2"
2953 </literallayout>
2954 For the complete list of supported image formats from which
2955 you can choose, see
2956 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
2957 </para>
2958
2959 <note>
2960 If you add "live" to <filename>IMAGE_FSTYPES</filename>
2961 inside an image recipe, be sure that you do so prior to the
2962 "inherit image" line of the recipe or the live image will
2963 not build.
2964 </note>
2965
2966 <note>
2967 Due to the way this variable is processed, it is not
2968 possible to update its contents using
2969 <filename>_append</filename> or
2970 <filename>_prepend</filename>. To add one or more
2971 additional options to this variable the
2972 <filename>+=</filename> operator must be used.
2973 </note>
2974 </glossdef>
2975 </glossentry>
2976
2977 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
2978 <glossdef>
2979 <para>
2980 Specifies the packages to install into an image.
2981 The <filename>IMAGE_INSTALL</filename> variable is a
2982 mechanism for an image recipe and you should use it
2983 with care to avoid ordering issues.
2984 <note>
2985 When working with an
2986 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
2987 image, do not use the <filename>IMAGE_INSTALL</filename>
2988 variable to specify packages for installation.
2989 Instead, use the
2990 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
2991 variable, which allows the initial RAM disk (initramfs)
2992 recipe to use a fixed set of packages and not be
2993 affected by <filename>IMAGE_INSTALL</filename>.
2994 </note>
2995 </para>
2996
2997 <para>
2998 Image recipes set <filename>IMAGE_INSTALL</filename>
2999 to specify the packages to install into an image through
3000 <filename>image.bbclass</filename>.
3001 Additionally, "helper" classes exist, such as
3002 <filename>core-image.bbclass</filename>, that can take
3003 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
3004 lists and turn these into auto-generated entries in
3005 <filename>IMAGE_INSTALL</filename> in addition to its
3006 default contents.
3007 </para>
3008
3009 <para>
3010 Using <filename>IMAGE_INSTALL</filename> with the
3011 <filename>+=</filename> operator from the
3012 <filename>/conf/local.conf</filename> file or from within
3013 an image recipe is not recommended as it can cause ordering
3014 issues.
3015 Since <filename>core-image.bbclass</filename> sets
3016 <filename>IMAGE_INSTALL</filename> to a default value using
3017 the <filename>?=</filename> operator, using a
3018 <filename>+=</filename> operation against
3019 <filename>IMAGE_INSTALL</filename> will result in
3020 unexpected behavior when used in
3021 <filename>conf/local.conf</filename>.
3022 Furthermore, the same operation from within an image
3023 recipe may or may not succeed depending on the specific
3024 situation.
3025 In both these cases, the behavior is contrary to how most
3026 users expect the <filename>+=</filename> operator to work.
3027 </para>
3028
3029 <para>
3030 When you use this variable, it is best to use it as follows:
3031 <literallayout class='monospaced'>
3032 IMAGE_INSTALL_append = " package-name"
3033 </literallayout>
3034 Be sure to include the space between the quotation character
3035 and the start of the package name or names.
3036 </para>
3037 </glossdef>
3038 </glossentry>
3039
3040 <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
3041 <glossdef>
3042 <para>
3043 Specifies the list of locales to install into the image
3044 during the root filesystem construction process.
3045 The OpenEmbedded build system automatically splits locale
3046 files, which are used for localization, into separate
3047 packages.
3048 Setting the <filename>IMAGE_LINGUAS</filename> variable
3049 ensures that any locale packages that correspond to packages
3050 already selected for installation into the image are also
3051 installed.
3052 Here is an example:
3053 <literallayout class='monospaced'>
3054 IMAGE_LINGUAS = "pt-br de-de"
3055 </literallayout>
3056 In this example, the build system ensures any Brazilian
3057 Portuguese and German locale files that correspond to
3058 packages in the image are installed (i.e.
3059 <filename>*-locale-pt-br</filename>
3060 and <filename>*-locale-de-de</filename> as well as
3061 <filename>*-locale-pt</filename>
3062 and <filename>*-locale-de</filename>, since some software
3063 packages only provide locale files by language and not by
3064 country-specific language).
3065 </para>
3066 </glossdef>
3067 </glossentry>
3068
3069 <glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm>
3070 <glossdef>
3071 <para>
3072 The manifest file for the image.
3073 This file lists all the installed packages that make up
3074 the image.
3075 The file contains package information on a line-per-package
3076 basis as follows:
3077 <literallayout class='monospaced'>
3078 &lt;packagename&gt; &lt;packagearch&gt; &lt;version&gt;
3079 </literallayout>
3080 </para>
3081
3082 <para>
3083 The
3084 <link linkend='ref-classes-image'><filename>image</filename></link>
3085 class defines the manifest file as follows:
3086 <literallayout class='monospaced'>
3087 IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"
3088 </literallayout>
3089 The location is derived using the
3090 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
3091 and
3092 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>
3093 variables.
3094 You can find information on how the image
3095 is created in the
3096 "<link linkend='image-generation-dev-environment'>Image Generation</link>"
3097 section.
3098 </para>
3099 </glossdef>
3100 </glossentry>
3101
3102 <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
3103 <glossdef>
3104 <para>
3105 The name of the output image files minus the extension.
3106 This variable is derived using the
3107 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
3108 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
3109 and
3110 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
3111 variables:
3112 <literallayout class='monospaced'>
3113 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
3114 </literallayout>
3115 </para>
3116 </glossdef>
3117 </glossentry>
3118
3119 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
3120 <glossdef>
3121 <para>
3122 Defines a multiplier that the build system applies to the initial image
3123 size for cases when the multiplier times the returned disk usage value
3124 for the image is greater than the sum of
3125 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
3126 and
3127 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
3128 The result of the multiplier applied to the initial image size creates
3129 free disk space in the image as overhead.
3130 By default, the build process uses a multiplier of 1.3 for this variable.
3131 This default value results in 30% free disk space added to the image when this
3132 method is used to determine the final generated image size.
3133 You should be aware that post install scripts and the package management
3134 system uses disk space inside this overhead area.
3135 Consequently, the multiplier does not produce an image with
3136 all the theoretical free disk space.
3137 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
3138 for information on how the build system determines the overall image size.
3139 </para>
3140
3141 <para>
3142 The default 30% free disk space typically gives the image enough room to boot
3143 and allows for basic post installs while still leaving a small amount of
3144 free disk space.
3145 If 30% free space is inadequate, you can increase the default value.
3146 For example, the following setting gives you 50% free space added to the image:
3147 <literallayout class='monospaced'>
3148 IMAGE_OVERHEAD_FACTOR = "1.5"
3149 </literallayout>
3150 </para>
3151
3152 <para>
3153 Alternatively, you can ensure a specific amount of free disk space is added
3154 to the image by using the
3155 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
3156 variable.
3157 </para>
3158 </glossdef>
3159 </glossentry>
3160
3161 <glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm>
3162 <glossdef>
3163 <para>
3164 Defines the package type (DEB, RPM, IPK, or TAR) used
3165 by the OpenEmbedded build system.
3166 The variable is defined appropriately by the
3167 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
3168 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
3169 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
3170 or
3171 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
3172 class.
3173 </para>
3174
3175 <para>
3176 The
3177 <link linkend='ref-classes-populate-sdk-*'><filename>package_sdk_base</filename></link>
3178 and
3179 <link linkend='ref-classes-image'><filename>image</filename></link>
3180 classes use the <filename>IMAGE_PKGTYPE</filename> for
3181 packaging up images and SDKs.
3182 </para>
3183
3184 <para>
3185 You should not set the <filename>IMAGE_PKGTYPE</filename>
3186 manually.
3187 Rather, the variable is set indirectly through the
3188 appropriate
3189 <link linkend='ref-classes-package'><filename>package_*</filename></link>
3190 class using the
3191 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3192 variable.
3193 The OpenEmbedded build system uses the first package type
3194 (e.g. DEB, RPM, or IPK) that appears with the variable
3195 <note>
3196 Files using the <filename>.tar</filename> format are
3197 never used as a substitute packaging format for DEB,
3198 RPM, and IPK formatted files for your image or SDK.
3199 </note>
3200 </para>
3201 </glossdef>
3202 </glossentry>
3203
3204 <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
3205 <glossdef>
3206 <para>
3207 Added by classes to run post processing commands once the
3208 OpenEmbedded build system has created the image.
3209 You can specify shell commands separated by semicolons:
3210 <literallayout class='monospaced'>
3211 IMAGE_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
3212 </literallayout>
3213 If you need to pass the path to the root filesystem within
3214 the command, you can use
3215 <filename>${IMAGE_ROOTFS}</filename>, which points to
3216 the root filesystem image.
3217 </para>
3218 </glossdef>
3219 </glossentry>
3220
3221 <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
3222 <glossdef>
3223 <para>
3224 The location of the root filesystem while it is under
3225 construction (i.e. during <filename>do_rootfs</filename>).
3226 This variable is not configurable.
3227 Do not change it.
3228 </para>
3229 </glossdef>
3230 </glossentry>
3231
3232 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
3233 <glossdef>
3234 <para>
3235 Defines additional free disk space created in the image in Kbytes.
3236 By default, this variable is set to "0".
3237 This free disk space is added to the image after the build system determines
3238 the image size as described in
3239 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
3240 </para>
3241
3242 <para>
3243 This variable is particularly useful when you want to ensure that a
3244 specific amount of free disk space is available on a device after an image
3245 is installed and running.
3246 For example, to be sure 5 Gbytes of free disk space is available, set the
3247 variable as follows:
3248 <literallayout class='monospaced'>
3249 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
3250 </literallayout>
3251 </para>
3252
3253 <para>
3254 For example, the Yocto Project Build Appliance specifically requests 40 Gbytes
3255 of extra space with the line:
3256 <literallayout class='monospaced'>
3257 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
3258 </literallayout>
3259 </para>
3260 </glossdef>
3261 </glossentry>
3262
3263 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
3264 <glossdef>
3265 <para>
3266 Defines the size in Kbytes for the generated image.
3267 The OpenEmbedded build system determines the final size for the generated
3268 image using an algorithm that takes into account the initial disk space used
3269 for the generated image, a requested size for the image, and requested
3270 additional free disk space to be added to the image.
3271 Programatically, the build system determines the final size of the
3272 generated image as follows:
3273 <literallayout class='monospaced'>
3274 if (image-du * overhead) &lt; rootfs-size:
3275 internal-rootfs-size = rootfs-size + xspace
3276 else:
3277 internal-rootfs-size = (image-du * overhead) + xspace
3278
3279 where:
3280
3281 image-du = Returned value of the du command on
3282 the image.
3283
3284 overhead = IMAGE_OVERHEAD_FACTOR
3285
3286 rootfs-size = IMAGE_ROOTFS_SIZE
3287
3288 internal-rootfs-size = Initial root filesystem
3289 size before any modifications.
3290
3291 xspace = IMAGE_ROOTFS_EXTRA_SPACE
3292 </literallayout>
3293 See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
3294 and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
3295 variables for related information.
3296<!-- In the above example, <filename>overhead</filename> is defined by the
3297 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
3298 variable, <filename>xspace</filename> is defined by the
3299 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
3300 variable, and <filename>du</filename> is the results of the disk usage command
3301 on the initially generated image. -->
3302 </para>
3303 </glossdef>
3304 </glossentry>
3305
3306 <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm>
3307 <glossdef>
3308 <para>
3309 Specifies a dependency from one image type on another.
3310 Here is an example from the
3311 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
3312 class:
3313 <literallayout class='monospaced'>
3314 IMAGE_TYPEDEP_live = "ext3"
3315 </literallayout>
3316 In the previous example, the variable ensures that when
3317 "live" is listed with the
3318 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
3319 variable, the OpenEmbedded build system produces an
3320 <filename>ext3</filename> image first since one of the
3321 components of the live
3322 image is an <filename>ext3</filename>
3323 formatted partition containing the root
3324 filesystem.
3325 </para>
3326 </glossdef>
3327 </glossentry>
3328
3329 <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
3330 <glossdef>
3331 <para>
3332 Specifies the complete list of supported image types
3333 by default:
3334 <literallayout class='monospaced'>
3335 jffs2
3336 jffs2.sum
3337 cramfs
3338 ext2
3339 ext2.gz
3340 ext2.bz2
3341 ext3
3342 ext3.gz
3343 ext2.lzma
3344 btrfs
3345 live
3346 squashfs
3347 squashfs-xz
3348 ubi
3349 ubifs
3350 tar
3351 tar.gz
3352 tar.bz2
3353 tar.xz
3354 cpio
3355 cpio.gz
3356 cpio.xz
3357 cpio.lzma
3358 vmdk
3359 elf
3360 </literallayout>
3361 For more information on how these types of images, see
3362 <filename>meta/classes/image_types*.bbclass</filename>
3363 in the
3364 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
3365 </para>
3366 </glossdef>
3367 </glossentry>
3368
3369 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
3370 <glossdef>
3371 <para>Helps define the recipe revision for recipes that share
3372 a common <filename>include</filename> file.
3373 You can think of this variable as part of the recipe revision
3374 as set from within an include file.</para>
3375 <para>Suppose, for example, you have a set of recipes that
3376 are used across several projects.
3377 And, within each of those recipes the revision
3378 (its <link linkend='var-PR'><filename>PR</filename></link>
3379 value) is set accordingly.
3380 In this case, when the revision of those recipes changes,
3381 the burden is on you to find all those recipes and
3382 be sure that they get changed to reflect the updated
3383 version of the recipe.
3384 In this scenario, it can get complicated when recipes
3385 that are used in many places and provide common functionality
3386 are upgraded to a new revision.</para>
3387 <para>A more efficient way of dealing with this situation is
3388 to set the <filename>INC_PR</filename> variable inside
3389 the <filename>include</filename> files that the recipes
3390 share and then expand the <filename>INC_PR</filename>
3391 variable within the recipes to help
3392 define the recipe revision.
3393 </para>
3394 <para>
3395 The following provides an example that shows how to use
3396 the <filename>INC_PR</filename> variable
3397 given a common <filename>include</filename> file that
3398 defines the variable.
3399