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.xml8417
1 files changed, 8417 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
new file mode 100644
index 0000000000..71369ab0a2
--- /dev/null
+++ b/documentation/ref-manual/ref-variables.xml
@@ -0,0 +1,8417 @@
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
2435 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake Manual</ulink>.
2436 </para>
2437
2438 <para>
2439 By default, the <filename>FILESOVERRIDES</filename>
2440 variable is defined as:
2441 <literallayout class='monospaced'>
2442 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
2443 </literallayout>
2444
2445 <note>
2446 Do not hand-edit the <filename>FILESOVERRIDES</filename>
2447 variable.
2448 The values match up with expected overrides and are
2449 used in an expected manner by the build system.
2450 </note>
2451 </para>
2452 </glossdef>
2453 </glossentry>
2454
2455 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
2456 <glossdef>
2457 <para>
2458 The default set of directories the OpenEmbedded build system
2459 uses when searching for patches and files.
2460 During the build process, BitBake searches each directory in
2461 <filename>FILESPATH</filename> in the specified order when
2462 looking for files and patches specified by each
2463 <filename>file://</filename> URI in a recipe.
2464 </para>
2465
2466 <para>
2467 The default value for the <filename>FILESPATH</filename>
2468 variable is defined in the <filename>base.bbclass</filename>
2469 class found in <filename>meta/classes</filename> in the
2470 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
2471 <literallayout class='monospaced'>
2472 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
2473 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
2474 </literallayout>
2475 <note>
2476 Do not hand-edit the <filename>FILESPATH</filename>
2477 variable.
2478 If you want the build system to look in directories
2479 other than the defaults, extend the
2480 <filename>FILESPATH</filename> variable by using the
2481 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
2482 variable.
2483 </note>
2484 Be aware that the default <filename>FILESPATH</filename>
2485 directories do not map to directories in custom layers
2486 where append files (<filename>.bbappend</filename>)
2487 are used.
2488 If you want the build system to find patches or files
2489 that reside with your append files, you need to extend
2490 the <filename>FILESPATH</filename> variable by using
2491 the
2492 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
2493 variable.
2494 </para>
2495 </glossdef>
2496 </glossentry>
2497
2498 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
2499 <glossdef>
2500 <para>Allows you to define your own file permissions settings table as part of
2501 your configuration for the packaging process.
2502 For example, suppose you need a consistent set of custom permissions for
2503 a set of groups and users across an entire work project.
2504 It is best to do this in the packages themselves but this is not always
2505 possible.
2506 </para>
2507 <para>
2508 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
2509 is located in the <filename>meta/files</filename> folder in the
2510 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2511 If you create your own file permissions setting table, you should place it in your
2512 layer or the distro's layer.
2513 </para>
2514 <para>
2515 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
2516 <filename>conf/local.conf</filename> file, which is found in the
2517 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to
2518 point to your custom <filename>fs-perms.txt</filename>.
2519 You can specify more than a single file permissions setting table.
2520 The paths you specify to these files must be defined within the
2521 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
2522 </para>
2523 <para>
2524 For guidance on how to create your own file permissions settings table file,
2525 examine the existing <filename>fs-perms.txt</filename>.
2526 </para>
2527 </glossdef>
2528 </glossentry>
2529
2530 <glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm>
2531 <glossdef>
2532 <para>
2533 When a recipe inherits the
2534 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
2535 class, this variable identifies packages containing font
2536 files that need to be cached by Fontconfig.
2537 By default, the <filename>fontcache</filename> class assumes
2538 that fonts are in the recipe's main package
2539 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
2540 Use this variable if fonts you need are in a package
2541 other than that main package.
2542 </para>
2543 </glossdef>
2544 </glossentry>
2545
2546 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
2547 <glossdef>
2548 <para>
2549 The options to pass in
2550 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
2551 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
2552 when compiling an optimized system.
2553 This variable defaults to
2554 "-O2 -pipe ${DEBUG_FLAGS}".
2555 </para>
2556 </glossdef>
2557 </glossentry>
2558 </glossdiv>
2559
2560 <glossdiv id='var-glossary-g'><title>G</title>
2561
2562 <glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm>
2563 <glossdef>
2564 <para>
2565 When a recipe inherits the
2566 <filename>useradd</filename> class, this variable
2567 specifies for a package what parameters should be passed
2568 to the <filename>groupadd</filename> command
2569 if you wish to add a group to the system when the package
2570 is installed.
2571 </para>
2572
2573 <para>
2574 Here is an example from the <filename>dbus</filename>
2575 recipe:
2576 <literallayout class='monospaced'>
2577 GROUPADD_PARAM_${PN} = "-r netdev"
2578 </literallayout>
2579 For information on the standard Linux shell command
2580 <filename>groupadd</filename>, see
2581 <ulink url='http://linux.die.net/man/8/groupadd'></ulink>.
2582 </para>
2583 </glossdef>
2584 </glossentry>
2585
2586 <glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm>
2587 <glossdef>
2588 <para>
2589 When a recipe inherits the
2590 <filename>useradd</filename> class, this variable
2591 specifies for a package what parameters should be passed
2592 to the <filename>groupmems</filename> command
2593 if you wish to modify the members of a group when the
2594 package is installed.
2595 </para>
2596
2597 <para>
2598 For information on the standard Linux shell command
2599 <filename>groupmems</filename>, see
2600 <ulink url='http://linux.die.net/man/8/groupmems'></ulink>.
2601 </para>
2602 </glossdef>
2603 </glossentry>
2604
2605 <glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm>
2606 <glossdef>
2607 <para>
2608 Configures the GNU GRand Unified Bootloader (GRUB) to have
2609 graphics and serial in the boot menu.
2610 Set this variable to "1" in your
2611 <filename>local.conf</filename> or distribution
2612 configuration file to enable graphics and serial
2613 in the menu.
2614 </para>
2615
2616 <para>
2617 See the
2618 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2619 class for more information on how this variable is used.
2620 </para>
2621 </glossdef>
2622 </glossentry>
2623
2624 <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm>
2625 <glossdef>
2626 <para>
2627 Additional options to add to the GNU GRand Unified
2628 Bootloader (GRUB) configuration.
2629 Use a semi-colon character (<filename>;</filename>) to
2630 separate multiple options.
2631 </para>
2632
2633 <para>
2634 The <filename>GRUB_OPTS</filename> variable is optional.
2635 See the
2636 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2637 class for more information on how this variable is used.
2638 </para>
2639 </glossdef>
2640 </glossentry>
2641
2642 <glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm>
2643 <glossdef>
2644 <para>
2645 Specifies the timeout before executing the default
2646 <filename>LABEL</filename> in the GNU GRand Unified
2647 Bootloader (GRUB).
2648 </para>
2649
2650 <para>
2651 The <filename>GRUB_TIMEOUT</filename> variable is optional.
2652 See the
2653 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2654 class for more information on how this variable is used.
2655 </para>
2656 </glossdef>
2657 </glossentry>
2658
2659 <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm>
2660 <glossdef>
2661 <para>
2662 For recipes that inherit the
2663 <link linkend='ref-classes-gtk-immodules-cache'><filename>gtk-immodules-cache</filename></link>
2664 class, this variable specifies the packages that contain the
2665 GTK+ input method modules being installed when the modules
2666 are in packages other than the main package.
2667 </para>
2668 </glossdef>
2669 </glossentry>
2670
2671 </glossdiv>
2672
2673 <glossdiv id='var-glossary-h'><title>H</title>
2674
2675 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
2676 <glossdef>
2677 <para>Website where more information about the software the recipe is building
2678 can be found.</para>
2679 </glossdef>
2680 </glossentry>
2681
2682 <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
2683 <glossdef>
2684 <para>
2685 Specifies the system, including the architecture and the
2686 operating system, for with the build is occurring
2687 in the context of the current
2688 recipe.
2689 The OpenEmbedded build system automatically sets this
2690 variable.
2691 You do not need to set the variable yourself.
2692 </para>
2693
2694 <para>
2695 Here are two examples:
2696 <itemizedlist>
2697 <listitem><para>Given a native recipe on a 32-bit
2698 x86 machine running Linux, the value is
2699 "i686-linux".
2700 </para></listitem>
2701 <listitem><para>Given a recipe being built for a
2702 little-endian MIPS target running Linux,
2703 the value might be "mipsel-linux".
2704 </para></listitem>
2705 </itemizedlist>
2706 </para>
2707 </glossdef>
2708 </glossentry>
2709
2710 </glossdiv>
2711
2712 <glossdiv id='var-glossary-i'><title>I</title>
2713
2714 <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm>
2715 <glossdef>
2716 <para>
2717 Disables or enables the <filename>icecc</filename>
2718 (Icecream) function.
2719 For more information on this function and best practices
2720 for using this variable, see the
2721 "<link linkend='ref-classes-icecc'><filename>icecc.bbclass</filename></link>"
2722 section.
2723 </para>
2724
2725 <para>
2726 Setting this variable to "1" in your
2727 <filename>local.conf</filename> disables the function:
2728 <literallayout class='monospaced'>
2729 ICECC_DISABLED ??= "1"
2730 </literallayout>
2731 To enable the function, set the variable as follows:
2732 <literallayout class='monospaced'>
2733 ICECC_DISABLED = ""
2734 </literallayout>
2735 </para>
2736 </glossdef>
2737 </glossentry>
2738
2739 <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm>
2740 <glossdef>
2741 <para>
2742 Points to the <filename>icecc-create-env</filename> script
2743 that you provide.
2744 This variable is used by the
2745 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2746 class.
2747 You set this variable in your
2748 <filename>local.conf</filename> file.
2749 </para>
2750
2751 <para>
2752 If you do not point to a script that you provide, the
2753 OpenEmbedded build system uses the default script provided
2754 by the <filename>icecc-create-env.bb</filename> recipe,
2755 which is a modified version and not the one that comes with
2756 <filename>icecc</filename>.
2757 </para>
2758 </glossdef>
2759 </glossentry>
2760
2761 <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm>
2762 <glossdef>
2763 <para>
2764 Extra options passed to the <filename>make</filename>
2765 command during the <filename>do_compile</filename> task
2766 that specify parallel compilation.
2767 This variable usually takes the form of
2768 <filename>-j 4</filename>, where the number
2769 represents the maximum number of parallel threads
2770 <filename>make</filename> can run.
2771 <note>
2772 The options passed affect builds on all enabled
2773 machines on the network, which are machines running the
2774 <filename>iceccd</filename> daemon.
2775 </note>
2776 </para>
2777
2778 <para>
2779 If your enabled machines support multiple cores,
2780 coming up with the maximum number of parallel threads
2781 that gives you the best performance could take some
2782 experimentation since machine speed, network lag,
2783 available memory, and existing machine loads can all
2784 affect build time.
2785 Consequently, unlike the
2786 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
2787 variable, there is no rule-of-thumb for setting
2788 <filename>ICECC_PARALLEL_MAKE</filename> to achieve
2789 optimal performance.
2790 </para>
2791
2792 <para>
2793 If you do not set <filename>ICECC_PARALLEL_MAKE</filename>,
2794 the build system does not use it (i.e. the system does
2795 not detect and assign the number of cores as is done with
2796 <filename>PARALLEL_MAKE</filename>).
2797 </para>
2798 </glossdef>
2799 </glossentry>
2800
2801 <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm>
2802 <glossdef>
2803 <para>
2804 The location of the <filename>icecc</filename> binary.
2805 You can set this variable in your
2806 <filename>local.conf</filename> file.
2807 If your <filename>local.conf</filename> file does not define
2808 this variable, the
2809 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2810 class attempts to define it by locating
2811 <filename>icecc</filename> using <filename>which</filename>.
2812 </para>
2813 </glossdef>
2814 </glossentry>
2815
2816 <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm>
2817 <glossdef>
2818 <para>
2819 Identifies user classes that you do not want the
2820 Icecream distributed compile support to consider.
2821 This variable is used by the
2822 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2823 class.
2824 You set this variable in your
2825 <filename>local.conf</filename> file.
2826 </para>
2827
2828 <para>
2829 When you list classes using this variable, you are
2830 "blacklisting" them from distributed compilation across
2831 remote hosts.
2832 Any classes you list will be distributed and compiled
2833 locally.
2834 </para>
2835 </glossdef>
2836 </glossentry>
2837
2838 <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm>
2839 <glossdef>
2840 <para>
2841 Identifies user recipes that you do not want the
2842 Icecream distributed compile support to consider.
2843 This variable is used by the
2844 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2845 class.
2846 You set this variable in your
2847 <filename>local.conf</filename> file.
2848 </para>
2849
2850 <para>
2851 When you list packages using this variable, you are
2852 "blacklisting" them from distributed compilation across
2853 remote hosts.
2854 Any packages you list will be distributed and compiled
2855 locally.
2856 </para>
2857 </glossdef>
2858 </glossentry>
2859
2860 <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm>
2861 <glossdef>
2862 <para>
2863 Identifies user recipes that use an empty
2864 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
2865 variable that you want to force remote distributed
2866 compilation on using the Icecream distributed compile
2867 support.
2868 This variable is used by the
2869 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2870 class.
2871 You set this variable in your
2872 <filename>local.conf</filename> file.
2873 </para>
2874 </glossdef>
2875 </glossentry>
2876
2877 <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
2878 <glossdef>
2879 <para>
2880 The base name of image output files.
2881 This variable defaults to the recipe name
2882 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
2883 </para>
2884 </glossdef>
2885 </glossentry>
2886
2887 <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
2888 <glossdef>
2889 <para>
2890 A list of classes that all images should inherit.
2891 You typically use this variable to specify the list of
2892 classes that register the different types of images
2893 the OpenEmbedded build system creates.
2894 </para>
2895
2896 <para>
2897 The default value for <filename>IMAGE_CLASSES</filename> is
2898 <filename>image_types</filename>.
2899 You can set this variable in your
2900 <filename>local.conf</filename> or in a distribution
2901 configuration file.
2902 </para>
2903
2904 <para>
2905 For more information, see
2906 <filename>meta/classes/image_types.bbclass</filename> in the
2907 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2908 </para>
2909 </glossdef>
2910 </glossentry>
2911
2912 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
2913 <glossdef>
2914 <para>
2915 The primary list of features to include in an image.
2916 Typically, you configure this variable in an image recipe.
2917 Although you can use this variable from your
2918 <filename>local.conf</filename> file, which is found in the
2919 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
2920 best practices dictate that you do not.
2921 <note>
2922 To enable extra features from outside the image recipe,
2923 use the
2924 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
2925 </note>
2926 For a list of image features that ships with the Yocto
2927 Project, see the
2928 "<link linkend="ref-features-image">Image Features</link>"
2929 section.
2930 </para>
2931
2932 <para>
2933 For an example that shows how to customize your image by
2934 using this variable, see the
2935 "<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>"
2936 section in the Yocto Project Development Manual.
2937 </para>
2938 </glossdef>
2939 </glossentry>
2940
2941 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
2942 <glossdef>
2943 <para>
2944 Specifies the formats the OpenEmbedded build system uses
2945 during the build when creating the root filesystem.
2946 For example, setting <filename>IMAGE_FSTYPES</filename>
2947 as follows causes the build system to create root
2948 filesystems using two formats: <filename>.ext3</filename>
2949 and <filename>.tar.bz2</filename>:
2950 <literallayout class='monospaced'>
2951 IMAGE_FSTYPES = "ext3 tar.bz2"
2952 </literallayout>
2953 For the complete list of supported image formats from which
2954 you can choose, see
2955 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
2956 </para>
2957
2958 <note>
2959 If you add "live" to <filename>IMAGE_FSTYPES</filename>
2960 inside an image recipe, be sure that you do so prior to the
2961 "inherit image" line of the recipe or the live image will
2962 not build.
2963 </note>
2964
2965 <note>
2966 Due to the way this variable is processed, it is not
2967 possible to update its contents using
2968 <filename>_append</filename> or
2969 <filename>_prepend</filename>. To add one or more
2970 additional options to this variable the
2971 <filename>+=</filename> operator must be used.
2972 </note>
2973 </glossdef>
2974 </glossentry>
2975
2976 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
2977 <glossdef>
2978 <para>
2979 Specifies the packages to install into an image.
2980 The <filename>IMAGE_INSTALL</filename> variable is a
2981 mechanism for an image recipe and you should use it
2982 with care to avoid ordering issues.
2983 <note>
2984 When working with an
2985 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
2986 image, do not use the <filename>IMAGE_INSTALL</filename>
2987 variable to specify packages for installation.
2988 Instead, use the
2989 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
2990 variable, which allows the initial RAM disk (initramfs)
2991 recipe to use a fixed set of packages and not be
2992 affected by <filename>IMAGE_INSTALL</filename>.
2993 </note>
2994 </para>
2995
2996 <para>
2997 Image recipes set <filename>IMAGE_INSTALL</filename>
2998 to specify the packages to install into an image through
2999 <filename>image.bbclass</filename>.
3000 Additionally, "helper" classes exist, such as
3001 <filename>core-image.bbclass</filename>, that can take
3002 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
3003 lists and turn these into auto-generated entries in
3004 <filename>IMAGE_INSTALL</filename> in addition to its
3005 default contents.
3006 </para>
3007
3008 <para>
3009 Using <filename>IMAGE_INSTALL</filename> with the
3010 <filename>+=</filename> operator from the
3011 <filename>/conf/local.conf</filename> file or from within
3012 an image recipe is not recommended as it can cause ordering
3013 issues.
3014 Since <filename>core-image.bbclass</filename> sets
3015 <filename>IMAGE_INSTALL</filename> to a default value using
3016 the <filename>?=</filename> operator, using a
3017 <filename>+=</filename> operation against
3018 <filename>IMAGE_INSTALL</filename> will result in
3019 unexpected behavior when used in
3020 <filename>conf/local.conf</filename>.
3021 Furthermore, the same operation from within an image
3022 recipe may or may not succeed depending on the specific
3023 situation.
3024 In both these cases, the behavior is contrary to how most
3025 users expect the <filename>+=</filename> operator to work.
3026 </para>
3027
3028 <para>
3029 When you use this variable, it is best to use it as follows:
3030 <literallayout class='monospaced'>
3031 IMAGE_INSTALL_append = " package-name"
3032 </literallayout>
3033 Be sure to include the space between the quotation character
3034 and the start of the package name or names.
3035 </para>
3036 </glossdef>
3037 </glossentry>
3038
3039 <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
3040 <glossdef>
3041 <para>
3042 Specifies the list of locales to install into the image
3043 during the root filesystem construction process.
3044 The OpenEmbedded build system automatically splits locale
3045 files, which are used for localization, into separate
3046 packages.
3047 Setting the <filename>IMAGE_LINGUAS</filename> variable
3048 ensures that any locale packages that correspond to packages
3049 already selected for installation into the image are also
3050 installed.
3051 Here is an example:
3052 <literallayout class='monospaced'>
3053 IMAGE_LINGUAS = "pt-br de-de"
3054 </literallayout>
3055 In this example, the build system ensures any Brazilian
3056 Portuguese and German locale files that correspond to
3057 packages in the image are installed (i.e.
3058 <filename>*-locale-pt-br</filename>
3059 and <filename>*-locale-de-de</filename> as well as
3060 <filename>*-locale-pt</filename>
3061 and <filename>*-locale-de</filename>, since some software
3062 packages only provide locale files by language and not by
3063 country-specific language).
3064 </para>
3065 </glossdef>
3066 </glossentry>
3067
3068 <glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm>
3069 <glossdef>
3070 <para>
3071 The manifest file for the image.
3072 This file lists all the installed packages that make up
3073 the image.
3074 The file contains package information on a line-per-package
3075 basis as follows:
3076 <literallayout class='monospaced'>
3077 &lt;packagename&gt; &lt;packagearch&gt; &lt;version&gt;
3078 </literallayout>
3079 </para>
3080
3081 <para>
3082 The
3083 <link linkend='ref-classes-image'><filename>image</filename></link>
3084 class defines the manifest file as follows:
3085 <literallayout class='monospaced'>
3086 IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"
3087 </literallayout>
3088 The location is derived using the
3089 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
3090 and
3091 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>
3092 variables.
3093 You can find information on how the image
3094 is created in the
3095 "<link linkend='image-generation-dev-environment'>Image Generation</link>"
3096 section.
3097 </para>
3098 </glossdef>
3099 </glossentry>
3100
3101 <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
3102 <glossdef>
3103 <para>
3104 The name of the output image files minus the extension.
3105 This variable is derived using the
3106 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
3107 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
3108 and
3109 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
3110 variables:
3111 <literallayout class='monospaced'>
3112 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
3113 </literallayout>
3114 </para>
3115 </glossdef>
3116 </glossentry>
3117
3118 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
3119 <glossdef>
3120 <para>
3121 Defines a multiplier that the build system applies to the initial image
3122 size for cases when the multiplier times the returned disk usage value
3123 for the image is greater than the sum of
3124 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
3125 and
3126 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
3127 The result of the multiplier applied to the initial image size creates
3128 free disk space in the image as overhead.
3129 By default, the build process uses a multiplier of 1.3 for this variable.
3130 This default value results in 30% free disk space added to the image when this
3131 method is used to determine the final generated image size.
3132 You should be aware that post install scripts and the package management
3133 system uses disk space inside this overhead area.
3134 Consequently, the multiplier does not produce an image with
3135 all the theoretical free disk space.
3136 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
3137 for information on how the build system determines the overall image size.
3138 </para>
3139
3140 <para>
3141 The default 30% free disk space typically gives the image enough room to boot
3142 and allows for basic post installs while still leaving a small amount of
3143 free disk space.
3144 If 30% free space is inadequate, you can increase the default value.
3145 For example, the following setting gives you 50% free space added to the image:
3146 <literallayout class='monospaced'>
3147 IMAGE_OVERHEAD_FACTOR = "1.5"
3148 </literallayout>
3149 </para>
3150
3151 <para>
3152 Alternatively, you can ensure a specific amount of free disk space is added
3153 to the image by using the
3154 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
3155 variable.
3156 </para>
3157 </glossdef>
3158 </glossentry>
3159
3160 <glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm>
3161 <glossdef>
3162 <para>
3163 Defines the package type (DEB, RPM, IPK, or TAR) used
3164 by the OpenEmbedded build system.
3165 The variable is defined appropriately by the
3166 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
3167 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
3168 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
3169 or
3170 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
3171 class.
3172 </para>
3173
3174 <para>
3175 The
3176 <link linkend='ref-classes-populate-sdk-*'><filename>package_sdk_base</filename></link>
3177 and
3178 <link linkend='ref-classes-image'><filename>image</filename></link>
3179 classes use the <filename>IMAGE_PKGTYPE</filename> for
3180 packaging up images and SDKs.
3181 </para>
3182
3183 <para>
3184 You should not set the <filename>IMAGE_PKGTYPE</filename>
3185 manually.
3186 Rather, the variable is set indirectly through the
3187 appropriate
3188 <link linkend='ref-classes-package'><filename>package_*</filename></link>
3189 class using the
3190 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3191 variable.
3192 The OpenEmbedded build system uses the first package type
3193 (e.g. DEB, RPM, or IPK) that appears with the variable
3194 <note>
3195 Files using the <filename>.tar</filename> format are
3196 never used as a substitute packaging format for DEB,
3197 RPM, and IPK formatted files for your image or SDK.
3198 </note>
3199 </para>
3200 </glossdef>
3201 </glossentry>
3202
3203 <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
3204 <glossdef>
3205 <para>
3206 Added by classes to run post processing commands once the
3207 OpenEmbedded build system has created the image.
3208 You can specify shell commands separated by semicolons:
3209 <literallayout class='monospaced'>
3210 IMAGE_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
3211 </literallayout>
3212 If you need to pass the path to the root filesystem within
3213 the command, you can use
3214 <filename>${IMAGE_ROOTFS}</filename>, which points to
3215 the root filesystem image.
3216 </para>
3217 </glossdef>
3218 </glossentry>
3219
3220 <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
3221 <glossdef>
3222 <para>
3223 The location of the root filesystem while it is under
3224 construction (i.e. during <filename>do_rootfs</filename>).
3225 This variable is not configurable.
3226 Do not change it.
3227 </para>
3228 </glossdef>
3229 </glossentry>
3230
3231 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
3232 <glossdef>
3233 <para>
3234 Defines additional free disk space created in the image in Kbytes.
3235 By default, this variable is set to "0".
3236 This free disk space is added to the image after the build system determines
3237 the image size as described in
3238 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
3239 </para>
3240
3241 <para>
3242 This variable is particularly useful when you want to ensure that a
3243 specific amount of free disk space is available on a device after an image
3244 is installed and running.
3245 For example, to be sure 5 Gbytes of free disk space is available, set the
3246 variable as follows:
3247 <literallayout class='monospaced'>
3248 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
3249 </literallayout>
3250 </para>
3251
3252 <para>
3253 For example, the Yocto Project Build Appliance specifically requests 40 Gbytes
3254 of extra space with the line:
3255 <literallayout class='monospaced'>
3256 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
3257 </literallayout>
3258 </para>
3259 </glossdef>
3260 </glossentry>
3261
3262 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
3263 <glossdef>
3264 <para>
3265 Defines the size in Kbytes for the generated image.
3266 The OpenEmbedded build system determines the final size for the generated
3267 image using an algorithm that takes into account the initial disk space used
3268 for the generated image, a requested size for the image, and requested
3269 additional free disk space to be added to the image.
3270 Programatically, the build system determines the final size of the
3271 generated image as follows:
3272 <literallayout class='monospaced'>
3273 if (image-du * overhead) &lt; rootfs-size:
3274 internal-rootfs-size = rootfs-size + xspace
3275 else:
3276 internal-rootfs-size = (image-du * overhead) + xspace
3277
3278 where:
3279
3280 image-du = Returned value of the du command on
3281 the image.
3282
3283 overhead = IMAGE_OVERHEAD_FACTOR
3284
3285 rootfs-size = IMAGE_ROOTFS_SIZE
3286
3287 internal-rootfs-size = Initial root filesystem
3288 size before any modifications.
3289
3290 xspace = IMAGE_ROOTFS_EXTRA_SPACE
3291 </literallayout>
3292 See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
3293 and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
3294 variables for related information.
3295<!-- In the above example, <filename>overhead</filename> is defined by the
3296 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
3297 variable, <filename>xspace</filename> is defined by the
3298 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
3299 variable, and <filename>du</filename> is the results of the disk usage command
3300 on the initially generated image. -->
3301 </para>
3302 </glossdef>
3303 </glossentry>
3304
3305 <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm>
3306 <glossdef>
3307 <para>
3308 Specifies a dependency from one image type on another.
3309 Here is an example from the
3310 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
3311 class:
3312 <literallayout class='monospaced'>
3313 IMAGE_TYPEDEP_live = "ext3"
3314 </literallayout>
3315 In the previous example, the variable ensures that when
3316 "live" is listed with the
3317 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
3318 variable, the OpenEmbedded build system produces an
3319 <filename>ext3</filename> image first since one of the
3320 components of the live
3321 image is an <filename>ext3</filename>
3322 formatted partition containing the root
3323 filesystem.
3324 </para>
3325 </glossdef>
3326 </glossentry>
3327
3328 <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
3329 <glossdef>
3330 <para>
3331 Specifies the complete list of supported image types
3332 by default:
3333 <literallayout class='monospaced'>
3334 jffs2
3335 jffs2.sum
3336 cramfs
3337 ext2
3338 ext2.gz
3339 ext2.bz2
3340 ext3
3341 ext3.gz
3342 ext2.lzma
3343 btrfs
3344 live
3345 squashfs
3346 squashfs-xz
3347 ubi
3348 ubifs
3349 tar
3350 tar.gz
3351 tar.bz2
3352 tar.xz
3353 cpio
3354 cpio.gz
3355 cpio.xz
3356 cpio.lzma
3357 vmdk
3358 elf
3359 </literallayout>
3360 For more information on how these types of images, see
3361 <filename>meta/classes/image_types*.bbclass</filename>
3362 in the
3363 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
3364 </para>
3365 </glossdef>
3366 </glossentry>
3367
3368 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
3369 <glossdef>
3370 <para>Helps define the recipe revision for recipes that share
3371 a common <filename>include</filename> file.
3372 You can think of this variable as part of the recipe revision
3373 as set from within an include file.</para>
3374 <para>Suppose, for example, you have a set of recipes that
3375 are used across several projects.
3376 And, within each of those recipes the revision
3377 (its <link linkend='var-PR'><filename>PR</filename></link>
3378 value) is set accordingly.
3379 In this case, when the revision of those recipes changes,
3380 the burden is on you to find all those recipes and
3381 be sure that they get changed to reflect the updated
3382 version of the recipe.
3383 In this scenario, it can get complicated when recipes
3384 that are used in many places and provide common functionality
3385 are upgraded to a new revision.</para>
3386 <para>A more efficient way of dealing with this situation is
3387 to set the <filename>INC_PR</filename> variable inside
3388 the <filename>include</filename> files that the recipes
3389 share and then expand the <filename>INC_PR</filename>
3390 variable within the recipes to help
3391 define the recipe revision.
3392 </para>
3393 <para>
3394 The following provides an example that shows how to use
3395 the <filename>INC_PR</filename> variable
3396 given a common <filename>include</filename> file that
3397 defines the variable.
3398 Once the variable is defined in the
3399 <filename>include</filename> file, you can use the
3400 variable to set the <filename>PR</filename> values in
3401 each recipe.
3402 You will notice that when you set a recipe's
3403 <filename>PR</filename> you can provide more granular
3404 revisioning by appending values to the
3405 <filename>INC_PR</filename> variable:
3406 <literallayout class='monospaced'>
3407recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
3408recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
3409recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
3410recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
3411 </literallayout>
3412 The first line of the example establishes the baseline
3413 revision to be used for all recipes that use the
3414 <filename>include</filename> file.
3415 The remaining lines in the example are from individual
3416 recipes and show how the <filename>PR</filename> value
3417 is set.</para>
3418 </glossdef>
3419 </glossentry>
3420
3421 <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
3422 <glossdef>
3423 <para>
3424 Specifies a space-separated list of license names
3425 (as they would appear in
3426 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
3427 that should be excluded from the build.
3428 Recipes that provide no alternatives to listed incompatible
3429 licenses are not built.
3430 Packages that are individually licensed with the specified
3431 incompatible licenses will be deleted.
3432 </para>
3433
3434 <note>
3435 This functionality is only regularly tested using
3436 the following setting:
3437 <literallayout class='monospaced'>
3438 INCOMPATIBLE_LICENSE = "GPLv3"
3439 </literallayout>
3440 Although you can use other settings, you might be required
3441 to remove dependencies on or provide alternatives to
3442 components that are required to produce a functional system
3443 image.
3444 </note>
3445 </glossdef>
3446 </glossentry>
3447
3448 <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
3449 <glossdef>
3450 <para>
3451 Prevents the default dependencies, namely the C compiler
3452 and standard C library (libc), from being added to
3453 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
3454 This variable is usually used within recipes that do not
3455 require any compilation using the C compiler.
3456 </para>
3457
3458 <para>
3459 Set the variable to "1" to prevent the default dependencies
3460 from being added.
3461 </para>
3462 </glossdef>
3463 </glossentry>
3464
3465 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
3466 <glossdef>
3467 <para>
3468 If set to "1", causes the build to not strip binaries in resulting packages.
3469 </para>
3470 </glossdef>
3471 </glossentry>
3472
3473 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
3474 <glossdef>
3475 <para>
3476 Causes the named class to be inherited at
3477 this point during parsing.
3478 The variable is only valid in configuration files.
3479 </para>
3480 </glossdef>
3481 </glossentry>
3482
3483 <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm>
3484 <glossdef>
3485 <para>
3486 Lists classes that will be inherited at the
3487 distribution level.
3488 It is unlikely that you want to edit this variable.
3489 </para>
3490
3491 <para>
3492 The default value of the variable is set as follows in the
3493 <filename>meta/conf/distro/defaultsetup.conf</filename>
3494 file:
3495 <literallayout class='monospaced'>
3496 INHERIT_DISTRO ?= "debian devshell sstate license"
3497 </literallayout>
3498 </para>
3499 </glossdef>
3500 </glossentry>
3501
3502 <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
3503 <glossdef>
3504 <para>
3505 Defines the format for the output image of an initial
3506 RAM disk (initramfs), which is used during boot.
3507 Supported formats are the same as those supported by the
3508 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
3509 variable.
3510 </para>
3511 </glossdef>
3512 </glossentry>
3513
3514 <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>
3515 <glossdef>
3516 <para>
3517 Causes the OpenEmbedded build system to build an additional
3518 recipe as a dependency to your root filesystem recipe
3519 (e.g. <filename>core-image-sato</filename>).
3520 The additional recipe is used to create an initial RAM disk
3521 (initramfs) that might be needed during the initial boot of
3522 the target system to accomplish such things as loading
3523 kernel modules prior to mounting the root file system.
3524 </para>
3525
3526 <para>
3527 When you set the variable, specify the name of the
3528 initramfs you want created.
3529 The following example, which is set in the
3530 <filename>local.conf</filename> configuration file, causes
3531 a separate recipe to be created that results in an
3532 initramfs image named
3533 <filename>core-image-sato-initramfs.bb</filename> to be
3534 created:
3535 <literallayout class='monospaced'>
3536 INITRAMFS_IMAGE = "core-image-minimal-initramfs"
3537 </literallayout>
3538 By default, the
3539 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
3540 class sets this variable to a null string as follows:
3541 <literallayout class='monospaced'>
3542 INITRAMFS_IMAGE = ""
3543 </literallayout>
3544 </para>
3545
3546 <para>
3547 See the
3548 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
3549 file for additional information.
3550 You can also reference the
3551 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/kernel.bbclass'><filename>kernel.bbclass</filename></ulink>
3552 file to see how the variable is used.
3553 </para>
3554 </glossdef>
3555 </glossentry>
3556
3557 <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
3558 <glossdef>
3559 <para>
3560 Controls whether or not the image recipe specified by
3561 <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link>
3562 is run through an extra pass during kernel compilation
3563 in order to build a single binary that contains both the
3564 kernel image and the initial RAM disk (initramfs).
3565 Using an extra compilation pass ensures that when a kernel
3566 attempts to use an initramfs, it does not encounter
3567 circular dependencies should the initramfs include kernel
3568 modules.
3569 </para>
3570
3571 <para>
3572 The combined binary is deposited into the
3573 <filename>tmp/deploy</filename> directory, which is part
3574 of the
3575 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
3576 </para>
3577
3578 <para>
3579 Setting the variable to "1" in a configuration file causes
3580 the OpenEmbedded build system to make the extra pass during
3581 kernel compilation:
3582 <literallayout class='monospaced'>
3583 INITRAMFS_IMAGE_BUNDLE = "1"
3584 </literallayout>
3585 By default, the
3586 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
3587 class sets this variable to a null string as follows:
3588 <literallayout class='monospaced'>
3589 INITRAMFS_IMAGE_BUNDLE = ""
3590 </literallayout>
3591 <note>
3592 You must set the
3593 <filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in
3594 a configuration file.
3595 You cannot set the variable in a recipe file.
3596 </note>
3597 See the
3598 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
3599 file for additional information.
3600 </para>
3601 </glossdef>
3602 </glossentry>
3603
3604 <glossentry id='var-INITRD'><glossterm>INITRD</glossterm>
3605 <glossdef>
3606 <para>
3607 Indicates a filesystem image to use as an initial RAM
3608 disk (<filename>initrd</filename>).
3609 </para>
3610
3611 <para>
3612 The <filename>INITRD</filename> variable is an optional
3613 variable used with the
3614 <link linkend='ref-classes-bootimg'><filename>buildimg</filename></link>
3615 class.
3616 </para>
3617 </glossdef>
3618 </glossentry>
3619
3620 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
3621 <glossdef>
3622 <para>
3623 The filename of the initialization script as installed to
3624 <filename>${sysconfdir}/init.d</filename>.
3625 </para>
3626 <para>
3627 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
3628 The variable is mandatory.
3629 </para>
3630 </glossdef>
3631 </glossentry>
3632
3633 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
3634 <glossdef>
3635 <para>
3636 A list of the packages that contain initscripts.
3637 If multiple packages are specified, you need to append the package name
3638 to the other <filename>INITSCRIPT_*</filename> as an override.</para>
3639 <para>
3640 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
3641 The variable is optional and defaults to the
3642 <link linkend='var-PN'><filename>PN</filename></link> variable.
3643 </para>
3644 </glossdef>
3645 </glossentry>
3646
3647 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
3648 <glossdef>
3649 <para>
3650 Specifies the options to pass to <filename>update-rc.d</filename>.
3651 Here is an example:
3652 <literallayout class='monospaced'>
3653 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
3654 </literallayout>
3655 In this example, the script has a runlevel of 99,
3656 starts the script in initlevels 2 and 5, and
3657 stops the script in levels 0, 1 and 6.
3658 </para>
3659 <para>
3660 The variable is mandatory and is used in recipes when using
3661 <filename>update-rc.d.bbclass</filename>.
3662 </para>
3663 </glossdef>
3664 </glossentry>
3665
3666 <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
3667 <glossdef>
3668 <para>
3669 Specifies the QA checks to skip for a specific package
3670 within a recipe.
3671 For example, to skip the check for symbolic link
3672 <filename>.so</filename> files in the main package of a
3673 recipe, add the following to the recipe.
3674 The package name override must be used, which in this
3675 example is <filename>${PN}</filename>:
3676 <literallayout class='monospaced'>
3677 INSANE_SKIP_${PN} += "dev-so"
3678 </literallayout>
3679 </para>
3680 <para>
3681 See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
3682 section for a list of the valid QA checks you can
3683 specify using this variable.
3684 </para>
3685 </glossdef>
3686 </glossentry>
3687
3688 <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
3689 <glossdef>
3690 <para>
3691 When the IPK backend is in use and package management
3692 is enabled on the target, you can use this variable to
3693 set up <filename>opkg</filename> in the target image
3694 to point to package feeds on a nominated server.
3695 Once the feed is established, you can perform
3696 installations or upgrades using the package manager
3697 at runtime.
3698 </para>
3699 </glossdef>
3700 </glossentry>
3701
3702<!--
3703 <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
3704 <glossdef>
3705 <para>
3706 An environment variable that defines the directory where
3707 post installation hooks are installed for the
3708 post install environment.
3709 This variable is fixed as follows:
3710 <literallayout class='monospaced'>
3711 ${WORKDIR}/intercept_scripts
3712 </literallayout>
3713 </para>
3714
3715 <para>
3716 After installation of a target's root filesystem,
3717 post installation scripts, which are essentially bash scripts,
3718 are all executed just a single time.
3719 Limiting execution of these scripts minimizes installation
3720 time that would be lengthened due to certain packages
3721 triggering redundant operations.
3722 For example, consider the installation of font packages
3723 as a common example.
3724 Without limiting the execution of post installation scripts,
3725 all font directories would be rescanned to create the
3726 cache after each individual font package was installed.
3727 </para>
3728
3729 <para>
3730 Do not edit the <filename>INTERCEPT_DIR</filename>
3731 variable.
3732 </para>
3733 </glossdef>
3734 </glossentry>
3735-->
3736
3737 </glossdiv>
3738
3739<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
3740<!-- </glossdiv>-->
3741
3742 <glossdiv id='var-glossary-k'><title>K</title>
3743
3744 <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
3745 <glossdef>
3746 <para>
3747 Defines the kernel architecture used when assembling
3748 the configuration.
3749 Architectures supported for this release are:
3750 <literallayout class='monospaced'>
3751 powerpc
3752 i386
3753 x86_64
3754 arm
3755 qemu
3756 mips
3757 </literallayout>
3758 </para>
3759
3760 <para>
3761 You define the <filename>KARCH</filename> variable in the
3762 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
3763 </para>
3764 </glossdef>
3765 </glossentry>
3766
3767 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
3768 <glossdef>
3769 <para>
3770 A regular expression used by the build process to explicitly
3771 identify the kernel branch that is validated, patched
3772 and configured during a build.
3773 The <filename>KBRANCH</filename> variable is optional.
3774 You can use it to trigger checks to ensure the exact kernel
3775 branch you want is being used by the build process.
3776 </para>
3777
3778 <para>
3779 Values for this variable are set in the kernel's recipe
3780 file and the kernel's append file.
3781 For example, if you are using the Yocto Project kernel that
3782 is based on the Linux 3.10 kernel, the kernel recipe file
3783 is the
3784 <filename>meta/recipes-kernel/linux/linux-yocto_3.10.bb</filename>
3785 file.
3786 Following is the default value for <filename>KBRANCH</filename>
3787 and the default override for the architectures the Yocto
3788 Project supports:
3789 <literallayout class='monospaced'>
3790 KBRANCH_DEFAULT = "standard/base"
3791 KBRANCH = "${KBRANCH_DEFAULT}"
3792 </literallayout>
3793 This branch exists in the <filename>linux-yocto-3.10</filename>
3794 kernel Git repository
3795 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.10/refs/heads'></ulink>.
3796 </para>
3797
3798 <para>
3799 This variable is also used from the kernel's append file
3800 to identify the kernel branch specific to a particular
3801 machine or target hardware.
3802 The kernel's append file is located in the BSP layer for
3803 a given machine.
3804 For example, the kernel append file for the Crown Bay BSP is in the
3805 <filename>meta-intel</filename> Git repository and is named
3806 <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend</filename>.
3807 Here are the related statements from the append file:
3808 <literallayout class='monospaced'>
3809 COMPATIBLE_MACHINE_crownbay = "crownbay"
3810 KMACHINE_crownbay = "crownbay"
3811 KBRANCH_crownbay = "standard/crownbay"
3812 KERNEL_FEATURES_append_crownbay = " features/drm-emgd/drm-emgd-1.18 cfg/vesafb"
3813
3814 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
3815 KMACHINE_crownbay-noemgd = "crownbay"
3816 KBRANCH_crownbay-noemgd = "standard/crownbay"
3817 KERNEL_FEATURES_append_crownbay-noemgd = " cfg/vesafb"
3818 </literallayout>
3819 The <filename>KBRANCH_*</filename> statements identify
3820 the kernel branch to use when building for the Crown
3821 Bay BSP.
3822 In this case there are two identical statements: one
3823 for each type of Crown Bay machine.
3824 </para>
3825 </glossdef>
3826 </glossentry>
3827
3828 <glossentry id='var-KBRANCH_DEFAULT'><glossterm>KBRANCH_DEFAULT</glossterm>
3829 <glossdef>
3830 <para>
3831 Defines the Linux kernel source repository's default
3832 branch used to build the Linux kernel.
3833 The <filename>KBRANCH_DEFAULT</filename> value is
3834 the default value for
3835 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>.
3836 Unless you specify otherwise,
3837 <filename>KBRANCH_DEFAULT</filename> initializes to
3838 "master".
3839 </para>
3840 </glossdef>
3841 </glossentry>
3842
3843 <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
3844 <glossdef>
3845 <para>
3846 Specifies additional <filename>make</filename>
3847 command-line arguments the OpenEmbedded build system
3848 passes on when compiling the kernel.
3849 </para>
3850 </glossdef>
3851 </glossentry>
3852
3853 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
3854 <glossdef>
3855 <para>Includes additional metadata from the Yocto Project kernel Git repository.
3856 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
3857 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
3858 is provided through
3859 the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
3860 and <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link> variables.
3861 You can use the <filename>KERNEL_FEATURES</filename> variable to further
3862 add metadata for all BSPs.</para>
3863 <para>The metadata you add through this variable includes config fragments and
3864 features descriptions,
3865 which usually includes patches as well as config fragments.
3866 You typically override the <filename>KERNEL_FEATURES</filename> variable
3867 for a specific machine.
3868 In this way, you can provide validated, but optional, sets of kernel
3869 configurations and features.</para>
3870 <para>For example, the following adds <filename>netfilter</filename> to all
3871 the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>
3872 machine:
3873 <literallayout class='monospaced'>
3874 # Add netfilter to all linux-yocto kernels
3875 KERNEL_FEATURES="features/netfilter"
3876
3877 # Add sound support to the qemux86 machine
3878 KERNEL_FEATURES_append_qemux86=" cfg/sound"
3879 </literallayout></para>
3880 </glossdef>
3881 </glossentry>
3882
3883 <glossentry id='var-KERNEL_IMAGE_BASE_NAME'><glossterm>KERNEL_IMAGE_BASE_NAME</glossterm>
3884 <glossdef>
3885 <para>
3886 The base name of the kernel image.
3887 This variable is set in the
3888 <link linkend='ref-classes-kernel'>kernel</link> class
3889 as follows:
3890 <literallayout class='monospaced'>
3891 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
3892 </literallayout>
3893 See the
3894 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>,
3895 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
3896 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
3897 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
3898 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
3899 and
3900 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
3901 variables for additional information.
3902 </para>
3903 </glossdef>
3904 </glossentry>
3905
3906 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
3907 <glossdef>
3908 <para>The type of kernel to build for a device, usually set by the
3909 machine configuration files and defaults to "zImage".
3910 This variable is used
3911 when building the kernel and is passed to <filename>make</filename> as the target to
3912 build.</para>
3913 </glossdef>
3914 </glossentry>
3915
3916 <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
3917 <glossdef>
3918 <para>
3919 The location of the kernel sources.
3920 This variable is set to the value of the
3921 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
3922 within the <filename>module.bbclass</filename> class.
3923 For information on how this variable is used, see the
3924 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
3925 section.
3926 </para>
3927
3928 <para>
3929 To help maximize compatibility with out-of-tree drivers
3930 used to build modules, the OpenEmbedded build system also
3931 recognizes and uses the
3932 <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
3933 variable, which is identical to the
3934 <filename>KERNEL_PATH</filename> variable.
3935 Both variables are common variables used by external
3936 Makefiles to point to the kernel source directory.
3937 </para>
3938 </glossdef>
3939 </glossentry>
3940
3941 <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
3942 <glossdef>
3943 <para>
3944 The location of the kernel sources.
3945 This variable is set to the value of the
3946 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
3947 within the <filename>module.bbclass</filename> class.
3948 For information on how this variable is used, see the
3949 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
3950 section.
3951 </para>
3952
3953 <para>
3954 To help maximize compatibility with out-of-tree drivers
3955 used to build modules, the OpenEmbedded build system also
3956 recognizes and uses the
3957 <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
3958 variable, which is identical to the
3959 <filename>KERNEL_SRC</filename> variable.
3960 Both variables are common variables used by external
3961 Makefiles to point to the kernel source directory.
3962 </para>
3963 </glossdef>
3964 </glossentry>
3965
3966 <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
3967 <glossdef>
3968 <para>
3969 Provides a short description of a configuration fragment.
3970 You use this variable in the <filename>.scc</filename>
3971 file that describes a configuration fragment file.
3972 Here is the variable used in a file named
3973 <filename>smp.scc</filename> to describe SMP being
3974 enabled:
3975 <literallayout class='monospaced'>
3976 define KFEATURE_DESCRIPTION "Enable SMP"
3977 </literallayout>
3978 </para>
3979 </glossdef>
3980 </glossentry>
3981
3982 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
3983 <glossdef>
3984 <para>
3985 The machine as known by the kernel.
3986 Sometimes the machine name used by the kernel does not match the machine name
3987 used by the OpenEmbedded build system.
3988 For example, the machine name that the OpenEmbedded build system understands as
3989 <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel.
3990 The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
3991 For cases like these, the <filename>KMACHINE</filename> variable maps the
3992 kernel machine name to the OpenEmbedded build system machine name.
3993 </para>
3994
3995 <para>
3996 Kernel machine names are initially defined in the
3997 Yocto Linux Kernel's <filename>meta</filename> branch.
3998 From the <filename>meta</filename> branch, look in
3999 the <filename>meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</filename> file.
4000 For example, from the <filename>meta</filename> branch in the
4001 <filename>linux-yocto-3.0</filename> kernel, the
4002 <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file
4003 has the following:
4004 <literallayout class='monospaced'>
4005 define KMACHINE cedartrail
4006 define KTYPE standard
4007 define KARCH i386
4008
4009 include ktypes/standard
4010 branch cedartrail
4011
4012 include cedartrail.scc
4013 </literallayout>
4014 You can see that the kernel understands the machine name for
4015 the Cedar Trail Board Support Package (BSP) as
4016 <filename>cedartrail</filename>.
4017 </para>
4018
4019 <para>
4020 If you look in the Cedar Trail BSP layer in the
4021 <filename>meta-intel</filename>
4022 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
4023 at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>,
4024 you will find the following statements among others:
4025 <literallayout class='monospaced'>
4026 COMPATIBLE_MACHINE_cedartrail = "cedartrail"
4027 KMACHINE_cedartrail = "cedartrail"
4028 KBRANCH_cedartrail = "yocto/standard/cedartrail"
4029 KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
4030 KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
4031
4032 COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
4033 KMACHINE_cedartrail-nopvr = "cedartrail"
4034 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
4035 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
4036 </literallayout>
4037 The <filename>KMACHINE</filename> statements in the kernel's append file make sure that
4038 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
4039 names.
4040 </para>
4041
4042 <para>
4043 This append file uses two <filename>KMACHINE</filename> statements.
4044 The first is not really necessary but does ensure that the machine known to the
4045 OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
4046 in the kernel also known as <filename>cedartrail</filename>:
4047 <literallayout class='monospaced'>
4048 KMACHINE_cedartrail = "cedartrail"
4049 </literallayout>
4050 </para>
4051
4052 <para>
4053 The second statement is a good example of why the <filename>KMACHINE</filename> variable
4054 is needed.
4055 In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename>
4056 machine name to refer to the Cedar Trail BSP that does not support the proprietary
4057 PowerVR driver.
4058 The kernel, however, uses the machine name <filename>cedartrail</filename>.
4059 Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to
4060 the kernel's <filename>cedartrail</filename> name:
4061 <literallayout class='monospaced'>
4062 KMACHINE_cedartrail-nopvr = "cedartrail"
4063 </literallayout>
4064 </para>
4065
4066 <para>
4067 BSPs that ship with the Yocto Project release provide all mappings between the Yocto
4068 Project kernel machine names and the OpenEmbedded machine names.
4069 Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine
4070 name you use is different than that used in the kernel.
4071 </para>
4072 </glossdef>
4073 </glossentry>
4074
4075 <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
4076 <glossdef>
4077 <para>
4078 Defines the kernel type to be used in assembling the
4079 configuration.
4080 The linux-yocto recipes define "standard", "tiny",
4081 and "preempt-rt" kernel types.
4082 See the
4083 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
4084 section in the Yocto Project Linux Kernel Development
4085 Manual for more information on kernel types.
4086 </para>
4087
4088 <para>
4089 You define the <filename>KTYPE</filename> variable in the
4090 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
4091 The value you use must match the value used for the
4092 <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
4093 value used by the kernel recipe.
4094 </para>
4095 </glossdef>
4096 </glossentry>
4097 </glossdiv>
4098
4099 <glossdiv id='var-glossary-l'><title>L</title>
4100
4101 <glossentry id='var-LABELS'><glossterm>LABELS</glossterm>
4102 <glossdef>
4103 <para>
4104 Provides a list of targets for automatic configuration.
4105 </para>
4106
4107 <para>
4108 See the
4109 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
4110 class for more information on how this variable is used.
4111 </para>
4112 </glossdef>
4113 </glossentry>
4114
4115 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
4116 <glossdef>
4117 <para>Lists the layers that this recipe depends upon, separated by spaces.
4118 Optionally, you can specify a specific layer version for a dependency
4119 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
4120 to be compared against
4121 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>
4122 in this case).
4123 An error will be produced if any dependency is missing or
4124 the version numbers do not match exactly (if specified).
4125 This variable is used in the <filename>conf/layer.conf</filename> file
4126 and must be suffixed with the name of the specific layer (e.g.
4127 <filename>LAYERDEPENDS_mylayer</filename>).</para>
4128 </glossdef>
4129 </glossentry>
4130
4131 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
4132 <glossdef>
4133 <para>When used inside the <filename>layer.conf</filename> configuration
4134 file, this variable provides the path of the current layer.
4135 This variable is not available outside of <filename>layer.conf</filename>
4136 and references are expanded immediately when parsing of the file completes.</para>
4137 </glossdef>
4138 </glossentry>
4139
4140 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
4141 <glossdef>
4142 <para>Optionally specifies the version of a layer as a single number.
4143 You can use this within
4144 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
4145 for another layer in order to depend on a specific version
4146 of the layer.
4147 This variable is used in the <filename>conf/layer.conf</filename> file
4148 and must be suffixed with the name of the specific layer (e.g.
4149 <filename>LAYERVERSION_mylayer</filename>).</para>
4150 </glossdef>
4151 </glossentry>
4152
4153 <glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>
4154 <glossdef>
4155 <para>
4156 Specifies the lead (or primary) compiled library file
4157 (<filename>.so</filename>) that the
4158 <link linkend='ref-classes-debian'><filename>debian</filename></link>
4159 class applies its naming policy to given a recipe that
4160 packages multiple libraries.
4161 </para>
4162
4163 <para>
4164 This variable works in conjunction with the
4165 <filename>debian</filename> class.
4166 </para>
4167 </glossdef>
4168 </glossentry>
4169
4170 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
4171 <glossdef>
4172 <para>Checksums of the license text in the recipe source code.</para>
4173 <para>This variable tracks changes in license text of the source
4174 code files.
4175 If the license text is changed, it will trigger a build
4176 failure, which gives the developer an opportunity to review any
4177 license change.</para>
4178 <para>
4179 This variable must be defined for all recipes (unless
4180 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
4181 is set to "CLOSED")</para>
4182 <para>For more information, see the
4183 <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
4184 Tracking License Changes</link> section</para>
4185 </glossdef>
4186 </glossentry>
4187
4188 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
4189 <glossdef>
4190 <para>
4191 The list of source licenses for the recipe.
4192 Follow these rules:
4193 <itemizedlist>
4194 <listitem><para>Do not use spaces within individual
4195 license names.</para></listitem>
4196 <listitem><para>Separate license names using
4197 | (pipe) when there is a choice between licenses.
4198 </para></listitem>
4199 <listitem><para>Separate license names using
4200 &amp; (ampersand) when multiple licenses exist
4201 that cover different parts of the source.
4202 </para></listitem>
4203 <listitem><para>You can use spaces between license
4204 names.</para></listitem>
4205 <listitem><para>For standard licenses, use the names
4206 of the files in
4207 <filename>meta/files/common-licenses/</filename>
4208 or the
4209 <link linkend='var-SPDXLICENSEMAP'><filename>SPDXLICENSEMAP</filename></link>
4210 flag names defined in
4211 <filename>meta/conf/licenses.conf</filename>.
4212 </para></listitem>
4213 </itemizedlist>
4214 </para>
4215
4216 <para>
4217 Here are some examples:
4218 <literallayout class='monospaced'>
4219 LICENSE = "LGPLv2.1 | GPLv3"
4220 LICENSE = "MPL-1 &amp; LGPLv2.1"
4221 LICENSE = "GPLv2+"
4222 </literallayout>
4223 The first example is from the recipes for Qt, which the user
4224 may choose to distribute under either the LGPL version
4225 2.1 or GPL version 3.
4226 The second example is from Cairo where two licenses cover
4227 different parts of the source code.
4228 The final example is from <filename>sysstat</filename>,
4229 which presents a single license.
4230 </para>
4231
4232 <para>
4233 You can also specify licenses on a per-package basis to
4234 handle situations where components of the output have
4235 different licenses.
4236 For example, a piece of software whose code is
4237 licensed under GPLv2 but has accompanying documentation
4238 licensed under the GNU Free Documentation License 1.2 could
4239 be specified as follows:
4240 <literallayout class='monospaced'>
4241 LICENSE = "GFDL-1.2 &amp; GPLv2"
4242 LICENSE_${PN} = "GPLv2"
4243 LICENSE_${PN}-doc = "GFDL-1.2"
4244 </literallayout>
4245 </para>
4246 </glossdef>
4247 </glossentry>
4248
4249 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
4250 <glossdef>
4251 <para>Path to additional licenses used during the build.
4252 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
4253 to define the directory that holds common license text used during the build.
4254 The <filename>LICENSE_PATH</filename> variable allows you to extend that
4255 location to other areas that have additional licenses:
4256 <literallayout class='monospaced'>
4257 LICENSE_PATH += "/path/to/additional/common/licenses"
4258 </literallayout></para>
4259 </glossdef>
4260 </glossentry>
4261
4262 <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
4263 <glossdef>
4264 <para>
4265 Defines the kernel type to be used in assembling the
4266 configuration.
4267 The linux-yocto recipes define "standard", "tiny", and
4268 "preempt-rt" kernel types.
4269 See the
4270 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
4271 section in the Yocto Project Linux Kernel Development
4272 Manual for more information on kernel types.
4273 </para>
4274
4275 <para>
4276 If you do not specify a
4277 <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
4278 "standard".
4279 Together with
4280 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
4281 the <filename>LINUX_KERNEL_TYPE</filename> variable
4282 defines the search
4283 arguments used by the kernel tools to find the appropriate
4284 description within the kernel
4285 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
4286 with which to build out the sources and configuration.
4287 </para>
4288 </glossdef>
4289 </glossentry>
4290
4291 <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
4292 <glossdef>
4293 <para>The Linux version from <filename>kernel.org</filename>
4294 on which the Linux kernel image being built using the
4295 OpenEmbedded build system is based.
4296 You define this variable in the kernel recipe.
4297 For example, the <filename>linux-yocto-3.4.bb</filename>
4298 kernel recipe found in
4299 <filename>meta/recipes-kernel/linux</filename>
4300 defines the variables as follows:
4301 <literallayout class='monospaced'>
4302 LINUX_VERSION ?= "3.4.24"
4303 </literallayout>
4304 The <filename>LINUX_VERSION</filename> variable is used to
4305 define <link linkend='var-PV'><filename>PV</filename></link>
4306 for the recipe:
4307 <literallayout class='monospaced'>
4308 PV = "${LINUX_VERSION}+git${SRCPV}"
4309 </literallayout></para>
4310 </glossdef>
4311 </glossentry>
4312
4313 <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
4314 <glossdef>
4315 <para>A string extension compiled into the version
4316 string of the Linux kernel built with the OpenEmbedded
4317 build system.
4318 You define this variable in the kernel recipe.
4319 For example, the linux-yocto kernel recipes all define
4320 the variable as follows:
4321 <literallayout class='monospaced'>
4322 LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
4323 </literallayout>
4324 Defining this variable essentially sets the
4325 Linux kernel configuration item
4326 <filename>CONFIG_LOCALVERSION</filename>, which is visible
4327 through the <filename>uname</filename> command.
4328 Here is an example that shows the extension assuming it
4329 was set as previously shown:
4330 <literallayout class='monospaced'>
4331 $ uname -r
4332 3.7.0-rc8-custom
4333 </literallayout>
4334 </para>
4335 </glossdef>
4336 </glossentry>
4337
4338 <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
4339 <glossdef>
4340 <para>
4341 Specifies the directory to which the OpenEmbedded build
4342 system writes overall log files.
4343 The default directory is <filename>${TMPDIR}/log</filename>.
4344 </para>
4345 <para>
4346 For the directory containing logs specific to each task,
4347 see the <link linkend='var-T'><filename>T</filename></link>
4348 variable.
4349 </para>
4350 </glossdef>
4351 </glossentry>
4352
4353 </glossdiv>
4354
4355 <glossdiv id='var-glossary-m'><title>M</title>
4356
4357 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
4358 <glossdef>
4359 <para>
4360 Specifies the target device for which the image is built.
4361 You define <filename>MACHINE</filename> in the
4362 <filename>local.conf</filename> file found in the
4363 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
4364 By default, <filename>MACHINE</filename> is set to
4365 "qemux86", which is an x86-based architecture machine to
4366 be emulated using QEMU:
4367 <literallayout class='monospaced'>
4368 MACHINE ?= "qemux86"
4369 </literallayout>
4370 The variable corresponds to a machine configuration file of the
4371 same name, through which machine-specific configurations are set.
4372 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
4373 exists the corresponding <filename>qemux86.conf</filename> machine
4374 configuration file, which can be found in the
4375 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
4376 in <filename>meta/conf/machine</filename>.
4377 </para>
4378
4379 <para>
4380 The list of machines supported by the Yocto Project as
4381 shipped include the following:
4382 <literallayout class='monospaced'>
4383 MACHINE ?= "qemuarm"
4384 MACHINE ?= "qemumips"
4385 MACHINE ?= "qemuppc"
4386 MACHINE ?= "qemux86"
4387 MACHINE ?= "qemux86-64"
4388 MACHINE ?= "genericx86"
4389 MACHINE ?= "genericx86-64"
4390 MACHINE ?= "beaglebone"
4391 MACHINE ?= "mpc8315e-rdb"
4392 MACHINE ?= "edgerouter"
4393 </literallayout>
4394 The last five are Yocto Project reference hardware boards, which
4395 are provided in the <filename>meta-yocto-bsp</filename> layer.
4396 <note>Adding additional Board Support Package (BSP) layers
4397 to your configuration adds new possible settings for
4398 <filename>MACHINE</filename>.
4399 </note>
4400 </para>
4401 </glossdef>
4402 </glossentry>
4403
4404 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
4405 <glossdef>
4406 <para></para>
4407 <para>
4408 A list of required machine-specific packages to install as part of
4409 the image being built.
4410 The build process depends on these packages being present.
4411 Furthermore, because this is a "machine essential" variable, the list of
4412 packages are essential for the machine to boot.
4413 The impact of this variable affects images based on
4414 <filename>packagegroup-core-boot</filename>,
4415 including the <filename>core-image-minimal</filename> image.
4416 </para>
4417 <para>
4418 This variable is similar to the
4419 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
4420 variable with the exception that the image being built has a build
4421 dependency on the variable's list of packages.
4422 In other words, the image will not build if a file in this list is not found.
4423 </para>
4424 <para>
4425 As an example, suppose the machine for which you are building requires
4426 <filename>example-init</filename> to be run during boot to initialize the hardware.
4427 In this case, you would use the following in the machine's
4428 <filename>.conf</filename> configuration file:
4429 <literallayout class='monospaced'>
4430 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
4431 </literallayout>
4432 </para>
4433 </glossdef>
4434 </glossentry>
4435
4436 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
4437 <glossdef>
4438 <para></para>
4439 <para>
4440 A list of recommended machine-specific packages to install as part of
4441 the image being built.
4442 The build process does not depend on these packages being present.
4443 However, because this is a "machine essential" variable, the list of
4444 packages are essential for the machine to boot.
4445 The impact of this variable affects images based on
4446 <filename>packagegroup-core-boot</filename>,
4447 including the <filename>core-image-minimal</filename> image.
4448 </para>
4449 <para>
4450 This variable is similar to the
4451 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
4452 variable with the exception that the image being built does not have a build
4453 dependency on the variable's list of packages.
4454 In other words, the image will still build if a package in this list is not found.
4455 Typically, this variable is used to handle essential kernel modules, whose
4456 functionality may be selected to be built into the kernel rather than as a module,
4457 in which case a package will not be produced.
4458 </para>
4459 <para>
4460 Consider an example where you have a custom kernel where a specific touchscreen
4461 driver is required for the machine to be usable.
4462 However, the driver can be built as a module or
4463 into the kernel depending on the kernel configuration.
4464 If the driver is built as a module, you want it to be installed.
4465 But, when the driver is built into the kernel, you still want the
4466 build to succeed.
4467 This variable sets up a "recommends" relationship so that in the latter case,
4468 the build will not fail due to the missing package.
4469 To accomplish this, assuming the package for the module was called
4470 <filename>kernel-module-ab123</filename>, you would use the
4471 following in the machine's <filename>.conf</filename> configuration
4472 file:
4473 <literallayout class='monospaced'>
4474 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
4475 </literallayout>
4476 </para>
4477 <para>
4478 Some examples of these machine essentials are flash, screen, keyboard, mouse,
4479 or touchscreen drivers (depending on the machine).
4480 </para>
4481 </glossdef>
4482 </glossentry>
4483
4484 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
4485 <glossdef>
4486 <para>
4487 A list of machine-specific packages to install as part of the
4488 image being built that are not essential for the machine to boot.
4489 However, the build process for more fully-featured images
4490 depends on the packages being present.
4491 </para>
4492 <para>
4493 This variable affects all images based on
4494 <filename>packagegroup-base</filename>, which does not include the
4495 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
4496 images.
4497 </para>
4498 <para>
4499 The variable is similar to the
4500 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
4501 variable with the exception that the image being built has a build
4502 dependency on the variable's list of packages.
4503 In other words, the image will not build if a file in this list is not found.
4504 </para>
4505 <para>
4506 An example is a machine that has WiFi capability but is not
4507 essential for the machine to boot the image.
4508 However, if you are building a more fully-featured image, you want to enable
4509 the WiFi.
4510 The package containing the firmware for the WiFi hardware is always
4511 expected to exist, so it is acceptable for the build process to depend upon
4512 finding the package.
4513 In this case, assuming the package for the firmware was called
4514 <filename>wifidriver-firmware</filename>, you would use the following in the
4515 <filename>.conf</filename> file for the machine:
4516 <literallayout class='monospaced'>
4517 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
4518 </literallayout>
4519 </para>
4520 </glossdef>
4521 </glossentry>
4522
4523 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
4524 <glossdef>
4525 <para></para>
4526 <para>
4527 A list of machine-specific packages to install as part of the
4528 image being built that are not essential for booting the machine.
4529 The image being built has no build dependency on this list of packages.
4530 </para>
4531 <para>
4532 This variable affects only images based on
4533 <filename>packagegroup-base</filename>, which does not include the
4534 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
4535 images.
4536 </para>
4537 <para>
4538 This variable is similar to the
4539 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
4540 variable with the exception that the image being built does not have a build
4541 dependency on the variable's list of packages.
4542 In other words, the image will build if a file in this list is not found.
4543 </para>
4544 <para>
4545 An example is a machine that has WiFi capability but is not essential
4546 For the machine to boot the image.
4547 However, if you are building a more fully-featured image, you want to enable
4548 WiFi.
4549 In this case, the package containing the WiFi kernel module will not be produced
4550 if the WiFi driver is built into the kernel, in which case you still want the
4551 build to succeed instead of failing as a result of the package not being found.
4552 To accomplish this, assuming the package for the module was called
4553 <filename>kernel-module-examplewifi</filename>, you would use the
4554 following in the <filename>.conf</filename> file for the machine:
4555 <literallayout class='monospaced'>
4556 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
4557 </literallayout>
4558 </para>
4559 </glossdef>
4560 </glossentry>
4561
4562 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
4563 <glossdef>
4564 <para>
4565 Specifies the list of hardware features the
4566 <link linkend='var-MACHINE'><filename>MACHINE</filename></link> is capable
4567 of supporting.
4568 For related information on enabling features, see the
4569 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>,
4570 <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>,
4571 and
4572 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
4573 variables.
4574 </para>
4575
4576 <para>
4577 For a list of hardware features supported by the Yocto
4578 Project as shipped, see the
4579 "<link linkend='ref-features-machine'>Machine Features</link>"
4580 section.
4581 </para>
4582 </glossdef>
4583 </glossentry>
4584
4585 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
4586 <glossdef>
4587 <para>Features to be added to
4588 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
4589 if not also present in
4590 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
4591 </para>
4592
4593 <para>
4594 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
4595 It is not intended to be user-configurable.
4596 It is best to just reference the variable to see which machine features are
4597 being backfilled for all machine configurations.
4598 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
4599 more information.
4600 </para>
4601 </glossdef>
4602 </glossentry>
4603
4604 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
4605 <glossdef>
4606 <para>Features from
4607 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
4608 that should not be backfilled (i.e. added to
4609 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
4610 during the build.
4611 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
4612 more information.
4613 </para>
4614 </glossdef>
4615 </glossentry>
4616
4617 <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
4618 <glossdef>
4619 <para>
4620 Lists overrides specific to the current machine.
4621 By default, this list includes the value
4622 of <filename><link linkend='var-MACHINE'>MACHINE</link></filename>.
4623 You can extend the list to apply variable overrides for
4624 classes of machines.
4625 For example, all QEMU emulated machines (e.g. qemuarm,
4626 qemux86, and so forth) include a common file named
4627 <filename>meta/conf/machine/include/qemu.inc</filename>
4628 that prepends <filename>MACHINEOVERRIDES</filename> with
4629 the following variable override:
4630 <literallayout class='monospaced'>
4631 MACHINEOVERRIDES =. "qemuall:"
4632 </literallayout>
4633 Applying an override like <filename>qemuall</filename>
4634 affects all QEMU emulated machines elsewhere.
4635 Here is an example from the
4636 <filename>connman-conf</filename> recipe:
4637 <literallayout class='monospaced'>
4638 SRC_URI_append_qemuall = "file://wired.config \
4639 file://wired-setup \
4640 "
4641 </literallayout>
4642 </para>
4643 </glossdef>
4644 </glossentry>
4645
4646 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
4647 <glossdef>
4648 <para>The email address of the distribution maintainer.</para>
4649 </glossdef>
4650 </glossentry>
4651
4652 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
4653 <glossdef>
4654 <para>
4655 Specifies additional paths from which the OpenEmbedded
4656 build system gets source code.
4657 When the build system searches for source code, it first
4658 tries the local download directory.
4659 If that location fails, the build system tries locations
4660 defined by
4661 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
4662 the upstream source, and then locations specified by
4663 <filename>MIRRORS</filename> in that order.
4664 </para>
4665
4666 <para>
4667 Assuming your distribution
4668 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
4669 is "poky", the default value for
4670 <filename>MIRRORS</filename> is defined in the
4671 <filename>conf/distro/poky.conf</filename> file in the
4672 <filename>meta-yocto</filename> Git repository.
4673 </para>
4674 </glossdef>
4675 </glossentry>
4676
4677 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
4678 <glossdef>
4679 <para>
4680 Specifies a prefix has been added to
4681 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
4682 of a recipe or package, such as a Multilib version.
4683 The variable is used in places where the prefix needs to be
4684 added to or removed from a the name (e.g. the
4685 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
4686 <filename>MLPREFIX</filename> gets set when a prefix has been
4687 added to <filename>PN</filename>.
4688 </para>
4689 </glossdef>
4690 </glossentry>
4691
4692 <glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm>
4693 <glossdef>
4694 <para>
4695 Lists kernel modules that need to be auto-loaded during
4696 boot.
4697 </para>
4698
4699 <para>
4700 You can use this variable anywhere that it can be
4701 recognized by the kernel recipe or out-of-tree kernel
4702 module recipe (e.g. a machine configuration file, a
4703 distribution configuration file, an append file for the
4704 recipe, or the recipe itself).
4705 </para>
4706
4707 <para>
4708 Specify it as follows:
4709 <literallayout class='monospaced'>
4710 module_autoload_&lt;modname&gt; = "modname1 modname2 modname3"
4711 </literallayout>
4712 You must use the kernel module name override.
4713 </para>
4714
4715 <para>
4716 Including <filename>module_autoload</filename> causes the
4717 OpenEmbedded build system to populate the
4718 <filename>/etc/modules-load.d/modname.conf</filename>
4719 file with the list of modules to be auto-loaded on boot.
4720 The modules appear one-per-line in the file.
4721 Here is an example of the most common use case:
4722 <literallayout class='monospaced'>
4723 module_autoload_modname = "modname"
4724 </literallayout>
4725 </para>
4726
4727 <para>
4728 For information on how to populate the
4729 <filename>modname.conf</filename> file with
4730 <filename>modprobe.d</filename> syntax lines, see the
4731 <link linkend='var-module_conf'><filename>module_conf</filename></link>
4732 variable.
4733 </para>
4734 </glossdef>
4735 </glossentry>
4736
4737 <glossentry id='var-module_conf'><glossterm>module_conf</glossterm>
4738 <glossdef>
4739 <para>
4740 Specifies <filename>modprobe.d</filename> syntax lines
4741 for inclusion in the
4742 <filename>/etc/modprobe.d/modname.conf</filename> file.
4743 </para>
4744
4745 <para>
4746 You can use this variable anywhere that it can be
4747 recognized by the kernel recipe or out-of-tree kernel
4748 module recipe (e.g. a machine configuration file, a
4749 distribution configuration file, an append file for the
4750 recipe, or the recipe itself).
4751 </para>
4752
4753 <para>
4754 Here is the general syntax:
4755 <literallayout class='monospaced'>
4756 module_conf_&lt;modname&gt; = "modprobe.d-syntax"
4757 </literallayout>
4758 You must use the kernel module name override.
4759 </para>
4760
4761 <para>
4762 Run <filename>man modprobe.d</filename> in the shell to
4763 find out more information on the exact syntax for lines
4764 you want to provide with <filename>module_conf</filename>.
4765 </para>
4766
4767 <para>
4768 Including <filename>module_conf</filename> causes the
4769 OpenEmbedded build system to populate the
4770 <filename>/etc/modprobe.d/modname.conf</filename>
4771 file with <filename>modprobe.d</filename> syntax lines.
4772 Here is an example:
4773 <literallayout class='monospaced'>
4774 module_conf_&lt;modname&gt; = "options modname arg1=val1 arg2=val2"
4775 </literallayout>
4776 </para>
4777
4778 <para>
4779 For information on how to specify kernel modules to
4780 auto-load on boot, see the
4781 <link linkend='var-module_autoload'><filename>module_autoload</filename></link>
4782 variable.
4783 </para>
4784 </glossdef>
4785 </glossentry>
4786
4787 <glossentry id='var-MODULE_IMAGE_BASE_NAME'><glossterm>MODULE_IMAGE_BASE_NAME</glossterm>
4788 <glossdef>
4789 <para>
4790 The base name of the kernel modules tarball.
4791 This variable is set in the
4792 <link linkend='ref-classes-kernel'>kernel</link> class
4793 as follows:
4794 <literallayout class='monospaced'>
4795 MODULE_IMAGE_BASE_NAME ?= "modules-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
4796 </literallayout>
4797 See the
4798 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
4799 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
4800 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
4801 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
4802 and
4803 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
4804 variables for additional information.
4805 </para>
4806 </glossdef>
4807 </glossentry>
4808
4809 <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
4810 <glossdef>
4811 <para>
4812 Controls creation of the <filename>modules-*.tgz</filename>
4813 file.
4814 Set this variable to "0" to disable creation of this
4815 file, which contains all of the kernel modules resulting
4816 from a kernel build.
4817 </para>
4818 </glossdef>
4819 </glossentry>
4820
4821 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
4822 <glossdef>
4823 <para>
4824 Separates files for different machines such that you can build
4825 for multiple target machines using the same output directories.
4826 See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable
4827 for an example.
4828 </para>
4829 </glossdef>
4830 </glossentry>
4831
4832 </glossdiv>
4833
4834 <glossdiv id='var-glossary-n'><title>N</title>
4835
4836 <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
4837 <glossdef>
4838 <para>
4839 A string identifying the host distribution.
4840 Strings consist of the host distributor ID
4841 followed by the release, as reported by the
4842 <filename>lsb_release</filename> tool
4843 or as read from <filename>/etc/lsb-release</filename>.
4844 For example, when running a build on Ubuntu 12.10, the value
4845 is "Ubuntu-12.10".
4846 If this information is unable to be determined, the value
4847 resolves to "Unknown".
4848 </para>
4849 <para>
4850 This variable is used by default to isolate native shared
4851 state packages for different distributions (e.g. to avoid
4852 problems with <filename>glibc</filename> version
4853 incompatibilities).
4854 Additionally, the variable is checked against
4855 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
4856 if that variable is set.
4857 </para>
4858 </glossdef>
4859 </glossentry>
4860
4861 <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
4862 <glossdef>
4863 <para>
4864 Prevents installation of all "recommended-only" packages.
4865 Recommended-only packages are packages installed only
4866 through the
4867 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
4868 variable).
4869 Setting the <filename>NO_RECOMMENDATIONS</filename> variable
4870 to "1" turns this feature on:
4871 <literallayout class='monospaced'>
4872 NO_RECOMMENDATIONS = "1"
4873 </literallayout>
4874 You can set this variable globally in your
4875 <filename>local.conf</filename> file or you can attach it to
4876 a specific image recipe by using the recipe name override:
4877 <literallayout class='monospaced'>
4878 NO_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
4879 </literallayout>
4880 </para>
4881
4882 <para>
4883 It is important to realize that if you choose to not install
4884 packages using this variable and some other packages are
4885 dependent on them (i.e. listed in a recipe's
4886 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
4887 variable), the OpenEmbedded build system ignores your
4888 request and will install the packages to avoid dependency
4889 errors.
4890 <note>
4891 Some recommended packages might be required for certain
4892 system functionality, such as kernel modules.
4893 It is up to you to add packages with the
4894 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
4895 variable.
4896 </note>
4897 </para>
4898
4899 <para>
4900 Support for this variable exists only when using the
4901 IPK and RPM packaging backend.
4902 Support does not exist for DEB.
4903 </para>
4904
4905 <para>
4906 See the
4907 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
4908 and the
4909 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
4910 variables for related information.
4911 </para>
4912 </glossdef>
4913 </glossentry>
4914
4915 <glossentry id='var-NOHDD'><glossterm>NOHDD</glossterm>
4916 <glossdef>
4917 <para>
4918 Causes the OpenEmbedded build system to skip building the
4919 <filename>.hddimg</filename> image.
4920 The <filename>NOHDD</filename> variable is used with the
4921 <link linkend='ref-classes-bootimg'><filename>buildimg</filename></link>
4922 class.
4923 Set the variable to "1" to prevent the
4924 <filename>.hddimg</filename> image from being built.
4925 </para>
4926 </glossdef>
4927 </glossentry>
4928
4929 <glossentry id='var-NOISO'><glossterm>NOISO</glossterm>
4930 <glossdef>
4931 <para>
4932 Causes the OpenEmbedded build system to skip building the
4933 ISO image.
4934 The <filename>NOISO</filename> variable is used with the
4935 <link linkend='ref-classes-bootimg'><filename>buildimg</filename></link>
4936 class.
4937 Set the variable to "1" to prevent the ISO image from
4938 being built.
4939 To enable building an ISO image, set the variable to "0".
4940 </para>
4941 </glossdef>
4942 </glossentry>
4943
4944 </glossdiv>
4945
4946 <glossdiv id='var-glossary-o'><title>O</title>
4947
4948 <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
4949 <glossdef>
4950 <para>
4951 When a recipe inherits the
4952 <filename>binconfig.bbclass</filename> class, this variable
4953 specifies additional arguments passed to the "sed" command.
4954 The sed command alters any paths in configuration scripts
4955 that have been set up during compilation.
4956 Inheriting this class results in all paths in these scripts
4957 being changed to point into the
4958 <filename>sysroots/</filename> directory so that all builds
4959 that use the script will use the correct directories
4960 for the cross compiling layout.
4961 </para>
4962
4963 <para>
4964 See the <filename>meta/classes/binconfig.bbclass</filename>
4965 in the
4966 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
4967 for details on how this class applies these additional
4968 sed command arguments.
4969 For general information on the
4970 <filename>binconfig.bbclass</filename> class, see the
4971 "<link linkend='ref-classes-binconfig'>Binary Configuration Scripts - <filename>binconfig.bbclass</filename></link>"
4972 section.
4973 </para>
4974 </glossdef>
4975 </glossentry>
4976
4977 <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
4978 <glossdef>
4979 <para>
4980 An internal variable used to tell the OpenEmbedded build
4981 system what Python modules to import for every Python
4982 function run by the system.
4983 </para>
4984
4985 <note>
4986 Do not set this variable.
4987 It is for internal use only.
4988 </note>
4989 </glossdef>
4990 </glossentry>
4991
4992 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
4993 <glossdef>
4994 <para>
4995 Controls how the OpenEmbedded build system spawns
4996 interactive terminals on the host development system
4997 (e.g. using the BitBake command with the
4998 <filename>-c devshell</filename> command-line option).
4999 For more information, see the
5000 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
5001 in the Yocto Project Development Manual.
5002 </para>
5003
5004 <para>
5005 You can use the following values for the
5006 <filename>OE_TERMINAL</filename> variable:
5007 <literallayout class='monospaced'>
5008 auto
5009 gnome
5010 xfce
5011 rxvt
5012 screen
5013 konsole
5014 none
5015 </literallayout>
5016 <note>Konsole support only works for KDE 3.x.
5017 Also, "auto" is the default behavior for
5018 <filename>OE_TERMINAL</filename></note>
5019 </para>
5020 </glossdef>
5021 </glossentry>
5022
5023 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
5024 <glossdef>
5025 <para>
5026 The directory from which the top-level build environment
5027 setup script is sourced.
5028 The Yocto Project makes two top-level build environment
5029 setup scripts available:
5030 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
5031 and
5032 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
5033 When you run one of these scripts, the
5034 <filename>OEROOT</filename> variable resolves to the
5035 directory that contains the script.
5036 </para>
5037
5038 <para>
5039 For additional information on how this variable is used,
5040 see the initialization scripts.
5041 </para>
5042 </glossdef>
5043 </glossentry>
5044
5045 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
5046 <glossdef>
5047 <para>
5048 Declares the oldest version of the Linux kernel that the
5049 produced binaries must support.
5050 This variable is passed into the build of the Embedded
5051 GNU C Library (<filename>eglibc</filename>).
5052 </para>
5053
5054 <para>
5055 The default for this variable comes from the
5056 <filename>meta/conf/bitbake.conf</filename> configuration
5057 file.
5058 You can override this default by setting the variable
5059 in a custom distribution configuration file.
5060 </para>
5061 </glossdef>
5062 </glossentry>
5063
5064 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
5065 <glossdef>
5066 <para>
5067 BitBake uses <filename>OVERRIDES</filename> to control
5068 what variables are overridden after BitBake parses
5069 recipes and configuration files.
5070 You can find more information on how overrides are handled
5071 in the
5072 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake Manual</ulink>.
5073 </para>
5074 </glossdef>
5075 </glossentry>
5076 </glossdiv>
5077
5078 <glossdiv id='var-glossary-p'><title>P</title>
5079
5080 <glossentry id='var-P'><glossterm>P</glossterm>
5081 <glossdef>
5082 <para>The recipe name and version.
5083 <filename>P</filename> is comprised of the following:
5084 <literallayout class='monospaced'>
5085 ${PN}-${PV}
5086 </literallayout></para>
5087 </glossdef>
5088 </glossentry>
5089
5090 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
5091 <glossdef>
5092 <para>The architecture of the resulting package or packages.</para>
5093 </glossdef>
5094 </glossentry>
5095
5096 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
5097 <glossdef>
5098 <para>Enables easily adding packages to
5099 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
5100 before <filename>${<link linkend='var-PN'>PN</link>}</filename>
5101 so that those added packages can pick up files that would normally be
5102 included in the default package.</para>
5103 </glossdef>
5104 </glossentry>
5105
5106 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
5107 <glossdef>
5108 <para>
5109 This variable, which is set in the
5110 <filename>local.conf</filename> configuration file found in
5111 the <filename>conf</filename> folder of the
5112 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
5113 specifies the package manager the OpenEmbedded build system
5114 uses when packaging data.
5115 </para>
5116
5117 <para>
5118 You can provide one or more of the following arguments for
5119 the variable:
5120 <literallayout class='monospaced'>
5121 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"
5122 </literallayout>
5123 The build system uses only the first argument in the list
5124 as the package manager when creating your image or SDK.
5125 However, packages will be created using any additional
5126 packaging classes you specify.
5127 For example, if you use the following in your
5128 <filename>local.conf</filename> file:
5129 <literallayout class='monospaced'>
5130 PACKAGE_CLASSES ?= "package_ipk package_tar"
5131 </literallayout>
5132 The OpenEmbedded build system uses the IPK package manager
5133 to create your image or SDK as well as generating
5134 TAR packages.
5135 </para>
5136
5137 <para>
5138 You cannot specify the
5139 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
5140 class first in the list.
5141 Files using the <filename>.tar</filename> format cannot
5142 be used as a substitute packaging format
5143 for DEB, RPM, and IPK formatted files for your image or SDK.
5144 </para>
5145
5146 <para>
5147 For information on packaging and build performance effects
5148 as a result of the package manager in use, see the
5149 "<link linkend='ref-classes-package'><filename>package.bbclass</filename></link>"
5150 section.
5151 </para>
5152 </glossdef>
5153 </glossentry>
5154
5155 <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
5156 <glossdef>
5157 <para>
5158 Lists packages that should not be installed into an image.
5159 For example:
5160 <literallayout class='monospaced'>
5161 PACKAGE_EXCLUDE = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
5162 </literallayout>
5163 You can set this variable globally in your
5164 <filename>local.conf</filename> file or you can attach it to
5165 a specific image recipe by using the recipe name override:
5166 <literallayout class='monospaced'>
5167 PACKAGE_EXCLUDE_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
5168 </literallayout>
5169 </para>
5170
5171 <para>
5172 If you choose to not install
5173 a package using this variable and some other package is
5174 dependent on it (i.e. listed in a recipe's
5175 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
5176 variable), the OpenEmbedded build system generates a fatal
5177 installation error.
5178 Because the build system halts the process with a fatal
5179 error, you can use the variable with an iterative
5180 development process to remove specific components from a
5181 system.
5182 </para>
5183
5184 <para>
5185 Support for this variable exists only when using the
5186 IPK and RPM packaging backend.
5187 Support does not exist for DEB.
5188 </para>
5189
5190 <para>
5191 See the
5192 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
5193 and the
5194 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
5195 variables for related information.
5196 </para>
5197 </glossdef>
5198 </glossentry>
5199
5200 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
5201 <glossdef>
5202 <para>Specifies the list of architectures compatible with the device CPU.
5203 This variable is useful when you build for several different devices that use
5204 miscellaneous processors such as XScale and ARM926-EJS).</para>
5205 </glossdef>
5206 </glossentry>
5207
5208 <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
5209 <glossdef>
5210
5211 <para>
5212 The <filename>PACKAGE_GROUP</filename> variable has been
5213 renamed to
5214 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>.
5215 See the variable description for
5216 <filename>FEATURE_PACKAGES</filename> for information.
5217 </para>
5218
5219 <para>
5220 If if you use the <filename>PACKAGE_GROUP</filename>
5221 variable, the OpenEmbedded build system issues a warning
5222 message.
5223 </para>
5224 </glossdef>
5225 </glossentry>
5226
5227 <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
5228 <glossdef>
5229 <para>
5230 The final list of packages passed to the package manager
5231 for installation into the image.
5232 </para>
5233
5234 <para>
5235 Because the package manager controls actual installation
5236 of all packages, the list of packages passed using
5237 <filename>PACKAGE_INSTALL</filename> is not the final list
5238 of packages that are actually installed.
5239 This variable is internal to the image construction
5240 code.
5241 Consequently, in general, you should use the
5242 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
5243 variable to specify packages for installation.
5244 The exception to this is when working with
5245 the
5246 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
5247 image.
5248 When working with an initial RAM disk (initramfs)
5249 image, use the <filename>PACKAGE_INSTALL</filename>
5250 variable.
5251 </para>
5252 </glossdef>
5253 </glossentry>
5254
5255 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
5256 <glossdef>
5257 <para>
5258 This variable provides a means of enabling or disabling
5259 features of a recipe on a per-recipe basis.
5260 <filename>PACKAGECONFIG</filename> blocks are defined
5261 in recipes when you specify features and then arguments
5262 that define feature behaviors.
5263 Here is the basic block structure:
5264 <literallayout class='monospaced'>
5265 PACKAGECONFIG ??= "f1 f2 f3 ..."
5266 PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1"
5267 PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2"
5268 PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3"
5269 </literallayout>
5270 The <filename>PACKAGECONFIG</filename>
5271 variable itself specifies a space-separated list of the
5272 features to enable.
5273 Following the features, you can determine the behavior of
5274 each feature by providing up to four order-dependent
5275 arguments, which are separated by commas.
5276 You can omit any argument you like but must retain the
5277 separating commas.
5278 The order is important and specifies the following:
5279 <orderedlist>
5280 <listitem><para>Extra arguments
5281 that should be added to the configure script
5282 argument list
5283 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>)
5284 if the feature is enabled.</para></listitem>
5285 <listitem><para>Extra arguments
5286 that should be added to <filename>EXTRA_OECONF</filename>
5287 if the feature is disabled.
5288 </para></listitem>
5289 <listitem><para>Additional build dependencies
5290 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
5291 that should be added if the feature is enabled.
5292 </para></listitem>
5293 <listitem><para>Additional runtime dependencies
5294 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
5295 that should be added if the feature is enabled.
5296 </para></listitem>
5297 </orderedlist>
5298 </para>
5299
5300 <para>
5301 Consider the following
5302 <filename>PACKAGECONFIG</filename> block taken from the
5303 <filename>librsvg</filename> recipe.
5304 In this example the feature is <filename>croco</filename>,
5305 which has three arguments that determine the feature's
5306 behavior.
5307 <literallayout class='monospaced'>
5308 PACKAGECONFIG ??= "croco"
5309 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
5310 </literallayout>
5311 The <filename>--with-croco</filename> and
5312 <filename>libcroco</filename> arguments apply only if
5313 the feature is enabled.
5314 In this case, <filename>--with-croco</filename> is
5315 added to the configure script argument list and
5316 <filename>libcroco</filename> is added to
5317 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
5318 On the other hand, if the feature is disabled say through
5319 a <filename>.bbappend</filename> file in another layer, then
5320 the second argument <filename>--without-croco</filename> is
5321 added to the configure script rather than
5322 <filename>--with-croco</filename>.
5323 </para>
5324
5325 <para>
5326 The basic <filename>PACKAGECONFIG</filename> structure
5327 previously described holds true regardless of whether you
5328 are creating a block or changing a block.
5329 When creating a block, use the structure inside your
5330 recipe.
5331 </para>
5332
5333 <para>
5334 If you want to change an existing
5335 <filename>PACKAGECONFIG</filename> block, you can do so
5336 one of two ways:
5337 <itemizedlist>
5338 <listitem><para><emphasis>Append file:</emphasis>
5339 Create an append file named
5340 <filename>&lt;recipename&gt;.bbappend</filename> in your
5341 layer and override the value of
5342 <filename>PACKAGECONFIG</filename>.
5343 You can either completely override the variable:
5344 <literallayout class='monospaced'>
5345 PACKAGECONFIG="f4 f5"
5346 </literallayout>
5347 Or, you can just append the variable:
5348 <literallayout class='monospaced'>
5349 PACKAGECONFIG_append = " f4"
5350 </literallayout></para></listitem>
5351 <listitem><para><emphasis>Configuration file:</emphasis>
5352 This method is identical to changing the block
5353 through an append file except you edit your
5354 <filename>local.conf</filename> or
5355 <filename>&lt;mydistro&gt;.conf</filename> file.
5356 As with append files previously described,
5357 you can either completely override the variable:
5358 <literallayout class='monospaced'>
5359 PACKAGECONFIG_pn-&lt;recipename&gt;="f4 f5"
5360 </literallayout>
5361 Or, you can just amend the variable:
5362 <literallayout class='monospaced'>
5363 PACKAGECONFIG_append_pn-&lt;recipename&gt; = " f4"
5364 </literallayout></para></listitem>
5365 </itemizedlist>
5366 </para>
5367 </glossdef>
5368 </glossentry>
5369
5370 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
5371 <glossdef>
5372 <para>The list of packages to be created from the recipe.
5373 The default value is the following:
5374 <literallayout class='monospaced'>
5375 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
5376 </literallayout></para>
5377 </glossdef>
5378 </glossentry>
5379
5380 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
5381 <glossdef>
5382 <para>
5383 A promise that your recipe satisfies runtime dependencies
5384 for optional modules that are found in other recipes.
5385 <filename>PACKAGES_DYNAMIC</filename>
5386 does not actually satisfy the dependencies, it only states that
5387 they should be satisfied.
5388 For example, if a hard, runtime dependency
5389 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
5390 of another package is satisfied
5391 at build time through the <filename>PACKAGES_DYNAMIC</filename>
5392 variable, but a package with the module name is never actually
5393 produced, then the other package will be broken.
5394 Thus, if you attempt to include that package in an image,
5395 you will get a dependency failure from the packaging system
5396 during <filename>do_rootfs</filename>.
5397 </para>
5398 <para>
5399 Typically, if there is a chance that such a situation can
5400 occur and the package that is not created is valid
5401 without the dependency being satisfied, then you should use
5402 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
5403 (a soft runtime dependency) instead of
5404 <filename>RDEPENDS</filename>.
5405 </para>
5406
5407 <para>
5408 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
5409 variable when you are splitting packages, see the
5410 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
5411 in the Yocto Project Development Manual.
5412 </para>
5413 </glossdef>
5414 </glossentry>
5415
5416 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
5417 <glossdef>
5418 <para>
5419 Extra options passed to the <filename>make</filename>
5420 command during the <filename>do_compile</filename> task
5421 in order to specify parallel compilation on the local
5422 build host.
5423 This variable is usually in the form "-j &lt;x&gt;",
5424 where x represents the maximum number of parallel threads
5425 <filename>make</filename> can run.
5426 </para>
5427
5428 <para>
5429 If your development host supports multiple cores, a good
5430 rule of thumb is to set this variable to twice the number
5431 of cores on the host.
5432 If you do not set <filename>PARALLEL_MAKE</filename>, it
5433 defaults to the number of cores your build system has.
5434 <note>
5435 Individual recipes might clear out this variable if
5436 the software being built has problems running its
5437 <filename>make</filename> process in parallel.
5438 </note>
5439 </para>
5440 </glossdef>
5441 </glossentry>
5442
5443 <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
5444 <glossdef>
5445 <para>
5446 Extra options passed to the
5447 <filename>make install</filename> command during the
5448 <filename>do_install</filename> task in order to specify
5449 parallel installation.
5450 This variable defaults to the value of
5451 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
5452 <note>
5453 Individual recipes might clear out this variable if
5454 the software being built has problems running its
5455 <filename>make install</filename> process in parallel.
5456 </note>
5457 </para>
5458 </glossdef>
5459 </glossentry>
5460
5461 <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
5462 <glossdef>
5463 <para>
5464 Determines the action to take when a patch fails.
5465 You can set this variable to one of two values: "noop" and
5466 "user".
5467 </para>
5468
5469 <para>
5470 The default value of "noop" causes the build to simply fail
5471 when the OpenEmbedded build system cannot successfully
5472 apply a patch.
5473 Setting the value to "user" causes the build system to
5474 launch a shell and places you in the right location so that
5475 you can manually resolve the conflicts.
5476 </para>
5477
5478 <para>
5479 Set this variable in your
5480 <filename>local.conf</filename> file.
5481 </para>
5482 </glossdef>
5483 </glossentry>
5484
5485 <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
5486 <glossdef>
5487 <para>
5488 Specifies the utility used to apply patches for a recipe
5489 during <filename>do_patch</filename>.
5490 You can specify one of three utilities: "patch", "quilt", or
5491 "git".
5492 The default utility used is "quilt" except for the
5493 quilt-native recipe itself.
5494 Because the quilt tool is not available at the
5495 time quilt-native is being patched, it uses "patch".
5496 </para>
5497
5498 <para>
5499 If you wish to use an alternative patching tool, set the
5500 variable in the recipe using one of the following:
5501 <literallayout class='monospaced'>
5502 PATCHTOOL = "patch"
5503 PATCHTOOL = "quilt"
5504 PATCHTOOL = "git"
5505 </literallayout>
5506 </para>
5507 </glossdef>
5508 </glossentry>
5509
5510 <glossentry id='var-PE'><glossterm>PE</glossterm>
5511 <glossdef>
5512 <para>
5513 The epoch of the recipe.
5514 By default, this variable is unset.
5515 The variable is used to make upgrades possible when the
5516 versioning scheme changes in some backwards incompatible
5517 way.
5518 </para>
5519 </glossdef>
5520 </glossentry>
5521
5522 <glossentry id='var-PF'><glossterm>PF</glossterm>
5523 <glossdef>
5524 <para>Specifies the recipe or package name and includes all version and revision
5525 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
5526 <filename>bash-4.2-r1/</filename>).
5527 This variable is comprised of the following:
5528 <literallayout class='monospaced'>
5529 ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
5530 </literallayout></para>
5531 </glossdef>
5532 </glossentry>
5533
5534 <glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm>
5535 <glossdef>
5536 <para>
5537 When a recipe inherits the
5538 <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link>
5539 class, this variable identifies packages that contain
5540 the pixbuf loaders used with
5541 <filename>gdk-pixbuf</filename>.
5542 By default, the <filename>pixbufcache</filename> class
5543 assumes that the loaders are in the recipe's main package
5544 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
5545 Use this variable if the loaders you need are in a package
5546 other than that main package.
5547 </para>
5548 </glossdef>
5549 </glossentry>
5550
5551 <glossentry id='var-PKG'><glossterm>PKG</glossterm>
5552 <glossdef>
5553 <para>
5554 The name of the resulting package created by the
5555 OpenEmbedded build system.
5556 <note>
5557 When using the <filename>PKG</filename> variable, you
5558 must use a package name override.
5559 </note>
5560 For example, when the
5561 <link linkend='ref-classes-debian'><filename>debian</filename></link>
5562 class renames the output package, it does so by setting
5563 <filename>PKG_&lt;packagename&gt;</filename>.
5564 </para>
5565 </glossdef>
5566 </glossentry>
5567
5568 <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
5569 <glossdef>
5570 <para>
5571 Points to the destination directory for files to be
5572 packaged before they are split into individual packages.
5573 This directory defaults to the following:
5574 <literallayout class='monospaced'>
5575 ${WORKDIR}/package
5576 </literallayout>
5577 Do not change this default.
5578 </para>
5579 </glossdef>
5580 </glossentry>
5581
5582 <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
5583 <glossdef>
5584 <para>
5585 Points to a shared, global-state directory that holds data
5586 generated during the packaging process.
5587 During the packaging process, the
5588 <filename>do_packagedata</filename> task packages
5589 data for each recipe and installs it into this temporary,
5590 shared area.
5591 This directory defaults to the following:
5592 <literallayout class='monospaced'>
5593 ${STAGING_DIR_HOST}/pkgdata
5594 </literallayout>
5595 Do not change this default.
5596 </para>
5597 </glossdef>
5598 </glossentry>
5599
5600 <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
5601 <glossdef>
5602 <para>
5603 Points to the parent directory for files to be packaged
5604 after they have been split into individual packages.
5605 This directory defaults to the following:
5606 <literallayout class='monospaced'>
5607 ${WORKDIR}/packages-split
5608 </literallayout>
5609 Under this directory, the build system creates
5610 directories for each package specified in
5611 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
5612 Do not change this default.
5613 </para>
5614 </glossdef>
5615 </glossentry>
5616
5617 <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
5618 <glossdef>
5619 <para>
5620 Points to a temporary work area used by the
5621 <filename>do_package</filename> task to write output
5622 from the <filename>do_packagedata</filename> task.
5623 The <filename>PKGDESTWORK</filename> location defaults to
5624 the following:
5625 <literallayout class='monospaced'>
5626 ${WORKDIR}/pkgdata
5627 </literallayout>
5628 The <filename>do_packagedata</filename> task then packages
5629 the data in the temporary work area and installs it into a
5630 shared directory pointed to by
5631 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
5632 </para>
5633
5634 <para>
5635 Do not change this default.
5636 </para>
5637 </glossdef>
5638 </glossentry>
5639
5640 <glossentry id='var-PKGE'><glossterm>PKGE</glossterm>
5641 <glossdef>
5642 <para>
5643 The epoch of the output package built by the
5644 OpenEmbedded build system.
5645 By default, <filename>PKGE</filename> is set to
5646 <link linkend='var-PE'><filename>PE</filename></link>.
5647 </para>
5648 </glossdef>
5649 </glossentry>
5650
5651 <glossentry id='var-PKGR'><glossterm>PKGR</glossterm>
5652 <glossdef>
5653 <para>
5654 The revision of the output package built by the
5655 OpenEmbedded build system.
5656 By default, <filename>PKGR</filename> is set to
5657 <link linkend='var-PR'><filename>PR</filename></link>.
5658 </para>
5659 </glossdef>
5660 </glossentry>
5661
5662 <glossentry id='var-PKGV'><glossterm>PKGV</glossterm>
5663 <glossdef>
5664 <para>
5665 The version of the output package built by the
5666 OpenEmbedded build system.
5667 By default, <filename>PKGV</filename> is set to
5668 <link linkend='var-PV'><filename>PV</filename></link>.
5669 </para>
5670 </glossdef>
5671 </glossentry>
5672
5673 <glossentry id='var-PN'><glossterm>PN</glossterm>
5674 <glossdef>
5675 <para>This variable can have two separate functions depending on the context: a recipe
5676 name or a resulting package name.</para>
5677 <para><filename>PN</filename> refers to a recipe name in the context of a file used
5678 by the OpenEmbedded build system as input to create a package.
5679 The name is normally extracted from the recipe file name.
5680 For example, if the recipe is named
5681 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
5682 will be "expat".</para>
5683 <para>
5684 The variable refers to a package name in the context of a file created or produced by the
5685 OpenEmbedded build system.</para>
5686 <para>If applicable, the <filename>PN</filename> variable also contains any special
5687 suffix or prefix.
5688 For example, using <filename>bash</filename> to build packages for the native
5689 machine, <filename>PN</filename> is <filename>bash-native</filename>.
5690 Using <filename>bash</filename> to build packages for the target and for Multilib,
5691 <filename>PN</filename> would be <filename>bash</filename> and
5692 <filename>lib64-bash</filename>, respectively.
5693 </para>
5694 </glossdef>
5695 </glossentry>
5696
5697 <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>
5698 <glossdef>
5699 <para>
5700 Lists recipes you do not want the OpenEmbedded build system
5701 to build.
5702 This variable works in conjunction with the
5703 <link linkend='ref-classes-blacklist'><filename>blacklist</filename></link>
5704 class, which the recipe must inherit globally.
5705 </para>
5706
5707 <para>
5708 To prevent a recipe from being built, inherit the class
5709 globally and use the variable in your
5710 <filename>local.conf</filename> file.
5711 Here is an example that prevents
5712 <filename>myrecipe</filename> from being built:
5713 <literallayout class='monospaced'>
5714 INHERIT += "blacklist"
5715 PNBLACKLIST[myrecipe] = "Not supported by our organization."
5716 </literallayout>
5717 </para>
5718 </glossdef>
5719 </glossentry>
5720
5721 <glossentry id='var-PR'><glossterm>PR</glossterm>
5722 <glossdef>
5723 <para>
5724 The revision of the recipe.
5725 The default value for this variable is "r0".
5726 </para>
5727 </glossdef>
5728 </glossentry>
5729
5730 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
5731 <glossdef>
5732 <para>
5733 If multiple recipes provide an item, this variable
5734 determines which recipe should be given preference.
5735 You should always suffix the variable with the name of the
5736 provided item, and you should set it to the
5737 <link linkend='var-PN'><filename>PN</filename></link>
5738 of the recipe to which you want to give precedence.
5739 Some examples:
5740 <literallayout class='monospaced'>
5741 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
5742 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
5743 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
5744 </literallayout>
5745 </para>
5746 </glossdef>
5747 </glossentry>
5748
5749 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
5750 <glossdef>
5751 <para>
5752 If there are multiple versions of recipes available, this
5753 variable determines which recipe should be given preference.
5754 You must always suffix the variable with the
5755 <link linkend='var-PN'><filename>PN</filename></link>
5756 you want to select, and you should set the
5757 <link linkend='var-PV'><filename>PV</filename></link>
5758 accordingly for precedence.
5759 You can use the "<filename>%</filename>" character as a
5760 wildcard to match any number of characters, which can be
5761 useful when specifying versions that contain long revision
5762 numbers that could potentially change.
5763 Here are two examples:
5764 <literallayout class='monospaced'>
5765 PREFERRED_VERSION_python = "2.7.3"
5766 PREFERRED_VERSION_linux-yocto = "3.10%"
5767 </literallayout>
5768 </para>
5769 </glossdef>
5770 </glossentry>
5771
5772 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
5773 <glossdef>
5774 <para>
5775 Specifies additional paths from which the OpenEmbedded
5776 build system gets source code.
5777 When the build system searches for source code, it first
5778 tries the local download directory.
5779 If that location fails, the build system tries locations
5780 defined by <filename>PREMIRRORS</filename>, the upstream
5781 source, and then locations specified by
5782 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
5783 in that order.
5784 </para>
5785
5786 <para>
5787 Assuming your distribution
5788 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
5789 is "poky", the default value for
5790 <filename>PREMIRRORS</filename> is defined in the
5791 <filename>conf/distro/poky.conf</filename> file in the
5792 <filename>meta-yocto</filename> Git repository.
5793 </para>
5794
5795 <para>
5796 Typically, you could add a specific server for the
5797 build system to attempt before any others by adding
5798 something like the following to the
5799 <filename>local.conf</filename> configuration file in the
5800 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
5801 <literallayout class='monospaced'>
5802 PREMIRRORS_prepend = "\
5803 git://.*/.* http://www.yoctoproject.org/sources/ \n \
5804 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
5805 http://.*/.* http://www.yoctoproject.org/sources/ \n \
5806 https://.*/.* http://www.yoctoproject.org/sources/ \n"
5807 </literallayout>
5808 These changes cause the build system to intercept
5809 Git, FTP, HTTP, and HTTPS requests and direct them to
5810 the <filename>http://</filename> sources mirror.
5811 You can use <filename>file://</filename> URLs to point
5812 to local directories or network shares as well.
5813 </para>
5814 </glossdef>
5815 </glossentry>
5816
5817 <glossentry id='var-PRINC'><glossterm>PRINC</glossterm>
5818 <glossdef>
5819
5820 <para>
5821 The <filename>PRINC</filename> variable has been deprecated
5822 and triggers a warning if detected during a build.
5823 For
5824 <link linkend='var-PR'><filename>PR</filename></link>
5825 increments on changes, use the PR service instead.
5826 You can find out more about this service in the
5827 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
5828 section in the Yocto Project Development Manual.
5829 </para>
5830<!--
5831
5832 <para>
5833 Causes the
5834 <link linkend='var-PR'><filename>PR</filename></link>
5835 variable of <filename>.bbappend</filename> files to
5836 dynamically increment.
5837 This increment minimizes the impact of layer ordering.
5838 </para>
5839
5840 <para>
5841 In order to ensure multiple <filename>.bbappend</filename>
5842 files can co-exist,
5843 <filename>PRINC</filename> should be self-referencing.
5844 This variable defaults to 0.
5845 </para>
5846
5847 <para>
5848 Following is an example that increments
5849 <filename>PR</filename> by two:
5850 <literallayout class='monospaced'>
5851 PRINC := "${@int(PRINC) + 2}"
5852 </literallayout>
5853 It is advisable not to use strings such as ".= '.1'" with the variable because
5854 this usage is very sensitive to layer ordering.
5855 You should avoid explicit assignments as they cannot
5856 adequately represent multiple
5857 <filename>.bbappend</filename> files.
5858 </para>
5859-->
5860 </glossdef>
5861 </glossentry>
5862
5863 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
5864 <glossdef>
5865 <para>
5866 A list of aliases that a recipe also provides.
5867 These aliases are useful for satisfying dependencies of
5868 other recipes during the build (as specified by
5869 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>).
5870 <note>
5871 A recipe's own
5872 <filename><link linkend='var-PN'>PN</link></filename>
5873 is implicitly already in its
5874 <filename>PROVIDES</filename> list.
5875 </note>
5876 </para>
5877 </glossdef>
5878 </glossentry>
5879
5880 <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
5881 <glossdef>
5882 <para>
5883 The network based
5884 <link linkend='var-PR'><filename>PR</filename></link>
5885 service host and port.
5886 </para>
5887
5888 <para>
5889 The <filename>conf/local.conf.sample.extended</filename>
5890 configuration file in the
5891 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
5892 shows how the <filename>PRSERV_HOST</filename> variable is
5893 set:
5894 <literallayout class='monospaced'>
5895 PRSERV_HOST = "localhost:0"
5896 </literallayout>
5897 You must set the variable if you want to automatically
5898 start a local
5899 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.
5900 You can set <filename>PRSERV_HOST</filename> to other
5901 values to use a remote PR service.
5902 </para>
5903 </glossdef>
5904 </glossentry>
5905
5906 <glossentry id='var-PV'><glossterm>PV</glossterm>
5907 <glossdef>
5908 <para>
5909 The version of the recipe.
5910 The version is normally extracted from the recipe filename.
5911 For example, if the recipe is named
5912 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename>
5913 will be "2.0.1".
5914 <filename>PV</filename> is generally not overridden within
5915 a recipe unless it is building an unstable (i.e. development) version from a source code repository
5916 (e.g. Git or Subversion).
5917 </para>
5918 </glossdef>
5919 </glossentry>
5920
5921 <glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>
5922 <glossdef>
5923 <para>
5924 When used by recipes that inherit the
5925 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
5926 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
5927 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
5928 or
5929 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
5930 classes, denotes the Application Binary Interface (ABI)
5931 currently in use for Python.
5932 By default, the ABI is "m".
5933 You do not have to set this variable as the OpenEmbedded
5934 build system sets it for you.
5935 </para>
5936
5937 <para>
5938 The OpenEmbedded build system uses the ABI to construct
5939 directory names used when installing the Python headers
5940 and libraries in sysroot
5941 (e.g. <filename>.../python3.3m/...</filename>).
5942 </para>
5943
5944 <para>
5945 Recipes that inherit the
5946 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>
5947 class during cross-builds also use this variable to
5948 locate the headers and libraries of the appropriate Python
5949 that the extension is targeting.
5950 </para>
5951 </glossdef>
5952 </glossentry>
5953
5954 <glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>
5955 <glossdef>
5956 <para>
5957 When used by recipes that inherit the
5958 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
5959 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
5960 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
5961 or
5962 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
5963 classes, specifies the major Python version being built.
5964 For Python 2.x, <filename>PYTHON_PN</filename> would
5965 be "python2". For Python 3.x, the variable would be
5966 "python3".
5967 You do not have to set this variable as the
5968 OpenEmbedded build system automatically sets it for you.
5969 </para>
5970
5971 <para>
5972 The variable allows recipes to use common infrastructure
5973 such as the following:
5974 <literallayout class='monospaced'>
5975 DEPENDS += "${PYTHON_PN}-native"
5976 </literallayout>
5977 In the previous example, the version of the dependency
5978 is <filename>PYTHON_PN</filename>.
5979 </para>
5980 </glossdef>
5981 </glossentry>
5982
5983 </glossdiv>
5984
5985 <glossdiv id='var-glossary-q'><title>Q</title>
5986
5987 <glossentry id='var-QMAKE_PROFILES'><glossterm>QMAKE_PROFILES</glossterm>
5988 <glossdef>
5989 <para>
5990 Specifies your own subset of <filename>.pro</filename>
5991 files to be built for use with
5992 <filename>qmake</filename>.
5993 If you do not set this variable, all
5994 <filename>.pro</filename> files in the directory pointed to
5995 by <link linkend='var-S'><filename>S</filename></link>
5996 will be built by default.
5997 </para>
5998
5999 <para>
6000 This variable is used with recipes that inherit the
6001 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
6002 class or other classes that inherit
6003 <filename>qmake_base</filename>.
6004 </para>
6005 </glossdef>
6006 </glossentry>
6007
6008 </glossdiv>
6009
6010 <glossdiv id='var-glossary-r'><title>R</title>
6011
6012 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
6013 <glossdef>
6014 <para>
6015 The list of packages that conflict with packages.
6016 Note that packages will not be installed if conflicting
6017 packages are not first removed.
6018 </para>
6019
6020 <para>
6021 Like all package-controlling variables, you must always use
6022 them in conjunction with a package name override.
6023 Here is an example:
6024 <literallayout class='monospaced'>
6025 RCONFLICTS_${PN} = "another-conflicting-package-name"
6026 </literallayout>
6027 </para>
6028
6029 <para>
6030 BitBake, which the OpenEmbedded build system uses, supports
6031 specifying versioned dependencies.
6032 Although the syntax varies depending on the packaging
6033 format, BitBake hides these differences from you.
6034 Here is the general syntax to specify versions with
6035 the <filename>RCONFLICTS</filename> variable:
6036 <literallayout class='monospaced'>
6037 RCONFLICTS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6038 </literallayout>
6039 For <filename>operator</filename>, you can specify the
6040 following:
6041 <literallayout class='monospaced'>
6042 =
6043 &lt;
6044 &gt;
6045 &lt;=
6046 &gt;=
6047 </literallayout>
6048 For example, the following sets up a dependency on version
6049 1.2 or greater of the package <filename>foo</filename>:
6050 <literallayout class='monospaced'>
6051 RCONFLICTS_${PN} = "foo (>= 1.2)"
6052 </literallayout>
6053 </para>
6054 </glossdef>
6055 </glossentry>
6056
6057 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
6058 <glossdef>
6059 <para>
6060 Lists a package's runtime dependencies (i.e. other packages)
6061 that must be installed in order for the built package to run
6062 correctly.
6063 If a package in this list cannot be found during the build,
6064 you will get a build error.
6065 </para>
6066
6067 <para>
6068 When you use the <filename>RDEPENDS</filename> variable
6069 in a recipe, you are essentially stating that the recipe's
6070 <filename>do_build</filename> task depends on the existence
6071 of a specific package.
6072 Consider this simple example for two recipes named "a" and
6073 "b" that produce similarly named IPK packages.
6074 In this example, the <filename>RDEPENDS</filename>
6075 statement appears in the "a" recipe:
6076 <literallayout class='monospaced'>
6077 RDEPENDS_${PN} = "b"
6078 </literallayout>
6079 Here, the dependency is such that the
6080 <filename>do_build</filename> task for recipe "a" depends
6081 on the <filename>do_package_write_ipk</filename> task
6082 of recipe "b".
6083 This means the package file for "b" must be available when
6084 the output for recipe "a" has been completely built.
6085 More importantly, package "a" will be marked as depending
6086 on package "b" in a manner that is understood by the
6087 package manager.
6088 </para>
6089
6090 <para>
6091 The names of the packages you list within
6092 <filename>RDEPENDS</filename> must be the names of other
6093 packages - they cannot be recipe names.
6094 Although package names and recipe names usually match,
6095 the important point here is that you are
6096 providing package names within the
6097 <filename>RDEPENDS</filename> variable.
6098 For an example of the default list of packages created from
6099 a recipe, see the
6100 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
6101 variable.
6102 </para>
6103
6104 <para>
6105 Because the <filename>RDEPENDS</filename> variable applies
6106 to packages being built, you should always use the variable
6107 in a form with an attached package name.
6108 For example, suppose you are building a development package
6109 that depends on the <filename>perl</filename> package.
6110 In this case, you would use the following
6111 <filename>RDEPENDS</filename> statement:
6112 <literallayout class='monospaced'>
6113 RDEPENDS_${PN}-dev += "perl"
6114 </literallayout>
6115 In the example, the development package depends on
6116 the <filename>perl</filename> package.
6117 Thus, the <filename>RDEPENDS</filename> variable has the
6118 <filename>${PN}-dev</filename> package name as part of the
6119 variable.
6120 </para>
6121
6122 <para>
6123 The package name you attach to the
6124 <filename>RDEPENDS</filename> variable must appear
6125 as it would in the <filename>PACKAGES</filename>
6126 namespace before any renaming of the output package by
6127 classes like <filename>debian.bbclass</filename>.
6128 </para>
6129
6130 <para>
6131 In many cases you do not need to explicitly add
6132 runtime dependencies using
6133 <filename>RDEPENDS</filename> since some automatic
6134 handling occurs:
6135 <itemizedlist>
6136 <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If
6137 a runtime package contains a shared library
6138 (<filename>.so</filename>), the build
6139 processes the library in order to determine other
6140 libraries to which it is dynamically linked.
6141 The build process adds these libraries to
6142 <filename>RDEPENDS</filename> when creating the runtime
6143 package.</para></listitem>
6144 <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If
6145 the package ships a <filename>pkg-config</filename>
6146 information file, the build process uses this file
6147 to add items to the <filename>RDEPENDS</filename>
6148 variable to create the runtime packages.
6149 </para></listitem>
6150 </itemizedlist>
6151 </para>
6152
6153 <para>
6154 BitBake, which the OpenEmbedded build system uses, supports
6155 specifying versioned dependencies.
6156 Although the syntax varies depending on the packaging
6157 format, BitBake hides these differences from you.
6158 Here is the general syntax to specify versions with
6159 the <filename>RDEPENDS</filename> variable:
6160 <literallayout class='monospaced'>
6161 RDEPENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6162 </literallayout>
6163 For <filename>operator</filename>, you can specify the
6164 following:
6165 <literallayout class='monospaced'>
6166 =
6167 &lt;
6168 &gt;
6169 &lt;=
6170 &gt;=
6171 </literallayout>
6172 For example, the following sets up a dependency on version
6173 1.2 or greater of the package <filename>foo</filename>:
6174 <literallayout class='monospaced'>
6175 RDEPENDS_${PN} = "foo (>= 1.2)"
6176 </literallayout>
6177 </para>
6178
6179 <para>
6180 For information on build-time dependencies, see the
6181 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
6182 variable.
6183 </para>
6184 </glossdef>
6185 </glossentry>
6186
6187 <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm>
6188 <glossdef>
6189 <para>
6190 When a recipe inherits the
6191 <filename>distro_features_check</filename> class, this
6192 variable identifies distribution features that must
6193 exist in the current configuration in order for the
6194 OpenEmbedded build system to build the recipe.
6195 In other words, if the
6196 <filename>REQUIRED_DISTRO_FEATURES</filename> variable
6197 lists a feature that does not appear in
6198 <filename>DISTRO_FEATURES</filename> within the
6199 current configuration, an error occurs and the
6200 build stops.
6201 </para>
6202 </glossdef>
6203 </glossentry>
6204
6205 <glossentry id='var-RM_OLD_IMAGE'><glossterm>RM_OLD_IMAGE</glossterm>
6206 <glossdef>
6207 <para>
6208 Reclaims disk space by removing previously built
6209 versions of the same image from the
6210 <filename>images</filename> directory pointed to by the
6211 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
6212 variable.
6213 </para>
6214
6215 <para>
6216 Set this variable to "1" in your
6217 <filename>local.conf</filename> file to remove these
6218 images.
6219 </para>
6220 </glossdef>
6221 </glossentry>
6222
6223 <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
6224 <glossdef>
6225 <para>
6226 With <filename>rm_work</filename> enabled, this
6227 variable specifies a list of recipes whose work directories
6228 should not be removed.
6229 See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
6230 section for more details.
6231 </para>
6232 </glossdef>
6233 </glossentry>
6234
6235 <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm>
6236 <glossdef>
6237 <para>
6238 Defines the root home directory.
6239 By default, this directory is set as follows in the
6240 BitBake configuration file:
6241 <literallayout class='monospaced'>
6242 ROOT_HOME ??= "/home/root"
6243 </literallayout>
6244 <note>
6245 This default value is likely used because some
6246 embedded solutions prefer to have a read-only root
6247 filesystem and prefer to keep writeable data in one
6248 place.
6249 </note>
6250 </para>
6251
6252 <para>
6253 You can override the default by setting the variable
6254 in any layer or in the <filename>local.conf</filename> file.
6255 Because the default is set using a "weak" assignment
6256 (i.e. "??="), you can use either of the following forms
6257 to define your override:
6258 <literallayout class='monospaced'>
6259 ROOT_HOME = "/root"
6260 ROOT_HOME ?= "/root"
6261 </literallayout>
6262 These override examples use <filename>/root</filename>,
6263 which is probably the most commonly used override.
6264 </para>
6265 </glossdef>
6266 </glossentry>
6267
6268 <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>
6269 <glossdef>
6270 <para>
6271 Indicates a filesystem image to include as the root
6272 filesystem.
6273 </para>
6274
6275 <para>
6276 The <filename>ROOTFS</filename> variable is an optional
6277 variable used with the
6278 <link linkend='ref-classes-bootimg'><filename>buildimg</filename></link>
6279 class.
6280 </para>
6281 </glossdef>
6282 </glossentry>
6283
6284 <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
6285 <glossdef>
6286 <para>
6287 Added by classes to run post processing commands once the
6288 OpenEmbedded build system has created the root filesystem.
6289 You can specify shell commands separated by semicolons:
6290 <literallayout class='monospaced'>
6291 ROOTFS_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
6292 </literallayout>
6293 If you need to pass the path to the root filesystem within
6294 the command, you can use
6295 <filename>${IMAGE_ROOTFS}</filename>, which points to
6296 the root filesystem image.
6297 </para>
6298 </glossdef>
6299 </glossentry>
6300
6301 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
6302 <glossdef>
6303 <para>
6304 A list of package name aliases that a package also provides.
6305 These aliases are useful for satisfying runtime dependencies
6306 of other packages both during the build and on the target
6307 (as specified by
6308 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
6309 <note>
6310 A package's own name is implicitly already in its
6311 <filename>RPROVIDES</filename> list.
6312 </note>
6313 </para>
6314 <para>
6315 As with all package-controlling variables, you must always
6316 use the variable in conjunction with a package name override.
6317 Here is an example:
6318 <literallayout class='monospaced'>
6319 RPROVIDES_${PN} = "widget-abi-2"
6320 </literallayout>
6321 </para>
6322 </glossdef>
6323 </glossentry>
6324
6325 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
6326 <glossdef>
6327 <para>
6328 A list of packages that extends the usability of a package
6329 being built.
6330 The package being built does not depend on this list of
6331 packages in order to successfully build, but needs them for
6332 the extended usability.
6333 To specify runtime dependencies for packages, see the
6334 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
6335 variable.
6336 </para>
6337
6338 <para>
6339 The OpenEmbedded build process automatically installs the
6340 list of packages as part of the built package.
6341 However, you can remove these packages later if you want.
6342 If, during the build, a package from the
6343 <filename>RRECOMMENDS</filename> list cannot be
6344 found, the build process continues without an error.
6345 </para>
6346
6347 <para>
6348 You can also prevent packages in the list from being
6349 installed by using several variables.
6350 See the
6351 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
6352 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
6353 and
6354 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
6355 variables for more information.
6356 </para>
6357
6358 <para>
6359 Because the <filename>RRECOMMENDS</filename> variable
6360 applies to packages being built, you should always attach
6361 an override to the variable to specify the particular
6362 package whose usability is being extended.
6363 For example, suppose you are building a development package
6364 that is extended to support wireless functionality.
6365 In this case, you would use the following:
6366 <literallayout class='monospaced'>
6367 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
6368 </literallayout>
6369 In the example, the package name
6370 (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
6371 must appear as it would in the
6372 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
6373 namespace before any renaming of the output package by
6374 classes such as <filename>debian.bbclass</filename>.
6375 </para>
6376
6377 <para>
6378 BitBake, which the OpenEmbedded build system uses, supports
6379 specifying versioned recommends.
6380 Although the syntax varies depending on the packaging
6381 format, BitBake hides these differences from you.
6382 Here is the general syntax to specify versions with
6383 the <filename>RRECOMMENDS</filename> variable:
6384 <literallayout class='monospaced'>
6385 RRECOMMENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6386 </literallayout>
6387 For <filename>operator</filename>, you can specify the
6388 following:
6389 <literallayout class='monospaced'>
6390 =
6391 &lt;
6392 &gt;
6393 &lt;=
6394 &gt;=
6395 </literallayout>
6396 For example, the following sets up a recommend on version
6397 1.2 or greater of the package <filename>foo</filename>:
6398 <literallayout class='monospaced'>
6399 RRECOMMENDS_${PN} = "foo (>= 1.2)"
6400 </literallayout>
6401 </para>
6402 </glossdef>
6403 </glossentry>
6404
6405 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
6406 <glossdef>
6407 <para>
6408 A list of packages replaced by a package.
6409 The package manager uses this variable to determine which
6410 package should be installed to replace other package(s)
6411 during an upgrade.
6412 In order to also have the other package(s) removed at the
6413 same time, you must add the name of the other
6414 package to the
6415 <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
6416 </para>
6417 <para>
6418 As with all package-controlling variables, you must use
6419 this variable in conjunction with a package name
6420 override.
6421 Here is an example:
6422 <literallayout class='monospaced'>
6423 RREPLACES_${PN} = "other-package-being-replaced"
6424 </literallayout>
6425 </para>
6426
6427 <para>
6428 BitBake, which the OpenEmbedded build system uses, supports
6429 specifying versioned replacements.
6430 Although the syntax varies depending on the packaging
6431 format, BitBake hides these differences from you.
6432 Here is the general syntax to specify versions with
6433 the <filename>RREPLACES</filename> variable:
6434 <literallayout class='monospaced'>
6435 RREPLACES_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6436 </literallayout>
6437 For <filename>operator</filename>, you can specify the
6438 following:
6439 <literallayout class='monospaced'>
6440 =
6441 &lt;
6442 &gt;
6443 &lt;=
6444 &gt;=
6445 </literallayout>
6446 For example, the following sets up a replacement using
6447 version 1.2 or greater of the package
6448 <filename>foo</filename>:
6449 <literallayout class='monospaced'>
6450 RREPLACES_${PN} = "foo (>= 1.2)"
6451 </literallayout>
6452 </para>
6453 </glossdef>
6454 </glossentry>
6455
6456 <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
6457 <glossdef>
6458 <para>
6459 A list of additional packages that you can suggest for
6460 installation by the package manager at the time a package
6461 is installed.
6462 Not all package managers support this functionality.
6463 </para>
6464 <para>
6465 As with all package-controlling variables, you must always
6466 use this variable in conjunction with a package name
6467 override.
6468 Here is an example:
6469 <literallayout class='monospaced'>
6470 RSUGGESTS_${PN} = "useful-package another-package"
6471 </literallayout>
6472 </para>
6473 </glossdef>
6474 </glossentry>
6475
6476 </glossdiv>
6477
6478 <glossdiv id='var-glossary-s'><title>S</title>
6479
6480 <glossentry id='var-S'><glossterm>S</glossterm>
6481 <glossdef>
6482 <para>
6483 The location in the
6484 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
6485 where unpacked recipe source code resides.
6486 This location is within the work directory
6487 (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>),
6488 which is not static.
6489 The unpacked source location depends on the recipe name
6490 (<filename><link linkend='var-PN'>PN</link></filename>) and
6491 recipe version
6492 (<filename><link linkend='var-PV'>PV</link></filename>) as
6493 follows:
6494 <literallayout class='monospaced'>
6495 ${WORKDIR}/${PN}-${PV}
6496 </literallayout>
6497 As an example, assume a
6498 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
6499 top-level folder named <filename>poky</filename> and a
6500 default Build Directory at <filename>poky/build</filename>.
6501 In this case, the work directory the build system uses
6502 to keep the unpacked recipe for <filename>db</filename>
6503 is the following:
6504 <literallayout class='monospaced'>
6505 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
6506 </literallayout>
6507 </para>
6508 </glossdef>
6509 </glossentry>
6510
6511 <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
6512 <glossdef>
6513 <para>
6514 A list of the host distribution identifiers that the
6515 build system has been tested against.
6516 Identifiers consist of the host distributor ID
6517 followed by the release,
6518 as reported by the <filename>lsb_release</filename> tool
6519 or as read from <filename>/etc/lsb-release</filename>.
6520 Separate the list items with explicit newline
6521 characters (<filename>\n</filename>).
6522 If <filename>SANITY_TESTED_DISTROS</filename> is not empty
6523 and the current value of
6524 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
6525 does not appear in the list, then the build system reports
6526 a warning that indicates the current host distribution has
6527 not been tested as a build host.
6528 </para>
6529 </glossdef>
6530 </glossentry>
6531
6532 <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
6533 <glossdef>
6534 <para>
6535 The target architecture for the SDK.
6536 Typically, you do not directly set this variable.
6537 Instead, use
6538 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
6539 </para>
6540 </glossdef>
6541 </glossentry>
6542
6543 <glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>
6544 <glossdef>
6545 <para>
6546 The directory set up and used by the
6547 <link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link>
6548 to which the SDK is deployed.
6549 The <filename>populate_sdk_base</filename> class defines
6550 <filename>SDK_DEPLOY</filename> as follows:
6551 <literallayout class='monospaced'>
6552 SDK_DEPLOY = "${<link linkend='var-TMPDIR'>TMPDIR</link>}/deploy/sdk"
6553 </literallayout>
6554 </para>
6555 </glossdef>
6556 </glossentry>
6557
6558 <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm>
6559 <glossdef>
6560 <para>
6561 The parent directory used by the OpenEmbedded build system
6562 when creating SDK output.
6563 The
6564 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
6565 class defines the variable as follows:
6566 <literallayout class='monospaced'>
6567 SDK_DIR = "${<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>}/sdk"
6568 </literallayout>
6569 <note>
6570 The <filename>SDK_DIR</filename> directory is a
6571 temporary directory as it is part of
6572 <filename>WORKDIR</filename>.
6573 The final output directory is
6574 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
6575 </note>
6576 </para>
6577 </glossdef>
6578 </glossentry>
6579
6580 <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
6581 <glossdef>
6582 <para>
6583 The base name for SDK output files.
6584 The name is derived from the
6585 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
6586 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
6587 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
6588 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
6589 and
6590 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
6591 variables:
6592 <literallayout class='monospaced'>
6593 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
6594 </literallayout>
6595 </para>
6596 </glossdef>
6597 </glossentry>
6598
6599 <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>
6600 <glossdef>
6601 <para>
6602 The location used by the OpenEmbedded build system when
6603 creating SDK output.
6604 The
6605 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
6606 class defines the variable as follows:
6607 <literallayout class='monospaced'>
6608 SDK_OUTPUT = "${<link linkend='var-SDK_DIR'>SDK_DIR</link>}/image"
6609 </literallayout>
6610 <note>
6611 The <filename>SDK_OUTPUT</filename> directory is a
6612 temporary directory as it is part of
6613 <filename>WORKDIR</filename> by way of
6614 <filename>SDK_DIR</filename>.
6615 The final output directory is
6616 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
6617 </note>
6618
6619 </para>
6620 </glossdef>
6621 </glossentry>
6622
6623 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
6624 <glossdef>
6625 <para>Equivalent to
6626 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
6627 However, this variable applies to the SDK generated from an
6628 image using the following command:
6629 <literallayout class='monospaced'>
6630 $ bitbake -c populate_sdk imagename
6631 </literallayout>
6632 </para>
6633 </glossdef>
6634 </glossentry>
6635
6636 <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
6637 <glossdef>
6638 <para>
6639 The architecture of the machine that runs Application
6640 Development Toolkit (ADT) items.
6641 In other words, packages are built so that they will run
6642 on the target you specify with the argument.
6643 This implies that you can build out ADT/SDK items that
6644 run on an architecture other than that of your build host.
6645 For example, you can use an x86_64-based build host to
6646 create packages that will run on an i686-based
6647 SDK Machine.
6648 </para>
6649
6650 <para>
6651 You can use "i686" and "x86_64" as possible values for this
6652 variable.
6653 The variable defaults to "i686" and is set in the
6654 <filename>local.conf</filename> file in the
6655 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
6656 <literallayout class='monospaced'>
6657 SDKMACHINE ?= "i686"
6658 </literallayout>
6659 <note>
6660 You cannot set the <filename>SDKMACHINE</filename>
6661 variable in your distribution configuration file.
6662 If you do, the configuration will not take affect.
6663 </note>
6664 </para>
6665 </glossdef>
6666 </glossentry>
6667
6668 <glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>
6669 <glossdef>
6670 <para>
6671 Defines the path offered to the user for installation
6672 of the SDK that is generated by the OpenEmbedded build
6673 system.
6674 The path appears as the default location for installing
6675 the SDK when you run the SDK's installation script.
6676 You can override the offered path when you run the
6677 script.
6678 </para>
6679 </glossdef>
6680 </glossentry>
6681
6682 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
6683 <glossdef>
6684 <para>The section in which packages should be categorized.
6685 Package management utilities can make use of this variable.</para>
6686 </glossdef>
6687 </glossentry>
6688
6689 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
6690 <glossdef>
6691 <para>
6692 The variable takes the value of
6693 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
6694 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
6695 In this case the value of
6696 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
6697 </para>
6698 </glossdef>
6699 </glossentry>
6700
6701 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
6702 <glossdef>
6703 <para>
6704 Defines a serial console (TTY) to enable using getty.
6705 Provide a value that specifies the baud rate followed by
6706 the TTY device name separated by a space.
6707 You cannot specify more than one TTY device:
6708 <literallayout class='monospaced'>
6709 SERIAL_CONSOLE = "115200 ttyS0"
6710 </literallayout>
6711 <note>
6712 The <filename>SERIAL_CONSOLE</filename> variable
6713 is deprecated.
6714 Please use the
6715 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
6716 variable.
6717 </note>
6718 </para>
6719 </glossdef>
6720 </glossentry>
6721
6722 <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
6723 <glossdef>
6724 <para>
6725 Defines the serial consoles (TTYs) to enable using getty.
6726 Provide a value that specifies the baud rate followed by
6727 the TTY device name separated by a semicolon.
6728 Use spaces to separate multiple devices:
6729 <literallayout class='monospaced'>
6730 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
6731 </literallayout>
6732 </para>
6733 </glossdef>
6734 </glossentry>
6735
6736 <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
6737 <glossdef>
6738 <para>
6739 Similar to
6740 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
6741 except the device is checked for existence before attempting
6742 to enable it.
6743 This variable is currently only supported with SysVinit
6744 (i.e. not with systemd).
6745 </para>
6746 </glossdef>
6747 </glossentry>
6748
6749 <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
6750 <glossdef>
6751 <para>
6752 A list of recipe dependencies that should not be used to
6753 determine signatures of tasks from one recipe when they
6754 depend on tasks from another recipe.
6755 For example:
6756 <literallayout class='monospaced'>
6757 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
6758 </literallayout>
6759 In this example, <filename>intone</filename> depends on
6760 <filename>mplayer2</filename>.
6761 </para>
6762
6763 <para>
6764 Use of this variable is one mechanism to remove dependencies
6765 that affect task signatures and thus force rebuilds when a
6766 recipe changes.
6767 <note><title>Caution</title>
6768 If you add an inappropriate dependency for a recipe
6769 relationship, the software might break during
6770 runtime if the interface of the second recipe was
6771 changed after the first recipe had been built.
6772 </note>
6773 </para>
6774 </glossdef>
6775 </glossentry>
6776
6777 <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
6778 <glossdef>
6779 <para>
6780 A list of recipes that are completely stable and will
6781 never change.
6782 The ABI for the recipes in the list are presented by
6783 output from the tasks run to build the recipe.
6784 Use of this variable is one way to remove dependencies from
6785 one recipe on another that affect task signatures and
6786 thus force rebuilds when the recipe changes.
6787 <note><title>Caution</title>
6788 If you add an inappropriate variable to this list,
6789 the software might break at runtime if the
6790 interface of the recipe was changed after the other
6791 had been built.
6792 </note>
6793 </para>
6794 </glossdef>
6795 </glossentry>
6796
6797 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
6798 <glossdef>
6799 <para>
6800 Specifies the number of bits for the target system CPU.
6801 The value should be either "32" or "64".
6802 </para>
6803 </glossdef>
6804 </glossentry>
6805
6806 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
6807 <glossdef>
6808 <para>
6809 Specifies the endian byte order of the target system.
6810 The value should be either "le" for little-endian or "be" for big-endian.
6811 </para>
6812 </glossdef>
6813 </glossentry>
6814
6815 <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
6816 <glossdef>
6817 <para>
6818 Groups together machines based upon the same family
6819 of SOC (System On Chip).
6820 You typically set this variable in a common
6821 <filename>.inc</filename> file that you include in the
6822 configuration files of all the machines.
6823 <note>
6824 You must include
6825 <filename>conf/machine/include/soc-family.inc</filename>
6826 for this variable to appear in
6827 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
6828 </note>
6829 </para>
6830 </glossdef>
6831 </glossentry>
6832
6833 <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
6834 <glossdef>
6835 <para>
6836 Defines the suffix for shared libraries used on the
6837 target platform.
6838 By default, this suffix is ".so.*" for all Linux-based
6839 systems and is defined in the
6840 <filename>meta/conf/bitbake.conf</filename> configuration
6841 file.
6842 </para>
6843
6844 <para>
6845 You will see this variable referenced in the default values
6846 of <filename>FILES_${PN}</filename>.
6847 </para>
6848 </glossdef>
6849 </glossentry>
6850
6851 <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
6852 <glossdef>
6853 <para>
6854 Defines the suffix for the development symbolic link
6855 (symlink) for shared libraries on the target platform.
6856 By default, this suffix is ".so" for Linux-based
6857 systems and is defined in the
6858 <filename>meta/conf/bitbake.conf</filename> configuration
6859 file.
6860 </para>
6861
6862 <para>
6863 You will see this variable referenced in the default values
6864 of <filename>FILES_${PN}-dev</filename>.
6865 </para>
6866 </glossdef>
6867 </glossentry>
6868
6869 <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm>
6870 <glossdef>
6871 <para>
6872 Defines your own
6873 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
6874 from which to first fetch source before attempting to fetch
6875 from the upstream specified in
6876 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
6877 </para>
6878
6879 <para>
6880 To use this variable, you must globally inherit the
6881 <link linkend='ref-classes-own-mirrors'><filename>own-mirrors</filename></link>
6882 class and then provide the URL to your mirrors.
6883 Here is an example:
6884 <literallayout class='monospaced'>
6885 INHERIT += "own-mirrors"
6886 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
6887 </literallayout>
6888 <note>
6889 You can specify only a single URL in
6890 <filename>SOURCE_MIRROR_URL</filename>.
6891 </note>
6892 </para>
6893 </glossdef>
6894 </glossentry>
6895
6896 <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>
6897 <glossdef>
6898 <para>
6899 Maps commonly used license names to their SPDX counterparts
6900 found in <filename>meta/files/common-licenses/</filename>.
6901 For the default <filename>SPDXLICENSEMAP</filename>
6902 mappings, see the
6903 <filename>meta/conf/licenses.conf</filename> file.
6904 </para>
6905
6906 <para>
6907 For additional information, see the
6908 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
6909 variable.
6910 </para>
6911 </glossdef>
6912 </glossentry>
6913
6914 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
6915 <glossdef>
6916 <para>
6917 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
6918 OpenEmbedded build system to create variants of recipes or packages.
6919 The list specifies the prefixes to strip off during certain circumstances
6920 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
6921 </para>
6922 </glossdef>
6923 </glossentry>
6924
6925 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
6926 <glossdef>
6927 <para>The list of source files - local or remote.
6928 This variable tells the OpenEmbedded build system which bits
6929 to pull in for the build and how to pull them in.
6930 For example, if the recipe or append file only needs to
6931 fetch a tarball from the Internet, the recipe or
6932 append file uses a single <filename>SRC_URI</filename>
6933 entry.
6934 On the other hand, if the recipe or append file needs to
6935 fetch a tarball, apply two patches, and include a custom
6936 file, the recipe or append file would include four
6937 instances of the variable.</para>
6938 <para>The following list explains the available URI protocols:
6939 <itemizedlist>
6940 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
6941 Fetches files, which are usually files shipped with
6942 the
6943 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
6944 from the local machine.
6945 The path is relative to the
6946 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
6947 variable.
6948 Thus, the build system searches, in order, from the
6949 following directories, which are assumed to be a
6950 subdirectories of the directory in which the
6951 recipe file (<filename>.bb</filename>) or
6952 append file (<filename>.bbappend</filename>)
6953 resides:
6954 <itemizedlist>
6955 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
6956 The base recipe name without any special
6957 suffix or version numbers.
6958 </para></listitem>
6959 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
6960 <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
6961 The base recipe name and version but without
6962 any special package name suffix.
6963 </para></listitem>
6964 <listitem><para><emphasis>files -</emphasis>
6965 Files within a directory, which is named
6966 <filename>files</filename> and is also
6967 alongside the recipe or append file.
6968 </para></listitem>
6969 </itemizedlist>
6970 <note>
6971 If you want the build system to pick up files
6972 specified through a
6973 <filename>SRC_URI</filename>
6974 statement from your append file, you need to be
6975 sure to extend the
6976 <filename>FILESPATH</filename>
6977 variable by also using the
6978 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
6979 variable from within your append file.
6980 </note>
6981 </para></listitem>
6982 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
6983 Bazaar revision control repository.</para></listitem>
6984 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
6985 Git revision control repository.</para></listitem>
6986 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
6987 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
6988 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
6989 a repo (Git) repository.</para></listitem>
6990 <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from
6991 an SVK revision control repository.</para></listitem>
6992 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
6993 the Internet using <filename>http</filename>.</para></listitem>
6994 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
6995 from the Internet using <filename>https</filename>.</para></listitem>
6996 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
6997 from the Internet using <filename>ftp</filename>.</para></listitem>
6998 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
6999 a CVS revision control repository.</para></listitem>
7000 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
7001 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
7002 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
7003 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
7004 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
7005 a secure shell.</para></listitem>
7006 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
7007 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
7008 </itemizedlist>
7009 </para>
7010 <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
7011 Here are standard options:
7012 <itemizedlist>
7013 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
7014 the patch or not.
7015 The default action is to apply the patch.</para></listitem>
7016 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
7017 striplevel to use when applying the patch.
7018 The default level is 1.</para></listitem>
7019 <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
7020 the directory in which the patch should be applied.
7021 The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
7022 </para></listitem>
7023 </itemizedlist>
7024 </para>
7025 <para>Here are options specific to recipes building code from a revision control system:
7026 <itemizedlist>
7027 <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
7028 Apply the patch only if
7029 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
7030 is equal to or greater than <filename>mindate</filename>.
7031 </para></listitem>
7032 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
7033 Apply the patch only if <filename>SRCDATE</filename>
7034 is not later than <filename>mindate</filename>.
7035 </para></listitem>
7036 <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
7037 Apply the patch only if <filename>SRCREV</filename>
7038 is equal to or greater than <filename>minrev</filename>.
7039 </para></listitem>
7040 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
7041 Apply the patch only if <filename>SRCREV</filename>
7042 is not later than <filename>maxrev</filename>.
7043 </para></listitem>
7044 <listitem><para><emphasis><filename>rev</filename> -</emphasis>
7045 Apply the patch only if <filename>SRCREV</filename>
7046 is equal to <filename>rev</filename>.
7047 </para></listitem>
7048 <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
7049 Apply the patch only if <filename>SRCREV</filename>
7050 is not equal to <filename>rev</filename>.
7051 </para></listitem>
7052 </itemizedlist>
7053 </para>
7054 <para>Here are some additional options worth mentioning:
7055 <itemizedlist>
7056 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
7057 whether or not to unpack the file if it is an archive.
7058 The default action is to unpack the file.</para></listitem>
7059 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
7060 (or extracts its contents) into the specified
7061 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
7062 This option is useful for unusual tarballs or other archives that
7063 do not have their files already in a subdirectory within the archive.
7064 </para></listitem>
7065 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
7066 name to be used for association with <filename>SRC_URI</filename> checksums
7067 when you have more than one file specified in <filename>SRC_URI</filename>.
7068 </para></listitem>
7069 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
7070 the filename used when storing the downloaded file.</para></listitem>
7071 </itemizedlist>
7072 </para>
7073 </glossdef>
7074 </glossentry>
7075
7076 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
7077 <glossdef>
7078 <para></para>
7079 <para>
7080 By default, the OpenEmbedded build system automatically detects whether
7081 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
7082 contains files that are machine-specific.
7083 If so, the build system automatically changes
7084 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
7085 Setting this variable to "0" disables this behavior.
7086 </para>
7087 </glossdef>
7088 </glossentry>
7089
7090 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
7091 <glossdef>
7092 <para>
7093 The date of the source code used to build the package.
7094 This variable applies only if the source was fetched from a Source Code Manager (SCM).
7095 </para>
7096 </glossdef>
7097 </glossentry>
7098
7099 <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
7100 <glossdef>
7101 <para>
7102 Returns the version string of the current package.
7103 This string is used to help define the value of
7104 <link linkend='var-PV'><filename>PV</filename></link>.
7105 </para>
7106
7107 <para>
7108 The <filename>SRCPV</filename> variable is defined in the
7109 <filename>meta/conf/bitbake.conf</filename> configuration
7110 file in the
7111 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
7112 as follows:
7113 <literallayout class='monospaced'>
7114 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
7115 </literallayout>
7116 </para>
7117
7118 <para>
7119 Recipes that need to define <filename>PV</filename> do so
7120 with the help of the <filename>SRCPV</filename>.
7121 For example, the <filename>ofono</filename> recipe
7122 (<filename>ofono_git.bb</filename>) located in
7123 <filename>meta/recipes-connectivity</filename> in the
7124 Source Directory defines <filename>PV</filename> as
7125 follows:
7126 <literallayout class='monospaced'>
7127 PV = "0.12-git${SRCPV}"
7128 </literallayout>
7129 </para>
7130 </glossdef>
7131 </glossentry>
7132
7133 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
7134 <glossdef>
7135 <para>
7136 The revision of the source code used to build the package.
7137 This variable applies to Subversion, Git, Mercurial and Bazaar
7138 only.
7139 Note that if you wish to build a fixed revision and you wish
7140 to avoid performing a query on the remote repository every time
7141 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
7142 full revision identifier and not just a tag.
7143 </para>
7144 </glossdef>
7145 </glossentry>
7146
7147 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
7148 <glossdef>
7149 <para>The directory for the shared state cache.</para>
7150 </glossdef>
7151 </glossentry>
7152
7153 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
7154 <glossdef>
7155 <para>
7156 Configures the OpenEmbedded build system to search other
7157 mirror locations for prebuilt cache data objects before
7158 building out the data.
7159 This variable works like fetcher
7160 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
7161 and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
7162 and points to the cache locations to check for the shared
7163 objects.
7164 </para>
7165
7166 <para>
7167 You can specify a filesystem directory or a remote URL such
7168 as HTTP or FTP.
7169 The locations you specify need to contain the shared state
7170 cache (sstate-cache) results from previous builds.
7171 The sstate-cache you point to can also be from builds on
7172 other machines.
7173 </para>
7174
7175 <para>
7176 If a mirror uses the same structure as
7177 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
7178 you need to add
7179 "PATH" at the end as shown in the examples below.
7180 The build system substitutes the correct path within the
7181 directory structure.
7182 <literallayout class='monospaced'>
7183 SSTATE_MIRRORS ?= "\
7184 file://.* http://someserver.tld/share/sstate/PATH \n \
7185 file://.* file:///some/local/dir/sstate/PATH"
7186 </literallayout>
7187 </para>
7188 </glossdef>
7189 </glossentry>
7190
7191 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
7192 <glossdef>
7193 <para>
7194 The directory with kernel headers that are required to build out-of-tree
7195 modules.
7196 </para>
7197 </glossdef>
7198 </glossentry>
7199
7200 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
7201 <glossdef>
7202 <para>
7203 Specifies the base path used to create recipe stamp files.
7204 The path to an actual stamp file is constructed by evaluating this
7205 string and then appending additional information.
7206 Currently, the default assignment for <filename>STAMP</filename>
7207 as set in the <filename>meta/conf/bitbake.conf</filename> file
7208 is:
7209 <literallayout class='monospaced'>
7210 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
7211 </literallayout>
7212 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
7213 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
7214 <link linkend='var-PN'><filename>PN</filename></link>,
7215 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
7216 <link linkend='var-PV'><filename>PV</filename></link>, and
7217 <link linkend='var-PR'><filename>PR</filename></link> for related variable
7218 information.
7219 </para>
7220 </glossdef>
7221 </glossentry>
7222
7223 <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
7224 <glossdef>
7225 <para>
7226 Specifies the base directory in which the OpenEmbedded
7227 build system places stamps.
7228 The default directory is
7229 <filename>${TMPDIR}/stamps</filename>.
7230 </para>
7231 </glossdef>
7232 </glossentry>
7233
7234 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
7235 <glossdef>
7236 <para>The short (72 characters or less) summary of the binary package for packaging
7237 systems such as <filename>opkg</filename>, <filename>rpm</filename> or
7238 <filename>dpkg</filename>.
7239 By default, <filename>SUMMARY</filename> is used to define
7240 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
7241 variable if <filename>DESCRIPTION</filename> is not set
7242 in the recipe.
7243 </para>
7244 </glossdef>
7245 </glossentry>
7246
7247 <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm>
7248 <glossdef>
7249 <para>
7250 Specifies the kernel boot default console.
7251 If you want to use a console other than the default,
7252 set this variable in your recipe as follows where "X" is
7253 the console number you want to use:
7254 <literallayout class='monospaced'>
7255 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
7256 </literallayout>
7257 </para>
7258
7259 <para>
7260 The
7261 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7262 class initially sets this variable to null but then checks
7263 for a value later.
7264 </para>
7265 </glossdef>
7266 </glossentry>
7267
7268 <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm>
7269 <glossdef>
7270 <para>
7271 Lists additional options to add to the syslinux file.
7272 You need to set this variable in your recipe.
7273 If you want to list multiple options, separate the options
7274 with a semicolon character (<filename>;</filename>).
7275 </para>
7276
7277 <para>
7278 The
7279 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7280 class uses this variable to create a set of options.
7281 </para>
7282 </glossdef>
7283 </glossentry>
7284
7285 <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm>
7286 <glossdef>
7287 <para>
7288 Specifies the alternate serial port or turns it off.
7289 To turn off serial, set this variable to an empty string
7290 in your recipe.
7291 The variable's default value is set in the
7292 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7293 as follows:
7294 <literallayout class='monospaced'>
7295 SYSLINUX_SERIAL ?= "0 115200"
7296 </literallayout>
7297 The class checks for and uses the variable as needed. </para>
7298 </glossdef>
7299 </glossentry>
7300
7301 <glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm>
7302 <glossdef>
7303 <para>
7304 An <filename>.LSS</filename> file used as the background
7305 for the VGA boot menu when you are using the boot menu.
7306 You need to set this variable in your recipe.
7307 </para>
7308
7309 <para>
7310 The
7311 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7312 class checks for this variable and if found, the
7313 OpenEmbedded build system installs the splash screen.
7314 </para>
7315 </glossdef>
7316 </glossentry>
7317
7318 <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>
7319 <glossdef>
7320 <para>
7321 Specifies the alternate console=tty... kernel boot argument.
7322 The variable's default value is set in the
7323 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7324 as follows:
7325 <literallayout class='monospaced'>
7326 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
7327 </literallayout>
7328 The class checks for and uses the variable as needed.
7329 </para>
7330 </glossdef>
7331 </glossentry>
7332
7333 <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
7334 <glossdef>
7335 <para>
7336 A list of functions to execute after files are staged into
7337 the sysroot.
7338 These functions are usually used to apply additional
7339 processing on the staged files, or to stage additional
7340 files.
7341 </para>
7342 </glossdef>
7343 </glossentry>
7344
7345 <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>
7346 <glossdef>
7347 <para>
7348 For recipes that inherit the
7349 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
7350 class, this variable specifies whether the service you have
7351 specified in
7352 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
7353 should be started automatically or not.
7354 By default, the service is enabled to automatically start
7355 at boot time.
7356 The default setting is in the
7357 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
7358 class as follows:
7359 <literallayout class='monospaced'>
7360 SYSTEMD_AUTO_ENABLE ??= "enable"
7361 </literallayout>
7362 You can disable the service by setting the variable to
7363 "disable".
7364 </para>
7365 </glossdef>
7366 </glossentry>
7367
7368 <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>
7369 <glossdef>
7370 <para>
7371 For recipes that inherit the
7372 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
7373 class, this variable locates the systemd unit files when
7374 they are not found in the main recipe's package.
7375 By default, the
7376 <filename>SYSTEMD_PACKAGES</filename> variable is set
7377 such that the systemd unit files are assumed to reside in
7378 the recipes main package:
7379 <literallayout class='monospaced'>
7380 SYSTEMD_PACKAGES ?= "${PN}"
7381 </literallayout>
7382 If these unit files are not in this recipe's main
7383 package, you need to use
7384 <filename>SYSTEMD_PACKAGES</filename> to list the package
7385 or packages in which the build system can find the systemd
7386 unit files.
7387 </para>
7388 </glossdef>
7389 </glossentry>
7390
7391 <glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm>
7392 <glossdef>
7393 <para>
7394 For recipes that inherit the
7395 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
7396 class, this variable specifies the systemd service name for
7397 a package.
7398 </para>
7399
7400 <para>
7401 When you specify this file in your recipe, use a package
7402 name override to indicate the package to which the value
7403 applies.
7404 Here is an example from the connman recipe:
7405 <literallayout class='monospaced'>
7406 SYSTEMD_SERVICE_${PN} = "connman.service"
7407 </literallayout>
7408 </para>
7409 </glossdef>
7410 </glossentry>
7411
7412 </glossdiv>
7413
7414 <glossdiv id='var-glossary-t'><title>T</title>
7415
7416 <glossentry id='var-T'><glossterm>T</glossterm>
7417 <glossdef>
7418 <para>This variable points to a directory were BitBake places
7419 temporary files, which consist mostly of task logs and
7420 scripts, when building a particular recipe.
7421 The variable is typically set as follows:
7422 <literallayout class='monospaced'>
7423 T = "${WORKDIR}/temp"
7424 </literallayout>
7425 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
7426 is the directory into which BitBake unpacks and builds the
7427 recipe.
7428 The default <filename>bitbake.conf</filename> file sets this variable.</para>
7429 <para>The <filename>T</filename> variable is not to be confused with
7430 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
7431 which points to the root of the directory tree where BitBake
7432 places the output of an entire build.
7433 </para>
7434 </glossdef>
7435 </glossentry>
7436
7437 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
7438 <glossdef>
7439 <para>
7440 The target machine's architecture.
7441 The OpenEmbedded build system supports many
7442 architectures.
7443 Here is an example list of architectures supported.
7444 This list is by no means complete as the architecture
7445 is configurable:
7446 <literallayout class='monospaced'>
7447 arm
7448 i586
7449 x86_64
7450 powerpc
7451 powerpc64
7452 mips
7453 mipsel
7454 </literallayout>
7455 </para>
7456 </glossdef>
7457 </glossentry>
7458
7459 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
7460 <glossdef>
7461 <para>
7462 Flags passed to the C compiler for the target system.
7463 This variable evaluates to the same as
7464 <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>.
7465 </para>
7466 </glossdef>
7467 </glossentry>
7468
7469
7470 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
7471 <glossdef>
7472 <para>Specifies the method for handling FPU code.
7473 For FPU-less targets, which include most ARM CPUs, the variable must be
7474 set to "soft".
7475 If not, the kernel emulation gets used, which results in a performance penalty.</para>
7476 </glossdef>
7477 </glossentry>
7478
7479 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
7480 <glossdef>
7481 <para>Specifies the target's operating system.
7482 The variable can be set to "linux" for <filename>eglibc</filename>-based systems and
7483 to "linux-uclibc" for <filename>uclibc</filename>.
7484 For ARM/EABI targets, there are also "linux-gnueabi" and
7485 "linux-uclibc-gnueabi" values possible.</para>
7486 </glossdef>
7487 </glossentry>
7488
7489 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
7490 <glossdef>
7491 <para>
7492 Specifies the GNU standard C library (<filename>libc</filename>)
7493 variant to use during the build process.
7494 This variable replaces <filename>POKYLIBC</filename>, which is no longer
7495 supported.
7496 </para>
7497 <para>
7498 You can select "eglibc" or "uclibc".
7499 <note>
7500 This release of the Yocto Project does not support the
7501 <filename>glibc</filename> implementation of <filename>libc</filename>.
7502 </note>
7503 </para>
7504 </glossdef>
7505 </glossentry>
7506
7507 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
7508 <glossdef>
7509 <para>
7510 Specifies the toolchain selector.
7511 <filename>TCMODE</filename> controls the characteristics
7512 of the generated packages and images by telling the
7513 OpenEmbedded build system which toolchain profile to use.
7514 By default, the OpenEmbedded build system builds its own
7515 internal toolchain.
7516 The variable's default value is "default", which uses
7517 that internal toolchain.
7518 <note>
7519 If <filename>TCMODE</filename> is set to a value
7520 other than "default", then it is your responsibility
7521 to ensure that the toolchain is compatible with the
7522 default toolchain.
7523 Using older or newer versions of these components
7524 might cause build problems.
7525 See the
7526 <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
7527 for the specific components with which the toolchain
7528 must be compatible.
7529 </note>
7530 </para>
7531
7532 <para>
7533 With additional layers, it is possible to use a pre-compiled
7534 external toolchain.
7535 One example is the Sourcery G++ Toolchain.
7536 The support for this toolchain resides in the separate
7537 <filename>meta-sourcery</filename> layer at
7538 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
7539 You can use <filename>meta-sourcery</filename> as a
7540 template for adding support for other external toolchains.
7541 </para>
7542
7543 <para>
7544 The <filename>TCMODE</filename> variable points the build
7545 system to a file in
7546 <filename>conf/distro/include/tcmode-${TCMODE}.inc</filename>.
7547 Thus, for <filename>meta-sourcery</filename>,
7548 which has <filename>conf/distro/include/tcmode-external-sourcery.inc</filename>,
7549 you would set the variable as follows:
7550 <literallayout class='monospaced'>
7551 TCMODE ?= "external-sourcery"
7552 </literallayout>
7553 </para>
7554
7555 <para>
7556 The variable is similar to
7557 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
7558 which controls the variant of the GNU standard C library
7559 (<filename>libc</filename>) used during the build process:
7560 <filename>eglibc</filename> or <filename>uclibc</filename>.
7561 </para>
7562 </glossdef>
7563 </glossentry>
7564
7565 <glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>
7566 <glossdef>
7567 <para>
7568 The location the OpenEmbedded build system uses to export
7569 tests when the
7570 <link linkend='var-TEST_EXPORT_ONLY'><filename>TEST_EXPORT_ONLY</filename></link>
7571 variable is set to "1".
7572 </para>
7573
7574 <para>
7575 The <filename>TEST_EXPORT_DIR</filename> variable defaults
7576 to <filename>"${TMPDIR}/testimage/${PN}"</filename>.
7577 </para>
7578 </glossdef>
7579 </glossentry>
7580
7581 <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>
7582 <glossdef>
7583 <para>
7584 Specifies to export the tests only.
7585 Set this variable to "1" if you do not want to run the
7586 tests but you want them to be exported in a manner that
7587 you to run them outside of the build system.
7588 </para>
7589 </glossdef>
7590 </glossentry>
7591
7592 <glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm>
7593 <glossdef>
7594 <para>
7595 Automatically runs the series of automated tests for
7596 images when an image is successfully built.
7597 </para>
7598
7599 <para>
7600 These tests are written in Python making use of the
7601 <filename>unittest</filename> module, and the majority of
7602 them run commands on the target system over
7603 <filename>ssh</filename>.
7604 You can set this variable to "1" in your
7605 <filename>local.conf</filename> file in the
7606 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
7607 to have the OpenEmbedded build system automatically run
7608 these tests after an image successfully builds:
7609 <literallayout class='monospaced'>
7610 TEST_IMAGE = "1"
7611 </literallayout>
7612 For more information on enabling, running, and writing
7613 these tests, see the
7614 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
7615 section in the Yocto Project Development Manual and the
7616 "<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>"
7617 section.
7618 </para>
7619 </glossdef>
7620 </glossentry>
7621
7622 <glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm>
7623 <glossdef>
7624 <para>
7625 Holds the SSH log and the boot log for QEMU machines.
7626 The <filename>TEST_LOG_DIR</filename> variable defaults
7627 to <filename>"${WORKDIR}/testimage"</filename>.
7628 <note>
7629 Actual test results reside in the task log
7630 (<filename>log.do_testimage</filename>), which is in
7631 the <filename>${WORKDIR}/temp/</filename> directory.
7632 </note>
7633 </para>
7634 </glossdef>
7635 </glossentry>
7636
7637 <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
7638 <glossdef>
7639 <para>
7640 The time in seconds allowed for an image to boot before
7641 automated runtime tests begin to run against an
7642 image.
7643 The default timeout period to allow the boot process to
7644 reach the login prompt is 500 seconds.
7645 You can specify a different value in the
7646 <filename>local.conf</filename> file.
7647 </para>
7648
7649 <para>
7650 For more information on testing images, see the
7651 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
7652 section in the Yocto Project Development Manual.
7653 </para>
7654 </glossdef>
7655 </glossentry>
7656
7657 <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>
7658 <glossdef>
7659 <para>
7660 The IP address of the build machine (host machine).
7661 This IP address is usually automatically detected.
7662 However, if detection fails, this variable needs to be set
7663 to the IP address of the build machine (i.e. where
7664 the build is taking place).
7665 <note>
7666 The <filename>TEST_SERVER_IP</filename> variable
7667 is only used for a small number of tests such as
7668 the "smart" test suite, which needs to download
7669 packages from <filename>DEPLOY_DIR/rpm</filename>.
7670 </note>
7671 </para>
7672 </glossdef>
7673 </glossentry>
7674
7675 <glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>
7676 <glossdef>
7677 <para>
7678 Specifies the target controller to use when running tests
7679 against a test image.
7680 The default controller to use is "qemu":
7681 <literallayout class='monospaced'>
7682 TEST_TARGET = "qemu"
7683 </literallayout>
7684 A target controller is a class that defines how an
7685 image gets deployed on a target and how a target is started.
7686 A layer can extend the controllers by adding a module
7687 in the layer's <filename>/lib/oeqa/controllers</filename>
7688 directory and by inheriting the
7689 <filename>BaseTarget</filename> class, which is an abstract
7690 class that cannot be used as a value of
7691 <filename>TEST_TARGET</filename>.
7692 </para>
7693
7694 <para>
7695 You can provide the following arguments with
7696 <filename>TEST_TARGET</filename>:
7697 <itemizedlist>
7698 <listitem><para><emphasis>"qemu" and "QemuTarget":</emphasis>
7699 Boots a QEMU image and runs the tests.
7700 See the
7701 "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"
7702 section in the Yocto Project Development Manual for
7703 more information.
7704 </para></listitem>
7705 <listitem><para><emphasis>"simpleremote" and "SimpleRemoteTarget":</emphasis>
7706 Runs the tests on target hardware that is already
7707 up and running.
7708 The hardware can be on the network or it can be
7709 a device running an image on QEMU.
7710 You must also set
7711 <link linkend='var-TEST_TARGET_IP'><filename>TEST_TARGET_IP</filename></link>
7712 when you use "simpleremote" or "SimpleRemoteTarget".
7713 <note>
7714 This argument is defined in
7715 <filename>meta/lib/oeqa/targetcontrol.py</filename>.
7716 The small caps names are kept for compatibility
7717 reasons.
7718 </note>
7719 </para></listitem>
7720 <listitem><para><emphasis>"GummibootTarget":</emphasis>
7721 Automatically deploys and runs tests on an
7722 EFI-enabled machine that has a master image
7723 installed.
7724 <note>
7725 This argument is defined in
7726 <filename>meta/lib/oeqa/controllers/masterimage.py</filename>.
7727 </note>
7728 </para></listitem>
7729 </itemizedlist>
7730 </para>
7731
7732 <para>
7733 For information on running tests on hardware, see the
7734 "<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"
7735 section in the Yocto Project Development Manual.
7736 </para>
7737 </glossdef>
7738 </glossentry>
7739
7740 <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>
7741 <glossdef>
7742 <para>
7743 The IP address of your hardware under test.
7744 The <filename>TEST_TARGET_IP</filename> variable has no
7745 effect when
7746 <link linkend='var-TEST_TARGET'><filename>TEST_TARGET</filename></link>
7747 is set to "qemu".
7748 </para>
7749
7750 <para>
7751 When you specify the IP address, you can also include a
7752 port.
7753 Here is an example:
7754 <literallayout class='monospaced'>
7755 TEST_TARGET_IP = "192.168.1.4:2201"
7756 </literallayout>
7757 Specifying a port is useful when SSH is started on a
7758 non-standard port or in cases when your hardware under test
7759 is behind a firewall or network that is not directly
7760 accessible from your host and you need to do port address
7761 translation.
7762 </para>
7763 </glossdef>
7764 </glossentry>
7765
7766 <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
7767 <glossdef>
7768 <para>
7769 An ordered list of tests (modules) to run against
7770 an image when performing automated runtime testing.
7771 </para>
7772
7773 <para>
7774 The OpenEmbedded build system provides a core set of tests
7775 that can be used against images.
7776 <note>
7777 Currently, there is only support for running these tests
7778 under QEMU.
7779 </note>
7780 Tests include <filename>ping</filename>,
7781 <filename>ssh</filename>, <filename>df</filename> among
7782 others.
7783 You can add your own tests to the list of tests by
7784 appending <filename>TEST_SUITES</filename> as follows:
7785 <literallayout class='monospaced'>
7786 TEST_SUITES_append = " mytest"
7787 </literallayout>
7788 Alternatively, you can provide the "auto" option to
7789 have all applicable tests run against the image.
7790 <literallayout class='monospaced'>
7791 TEST_SUITES_append = " auto"
7792 </literallayout>
7793 Using this option causes the build system to automatically
7794 run tests that are applicable to the image.
7795 Tests that are not applicable are skipped.
7796 </para>
7797
7798 <para>
7799 The order in which tests are run is important.
7800 Tests that depend on another test must appear later in the
7801 list than the test on which they depend.
7802 For example, if you append the list of tests with two
7803 tests (<filename>test_A</filename> and
7804 <filename>test_B</filename>) where
7805 <filename>test_B</filename> is dependent on
7806 <filename>test_A</filename>, then you must order the tests
7807 as follows:
7808 <literallayout class='monospaced'>
7809 TEST_SUITES = " test_A test_B"
7810 </literallayout>
7811 </para>
7812
7813 <para>
7814 For more information on testing images, see the
7815 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
7816 section in the Yocto Project Development Manual.
7817 </para>
7818 </glossdef>
7819 </glossentry>
7820
7821 <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
7822 <glossdef>
7823 <para>
7824 The directory in which the file BitBake is currently
7825 parsing is located.
7826 Do not manually set this variable.
7827 </para>
7828 </glossdef>
7829 </glossentry>
7830
7831 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
7832 <glossdef>
7833 <para>
7834 This variable is the base directory the OpenEmbedded
7835 build system uses for all build output and intermediate
7836 files (other than the shared state cache).
7837 By default, the <filename>TMPDIR</filename> variable points
7838 to <filename>tmp</filename> within the
7839 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
7840 </para>
7841
7842 <para>
7843 If you want to establish this directory in a location other
7844 than the default, you can uncomment and edit the following
7845 statement in the
7846 <filename>conf/local.conf</filename> file in the
7847 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
7848 <literallayout class='monospaced'>
7849 #TMPDIR = "${TOPDIR}/tmp"
7850 </literallayout>
7851 An example use for this scenario is to set
7852 <filename>TMPDIR</filename> to a local disk, which does
7853 not use NFS, while having the Build Directory use NFS.
7854 </para>
7855
7856 <para>
7857 The filesystem used by <filename>TMPDIR</filename> must
7858 have standard filesystem semantics (i.e. mixed-case files
7859 are unique, POSIX file locking, and persistent inodes).
7860 Due to various issues with NFS and bugs in some
7861 implementations, NFS does not meet this minimum
7862 requirement.
7863 Consequently, <filename>TMPDIR</filename> cannot be on
7864 NFS.
7865 </para>
7866 </glossdef>
7867 </glossentry>
7868
7869 <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
7870 <glossdef>
7871 <para>
7872 This variable lists packages the OpenEmbedded build system
7873 uses when building an SDK, which contains a
7874 cross-development environment.
7875 The packages specified by this variable are part of the
7876 toolchain set that runs on the
7877 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
7878 and each package should usually have the prefix
7879 "nativesdk-".
7880 When building an SDK using
7881 <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>,
7882 a default list of packages is set in this variable, but
7883 you can add additional packages to the list.
7884 </para>
7885
7886 <para>
7887 For background information on cross-development toolchains
7888 in the Yocto Project development environment, see the
7889 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
7890 section.
7891 For information on setting up a cross-development
7892 environment, see the
7893 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
7894 section in the Yocto Project Application Developer's Guide.
7895 </para>
7896 </glossdef>
7897 </glossentry>
7898
7899 <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
7900 <glossdef>
7901 <para>
7902 This variable lists packages the OpenEmbedded build system
7903 uses when it creates the target part of an SDK
7904 (i.e. the part built for the target hardware), which
7905 includes libraries and headers.
7906 </para>
7907
7908 <para>
7909 For background information on cross-development toolchains
7910 in the Yocto Project development environment, see the
7911 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
7912 section.
7913 For information on setting up a cross-development
7914 environment, see the
7915 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
7916 section in the Yocto Project Application Developer's Guide.
7917 </para>
7918 </glossdef>
7919 </glossentry>
7920
7921 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
7922 <glossdef>
7923 <para>
7924 The top-level
7925 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
7926 BitBake automatically sets this variable when you
7927 initialize your build environment using either
7928 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
7929 or
7930 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
7931 </para>
7932 </glossdef>
7933 </glossentry>
7934
7935 <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
7936 <glossdef>
7937 <para>
7938 A sanitized version of
7939 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
7940 This variable is used where the architecture is needed in
7941 a value where underscores are not allowed, for example
7942 within package filenames.
7943 In this case, dash characters replace any underscore
7944 characters used in TARGET_ARCH.
7945 </para>
7946
7947 <para>
7948 Do not edit this variable.
7949 </para>
7950 </glossdef>
7951 </glossentry>
7952
7953 <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
7954 <glossdef>
7955 <para>
7956 The package architecture understood by the packaging
7957 system to define the architecture, ABI, and tuning of
7958 output packages.
7959 </para>
7960 </glossdef>
7961 </glossentry>
7962
7963 </glossdiv>
7964
7965 <glossdiv id='var-glossary-u'><title>U</title>
7966
7967 <glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm>
7968 <glossdef>
7969 <para>
7970 Configures the
7971 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
7972 and can also define
7973 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
7974 for individual cases.
7975 </para>
7976
7977 <para>
7978 Following is an example from the
7979 <filename>meta-fsl-arm</filename> layer.
7980 <literallayout class='monospaced'>
7981 UBOOT_CONFIG ??= "sd"
7982 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
7983 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
7984 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
7985 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
7986 </literallayout>
7987 In this example, "sd" is selected as the configuration
7988 of the possible four for the
7989 <filename>UBOOT_MACHINE</filename>.
7990 The "sd" configuration defines "mx6qsabreauto_config"
7991 as the value for <filename>UBOOT_MACHINE</filename>, while
7992 the "sdcard" specifies the
7993 <filename>IMAGE_FSTYPES</filename> to use for the U-boot
7994 image.
7995 </para>
7996
7997 <para>
7998 For more information on how the
7999 <filename>UBOOT_CONFIG</filename> is handled, see the
8000 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass'><filename>uboot-config</filename></ulink>
8001 class.
8002 </para>
8003 </glossdef>
8004 </glossentry>
8005
8006 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
8007 <glossdef>
8008 <para>
8009 Specifies the entry point for the U-Boot image.
8010 During U-Boot image creation, the
8011 <filename>UBOOT_ENTRYPOINT</filename> variable is passed
8012 as a command-line parameter to the
8013 <filename>uboot-mkimage</filename> utility.
8014 </para>
8015 </glossdef>
8016 </glossentry>
8017
8018 <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
8019 <glossdef>
8020 <para>
8021 Specifies the load address for the U-Boot image.
8022 During U-Boot image creation, the
8023 <filename>UBOOT_LOADADDRESS</filename> variable is passed
8024 as a command-line parameter to the
8025 <filename>uboot-mkimage</filename> utility.
8026 </para>
8027 </glossdef>
8028 </glossentry>
8029
8030 <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>
8031 <glossdef>
8032 <para>
8033 Appends a string to the name of the local version of the
8034 U-Boot image.
8035 For example, assuming the version of the U-Boot image
8036 built was "2013.10, the full version string reported by
8037 U-Boot would be "2013.10-yocto" given the following
8038 statement:
8039 <literallayout class='monospaced'>
8040 UBOOT_LOCALVERSION = "-yocto"
8041 </literallayout>
8042 </para>
8043 </glossdef>
8044 </glossentry>
8045
8046 <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
8047 <glossdef>
8048 <para>
8049 Specifies the value passed on the
8050 <filename>make</filename> command line when building
8051 a U-Boot image.
8052 The value indicates the target platform configuration.
8053 You typically set this variable from the machine
8054 configuration file (i.e.
8055 <filename>conf/machine/&lt;machine_name&gt;.conf</filename>).
8056 </para>
8057 </glossdef>
8058 </glossentry>
8059
8060 <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm>
8061 <glossdef>
8062 <para>
8063 Specifies the target called in the
8064 <filename>Makefile</filename>.
8065 The default target is "all".
8066 </para>
8067 </glossdef>
8068 </glossentry>
8069
8070 <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>
8071 <glossdef>
8072 <para>
8073 Points to the generated U-Boot extension.
8074 For example, <filename>u-boot.sb</filename> has a
8075 <filename>.sb</filename> extension.
8076 </para>
8077
8078 <para>
8079 The default U-Boot extension is
8080 <filename>.bin</filename>
8081 </para>
8082 </glossdef>
8083 </glossentry>
8084
8085 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
8086 <glossdef>
8087 <para>
8088 Specifies the target used for building U-Boot.
8089 The target is passed directly as part of the "make" command
8090 (e.g. SPL and AIS).
8091 If you do not specifically set this variable, the
8092 OpenEmbedded build process passes and uses "all" for the
8093 target during the U-Boot building process.
8094 </para>
8095 </glossdef>
8096 </glossentry>
8097
8098 <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
8099 <glossdef>
8100 <para>
8101 A list of classes to globally inherit.
8102 These classes are used by the OpenEmbedded build system
8103 to enable extra features (e.g.
8104 <filename>buildstats</filename>,
8105 <filename>image-mklibs</filename>, and so forth).
8106 </para>
8107
8108 <para>
8109 The default list is set in your
8110 <filename>local.conf</filename> file:
8111 <literallayout class='monospaced'>
8112 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
8113 </literallayout>
8114 For more information, see
8115 <filename>meta-yocto/conf/local.conf.sample</filename> in
8116 the
8117 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
8118 </para>
8119 </glossdef>
8120 </glossentry>
8121
8122 <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>
8123 <glossdef>
8124 <para>
8125 Forces the OpenEmbedded build system to produce an error
8126 if the user identification (<filename>uid</filename>) and
8127 group identification (<filename>gid</filename>) values
8128 are not defined in <filename>files/passwd</filename>
8129 and <filename>files/group</filename> files.
8130 </para>
8131
8132 <para>
8133 The default behavior for the build system is to dynamically
8134 apply <filename>uid</filename> and
8135 <filename>gid</filename> values.
8136 Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>
8137 variable is by default not set.
8138 If you plan on using statically assigned
8139 <filename>gid</filename> and <filename>uid</filename>
8140 values, you should set
8141 the <filename>USERADD_ERROR_DYNAMIC</filename> variable in
8142 your <filename>local.conf</filename> file as
8143 follows:
8144 <literallayout class='monospaced'>
8145 USERADD_ERROR_DYNAMIC = "1"
8146 </literallayout>
8147 Overriding the default behavior implies you are going to
8148 also take steps to set static <filename>uid</filename> and
8149 <filename>gid</filename> values through use of the
8150 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
8151 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
8152 and
8153 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
8154 variables.
8155 </para>
8156 </glossdef>
8157 </glossentry>
8158
8159 <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>
8160 <glossdef>
8161 <para>
8162 Specifies a password file to use for obtaining static
8163 group identification (<filename>gid</filename>) values
8164 when the OpenEmbedded build system adds a group to the
8165 system during package installation.
8166 </para>
8167
8168 <para>
8169 When applying static group identification
8170 (<filename>gid</filename>) values, the OpenEmbedded build
8171 system looks in
8172 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
8173 for a <filename>files/group</filename> file and then applies
8174 those <filename>uid</filename> values.
8175 Set the variable as follows in your
8176 <filename>local.conf</filename> file:
8177 <literallayout class='monospaced'>
8178 USERADD_GID_TABLES = "files/group"
8179 </literallayout>
8180 </para>
8181
8182 <note>
8183 Setting the
8184 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
8185 variable to "useradd-staticids" causes the build system
8186 to use static <filename>gid</filename> values.
8187 </note>
8188 </glossdef>
8189 </glossentry>
8190
8191 <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>
8192 <glossdef>
8193 <para>
8194 Specifies a password file to use for obtaining static
8195 user identification (<filename>uid</filename>) values
8196 when the OpenEmbedded build system adds a user to the
8197 system during package installation.
8198 </para>
8199
8200 <para>
8201 When applying static user identification
8202 (<filename>uid</filename>) values, the OpenEmbedded build
8203 system looks in
8204 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
8205 for a <filename>files/passwd</filename> file and then applies
8206 those <filename>uid</filename> values.
8207 Set the variable as follows in your
8208 <filename>local.conf</filename> file:
8209 <literallayout class='monospaced'>
8210 USERADD_UID_TABLES = "files/passwd"
8211 </literallayout>
8212 </para>
8213
8214 <note>
8215 Setting the
8216 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
8217 variable to "useradd-staticids" causes the build system
8218 to use static <filename>uid</filename> values.
8219 </note>
8220 </glossdef>
8221 </glossentry>
8222
8223 <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>
8224 <glossdef>
8225 <para>
8226 When a recipe inherits the
8227 <filename>useradd</filename> class, this variable
8228 specifies the individual packages within the recipe that
8229 require users and/or groups to be added.
8230 </para>
8231
8232 <para>
8233 You must set this variable if the recipe inherits the
8234 class.
8235 For example, the following enables adding a user for the
8236 main package in a recipe:
8237 <literallayout class='monospaced'>
8238 USERADD_PACKAGES = "${PN}"
8239 </literallayout>
8240 <note>
8241 If follows that if you are going to use the
8242 <filename>USERADD_PACKAGES</filename> variable,
8243 you need to set one or more of the
8244 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
8245 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
8246 or
8247 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
8248 variables.
8249 </note>
8250 </para>
8251
8252 </glossdef>
8253 </glossentry>
8254
8255 <glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>
8256 <glossdef>
8257 <para>
8258 When a recipe inherits the
8259 <filename>useradd</filename> class, this variable
8260 specifies for a package what parameters should be passed
8261 to the <filename>useradd</filename> command
8262 if you wish to add a user to the system when the package
8263 is installed.
8264 </para>
8265
8266 <para>
8267 Here is an example from the <filename>dbus</filename>
8268 recipe:
8269 <literallayout class='monospaced'>
8270 USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \
8271 --no-create-home --shell /bin/false \
8272 --user-group messagebus"
8273 </literallayout>
8274 For information on the standard Linux shell command
8275 <filename>useradd</filename>, see
8276 <ulink url='http://linux.die.net/man/8/useradd'></ulink>.
8277 </para>
8278 </glossdef>
8279 </glossentry>
8280
8281 <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>
8282 <glossdef>
8283 <para>
8284 When set to "useradd-staticids", causes the
8285 OpenEmbedded build system to base all user and group
8286 additions on a static
8287 <filename>passwd</filename> and
8288 <filename>group</filename> files found in
8289 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
8290 </para>
8291
8292 <para>
8293 To use static user identification (<filename>uid</filename>)
8294 and group identification (<filename>gid</filename>)
8295 values, set the variable
8296 as follows in your <filename>local.conf</filename> file:
8297 <literallayout class='monospaced'>
8298 USERADDEXTENSION = "useradd-staticids"
8299 </literallayout>
8300 <note>
8301 Setting this variable to use static
8302 <filename>uid</filename> and <filename>gid</filename>
8303 values causes the OpenEmbedded build system to employ
8304 the
8305 <link linkend='ref-classes-useradd-staticids'><filename>useradd-staticids</filename></link>
8306 class.
8307 </note>
8308 </para>
8309
8310 <para>
8311 If you use static <filename>uid</filename> and
8312 <filename>gid</filename> information, you must also
8313 specify the <filename>files/passwd</filename> and
8314 <filename>files/group</filename> files by setting the
8315 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
8316 and
8317 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
8318 variables.
8319 Additionally, you should also set the
8320 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
8321 variable.
8322 </para>
8323 </glossdef>
8324 </glossentry>
8325
8326 </glossdiv>
8327
8328<!-- <glossdiv id='var-glossary-v'><title>V</title>-->
8329<!-- </glossdiv>-->
8330
8331 <glossdiv id='var-glossary-w'><title>W</title>
8332
8333 <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
8334 <glossdef>
8335 <para>
8336 Specifies the quality assurance checks whose failures are
8337 reported as warnings by the OpenEmbedded build system.
8338 You set this variable in your distribution configuration
8339 file.
8340 For a list of the checks you can control with this variable,
8341 see the
8342 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
8343 section.
8344 </para>
8345 </glossdef>
8346 </glossentry>
8347
8348 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
8349 <glossdef>
8350 <para>
8351 The pathname of the work directory in which the OpenEmbedded
8352 build system builds a recipe.
8353 This directory is located within the
8354 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
8355 directory structure and is specific to the recipe being
8356 built and the system for which it is being built.
8357 </para>
8358
8359 <para>
8360 The <filename>WORKDIR</filename> directory is defined as
8361 follows:
8362 <literallayout class='monospaced'>
8363 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
8364 </literallayout>
8365 The actual directory depends on several things:
8366 <itemizedlist>
8367 <listitem><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>:
8368 The top-level build output directory</listitem>
8369 <listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>:
8370 The target system identifier</listitem>
8371 <listitem><link linkend='var-PN'><filename>PN</filename></link>:
8372 The recipe name</listitem>
8373 <listitem><link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>:
8374 The epoch - (if
8375 <link linkend='var-PE'><filename>PE</filename></link>
8376 is not specified, which is usually the case for most
8377 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
8378 <listitem><link linkend='var-PV'><filename>PV</filename></link>:
8379 The recipe version</listitem>
8380 <listitem><link linkend='var-PR'><filename>PR</filename></link>:
8381 The recipe revision</listitem>
8382 </itemizedlist>
8383 </para>
8384
8385 <para>
8386 As an example, assume a Source Directory top-level folder
8387 name <filename>poky</filename>, a default Build Directory at
8388 <filename>poky/build</filename>, and a
8389 <filename>qemux86-poky-linux</filename> machine target
8390 system.
8391 Furthermore, suppose your recipe is named
8392 <filename>foo_1.3.0-r0.bb</filename>.
8393 In this case, the work directory the build system uses to
8394 build the package would be as follows:
8395 <literallayout class='monospaced'>
8396 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
8397 </literallayout>
8398 </para>
8399 </glossdef>
8400 </glossentry>
8401
8402 </glossdiv>
8403
8404<!-- <glossdiv id='var-glossary-x'><title>X</title>-->
8405<!-- </glossdiv>-->
8406
8407<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
8408<!-- </glossdiv>-->
8409
8410<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
8411<!-- </glossdiv>-->
8412
8413</glossary>
8414</chapter>
8415<!--
8416vim: expandtab tw=80 ts=4
8417-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-01-31 04:29:24 +0000