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.xml5888
1 files changed, 5888 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..f3211f84ed
--- /dev/null
+++ b/documentation/ref-manual/ref-variables.xml
@@ -0,0 +1,5888 @@
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-FILES'>F</link>
25<!-- <link linkend='var-glossary-g'>G</link> -->
26 <link linkend='var-HOMEPAGE'>H</link>
27 <link linkend='var-IMAGE_BASENAME'>I</link>
28<!-- <link linkend='var-glossary-j'>J</link> -->
29 <link linkend='var-KARCH'>K</link>
30 <link linkend='var-LAYERDEPENDS'>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-glossary-q'>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_ENTRYPOINT'>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 runtime hard-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.
62 Here is an example:
63 <literallayout class='monospaced'>
64 ALLOW_EMPTY_${PN} = "1"
65 </literallayout>
66 </para>
67 </glossdef>
68 </glossentry>
69
70 <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
71 <glossdef>
72 <para>
73 Lists commands in a package that need an alternative
74 binary naming scheme.
75 Sometimes the same command is provided in multiple packages.
76 When this occurs, the OpenEmbedded build system needs to
77 use the alternatives system to create a different binary
78 naming scheme so the commands can co-exist.
79 </para>
80
81 <para>
82 To use the variable, list out the package's commands
83 that also exist as part of another package.
84 For example, if the <filename>busybox</filename> package
85 has four commands that also exist as part of another
86 package, you identify them as follows:
87 <literallayout class='monospaced'>
88 ALTERNATIVE_busybox = "sh sed test bracket"
89 </literallayout>
90 For more information on the alternatives system, see the
91 "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
92 section.
93 </para>
94 </glossdef>
95 </glossentry>
96
97 <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
98 <glossdef>
99 <para>
100 Used by the alternatives system to map duplicated commands
101 to actual locations.
102 For example, if the <filename>bracket</filename> command
103 provided by the <filename>busybox</filename> package is
104 duplicated through another package, you must use the
105 <filename>ALTERNATIVE_LINK_NAME</filename> variable to
106 specify the actual location:
107 <literallayout class='monospaced'>
108 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
109 </literallayout>
110 In this example, the binary for the
111 <filename>bracket</filename> command (i.e.
112 <filename>[</filename>) from the
113 <filename>busybox</filename> package resides in
114 <filename>/usr/bin/</filename>.
115 <note>
116 If <filename>ALTERNATIVE_LINK_NAME</filename> is not
117 defined, it defaults to
118 <filename>${bindir}/&lt;name&gt;</filename>.
119 </note>
120 </para>
121
122 <para>
123 For more information on the alternatives system, see the
124 "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
125 section.
126 </para>
127 </glossdef>
128 </glossentry>
129
130 <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
131 <glossdef>
132 <para>
133 Used by the alternatives system to create default
134 priorities for duplicated commands.
135 You can use the variable to create a single default
136 regardless of the command name or package, a default for
137 specific duplicated commands regardless of the package, or
138 a default for specific commands tied to particular packages.
139 Here are the available syntax forms:
140 <literallayout class='monospaced'>
141 ALTERNATIVE_PRIORITY = "&lt;priority&gt;"
142 ALTERNATIVE_PRIORITY[&lt;name&gt;] = "&lt;priority&gt;"
143 ALTERNATIVE_PRIORITY_&lt;pkg&gt;[&lt;name&gt;] = "&lt;priority&gt;"
144 </literallayout>
145 </para>
146
147 <para>
148 For more information on the alternatives system, see the
149 "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
150 section.
151 </para>
152 </glossdef>
153 </glossentry>
154
155 <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
156 <glossdef>
157 <para>
158 Used by the alternatives system to create default link
159 locations for duplicated commands.
160 You can use the variable to create a single default
161 location for all duplicated commands regardless of the
162 command name or package, a default for
163 specific duplicated commands regardless of the package, or
164 a default for specific commands tied to particular packages.
165 Here are the available syntax forms:
166 <literallayout class='monospaced'>
167 ALTERNATIVE_TARGET = "&lt;target&gt;"
168 ALTERNATIVE_TARGET[&lt;name&gt;] = "&lt;target&gt;"
169 ALTERNATIVE_TARGET_&lt;pkg&gt;[&lt;name&gt;] = "&lt;target&gt;"
170 </literallayout>
171 <note>
172 <para>
173 If <filename>ALTERNATIVE_TARGET</filename> is not
174 defined, it inherits the value from the
175 <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
176 variable.
177 </para>
178
179 <para>
180 If <filename>ALTERNATIVE_LINK_NAME</filename> and
181 <filename>ALTERNATIVE_TARGET</filename> are the
182 same, the target for
183 <filename>ALTERNATIVE_TARGET</filename>
184 has "<filename>.{BPN}</filename>" appended to it.
185 </para>
186
187 <para>
188 Finally, if the file referenced has not been
189 renamed, the alternatives system will rename it to
190 avoid the need to rename alternative files in the
191 <filename>do_install</filename> task while
192 retaining support for the command if necessary.
193 </para>
194 </note>
195 </para>
196
197 <para>
198 For more information on the alternatives system, see the
199 "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
200 section.
201 </para>
202 </glossdef>
203 </glossentry>
204
205 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
206 <glossdef>
207 <para>The email address used to contact the original author
208 or authors in order to send patches and forward bugs.</para>
209 </glossdef>
210 </glossentry>
211
212 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
213 <glossdef>
214 <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
215 is set to the value of this variable, it specifies to use the latest
216 source revision in the repository.
217 Here is an example:
218 <literallayout class='monospaced'>
219 SRCREV = "${AUTOREV}"
220 </literallayout>
221 </para>
222 </glossdef>
223 </glossentry>
224
225 </glossdiv>
226
227 <glossdiv id='var-glossary-b'><title>B</title>
228
229 <glossentry id='var-B'><glossterm>B</glossterm>
230 <glossdef>
231 <para>
232 The directory within the
233 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
234 in which the OpenEmbedded build system places generated
235 objects during a recipe's build process.
236 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
237 directory:
238 <literallayout class='monospaced'>
239 B = "${WORKDIR}/${BPN}/{PV}/"
240 </literallayout>
241 You can separate the (<filename>S</filename>) directory
242 and the directory pointed to by the <filename>B</filename>
243 variable.
244 Most Autotools-based recipes support separating these
245 directories.
246 The build system defaults to using separate directories for
247 <filename>gcc</filename> and some kernel recipes.
248 </para>
249 </glossdef>
250 </glossentry>
251
252 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
253 <glossdef>
254 <para>
255 Lists "recommended-only" packages to not install.
256 Recommended-only packages are packages installed only
257 through the
258 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
259 variable.
260 You can prevent any of these "recommended" packages from
261 being installed by listing them with the
262 <filename>BAD_RECOMMENDATIONS</filename> variable:
263 <literallayout class='monospaced'>
264 BAD_RECOMMENDATIONS = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
265 </literallayout>
266 You can set this variable globally in your
267 <filename>local.conf</filename> file or you can attach it to
268 a specific image recipe by using the recipe name override:
269 <literallayout class='monospaced'>
270 BAD_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
271 </literallayout>
272 </para>
273
274 <para>
275 It is important to realize that if you choose to not install
276 packages using this variable and some other packages are
277 dependent on them (i.e. listed in a recipe's
278 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
279 variable), the OpenEmbedded build system ignores your
280 request and will install the packages to avoid dependency
281 errors.
282 </para>
283
284 <para>
285 Support for this variable exists only when using the
286 IPK and RPM packaging backend.
287 Support does not exist for DEB.
288 </para>
289
290 <para>
291 See the
292 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
293 and the
294 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
295 variables for related information.
296 </para>
297 </glossdef>
298 </glossentry>
299
300 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
301 <glossdef>
302 <para>
303 Defines how BitBake handles situations where an append
304 file (<filename>.bbappend</filename>) has no
305 corresponding recipe file (<filename>.bb</filename>).
306 This condition often occurs when layers get out of sync
307 (e.g. <filename>oe-core</filename> bumps a
308 recipe version and the old recipe no longer exists and the
309 other layer has not been updated to the new version
310 of the recipe yet).
311 </para>
312
313 <para>
314 The default fatal behavior is safest because it is
315 the sane reaction given something is out of sync.
316 It is important to realize when your changes are no longer
317 being applied.
318 </para>
319
320 <para>
321 You can change the default behavior by setting this
322 variable to "1" in the <filename>local.conf</filename>
323 file in the
324 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
325 as follows:
326 <literallayout class='monospaced'>
327 BB_DANGLINGAPPENDS_WARNONLY = "1"
328 </literallayout>
329 </para>
330 </glossdef>
331 </glossentry>
332
333 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
334 <glossdef>
335 <para>
336 Monitors disk space and available inodes during the build
337 and allows you to control the build based on these
338 parameters.
339 </para>
340
341 <para>
342 Disk space monitoring is disabled by default.
343 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
344 variable to your <filename>conf/local.conf</filename> file found in the
345 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
346 Use the following form:
347 <literallayout class='monospaced'>
348 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
349
350 where:
351
352 &lt;action&gt; is:
353 ABORT: Immediately abort the build when
354 a threshold is broken.
355 STOPTASKS: Stop the build after the currently
356 executing tasks have finished when
357 a threshold is broken.
358 WARN: Issue a warning but continue the
359 build when a threshold is broken.
360 Subsequent warnings are issued as
361 defined by the
362 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
363 which must be defined in the
364 conf/local.conf file.
365
366 &lt;dir&gt; is:
367 Any directory you choose. You can specify one or
368 more directories to monitor by separating the
369 groupings with a space. If two directories are
370 on the same device, only the first directory
371 is monitored.
372
373 &lt;threshold&gt; is:
374 Either the minimum available disk space,
375 the minimum number of free inodes, or
376 both. You must specify at least one. To
377 omit one or the other, simply omit the value.
378 Specify the threshold using G, M, K for Gbytes,
379 Mbytes, and Kbytes, respectively. If you do
380 not specify G, M, or K, Kbytes is assumed by
381 default. Do not use GB, MB, or KB.
382 </literallayout>
383 </para>
384
385 <para>
386 Here are some examples:
387 <literallayout class='monospaced'>
388 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
389 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
390 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
391 </literallayout>
392 The first example works only if you also provide
393 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
394 in the <filename>conf/local.conf</filename>.
395 This example causes the build system to immediately
396 abort when either the disk space in <filename>${TMPDIR}</filename> drops
397 below 1 Gbyte or the available free inodes drops below
398 100 Kbytes.
399 Because two directories are provided with the variable, the
400 build system also issue a
401 warning when the disk space in the
402 <filename>${SSTATE_DIR}</filename> directory drops
403 below 1 Gbyte or the number of free inodes drops
404 below 100 Kbytes.
405 Subsequent warnings are issued during intervals as
406 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
407 variable.
408 </para>
409
410 <para>
411 The second example stops the build after all currently
412 executing tasks complete when the minimum disk space
413 in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
414 directory drops below 1 Gbyte.
415 No disk monitoring occurs for the free inodes in this case.
416 </para>
417
418 <para>
419 The final example immediately aborts the build when the
420 number of free inodes in the <filename>${TMPDIR}</filename> directory
421 drops below 100 Kbytes.
422 No disk space monitoring for the directory itself occurs
423 in this case.
424 </para>
425 </glossdef>
426 </glossentry>
427
428 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
429 <glossdef>
430 <para>
431 Defines the disk space and free inode warning intervals.
432 To set these intervals, define the variable in your
433 <filename>conf/local.conf</filename> file in the
434 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
435 </para>
436
437 <para>
438 If you are going to use the
439 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
440 also use the
441 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
442 and define its action as "WARN".
443 During the build, subsequent warnings are issued each time
444 disk space or number of free inodes further reduces by
445 the respective interval.
446 </para>
447
448 <para>
449 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
450 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
451 the "WARN" action, the disk monitoring interval defaults to
452 the following:
453 <literallayout class='monospaced'>
454 BB_DISKMON_WARNINTERVAL = "50M,5K"
455 </literallayout>
456 </para>
457
458 <para>
459 When specifying the variable in your configuration file,
460 use the following form:
461 <literallayout class='monospaced'>
462 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
463
464 where:
465
466 &lt;disk_space_interval&gt; is:
467 An interval of memory expressed in either
468 G, M, or K for Gbytes, Mbytes, or Kbytes,
469 respectively. You cannot use GB, MB, or KB.
470
471 &lt;disk_inode_interval&gt; is:
472 An interval of free inodes expressed in either
473 G, M, or K for Gbytes, Mbytes, or Kbytes,
474 respectively. You cannot use GB, MB, or KB.
475 </literallayout>
476 </para>
477
478 <para>
479 Here is an example:
480 <literallayout class='monospaced'>
481 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
482 BB_DISKMON_WARNINTERVAL = "50M,5K"
483 </literallayout>
484 These variables cause the OpenEmbedded build system to
485 issue subsequent warnings each time the available
486 disk space further reduces by 50 Mbytes or the number
487 of free inodes further reduces by 5 Kbytes in the
488 <filename>${SSTATE_DIR}</filename> directory.
489 Subsequent warnings based on the interval occur each time
490 a respective interval is reached beyond the initial warning
491 (i.e. 1 Gbytes and 100 Kbytes).
492 </para>
493 </glossdef>
494 </glossentry>
495
496 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
497 <glossdef>
498 <para>
499 Causes tarballs of the Git repositories to be placed in the
500 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
501 directory.
502 For performance reasons, creating and placing tarballs of
503 the Git repositories is not the default action by the
504 OpenEmbedded build system.
505 <literallayout class='monospaced'>
506 BB_Generate_MIRROR_TARBALLS = "1"
507 </literallayout>
508 Set this variable in your <filename>local.conf</filename>
509 file in the
510 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
511 </para>
512 </glossdef>
513 </glossentry>
514
515 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
516 <glossdef>
517 <para>The maximum number of tasks BitBake should run in parallel at any one time.
518 If your host development system supports multiple cores a good rule of thumb
519 is to set this variable to twice the number of cores.</para>
520 </glossdef>
521 </glossentry>
522
523 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
524 <glossdef>
525 <para>
526 Allows you to extend a recipe so that it builds variants of the software.
527 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
528 which is a copy of Quilt built to run on the build system;
529 "crosses" such as <filename>gcc-cross</filename>,
530 which is a compiler built to run on the build machine but produces binaries
531 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
532 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
533 and "mulitlibs" in the form "<filename>multilib:&lt;multilib_name&gt;</filename>".
534 </para>
535
536 <para>
537 To build a different variant of the recipe with a minimal amount of code, it usually
538 is as simple as adding the following to your recipe:
539 <literallayout class='monospaced'>
540 BBCLASSEXTEND =+ "native nativesdk"
541 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
542 </literallayout>
543 </para>
544 </glossdef>
545 </glossentry>
546
547 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
548 <glossdef>
549 <para>Lists the names of configured layers.
550 These names are used to find the other <filename>BBFILE_*</filename>
551 variables.
552 Typically, each layer will append its name to this variable in its
553 <filename>conf/layer.conf</filename> file.
554 </para>
555 </glossdef>
556 </glossentry>
557
558 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
559 <glossdef>
560 <para>Variable that expands to match files from
561 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
562 in a particular layer.
563 This variable is used in the <filename>conf/layer.conf</filename> file and must
564 be suffixed with the name of the specific layer (e.g.
565 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
566 </glossdef>
567 </glossentry>
568
569 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
570 <glossdef>
571 <para>Assigns the priority for recipe files in each layer.</para>
572 <para>This variable is useful in situations where the same recipe appears in
573 more than one layer.
574 Setting this variable allows you to prioritize a
575 layer against other layers that contain the same recipe - effectively
576 letting you control the precedence for the multiple layers.
577 The precedence established through this variable stands regardless of a
578 recipe's version
579 (<link linkend='var-PV'><filename>PV</filename></link> variable).
580 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
581 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
582 lower precedence.</para>
583 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
584 precedence.
585 For example, the value 6 has a higher precedence than the value 5.
586 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
587 dependencies (see the
588 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
589 more information.
590 The default priority, if unspecified
591 for a layer with no dependencies, is the lowest defined priority + 1
592 (or 1 if no priorities are defined).</para>
593 <tip>
594 You can use the command <filename>bitbake-layers show_layers</filename> to list
595 all configured layers along with their priorities.
596 </tip>
597 </glossdef>
598 </glossentry>
599
600 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
601 <glossdef>
602 <para>List of recipe files used by BitBake to build software.</para>
603 </glossdef>
604 </glossentry>
605
606 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
607 <glossdef>
608 <para>Variable that controls how BitBake displays logs on build failure.</para>
609 </glossdef>
610 </glossentry>
611
612 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
613 <glossdef>
614 <para>Lists the layers to enable during the build.
615 This variable is defined in the <filename>bblayers.conf</filename> configuration
616 file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
617 Here is an example:
618 <literallayout class='monospaced'>
619 BBLAYERS = " \
620 /home/scottrif/poky/meta \
621 /home/scottrif/poky/meta-yocto \
622 /home/scottrif/poky/meta-yocto-bsp \
623 /home/scottrif/poky/meta-mykernel \
624 "
625
626 BBLAYERS_NON_REMOVABLE ?= " \
627 /home/scottrif/poky/meta \
628 /home/scottrif/poky/meta-yocto \
629 "
630 </literallayout>
631 This example enables four layers, one of which is a custom, user-defined layer
632 named <filename>meta-mykernel</filename>.
633 </para>
634 </glossdef>
635 </glossentry>
636
637 <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm>
638 <glossdef>
639Core layer for images cannot be removed
640 <para>Lists core layers that cannot be removed from the
641 <filename>bblayers.conf</filename> file.
642 In order for BitBake to build your image, your
643 <filename>bblayers.conf</filename> file must include the
644 <filename>meta</filename> and <filename>meta-yocto</filename>
645 core layers.
646 Here is an example that shows these two layers listed in
647 the <filename>BBLAYERS_NON_REMOVABLE</filename> statement:
648 <literallayout class='monospaced'>
649 BBLAYERS = " \
650 /home/scottrif/poky/meta \
651 /home/scottrif/poky/meta-yocto \
652 /home/scottrif/poky/meta-yocto-bsp \
653 /home/scottrif/poky/meta-mykernel \
654 "
655
656 BBLAYERS_NON_REMOVABLE ?= " \
657 /home/scottrif/poky/meta \
658 /home/scottrif/poky/meta-yocto \
659 "
660 </literallayout>
661 </para>
662 </glossdef>
663 </glossentry>
664
665 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
666 <glossdef>
667 <para>
668 Prevents BitBake from processing recipes and recipe
669 append files.
670 Use the <filename>BBMASK</filename> variable from within the
671 <filename>conf/local.conf</filename> file found
672 in the
673 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
674 </para>
675
676 <para>
677 You can use the <filename>BBMASK</filename> variable
678 to "hide" these <filename>.bb</filename> and
679 <filename>.bbappend</filename> files.
680 BitBake ignores any recipe or recipe append files that
681 match the expression.
682 It is as if BitBake does not see them at all.
683 Consequently, matching files are not parsed or otherwise
684 used by BitBake.</para>
685 <para>
686 The value you provide is passed to Python's regular
687 expression compiler.
688 The expression is compared against the full paths to
689 the files.
690 For complete syntax information, see Python's
691 documentation at
692 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
693 </para>
694
695 <para>
696 The following example uses a complete regular expression
697 to tell BitBake to ignore all recipe and recipe append
698 files in the <filename>/meta-ti/recipes-misc/</filename>
699 directory:
700 <literallayout class='monospaced'>
701 BBMASK = "/meta-ti/recipes-misc/"
702 </literallayout>
703 If you want to mask out multiple directories or recipes,
704 use the vertical bar to separate the regular expression
705 fragments.
706 This next example masks out multiple directories and
707 individual recipes:
708 <literallayout class='monospaced'>
709 BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/"
710 BBMASK .= "|.*meta-oe/recipes-support/"
711 BBMASK .= "|.*openldap"
712 BBMASK .= "|.*opencv"
713 BBMASK .= "|.*lzma"
714 </literallayout>
715 Notice how the vertical bar is used to append the fragments.
716 <note>
717 When specifying a directory name, use the trailing
718 slash character to ensure you match just that directory
719 name.
720 </note>
721 </para>
722 </glossdef>
723 </glossentry>
724
725 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
726 <glossdef>
727 <para>
728 Used by BitBake to locate
729 <filename>.bbclass</filename> and configuration files.
730 This variable is analogous to the
731 <filename>PATH</filename> variable.
732 <note>
733 If you run BitBake from a directory outside of the
734 <ulink url='&YOCTO_DOCS_DEV_URL;build-directory'>Build Directory</ulink>,
735 you must be sure to set
736 <filename>BBPATH</filename> to point to the
737 Build Directory.
738 Set the variable as you would any environment variable
739 and then run BitBake:
740 <literallayout class='monospaced'>
741 $ BBPATH = "&lt;build_directory&gt;"
742 $ export BBPATH
743 $ bitbake &lt;target&gt;
744 </literallayout>
745 </note>
746 </para>
747 </glossdef>
748 </glossentry>
749
750 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
751 <glossdef>
752 <para>
753 Points to the server that runs memory-resident BitBake.
754 This variable is set by the
755 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
756 setup script and should not be hand-edited.
757 The variable is only used when you employ memory-resident
758 BitBake.
759 The setup script exports the value as follows:
760 <literallayout class='monospaced'>
761 export BBSERVER=localhost:$port
762 </literallayout>
763 For more information on how the
764 <filename>BBSERVER</filename> is used, see the
765 <filename>oe-init-build-env-memres</filename> script, which
766 is located in the
767 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
768 </para>
769 </glossdef>
770 </glossentry>
771
772 <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
773 <glossdef>
774 <para>
775 When inheriting <filename>binconfig.bbclass</filename>
776 from a recipe, this variable specifies a wildcard for
777 configuration scripts that need editing.
778 The scripts are edited to correct any paths that have been
779 set up during compilation so that they are correct for
780 use when installed into the sysroot and called by the
781 build processes of other recipes.
782 </para>
783
784 <para>
785 For more information on how this variable works, see
786 <filename>meta/classes/binconfig.bbclass</filename> in the
787 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
788 You can also find general information on the class in the
789 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
790 section.
791 </para>
792 </glossdef>
793 </glossentry>
794
795 <glossentry id='var-BP'><glossterm>BP</glossterm>
796 <glossdef>
797 <para>The base recipe name and version but without any special
798 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
799 and so forth).
800 <filename>BP</filename> is comprised of the following:
801 <literallayout class="monospaced">
802 ${BPN}-${PV}
803 </literallayout></para>
804 </glossdef>
805 </glossentry>
806
807 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
808 <glossdef>
809 <para>The bare name of the recipe.
810 This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable
811 but removes common suffixes such as "-native" and "-cross" as well
812 as removes common prefixes such as multilib's "lib64-" and "lib32-".
813 The exact list of suffixes removed is specified by the
814 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable.
815 The exact list of prefixes removed is specified by the
816 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable.
817 Prefixes are removed for <filename>multilib</filename>
818 and <filename>nativesdk</filename> cases.</para>
819 </glossdef>
820 </glossentry>
821
822 <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
823 <glossdef>
824 <para>
825 Points to the location of the
826 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
827 You can define this directory indirectly through the
828 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
829 and
830 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
831 scripts by passing in a Build Directory path when you run
832 the scripts.
833 If you run the scripts and do not provide a Build Directory
834 path, the <filename>BUILDDIR</filename> defaults to
835 <filename>build</filename> in the current directory.
836 </para>
837 </glossdef>
838 </glossentry>
839
840 <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
841 <glossdef>
842 <para>
843 For the BusyBox recipe, specifies whether to split the
844 output executable file into two parts: one for features
845 that require <filename>setuid root</filename>, and one for
846 the remaining features (i.e. those that do not require
847 <filename>setuid root</filename>).
848 </para>
849
850 <para>
851 The <filename>BUSYBOX_SPLIT_SUID</filename> variable
852 defaults to "1", which results in a single output
853 executable file.
854 Set the variable to "0" to split the output file.
855 </para>
856 </glossdef>
857 </glossentry>
858
859 </glossdiv>
860
861 <glossdiv id='var-glossary-c'><title>C</title>
862
863 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
864 <glossdef>
865 <para>
866 Flags passed to the C compiler for the target system.
867 This variable evaluates to the same as
868 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>.
869 </para>
870 </glossdef>
871 </glossentry>
872
873 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
874 <glossdef>
875 <para>A set of features common between
876 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
877 and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
878 See the glossary descriptions for these variables for more information.</para>
879 </glossdef>
880 </glossentry>
881
882 <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
883 <glossdef>
884 <para>
885 Points to <filename>meta/files/common-licenses</filename>
886 in the
887 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
888 which is where generic license files reside.
889 </para>
890 </glossdef>
891 </glossentry>
892
893 <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
894 <glossdef>
895 <para>A regular expression that resolves to one or more hosts
896 (when the recipe is native) or one or more targets (when
897 the recipe is non-native) with which a recipe is compatible.
898 The regular expression is matched against
899 <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
900 You can use the variable to stop recipes from being built
901 for classes of systems with which the recipes are not
902 compatible.
903 Stopping these builds is particularly useful with kernels.
904 The variable also helps to increase parsing speed
905 since the build system skips parsing recipes not
906 compatible with the current system.</para>
907 </glossdef>
908 </glossentry>
909
910 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
911 <glossdef>
912 <para>A regular expression that resolves to one or more
913 target machines with which a recipe is compatible.
914 The regular expression is matched against
915 <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
916 You can use the variable to stop recipes from being built
917 for machines with which the recipes are not compatible.
918 Stopping these builds is particularly useful with kernels.
919 The variable also helps to increase parsing speed
920 since the build system skips parsing recipes not
921 compatible with the current machine.</para>
922 </glossdef>
923 </glossentry>
924
925 <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
926 <glossdef>
927 <para>
928 Defines wildcards to match when installing a list of
929 complementary packages for all the packages explicitly
930 (or implicitly) installed in an image.
931 The resulting list of complementary packages is associated
932 with an item that can be added to
933 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
934 An example usage of this is the "dev-pkgs" item that when
935 added to <filename>IMAGE_FEATURES</filename> will
936 install -dev packages (containing headers and other
937 development files) for every package in the image.
938 </para>
939
940 <para>
941 To add a new feature item pointing to a wildcard, use a
942 variable flag to specify the feature item name and
943 use the value to specify the wildcard.
944 Here is an example:
945 <literallayout class='monospaced'>
946 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
947 </literallayout>
948 </para>
949 </glossdef>
950 </glossentry>
951
952 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
953 <glossdef>
954 <para>
955 Identifies editable or configurable files that are part of a package.
956 If the Package Management System (PMS) is being used to update
957 packages on the target system, it is possible that
958 configuration files you have changed after the original installation
959 and that you now want to remain unchanged are overwritten.
960 In other words, editable files might exist in the package that you do not
961 want reset as part of the package update process.
962 You can use the <filename>CONFFILES</filename> variable to list the files in the
963 package that you wish to prevent the PMS from overwriting during this update process.
964 </para>
965
966 <para>
967 To use the <filename>CONFFILES</filename> variable, provide a package name
968 override that identifies the resulting package.
969 Then, provide a space-separated list of files.
970 Here is an example:
971 <literallayout class='monospaced'>
972 CONFFILES_${PN} += "${sysconfdir}/file1 \
973 ${sysconfdir}/file2 ${sysconfdir}/file3"
974 </literallayout>
975 </para>
976
977 <para>
978 A relationship exists between the <filename>CONFFILES</filename> and
979 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
980 The files listed within <filename>CONFFILES</filename> must be a subset of
981 the files listed within <filename>FILES</filename>.
982 Because the configuration files you provide with <filename>CONFFILES</filename>
983 are simply being identified so that the PMS will not overwrite them,
984 it makes sense that
985 the files must already be included as part of the package through the
986 <filename>FILES</filename> variable.
987 </para>
988
989 <note>
990 When specifying paths as part of the <filename>CONFFILES</filename> variable,
991 it is good practice to use appropriate path variables.
992 For example, <filename>${sysconfdir}</filename> rather than
993 <filename>/etc</filename> or <filename>${bindir}</filename> rather
994 than <filename>/usr/bin</filename>.
995 You can find a list of these variables at the top of the
996 <filename>/meta/conf/bitbake.conf</filename> file in the
997 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
998 </note>
999 </glossdef>
1000 </glossentry>
1001
1002 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
1003 <glossdef>
1004 <para>
1005 A list of files that contains <filename>autoconf</filename> test results relevant
1006 to the current build.
1007 This variable is used by the Autotools utilities when running
1008 <filename>configure</filename>.
1009 </para>
1010 </glossdef>
1011 </glossentry>
1012
1013 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
1014 <glossdef>
1015 <para>
1016 Specifies the list of packages to be added to the image.
1017 You should only set this variable in the
1018 <filename>local.conf</filename> configuration file found
1019 in the
1020 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1021 </para>
1022
1023 <para>
1024 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
1025 </para>
1026 </glossdef>
1027 </glossentry>
1028
1029 <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
1030 <glossdef>
1031 <para>
1032 Specifies the parent directory of the OpenEmbedded
1033 Core Metadata layer (i.e. <filename>/meta</filename>).
1034 </para>
1035
1036 <para>
1037 It is an important distinction that
1038 <filename>COREBASE</filename> points to the parent of this
1039 layer and not the layer itself.
1040 Consider an example where you have cloned the Poky Git
1041 repository and retained the <filename>poky</filename>
1042 name for your local copy of the repository.
1043 In this case, <filename>COREBASE</filename> points to
1044 the <filename>poky</filename> folder because it is the
1045 parent directory of the <filename>poky/meta</filename>
1046 layer.
1047 </para>
1048 </glossdef>
1049 </glossentry>
1050
1051 </glossdiv>
1052
1053 <glossdiv id='var-glossary-d'><title>D</title>
1054
1055 <glossentry id='var-D'><glossterm>D</glossterm>
1056 <glossdef>
1057 <para>The destination directory.</para>
1058 </glossdef>
1059 </glossentry>
1060
1061 <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
1062 <glossdef>
1063 <para>
1064 The date and time on which the current build started.
1065 The format is suitable for timestamps.
1066 </para>
1067 </glossdef>
1068 </glossentry>
1069
1070 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
1071 <glossdef>
1072 <para>
1073 Specifies to build packages with debugging information.
1074 This influences the value of the
1075 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
1076 variable.
1077 </para>
1078 </glossdef>
1079 </glossentry>
1080
1081 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
1082 <glossdef>
1083 <para>
1084 The options to pass in
1085 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1086 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
1087 a system for debugging.
1088 This variable defaults to "-O -fno-omit-frame-pointer -g".
1089 </para>
1090 </glossdef>
1091 </glossentry>
1092
1093 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
1094 <glossdef>
1095 <para>
1096 Specifies a weak bias for recipe selection priority.
1097 </para>
1098 <para>
1099 The most common usage of this is variable is to set
1100 it to "-1" within a recipe for a development version of a
1101 piece of software.
1102 Using the variable in this way causes the stable version
1103 of the recipe to build by default in the absence of
1104 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
1105 being used to build the development version.
1106 </para>
1107 <note>
1108 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
1109 is weak and is overridden by
1110 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
1111 if the that variable is different between two layers
1112 that contain different versions of the same recipe.
1113 </note>
1114 </glossdef>
1115 </glossentry>
1116
1117 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
1118 <glossdef>
1119 <para>
1120 Lists a recipe's build-time dependencies
1121 (i.e. other recipe files).
1122 The system ensures that all the dependencies listed
1123 have been built and have their contents in the appropriate
1124 sysroots before the recipe's configure task is executed.
1125 </para>
1126
1127 <para>
1128 Consider this simple example for two recipes named "a" and
1129 "b" that produce similarly named packages.
1130 In this example, the <filename>DEPENDS</filename>
1131 statement appears in the "a" recipe:
1132 <literallayout class='monospaced'>
1133 DEPENDS = "b"
1134 </literallayout>
1135 Here, the dependency is such that the
1136 <filename>do_configure</filename> task for recipe "a"
1137 depends on the <filename>do_populate_sysroot</filename>
1138 task of recipe "b".
1139 This means anything that recipe "b" puts into sysroot
1140 is available when recipe "a" is configuring itself.
1141 </para>
1142
1143 <para>
1144 For information on runtime dependencies, see the
1145 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1146 variable.
1147 </para>
1148 </glossdef>
1149 </glossentry>
1150
1151 <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
1152 <glossdef>
1153 <para>
1154 Points to the general area that the OpenEmbedded build
1155 system uses to place images, packages, SDKs and other output
1156 files that are ready to be used outside of the build system.
1157 By default, this directory resides within the
1158 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1159 as <filename>tmp/deploy</filename>.
1160 </para>
1161
1162 <para>
1163 For more information on the structure of the Build
1164 Directory, see
1165 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1166 section.
1167 For more detail on the contents of the
1168 <filename>deploy</filename> directory, see the
1169 "<link linkend='images-dev-environment'>Images</link>" and
1170 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1171 sections.
1172 </para>
1173 </glossdef>
1174 </glossentry>
1175
1176 <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
1177 <glossdef>
1178 <para>
1179 Points to the area that the OpenEmbedded build system uses
1180 to place images and other associated output files that are
1181 ready to be deployed onto the target machine.
1182 The directory is machine-specific as it contains the
1183 <filename>${MACHINE}</filename> name.
1184 By default, this directory resides within the
1185 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1186 as <filename>tmp/deploy/images/${MACHINE}/</filename>.
1187 </para>
1188
1189 <para>
1190 For more information on the structure of the Build
1191 Directory, see
1192 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1193 section.
1194 For more detail on the contents of the
1195 <filename>deploy</filename> directory, see the
1196 "<link linkend='images-dev-environment'>Images</link>" and
1197 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1198 sections.
1199 </para>
1200 </glossdef>
1201 </glossentry>
1202
1203 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
1204 <glossdef>
1205 <para>The package description used by package managers.
1206 If not set, <filename>DESCRIPTION</filename> takes
1207 the value of the
1208 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
1209 variable.
1210 </para>
1211 </glossdef>
1212 </glossentry>
1213
1214 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
1215 <glossdef>
1216 <para>
1217 The short name of the distribution.
1218 This variable corresponds to a file with the
1219 extension <filename>.conf</filename>
1220 located in a <filename>conf/distro</filename> directory
1221 within the
1222 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
1223 that contains the distribution configuration.
1224 The value must not contain spaces, and is typically all lower-case.
1225 </para>
1226 <para>
1227 If the variable is blank, a set of default configuration
1228 will be used, which is specified
1229 within <filename>meta/conf/distro/defaultsetup.conf</filename>.
1230 </para>
1231 </glossdef>
1232 </glossentry>
1233
1234 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
1235 <glossdef>
1236 <para>
1237 Specifies a list of distro-specific packages to add to all images.
1238 This variable takes affect through
1239 <filename>packagegroup-base</filename> so the
1240 variable only really applies to the more full-featured
1241 images that include <filename>packagegroup-base</filename>.
1242 You can use this variable to keep distro policy out of
1243 generic images.
1244 As with all other distro variables, you set this variable
1245 in the distro <filename>.conf</filename> file.
1246 </para>
1247 </glossdef>
1248 </glossentry>
1249
1250 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
1251 <glossdef>
1252 <para>
1253 Specifies a list of distro-specific packages to add to all images
1254 if the packages exist.
1255 The packages might not exist or be empty (e.g. kernel modules).
1256 The list of packages are automatically installed but you can
1257 remove them.
1258 </para>
1259 </glossdef>
1260 </glossentry>
1261
1262 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
1263 <glossdef>
1264 <para>The features enabled for the distribution.
1265 For a list of supported features that ship with the
1266 Yocto Project, see the
1267 "<link linkend='ref-features-distro'>Distro</link>"
1268 section.
1269 </para>
1270 </glossdef>
1271 </glossentry>
1272
1273 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
1274 <glossdef>
1275 <para>Features to be added to
1276 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
1277 if not also present in
1278 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
1279 </para>
1280
1281 <para>
1282 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
1283 It is not intended to be user-configurable.
1284 It is best to just reference the variable to see which distro features are
1285 being backfilled for all distro configurations.
1286 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1287 more information.
1288 </para>
1289 </glossdef>
1290 </glossentry>
1291
1292 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
1293 <glossdef>
1294 <para>Features from
1295 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
1296 that should not be backfilled (i.e. added to
1297 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
1298 during the build.
1299 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
1300 more information.
1301 </para>
1302 </glossdef>
1303 </glossentry>
1304
1305 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
1306 <glossdef>
1307 <para>The long name of the distribution.</para>
1308 </glossdef>
1309 </glossentry>
1310
1311 <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
1312 <glossdef>
1313 <para>Alias names used for the recipe in various Linux distributions.</para>
1314 <para>See the
1315 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling
1316 a Package Name Alias</ulink>" section in the Yocto Project Development
1317 Manual for more information.</para>
1318 </glossdef>
1319 </glossentry>
1320
1321 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
1322 <glossdef>
1323 <para>the version of the distribution.</para>
1324 </glossdef>
1325 </glossentry>
1326
1327 <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
1328 <glossdef>
1329 <para>
1330 This variable lists overrides specific to the current
1331 distribution.
1332 By default, the variable list includes the value of the
1333 <filename><link linkend='var-DISTRO'>DISTRO</link></filename>
1334 variable.
1335 You can extend the variable to apply any variable overrides
1336 you want as part of the distribution and are not
1337 already in <filename>OVERRIDES</filename> through
1338 some other means.
1339 </para>
1340 </glossdef>
1341 </glossentry>
1342
1343 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
1344 <glossdef>
1345 <para>
1346 The central download directory used by the build process to
1347 store downloads.
1348 By default, <filename>DL_DIR</filename> gets files
1349 suitable for mirroring for everything except Git
1350 repositories.
1351 If you want tarballs of Git repositories, use the
1352 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
1353 variable.
1354 </para>
1355
1356 <para>
1357 You can set this directory by defining the
1358 <filename>DL_DIR</filename> variable in the
1359 <filename>/conf/local.conf</filename> file.
1360 This directory is self-maintaining and you should not have
1361 to touch it.
1362 By default, the directory is <filename>downloads</filename>
1363 in the
1364 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1365 <literallayout class='monospaced'>
1366 #DL_DIR ?= "${TOPDIR}/downloads"
1367 </literallayout>
1368 To specify a different download directory, simply remove
1369 the comment from the line and provide your directory.
1370 </para>
1371
1372 <para>
1373 During a first build, the system downloads many different
1374 source code tarballs from various upstream projects.
1375 Downloading can take a while, particularly if your network
1376 connection is slow.
1377 Tarballs are all stored in the directory defined by
1378 <filename>DL_DIR</filename> and the build system looks there
1379 first to find source tarballs.
1380 <note>
1381 When wiping and rebuilding, you can preserve this
1382 directory to speed up this part of subsequent
1383 builds.
1384 </note>
1385 </para>
1386
1387 <para>
1388 You can safely share this directory between multiple builds
1389 on the same development machine.
1390 For additional information on how the build process gets
1391 source files when working behind a firewall or proxy server,
1392 see this specific question in the
1393 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
1394 chapter.
1395 </para>
1396 </glossdef>
1397
1398 </glossentry>
1399 </glossdiv>
1400
1401 <glossdiv id='var-glossary-e'><title>E</title>
1402
1403 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
1404 <glossdef>
1405 <para></para>
1406 <para>Variable that controls which locales for
1407 <filename>eglibc</filename> are generated during the
1408 build (useful if the target device has 64Mbytes
1409 of RAM or less).</para>
1410 </glossdef>
1411 </glossentry>
1412
1413 <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
1414 <glossdef>
1415 <para>
1416 Specifies the quality assurance checks whose failures are
1417 reported as errors by the OpenEmbedded build system.
1418 You set this variable in your distribution configuration
1419 file.
1420 For a list of the checks you can control with this variable,
1421 see the
1422 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
1423 section.
1424 </para>
1425 </glossdef>
1426 </glossentry>
1427
1428 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
1429 <glossdef>
1430 <para>
1431 Directs BitBake to exclude a recipe from world builds (i.e.
1432 <filename>bitbake world</filename>).
1433 During world builds, BitBake locates, parses and builds all
1434 recipes found in every layer exposed in the
1435 <filename>bblayers.conf</filename> configuration file.
1436 </para>
1437
1438 <para>
1439 To exclude a recipe from a world build using this variable,
1440 set the variable to "1" in the recipe.
1441 </para>
1442
1443 <note>
1444 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
1445 may still be built during a world build in order to satisfy
1446 dependencies of other recipes.
1447 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
1448 only ensures that the recipe is not explicitly added
1449 to the list of build targets in a world build.
1450 </note>
1451 </glossdef>
1452 </glossentry>
1453
1454 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
1455 <glossdef>
1456 <para>
1457 Used with file and pathnames to create a prefix for a recipe's
1458 version based on the recipe's
1459 <link linkend='var-PE'><filename>PE</filename></link> value.
1460 If <filename>PE</filename> is set and greater than zero for a recipe,
1461 <filename>EXTENDPE</filename> becomes that value (e.g if
1462 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
1463 becomes "1_").
1464 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
1465 zero, <filename>EXTENDPE</filename> becomes "".</para>
1466 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
1467 variable for an example.
1468 </para>
1469 </glossdef>
1470 </glossentry>
1471
1472 <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
1473 <glossdef>
1474 <para>
1475 The full package version specification as it appears on the
1476 final packages produced by a recipe.
1477 The variable's value is normally used to fix a runtime
1478 dependency to the exact same version of another package
1479 in the same recipe:
1480 <literallayout class='monospaced'>
1481 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
1482 </literallayout>
1483 </para>
1484
1485 <para>
1486 The dependency relationships are intended to force the
1487 package manager to upgrade these types of packages in
1488 lock-step.
1489 </para>
1490 </glossdef>
1491 </glossentry>
1492
1493 <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
1494 <glossdef>
1495 <para>
1496 If <filename>externalsrc.bbclass</filename> is inherited,
1497 this variable points to the source tree, which is
1498 outside of the OpenEmbedded build system.
1499 When set, this variable sets the
1500 <link linkend='var-S'><filename>S</filename></link>
1501 variable, which is what the OpenEmbedded build system uses
1502 to locate unpacked recipe source code.
1503 </para>
1504
1505 <para>
1506 For more information on
1507 <filename>externalsrc.bbclass</filename>, see the
1508 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
1509 section.
1510 You can also find information on how to use this variable
1511 in the
1512 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
1513 section in the Yocto Project Development Manual.
1514 </para>
1515 </glossdef>
1516 </glossentry>
1517
1518 <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
1519 <glossdef>
1520 <para>
1521 If <filename>externalsrc.bbclass</filename> is inherited,
1522 this variable points to the directory in which the recipe's
1523 source code is built,
1524 which is outside of the OpenEmbedded build system.
1525 When set, this variable sets the
1526 <link linkend='var-B'><filename>B</filename></link>
1527 variable, which is what the OpenEmbedded build system uses
1528 to locate the Build Directory.
1529 </para>
1530
1531 <para>
1532 For more information on
1533 <filename>externalsrc.bbclass</filename>, see the
1534 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
1535 section.
1536 You can also find information on how to use this variable
1537 in the
1538 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
1539 section in the Yocto Project Development Manual.
1540 </para>
1541 </glossdef>
1542 </glossentry>
1543
1544 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
1545 <glossdef>
1546 <para>
1547 The list of additional features to include in an image.
1548 Typically, you configure this variable in your
1549 <filename>local.conf</filename> file, which is found in the
1550 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1551 Although you can use this variable from within a recipe,
1552 best practices dictate that you do not.
1553 <note>
1554 To enable primary features from within the image
1555 recipe, use the
1556 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
1557 variable.
1558 </note>
1559 </para>
1560
1561 <para>
1562 Here are some examples of features you can add:
1563 <literallayout class='monospaced'>
1564"dbg-pkgs" - Adds -dbg packages for all installed packages
1565 including symbol information for debugging and
1566 profiling.
1567
1568"debug-tweaks" - Makes an image suitable for development.
1569 For example, ssh root access has a blank
1570 password. You should remove this feature
1571 before you produce a production image.
1572
1573"dev-pkgs" - Adds -dev packages for all installed packages.
1574 This is useful if you want to develop against
1575 the libraries in the image.
1576
1577"read-only-rootfs" - Creates an image whose root
1578 filesystem is read-only. See the
1579 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
1580 section in the Yocto Project
1581 Development Manual for more
1582 information
1583
1584"tools-debug" - Adds debugging tools such as gdb and
1585 strace.
1586
1587"tools-profile" - Adds profiling tools such as oprofile,
1588 exmap, lttng and valgrind (x86 only).
1589
1590"tools-sdk" - Adds development tools such as gcc, make,
1591 pkgconfig and so forth.
1592
1593"tools-testapps" - Adds useful testing tools such as
1594 ts_print, aplay, arecord and so
1595 forth.
1596
1597 </literallayout>
1598 </para>
1599
1600 <para>
1601 For a complete list of image features that ships with the
1602 Yocto Project, see the
1603 "<link linkend="ref-features-image">Images</link>"
1604 section.
1605 </para>
1606
1607 <para>
1608 For an example that shows how to customize your image by
1609 using this variable, see the
1610 "<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>"
1611 section in the Yocto Project Development Manual.
1612 </para>
1613 </glossdef>
1614 </glossentry>
1615
1616 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
1617 <glossdef>
1618 <para>A list of recipes to build that do not provide packages
1619 for installing into the root filesystem.
1620 </para>
1621 <para>Sometimes a recipe is required to build the final image but is not
1622 needed in the root filesystem.
1623 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
1624 list these recipes and thus, specify the dependencies.
1625 A typical example is a required bootloader in a machine configuration.
1626 </para>
1627 <note>
1628 To add packages to the root filesystem, see the various
1629 <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
1630 and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
1631 variables.
1632 </note>
1633 </glossdef>
1634 </glossentry>
1635
1636 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
1637 <glossdef>
1638 <para>Additional <filename>cmake</filename> options.</para>
1639 </glossdef>
1640 </glossentry>
1641
1642 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
1643 <glossdef>
1644 <para>Additional <filename>configure</filename> script options.</para>
1645 </glossdef>
1646 </glossentry>
1647
1648 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
1649 <glossdef>
1650 <para>Additional GNU <filename>make</filename> options.</para>
1651 </glossdef>
1652 </glossentry>
1653
1654 </glossdiv>
1655
1656 <glossdiv id='var-glossary-f'><title>F</title>
1657
1658 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
1659 <glossdef>
1660 <para>
1661 The list of directories or files that are placed in packages.
1662 </para>
1663
1664 <para>
1665 To use the <filename>FILES</filename> variable, provide a package name
1666 override that identifies the resulting package.
1667 Then, provide a space-separated list of files or paths that identifies the
1668 files you want included as part of the resulting package.
1669 Here is an example:
1670 <literallayout class='monospaced'>
1671 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
1672 </literallayout>
1673 </para>
1674
1675 <note>
1676 When specifying paths as part of the <filename>FILES</filename> variable,
1677 it is good practice to use appropriate path variables.
1678 For example, <filename>${sysconfdir}</filename> rather than
1679 <filename>/etc</filename> or <filename>${bindir}</filename> rather
1680 than <filename>/usr/bin</filename>.
1681 You can find a list of these variables at the top of the
1682 <filename>/meta/conf/bitbake.conf</filename> file in the
1683 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1684 </note>
1685
1686 <para>
1687 If some of the files you provide with the <filename>FILES</filename> variable
1688 are editable and you know they should not be
1689 overwritten during the package update process by the Package Management
1690 System (PMS), you can identify these files so that the PMS will not
1691 overwrite them.
1692 See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename>
1693 variable for information on how to identify these files to the PMS.
1694 </para>
1695
1696 </glossdef>
1697 </glossentry>
1698
1699 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
1700 <glossdef>
1701 <para>
1702 Extends the search path the OpenEmbedded build system uses
1703 when looking for files and patches as it processes recipes
1704 and append files.
1705 The default directories BitBake uses when it processes
1706 recipes are initially defined by the
1707 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
1708 variable.
1709 You can extend <filename>FILESPATH</filename> variable
1710 by using <filename>FILESEXTRAPATHS</filename>.
1711 </para>
1712
1713 <para>
1714 Best practices dictate that you accomplish this by using
1715 <filename>FILESEXTRAPATHS</filename> from within a
1716 <filename>.bbappend</filename> file and that you prepend
1717 paths as follows:
1718 <literallayout class='monospaced'>
1719 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1720 </literallayout>
1721 In the above example, the build system first looks for files
1722 in a directory that has the same name as the corresponding
1723 append file.
1724 <note>
1725 <para>When extending <filename>FILESEXTRAPATHS</filename>,
1726 be sure to use the immediate expansion
1727 (<filename>:=</filename>) operator.
1728 Immediate expansion makes sure that BitBake evaluates
1729 <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
1730 at the time the directive is encountered rather than at
1731 some later time when expansion might result in a
1732 directory that does not contain the files you need.
1733 </para>
1734 <para>Also, include the trailing separating colon
1735 character if you are prepending.
1736 The trailing colon character is necessary because you
1737 are directing BitBake to extend the path by prepending
1738 directories to the search path.</para>
1739 </note>
1740 Here is another common use:
1741 <literallayout class='monospaced'>
1742 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
1743 </literallayout>
1744 In this example, the build system extends the
1745 <filename>FILESPATH</filename> variable to include a
1746 directory named <filename>files</filename> that is in the
1747 same directory as the corresponding append file.
1748 </para>
1749
1750 <para>
1751 Here is a final example that specifically adds three paths:
1752 <literallayout class='monospaced'>
1753 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
1754 </literallayout>
1755 </para>
1756
1757 <para>
1758 By prepending paths in <filename>.bbappend</filename>
1759 files, you allow multiple append files that reside in
1760 different layers but are used for the same recipe to
1761 correctly extend the path.
1762 </para>
1763 </glossdef>
1764 </glossentry>
1765
1766 <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
1767 <glossdef>
1768 <para>
1769 A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1770 used by the OpenEmbedded build system for creating
1771 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
1772 You can find more information on how overrides are handled
1773 in the BitBake Manual that is located at
1774 <filename>bitbake/doc/manual</filename> in the
1775 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1776 </para>
1777
1778 <para>
1779 By default, the <filename>FILESOVERRIDES</filename>
1780 variable is defined as:
1781 <literallayout class='monospaced'>
1782 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
1783 </literallayout>
1784
1785 <note>
1786 Do not hand-edit the <filename>FILESOVERRIDES</filename>
1787 variable.
1788 The values match up with expected overrides and are
1789 used in an expected manner by the build system.
1790 </note>
1791 </para>
1792 </glossdef>
1793 </glossentry>
1794
1795 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
1796 <glossdef>
1797 <para>
1798 The default set of directories the OpenEmbedded build system
1799 uses when searching for patches and files.
1800 During the build process, BitBake searches each directory in
1801 <filename>FILESPATH</filename> in the specified order when
1802 looking for files and patches specified by each
1803 <filename>file://</filename> URI in a recipe.
1804 </para>
1805
1806 <para>
1807 The default value for the <filename>FILESPATH</filename>
1808 variable is defined in the <filename>base.bbclass</filename>
1809 class found in <filename>meta/classes</filename> in the
1810 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
1811 <literallayout class='monospaced'>
1812 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
1813 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
1814 </literallayout>
1815 <note>
1816 Do not hand-edit the <filename>FILESPATH</filename>
1817 variable.
1818 If you want the build system to look in directories
1819 other than the defaults, extend the
1820 <filename>FILESPATH</filename> variable by using the
1821 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
1822 variable.
1823 </note>
1824 Be aware that the default <filename>FILESPATH</filename>
1825 directories do not map to directories in custom layers
1826 where append files (<filename>.bbappend</filename>)
1827 are used.
1828 If you want the build system to find patches or files
1829 that reside with your append files, you need to extend
1830 the <filename>FILESPATH</filename> variable by using
1831 the
1832 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
1833 variable.
1834 </para>
1835 </glossdef>
1836 </glossentry>
1837
1838 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
1839 <glossdef>
1840 <para>Allows you to define your own file permissions settings table as part of
1841 your configuration for the packaging process.
1842 For example, suppose you need a consistent set of custom permissions for
1843 a set of groups and users across an entire work project.
1844 It is best to do this in the packages themselves but this is not always
1845 possible.
1846 </para>
1847 <para>
1848 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
1849 is located in the <filename>meta/files</filename> folder in the
1850 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1851 If you create your own file permissions setting table, you should place it in your
1852 layer or the distros layer.
1853 </para>
1854 <para>
1855 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
1856 <filename>conf/local.conf</filename> file, which is found in the
1857 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to
1858 point to your custom <filename>fs-perms.txt</filename>.
1859 You can specify more than a single file permissions setting table.
1860 The paths you specify to these files must be defined within the
1861 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
1862 </para>
1863 <para>
1864 For guidance on how to create your own file permissions settings table file,
1865 examine the existing <filename>fs-perms.txt</filename>.
1866 </para>
1867 </glossdef>
1868 </glossentry>
1869
1870 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
1871 <glossdef>
1872 <para>
1873 The options to pass in
1874 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1875 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
1876 when compiling an optimized system.
1877 This variable defaults to
1878 "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
1879 </para>
1880 </glossdef>
1881 </glossentry>
1882
1883 </glossdiv>
1884
1885<!-- <glossdiv id='var-glossary-g'><title>G</title>-->
1886<!-- </glossdiv>-->
1887
1888 <glossdiv id='var-glossary-h'><title>H</title>
1889
1890 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
1891 <glossdef>
1892 <para>Website where more information about the software the recipe is building
1893 can be found.</para>
1894 </glossdef>
1895 </glossentry>
1896
1897 <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
1898 <glossdef>
1899 <para>
1900 Specifies the system, including the architecture and the
1901 operating system, for with the build is occurring
1902 in the context of the current
1903 recipe.
1904 The OpenEmbedded build system automatically sets this
1905 variable.
1906 You do not need to set the variable yourself.
1907 </para>
1908
1909 <para>
1910 Here are two examples:
1911 <itemizedlist>
1912 <listitem><para>Given a native recipe on a 32-bit
1913 x86 machine running Linux, the value is
1914 "i686-linux".
1915 </para></listitem>
1916 <listitem><para>Given a recipe being built for a
1917 little-endian MIPS target running Linux,
1918 the value might be "mipsel-linux".
1919 </para></listitem>
1920 </itemizedlist>
1921 </para>
1922 </glossdef>
1923 </glossentry>
1924
1925 </glossdiv>
1926
1927 <glossdiv id='var-glossary-i'><title>I</title>
1928
1929 <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
1930 <glossdef>
1931 <para>
1932 The base name of image output files.
1933 This variable defaults to the recipe name
1934 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
1935 </para>
1936 </glossdef>
1937 </glossentry>
1938
1939 <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
1940 <glossdef>
1941 <para>
1942 A list of classes that all images should inherit.
1943 You typically use this variable to specify the list of
1944 classes that register the different types of images
1945 the OpenEmbedded build system creates.
1946 </para>
1947
1948 <para>
1949 The default value for <filename>IMAGE_CLASSES</filename> is
1950 <filename>image_types</filename>.
1951 You can set this variable in your
1952 <filename>local.conf</filename> or in a distribution
1953 configuration file.
1954 </para>
1955
1956 <para>
1957 For more information, see
1958 <filename>meta/classes/image_types.bbclass</filename> in the
1959 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1960 </para>
1961 </glossdef>
1962 </glossentry>
1963
1964 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
1965 <glossdef>
1966 <para>
1967 The primary list of features to include in an image.
1968 Typically, you configure this variable in an image recipe.
1969 Although you can use this variable from your
1970 <filename>local.conf</filename> file, which is found in the
1971 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
1972 best practices dictate that you do not.
1973 <note>
1974 To enable extra features from outside the image recipe,
1975 use the
1976 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
1977 </note>
1978 For a list of image features that ships with the Yocto
1979 Project, see the
1980 "<link linkend="ref-features-image">Images</link>"
1981 section.
1982 </para>
1983
1984 <para>
1985 For example that shows how to customize your image by
1986 using this variable, see the
1987 "<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>"
1988 section in the Yocto Project Development Manual.
1989 </para>
1990 </glossdef>
1991 </glossentry>
1992
1993 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
1994 <glossdef>
1995 <para>
1996 Specifies the formats the OpenEmbedded build system uses
1997 during the build when creating the root filesystem.
1998 For example, setting <filename>IMAGE_FSTYPES</filename>
1999 as follows causes the build system to create root
2000 filesystems using two formats: <filename>.ext3</filename>
2001 and <filename>tar.bz2</filename>:
2002 <literallayout class='monospaced'>
2003 IMAGE_FSTYPES = "ext3 tar.bz2"
2004 </literallayout>
2005 For the complete list of supported image formats from which
2006 you can choose, see
2007 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
2008 </para>
2009 </glossdef>
2010 </glossentry>
2011
2012 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
2013 <glossdef>
2014 <para>
2015 Specifies the packages to install into an image.
2016 The <filename>IMAGE_INSTALL</filename> variable is a mechanism for an image
2017 recipe and you should use it with care to avoid ordering issues.
2018 </para>
2019
2020 <para>
2021 Image recipes set <filename>IMAGE_INSTALL</filename> to specify the
2022 packages to install into an image through <filename>image.bbclass</filename>.
2023 Additionally, "helper" classes exist, such as <filename>core-image.bbclass</filename>,
2024 that can take
2025 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> lists
2026 and turn these into auto-generated entries in
2027 <filename>IMAGE_INSTALL</filename> in addition to its default contents.
2028 </para>
2029
2030 <para>
2031 Using <filename>IMAGE_INSTALL</filename> with the <filename>+=</filename>
2032 operator from the <filename>/conf/local.conf</filename> file or from within
2033 an image recipe is not recommended as it can cause ordering issues.
2034 Since <filename>core-image.bbclass</filename> sets <filename>IMAGE_INSTALL</filename>
2035 to a default value using the <filename>?=</filename> operator, using a
2036 <filename>+=</filename> operation against <filename>IMAGE_INSTALL</filename>
2037 will result in unexpected behavior when used in
2038 <filename>/conf/local.conf</filename>.
2039 Furthermore, the same operation from with an image recipe may or may not
2040 succeed depending on the specific situation.
2041 In both these cases, the behavior is contrary to how most users expect
2042 the <filename>+=</filename> operator to work.
2043 </para>
2044
2045 <para>
2046 When you use this variable, it is best to use it as follows:
2047 <literallayout class='monospaced'>
2048 IMAGE_INSTALL_append = " package-name"
2049 </literallayout>
2050 Be sure to include the space between the quotation character and the start of the
2051 package name.
2052 </para>
2053 </glossdef>
2054 </glossentry>
2055
2056 <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
2057 <glossdef>
2058 <para>
2059 Specifies the list of locales to install into the image
2060 during the root filesystem construction process.
2061 The OpenEmbedded build system automatically splits locale
2062 files, which are used for localization, into separate
2063 packages.
2064 Setting the <filename>IMAGE_LINGUAS</filename> variable
2065 ensures that any locale packages that correspond to packages
2066 already selected for installation into the image are also
2067 installed.
2068 Here is an example:
2069 <literallayout class='monospaced'>
2070 IMAGE_LINGUAS = "pt-br de-de"
2071 </literallayout>
2072 In this example, the build system ensures any Brazilian
2073 Portuguese and German locale files that correspond to
2074 packages in the image are installed (i.e.
2075 <filename>*-locale-pt-br</filename>
2076 and <filename>*-locale-de-de</filename> as well as
2077 <filename>*-locale-pt</filename>
2078 and <filename>*-locale-de</filename>, since some software
2079 packages only provide locale files by language and not by
2080 country-specific language).
2081 </para>
2082 </glossdef>
2083 </glossentry>
2084
2085 <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
2086 <glossdef>
2087 <para>
2088 The name of the output image files minus the extension.
2089 This variable is derived using the
2090 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
2091 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
2092 and
2093 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
2094 variables:
2095 <literallayout class='monospaced'>
2096 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
2097 </literallayout>
2098 </para>
2099 </glossdef>
2100 </glossentry>
2101
2102 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
2103 <glossdef>
2104 <para>
2105 Defines a multiplier that the build system applies to the initial image
2106 size for cases when the multiplier times the returned disk usage value
2107 for the image is greater than the sum of
2108 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
2109 and
2110 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
2111 The result of the multiplier applied to the initial image size creates
2112 free disk space in the image as overhead.
2113 By default, the build process uses a multiplier of 1.3 for this variable.
2114 This default value results in 30% free disk space added to the image when this
2115 method is used to determine the final generated image size.
2116 You should be aware that post install scripts and the package management
2117 system uses disk space inside this overhead area.
2118 Consequently, the multiplier does not produce an image with
2119 all the theoretical free disk space.
2120 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
2121 for information on how the build system determines the overall image size.
2122 </para>
2123
2124 <para>
2125 The default 30% free disk space typically gives the image enough room to boot
2126 and allows for basic post installs while still leaving a small amount of
2127 free disk space.
2128 If 30% free space is inadequate, you can increase the default value.
2129 For example, the following setting gives you 50% free space added to the image:
2130 <literallayout class='monospaced'>
2131 IMAGE_OVERHEAD_FACTOR = "1.5"
2132 </literallayout>
2133 </para>
2134
2135 <para>
2136 Alternatively, you can ensure a specific amount of free disk space is added
2137 to the image by using
2138 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
2139 the variable.
2140 </para>
2141 </glossdef>
2142 </glossentry>
2143
2144 <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
2145 <glossdef>
2146 <para>
2147 Added by classes to run post processing commands once the
2148 OpenEmbedded build system has created the image.
2149 You can specify shell commands separated by semicolons:
2150 <literallayout class='monospaced'>
2151 IMAGE_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
2152 </literallayout>
2153 If you need to pass the path to the root filesystem within
2154 the command, you can use
2155 <filename>${IMAGE_ROOTFS}</filename>, which points to
2156 the root filesystem image.
2157 </para>
2158 </glossdef>
2159 </glossentry>
2160
2161 <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
2162 <glossdef>
2163 <para>
2164 The location of the root filesystem while it is under
2165 construction (i.e. during <filename>do_rootfs</filename>).
2166 This variable is not configurable.
2167 Do not change it.
2168 </para>
2169 </glossdef>
2170 </glossentry>
2171
2172 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
2173 <glossdef>
2174 <para>
2175 Defines additional free disk space created in the image in Kbytes.
2176 By default, this variable is set to "0".
2177 This free disk space is added to the image after the build system determines
2178 the image size as described in
2179 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
2180 </para>
2181
2182 <para>
2183 This variable is particularly useful when you want to ensure that a
2184 specific amount of free disk space is available on a device after an image
2185 is installed and running.
2186 For example, to be sure 5 Gbytes of free disk space is available, set the
2187 variable as follows:
2188 <literallayout class='monospaced'>
2189 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
2190 </literallayout>
2191 </para>
2192 </glossdef>
2193 </glossentry>
2194
2195 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
2196 <glossdef>
2197 <para>
2198 Defines the size in Kbytes for the generated image.
2199 The OpenEmbedded build system determines the final size for the generated
2200 image using an algorithm that takes into account the initial disk space used
2201 for the generated image, a requested size for the image, and requested
2202 additional free disk space to be added to the image.
2203 Programatically, the build system determines the final size of the
2204 generated image as follows:
2205 <literallayout class='monospaced'>
2206 if (image-du * overhead) &lt; rootfs-size:
2207 internal-rootfs-size = rootfs-size + xspace
2208 else:
2209 internal-rootfs-size = (image-du * overhead) + xspace
2210
2211 where:
2212
2213 image-du = Returned value of the du command on
2214 the image.
2215
2216 overhead = IMAGE_OVERHEAD_FACTOR
2217
2218 rootfs-size = IMAGE_ROOTFS_SIZE
2219
2220 internal-rootfs-size = Initial root filesystem
2221 size before any modifications.
2222
2223 xspace = IMAGE_ROOTFS_EXTRA_SPACE
2224 </literallayout>
2225 See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
2226 and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
2227 variables for related information.
2228<!-- In the above example, <filename>overhead</filename> is defined by the
2229 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
2230 variable, <filename>xspace</filename> is defined by the
2231 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
2232 variable, and <filename>du</filename> is the results of the disk usage command
2233 on the initially generated image. -->
2234 </para>
2235 </glossdef>
2236 </glossentry>
2237
2238 <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
2239 <glossdef>
2240 <para>
2241 Specifies the complete list of supported image types
2242 by default:
2243 <literallayout class='monospaced'>
2244 jffs2
2245 sum.jffs2
2246 cramfs
2247 ext2
2248 ext2.gz
2249 ext2.bz2
2250 ext3
2251 ext3.gz
2252 ext2.lzma
2253 btrfs
2254 live
2255 squashfs
2256 squashfs-xz
2257 ubi
2258 ubifs
2259 tar
2260 tar.gz
2261 tar.bz2
2262 tar.xz
2263 cpio
2264 cpio.gz
2265 cpio.xz
2266 cpio.lzma
2267 vmdk
2268 elf
2269 </literallayout>
2270 For more information on how these types of images, see
2271 <filename>meta/classes/image_types*.bbclass</filename>
2272 in the
2273 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2274 </para>
2275 </glossdef>
2276 </glossentry>
2277
2278 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
2279 <glossdef>
2280 <para>Helps define the recipe revision for recipes that share
2281 a common <filename>include</filename> file.
2282 You can think of this variable as part of the recipe revision
2283 as set from within an include file.</para>
2284 <para>Suppose, for example, you have a set of recipes that
2285 are used across several projects.
2286 And, within each of those recipes the revision
2287 (its <link linkend='var-PR'><filename>PR</filename></link>
2288 value) is set accordingly.
2289 In this case, when the revision of those recipes changes,
2290 the burden is on you to find all those recipes and
2291 be sure that they get changed to reflect the updated
2292 version of the recipe.
2293 In this scenario, it can get complicated when recipes
2294 that are used in many places and provide common functionality
2295 are upgraded to a new revision.</para>
2296 <para>A more efficient way of dealing with this situation is
2297 to set the <filename>INC_PR</filename> variable inside
2298 the <filename>include</filename> files that the recipes
2299 share and then expand the <filename>INC_PR</filename>
2300 variable within the recipes to help
2301 define the recipe revision.
2302 </para>
2303 <para>
2304 The following provides an example that shows how to use
2305 the <filename>INC_PR</filename> variable
2306 given a common <filename>include</filename> file that
2307 defines the variable.
2308 Once the variable is defined in the
2309 <filename>include</filename> file, you can use the
2310 variable to set the <filename>PR</filename> values in
2311 each recipe.
2312 You will notice that when you set a recipe's
2313 <filename>PR</filename> you can provide more granular
2314 revisioning by appending values to the
2315 <filename>INC_PR</filename> variable:
2316 <literallayout class='monospaced'>
2317recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
2318recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
2319recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
2320recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
2321 </literallayout>
2322 The first line of the example establishes the baseline
2323 revision to be used for all recipes that use the
2324 <filename>include</filename> file.
2325 The remaining lines in the example are from individual
2326 recipes and show how the <filename>PR</filename> value
2327 is set.</para>
2328 </glossdef>
2329 </glossentry>
2330
2331 <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
2332 <glossdef>
2333 <para>
2334 Specifies a space-separated list of license names
2335 (as they would appear in
2336 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
2337 that should be excluded from the build.
2338 Recipes that provide no alternatives to listed incompatible
2339 licenses are not built.
2340 Packages that are individually licensed with the specified
2341 incompatible licenses will be deleted.
2342 </para>
2343
2344 <note>
2345 This functionality is only regularly tested using
2346 the following setting:
2347 <literallayout class='monospaced'>
2348 INCOMPATIBLE_LICENSE = "GPLv3"
2349 </literallayout>
2350 Although you can use other settings, you might be required
2351 to remove dependencies on or provide alternatives to
2352 components that are required to produce a functional system
2353 image.
2354 </note>
2355 </glossdef>
2356 </glossentry>
2357
2358 <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
2359 <glossdef>
2360 <para>
2361 Prevents the default dependencies, namely the C compiler
2362 and standard C library (libc), from being added to
2363 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
2364 This variable is usually used within recipes that do not
2365 require any compilation using the C compiler.
2366 </para>
2367
2368 <para>
2369 Set the variable to "1" to prevent the default dependencies
2370 from being added.
2371 </para>
2372 </glossdef>
2373 </glossentry>
2374
2375 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
2376 <glossdef>
2377 <para>
2378 If set to "1", causes the build to not strip binaries in resulting packages.
2379 </para>
2380 </glossdef>
2381 </glossentry>
2382
2383 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
2384 <glossdef>
2385 <para>
2386 Causes the named class to be inherited at
2387 this point during parsing.
2388 The variable is only valid in configuration files.
2389 </para>
2390 </glossdef>
2391 </glossentry>
2392
2393 <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
2394 <glossdef>
2395 <para>
2396 Defines the format for the output image of an initial
2397 RAM disk (initramfs), which is used during boot.
2398 Supported formats are the same as those supported by the
2399 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
2400 variable.
2401 </para>
2402 </glossdef>
2403 </glossentry>
2404
2405 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
2406 <glossdef>
2407 <para>
2408 The filename of the initscript as installed to <filename>${etcdir}/init.d</filename>.
2409 </para>
2410 <para>
2411 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
2412 The variable is Mandatory.
2413 </para>
2414 </glossdef>
2415 </glossentry>
2416
2417 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
2418 <glossdef>
2419 <para>
2420 A list of the packages that contain initscripts.
2421 If multiple packages are specified, you need to append the package name
2422 to the other <filename>INITSCRIPT_*</filename> as an override.</para>
2423 <para>
2424 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
2425 The variable is optional and defaults to the
2426 <link linkend='var-PN'><filename>PN</filename></link> variable.
2427 </para>
2428 </glossdef>
2429 </glossentry>
2430
2431 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
2432 <glossdef>
2433 <para>
2434 Specifies the options to pass to <filename>update-rc.d</filename>.
2435 Here is an example:
2436 <literallayout class='monospaced'>
2437 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
2438 </literallayout>
2439 In this example, the script has a runlevel of 99,
2440 starts the script in initlevels 2 and 5, and
2441 stops the script in levels 0, 1 and 6.
2442 </para>
2443 <para>
2444 The variable is mandatory and is used in recipes when using
2445 <filename>update-rc.d.bbclass</filename>.
2446 </para>
2447 </glossdef>
2448 </glossentry>
2449
2450 <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
2451 <glossdef>
2452 <para>
2453 Specifies the QA checks to skip for a specific package
2454 within a recipe.
2455 For example, to skip the check for symbolic link
2456 <filename>.so</filename> files in the main package of a
2457 recipe, add the following to the recipe.
2458 The package name override must be used, which in this
2459 example is <filename>${PN}</filename>:
2460 <literallayout class='monospaced'>
2461 INSANE_SKIP_${PN} += "dev-so"
2462 </literallayout>
2463 </para>
2464 <para>
2465 See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
2466 section for a list of the valid QA checks you can
2467 specify using this variable.
2468 </para>
2469 </glossdef>
2470 </glossentry>
2471
2472 <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
2473 <glossdef>
2474 <para>
2475 When the IPK backend is in use and package management
2476 is enabled on the target, you can use this variable to
2477 set up <filename>opkg</filename> in the target image
2478 to point to package feeds on a nominated server.
2479 Once the feed is established, you can perform
2480 installations or upgrades using the package manager
2481 at runtime.
2482 </para>
2483 </glossdef>
2484 </glossentry>
2485
2486<!--
2487 <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
2488 <glossdef>
2489 <para>
2490 An environment variable that defines the directory where
2491 post installation hooks are installed for the
2492 post install environment.
2493 This variable is fixed as follows:
2494 <literallayout class='monospaced'>
2495 ${WORKDIR}/intercept_scripts
2496 </literallayout>
2497 </para>
2498
2499 <para>
2500 After installation of a target's root filesystem,
2501 post installation scripts, which are essentially bash scripts,
2502 are all executed just a single time.
2503 Limiting execution of these scripts minimizes installation
2504 time that would be lengthened due to certain packages
2505 triggering redundant operations.
2506 For example, consider the installation of font packages
2507 as a common example.
2508 Without limiting the execution of post installation scripts,
2509 all font directories would be rescanned to create the
2510 cache after each individual font package was installed.
2511 </para>
2512
2513 <para>
2514 Do not edit the <filename>INTERCEPT_DIR</filename>
2515 variable.
2516 </para>
2517 </glossdef>
2518 </glossentry>
2519-->
2520
2521 </glossdiv>
2522
2523<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
2524<!-- </glossdiv>-->
2525
2526 <glossdiv id='var-glossary-k'><title>K</title>
2527
2528 <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
2529 <glossdef>
2530 <para>
2531 Defines the kernel architecture used when assembling
2532 the configuration.
2533 Architectures supported for this release are:
2534 <literallayout class='monospaced'>
2535 powerpc
2536 i386
2537 x86_64
2538 arm
2539 qemu
2540 mips
2541 </literallayout>
2542 </para>
2543
2544 <para>
2545 You define the <filename>KARCH</filename> variable in the
2546 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
2547 </para>
2548 </glossdef>
2549 </glossentry>
2550
2551 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
2552 <glossdef>
2553 <para>
2554 A regular expression used by the build process to explicitly identify the kernel
2555 branch that is validated, patched and configured during a build.
2556 The <filename>KBRANCH</filename> variable is optional.
2557 You can use it to trigger checks to ensure the exact kernel branch you want is
2558 being used by the build process.
2559 </para>
2560
2561 <para>
2562 Values for this variable are set in the kernel's recipe file and the kernel's
2563 append file.
2564 For example, if you are using the Yocto Project kernel that is based on the
2565 Linux 3.4 kernel, the kernel recipe file is the
2566 <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename> file.
2567 Following is the default value for <filename>KBRANCH</filename> and the default
2568 override for the architectures the Yocto Project supports:
2569 <literallayout class='monospaced'>
2570 KBRANCH_DEFAULT = "standard/base"
2571 KBRANCH = "${KBRANCH_DEFAULT}"
2572 </literallayout>
2573 This branch exists in the <filename>linux-yocto-3.4</filename> kernel Git
2574 repository <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>.
2575 </para>
2576
2577 <para>
2578 This variable is also used from the kernel's append file to identify the kernel
2579 branch specific to a particular machine or target hardware.
2580 The kernel's append file is located in the BSP layer for a given machine.
2581 For example, the kernel append file for the Crown Bay BSP is in the
2582 <filename>meta-intel</filename> Git repository and is named
2583 <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>.
2584 Here are the related statements from the append file:
2585 <literallayout class='monospaced'>
2586 COMPATIBLE_MACHINE_crownbay = "crownbay"
2587 KMACHINE_crownbay = "crownbay"
2588 KBRANCH_crownbay = "standard/crownbay"
2589
2590 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
2591 KMACHINE_crownbay-noemgd = "crownbay"
2592 KBRANCH_crownbay-noemgd = "standard/crownbay"
2593 </literallayout>
2594 The <filename>KBRANCH_*</filename> statements identify the kernel branch to
2595 use when building for the Crown Bay BSP.
2596 In this case there are two identical statements: one for each type of
2597 Crown Bay machine.
2598 </para>
2599 </glossdef>
2600 </glossentry>
2601
2602 <glossentry id='var-KBRANCH_DEFAULT'><glossterm>KBRANCH_DEFAULT</glossterm>
2603 <glossdef>
2604 <para>
2605 Defines the Linux kernel source repository's default
2606 branch used to build the Linux kernel.
2607 The <filename>KBRANCH_DEFAULT</filename> value is
2608 the default value for
2609 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>.
2610 Unless you specify otherwise,
2611 <filename>KBRANCH_DEFAULT</filename> initializes to
2612 "master".
2613 </para>
2614 </glossdef>
2615 </glossentry>
2616
2617 <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
2618 <glossdef>
2619 <para>
2620 Specifies additional <filename>make</filename>
2621 command-line arguments the OpenEmbedded build system
2622 passes on when compiling the kernel.
2623 </para>
2624 </glossdef>
2625 </glossentry>
2626
2627 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
2628 <glossdef>
2629 <para>Includes additional metadata from the Yocto Project kernel Git repository.
2630 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
2631 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
2632 is provided through
2633 the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
2634 and <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link> variables.
2635 You can use the <filename>KERNEL_FEATURES</filename> variable to further
2636 add metadata for all BSPs.</para>
2637 <para>The metadata you add through this variable includes config fragments and
2638 features descriptions,
2639 which usually includes patches as well as config fragments.
2640 You typically override the <filename>KERNEL_FEATURES</filename> variable
2641 for a specific machine.
2642 In this way, you can provide validated, but optional, sets of kernel
2643 configurations and features.</para>
2644 <para>For example, the following adds <filename>netfilter</filename> to all
2645 the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>
2646 machine:
2647 <literallayout class='monospaced'>
2648 # Add netfilter to all linux-yocto kernels
2649 KERNEL_FEATURES="features/netfilter"
2650
2651 # Add sound support to the qemux86 machine
2652 KERNEL_FEATURES_append_qemux86=" cfg/sound"
2653 </literallayout></para>
2654 </glossdef>
2655 </glossentry>
2656
2657 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
2658 <glossdef>
2659 <para>The type of kernel to build for a device, usually set by the
2660 machine configuration files and defaults to "zImage".
2661 This variable is used
2662 when building the kernel and is passed to <filename>make</filename> as the target to
2663 build.</para>
2664 </glossdef>
2665 </glossentry>
2666
2667 <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
2668 <glossdef>
2669 <para>
2670 The location of the kernel sources.
2671 This variable is set to the value of the
2672 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
2673 within the <filename>module.bbclass</filename> class.
2674 For information on how this variable is used, see the
2675 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
2676 section.
2677 </para>
2678
2679 <para>
2680 The <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
2681 variable is identical to the <filename>KERNEL_PATH</filename>
2682 variable.
2683 </para>
2684 </glossdef>
2685 </glossentry>
2686
2687 <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
2688 <glossdef>
2689 <para>
2690 The location of the kernel sources.
2691 This variable is set to the value of the
2692 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
2693 within the <filename>module.bbclass</filename> class.
2694 For information on how this variable is used, see the
2695 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
2696 section.
2697 </para>
2698
2699 <para>
2700 The <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
2701 variable is identical to the <filename>KERNEL_SRC</filename>
2702 variable.
2703 </para>
2704 </glossdef>
2705 </glossentry>
2706
2707 <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
2708 <glossdef>
2709 <para>
2710 Provides a short description of a configuration fragment.
2711 You use this variable in the <filename>.scc</filename>
2712 file that describes a configuration fragment file.
2713 Here is the variable used in a file named
2714 <filename>smp.scc</filename> to describe SMP being
2715 enabled:
2716 <literallayout class='monospaced'>
2717 define KFEATURE_DESCRIPTION "Enable SMP"
2718 </literallayout>
2719 </para>
2720 </glossdef>
2721 </glossentry>
2722
2723 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
2724 <glossdef>
2725 <para>
2726 The machine as known by the kernel.
2727 Sometimes the machine name used by the kernel does not match the machine name
2728 used by the OpenEmbedded build system.
2729 For example, the machine name that the OpenEmbedded build system understands as
2730 <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel.
2731 The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
2732 For cases like these, the <filename>KMACHINE</filename> variable maps the
2733 kernel machine name to the OpenEmbedded build system machine name.
2734 </para>
2735
2736 <para>
2737 Kernel machine names are initially defined in the
2738 Yocto Linux Kernel's <filename>meta</filename> branch.
2739 From the <filename>meta</filename> branch, look in
2740 the <filename>meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</filename> file.
2741 For example, from the <filename>meta</filename> branch in the
2742 <filename>linux-yocto-3.0</filename> kernel, the
2743 <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file
2744 has the following:
2745 <literallayout class='monospaced'>
2746 define KMACHINE cedartrail
2747 define KTYPE standard
2748 define KARCH i386
2749
2750 include ktypes/standard
2751 branch cedartrail
2752
2753 include cedartrail.scc
2754 </literallayout>
2755 You can see that the kernel understands the machine name for
2756 the Cedar Trail Board Support Package (BSP) as
2757 <filename>cedartrail</filename>.
2758 </para>
2759
2760 <para>
2761 If you look in the Cedar Trail BSP layer in the
2762 <filename>meta-intel</filename>
2763 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
2764 at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>,
2765 you will find the following statements among others:
2766 <literallayout class='monospaced'>
2767 COMPATIBLE_MACHINE_cedartrail = "cedartrail"
2768 KMACHINE_cedartrail = "cedartrail"
2769 KBRANCH_cedartrail = "yocto/standard/cedartrail"
2770 KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
2771 KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
2772
2773 COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
2774 KMACHINE_cedartrail-nopvr = "cedartrail"
2775 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
2776 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
2777 </literallayout>
2778 The <filename>KMACHINE</filename> statements in the kernel's append file make sure that
2779 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
2780 names.
2781 </para>
2782
2783 <para>
2784 This append file uses two <filename>KMACHINE</filename> statements.
2785 The first is not really necessary but does ensure that the machine known to the
2786 OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
2787 in the kernel also known as <filename>cedartrail</filename>:
2788 <literallayout class='monospaced'>
2789 KMACHINE_cedartrail = "cedartrail"
2790 </literallayout>
2791 </para>
2792
2793 <para>
2794 The second statement is a good example of why the <filename>KMACHINE</filename> variable
2795 is needed.
2796 In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename>
2797 machine name to refer to the Cedar Trail BSP that does not support the proprietary
2798 PowerVR driver.
2799 The kernel, however, uses the machine name <filename>cedartrail</filename>.
2800 Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to
2801 the kernel's <filename>cedartrail</filename> name:
2802 <literallayout class='monospaced'>
2803 KMACHINE_cedartrail-nopvr = "cedartrail"
2804 </literallayout>
2805 </para>
2806
2807 <para>
2808 BSPs that ship with the Yocto Project release provide all mappings between the Yocto
2809 Project kernel machine names and the OpenEmbedded machine names.
2810 Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine
2811 name you use is different than that used in the kernel.
2812 </para>
2813 </glossdef>
2814 </glossentry>
2815
2816 <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
2817 <glossdef>
2818 <para>
2819 Defines the kernel type to be used in assembling the
2820 configuration.
2821 The linux-yocto recipes define "standard", "tiny",
2822 and "preempt-rt" kernel types.
2823 See the
2824 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
2825 section in the Yocto Project Linux Kernel Development
2826 Manual for more information on kernel types.
2827 </para>
2828
2829 <para>
2830 You define the <filename>KTYPE</filename> variable in the
2831 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
2832 The value you use must match the value used for the
2833 <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
2834 value used by the kernel recipe.
2835 </para>
2836 </glossdef>
2837 </glossentry>
2838 </glossdiv>
2839
2840 <glossdiv id='var-glossary-l'><title>L</title>
2841
2842 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
2843 <glossdef>
2844 <para>Lists the layers that this recipe depends upon, separated by spaces.
2845 Optionally, you can specify a specific layer version for a dependency
2846 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
2847 to be compared against
2848 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>
2849 in this case).
2850 An error will be produced if any dependency is missing or
2851 the version numbers do not match exactly (if specified).
2852 This variable is used in the <filename>conf/layer.conf</filename> file
2853 and must be suffixed with the name of the specific layer (e.g.
2854 <filename>LAYERDEPENDS_mylayer</filename>).</para>
2855 </glossdef>
2856 </glossentry>
2857
2858 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
2859 <glossdef>
2860 <para>When used inside the <filename>layer.conf</filename> configuration
2861 file, this variable provides the path of the current layer.
2862 This variable is not available outside of <filename>layer.conf</filename>
2863 and references are expanded immediately when parsing of the file completes.</para>
2864 </glossdef>
2865 </glossentry>
2866
2867 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
2868 <glossdef>
2869 <para>Optionally specifies the version of a layer as a single number.
2870 You can use this within
2871 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
2872 for another layer in order to depend on a specific version
2873 of the layer.
2874 This variable is used in the <filename>conf/layer.conf</filename> file
2875 and must be suffixed with the name of the specific layer (e.g.
2876 <filename>LAYERVERSION_mylayer</filename>).</para>
2877 </glossdef>
2878 </glossentry>
2879
2880 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
2881 <glossdef>
2882 <para>Checksums of the license text in the recipe source code.</para>
2883 <para>This variable tracks changes in license text of the source
2884 code files.
2885 If the license text is changed, it will trigger a build
2886 failure, which gives the developer an opportunity to review any
2887 license change.</para>
2888 <para>
2889 This variable must be defined for all recipes (unless
2890 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2891 is set to "CLOSED")</para>
2892 <para>For more information, see the
2893 <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
2894 Tracking License Changes</link> section</para>
2895 </glossdef>
2896 </glossentry>
2897
2898 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
2899 <glossdef>
2900 <para>
2901 The list of source licenses for the recipe.
2902 Follow these rules:
2903 <itemizedlist>
2904 <listitem><para>Do not use spaces within individual
2905 license names.</para></listitem>
2906 <listitem><para>Separate license names using
2907 | (pipe) when there is a choice between licenses.
2908 </para></listitem>
2909 <listitem><para>Separate license names using
2910 &amp; (ampersand) when multiple licenses exist
2911 that cover different parts of the source.
2912 </para></listitem>
2913 <listitem><para>You can use spaces between license
2914 names.</para></listitem>
2915 </itemizedlist>
2916 </para>
2917
2918 <para>
2919 Here are some examples:
2920 <literallayout class='monospaced'>
2921 LICENSE = "LGPLv2.1 | GPLv3"
2922 LICENSE = "MPL-1 &amp; LGPLv2.1"
2923 LICENSE = "GPLv2+"
2924 </literallayout>
2925 The first example is from the recipes for Qt, which the user
2926 may choose to distribute under either the LGPL version
2927 2.1 or GPL version 3.
2928 The second example is from Cairo where two licenses cover
2929 different parts of the source code.
2930 The final example is from <filename>sysstat</filename>,
2931 which presents a single license.
2932 </para>
2933
2934 <para>
2935 You can also specify licenses on a per-package basis to
2936 handle situations where components of the output have
2937 different licenses.
2938 For example, a piece of software whose code is
2939 licensed under GPLv2 but has accompanying documentation
2940 licensed under the GNU Free Documentation License 1.2 could
2941 be specified as follows:
2942 <literallayout class='monospaced'>
2943 LICENSE = "GFDL-1.2 &amp; GPLv2"
2944 LICENSE_${PN} = "GPLv2"
2945 LICENSE_${PN}-doc = "GFDL-1.2"
2946 </literallayout>
2947 </para>
2948 </glossdef>
2949 </glossentry>
2950
2951 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
2952 <glossdef>
2953 <para>Path to additional licenses used during the build.
2954 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
2955 to define the directory that holds common license text used during the build.
2956 The <filename>LICENSE_PATH</filename> variable allows you to extend that
2957 location to other areas that have additional licenses:
2958 <literallayout class='monospaced'>
2959 LICENSE_PATH += "/path/to/additional/common/licenses"
2960 </literallayout></para>
2961 </glossdef>
2962 </glossentry>
2963
2964 <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
2965 <glossdef>
2966 <para>
2967 Defines the kernel type to be used in assembling the
2968 configuration.
2969 The linux-yocto recipes define "standard", "tiny", and
2970 "preempt-rt" kernel types.
2971 See the
2972 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
2973 section in the Yocto Project Linux Kernel Development
2974 Manual for more information on kernel types.
2975 </para>
2976
2977 <para>
2978 If you do not specify a
2979 <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
2980 "standard".
2981 Together with
2982 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
2983 the <filename>LINUX_KERNEL_TYPE</filename> variable
2984 defines the search
2985 arguments used by the kernel tools to find the appropriate
2986 description within the kernel
2987 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
2988 with which to build out the sources and configuration.
2989 </para>
2990 </glossdef>
2991 </glossentry>
2992
2993 <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
2994 <glossdef>
2995 <para>The Linux version from <filename>kernel.org</filename>
2996 on which the Linux kernel image being built using the
2997 OpenEmbedded build system is based.
2998 You define this variable in the kernel recipe.
2999 For example, the <filename>linux-yocto-3.4.bb</filename>
3000 kernel recipe found in
3001 <filename>meta/recipes-kernel/linux</filename>
3002 defines the variables as follows:
3003 <literallayout class='monospaced'>
3004 LINUX_VERSION ?= "3.4.24"
3005 </literallayout>
3006 The <filename>LINUX_VERSION</filename> variable is used to
3007 define <link linkend='var-PV'><filename>PV</filename></link>
3008 for the recipe:
3009 <literallayout class='monospaced'>
3010 PV = "${LINUX_VERSION}+git${SRCPV}"
3011 </literallayout></para>
3012 </glossdef>
3013 </glossentry>
3014
3015 <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
3016 <glossdef>
3017 <para>A string extension compiled into the version
3018 string of the Linux kernel built with the OpenEmbedded
3019 build system.
3020 You define this variable in the kernel recipe.
3021 For example, the linux-yocto kernel recipes all define
3022 the variable as follows:
3023 <literallayout class='monospaced'>
3024 LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
3025 </literallayout>
3026 Defining this variable essentially sets the
3027 Linux kernel configuration item
3028 <filename>CONFIG_LOCALVERSION</filename>, which is visible
3029 through the <filename>uname</filename> command.
3030 Here is an example that shows the extension assuming it
3031 was set as previously shown:
3032 <literallayout class='monospaced'>
3033 $ uname -r
3034 3.7.0-rc8-custom
3035 </literallayout>
3036 </para>
3037 </glossdef>
3038 </glossentry>
3039
3040 <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
3041 <glossdef>
3042 <para>
3043 Specifies the directory to which the OpenEmbedded build
3044 system writes overall log files.
3045 The default directory is <filename>${TMPDIR}/log</filename>.
3046 </para>
3047 <para>
3048 For the directory containing logs specific to each task,
3049 see the <link linkend='var-T'><filename>T</filename></link>
3050 variable.
3051 </para>
3052 </glossdef>
3053 </glossentry>
3054
3055 </glossdiv>
3056
3057 <glossdiv id='var-glossary-m'><title>M</title>
3058
3059 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
3060 <glossdef>
3061 <para>
3062 Specifies the target device for which the image is built.
3063 You define <filename>MACHINE</filename> in the
3064 <filename>local.conf</filename> file found in the
3065 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
3066 By default, <filename>MACHINE</filename> is set to
3067 "qemux86", which is an x86-based architecture machine to
3068 be emulated using QEMU:
3069 <literallayout class='monospaced'>
3070 MACHINE ?= "qemux86"
3071 </literallayout>
3072 The variable corresponds to a machine configuration file of the
3073 same name, through which machine-specific configurations are set.
3074 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
3075 exists the corresponding <filename>qemux86.conf</filename> machine
3076 configuration file, which can be found in the
3077 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
3078 in <filename>meta/conf/machine</filename>.
3079 </para>
3080
3081 <para>
3082 The list of machines supported by the Yocto Project as
3083 shipped include the following:
3084 <literallayout class='monospaced'>
3085 MACHINE ?= "qemuarm"
3086 MACHINE ?= "qemumips"
3087 MACHINE ?= "qemuppc"
3088 MACHINE ?= "qemux86"
3089 MACHINE ?= "qemux86-64"
3090 MACHINE ?= "genericx86"
3091 MACHINE ?= "beagleboard"
3092 MACHINE ?= "mpc8315e-rdb"
3093 MACHINE ?= "routerstationpro"
3094 </literallayout>
3095 The last four are Yocto Project reference hardware boards, which
3096 are provided in the <filename>meta-yocto-bsp</filename> layer.
3097 <note>Adding additional Board Support Package (BSP) layers
3098 to your configuration adds new possible settings for
3099 <filename>MACHINE</filename>.
3100 </note>
3101 </para>
3102 </glossdef>
3103 </glossentry>
3104
3105 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
3106 <glossdef>
3107 <para></para>
3108 <para>
3109 A list of required machine-specific packages to install as part of
3110 the image being built.
3111 The build process depends on these packages being present.
3112 Furthermore, because this is a "machine essential" variable, the list of
3113 packages are essential for the machine to boot.
3114 The impact of this variable affects images based on
3115 <filename>packagegroup-core-boot</filename>,
3116 including the <filename>core-image-minimal</filename> image.
3117 </para>
3118 <para>
3119 This variable is similar to the
3120 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
3121 variable with the exception that the image being built has a build
3122 dependency on the variable's list of packages.
3123 In other words, the image will not build if a file in this list is not found.
3124 </para>
3125 <para>
3126 As an example, suppose the machine for which you are building requires
3127 <filename>example-init</filename> to be run during boot to initialize the hardware.
3128 In this case, you would use the following in the machine's
3129 <filename>.conf</filename> configuration file:
3130 <literallayout class='monospaced'>
3131 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
3132 </literallayout>
3133 </para>
3134 </glossdef>
3135 </glossentry>
3136
3137 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
3138 <glossdef>
3139 <para></para>
3140 <para>
3141 A list of recommended machine-specific packages to install as part of
3142 the image being built.
3143 The build process does not depend on these packages being present.
3144 However, because this is a "machine essential" variable, the list of
3145 packages are essential for the machine to boot.
3146 The impact of this variable affects images based on
3147 <filename>packagegroup-core-boot</filename>,
3148 including the <filename>core-image-minimal</filename> image.
3149 </para>
3150 <para>
3151 This variable is similar to the
3152 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
3153 variable with the exception that the image being built does not have a build
3154 dependency on the variable's list of packages.
3155 In other words, the image will still build if a package in this list is not found.
3156 Typically, this variable is used to handle essential kernel modules, whose
3157 functionality may be selected to be built into the kernel rather than as a module,
3158 in which case a package will not be produced.
3159 </para>
3160 <para>
3161 Consider an example where you have a custom kernel where a specific touchscreen
3162 driver is required for the machine to be usable.
3163 However, the driver can be built as a module or
3164 into the kernel depending on the kernel configuration.
3165 If the driver is built as a module, you want it to be installed.
3166 But, when the driver is built into the kernel, you still want the
3167 build to succeed.
3168 This variable sets up a "recommends" relationship so that in the latter case,
3169 the build will not fail due to the missing package.
3170 To accomplish this, assuming the package for the module was called
3171 <filename>kernel-module-ab123</filename>, you would use the
3172 following in the machine's <filename>.conf</filename> configuration
3173 file:
3174 <literallayout class='monospaced'>
3175 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
3176 </literallayout>
3177 </para>
3178 <para>
3179 Some examples of these machine essentials are flash, screen, keyboard, mouse,
3180 or touchscreen drivers (depending on the machine).
3181 </para>
3182 </glossdef>
3183 </glossentry>
3184
3185 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
3186 <glossdef>
3187 <para>
3188 A list of machine-specific packages to install as part of the
3189 image being built that are not essential for the machine to boot.
3190 However, the build process for more fully-featured images
3191 depends on the packages being present.
3192 </para>
3193 <para>
3194 This variable affects all images based on
3195 <filename>packagegroup-base</filename>, which does not include the
3196 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
3197 images.
3198 </para>
3199 <para>
3200 The variable is similar to the
3201 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
3202 variable with the exception that the image being built has a build
3203 dependency on the variable's list of packages.
3204 In other words, the image will not build if a file in this list is not found.
3205 </para>
3206 <para>
3207 An example is a machine that has WiFi capability but is not
3208 essential for the machine to boot the image.
3209 However, if you are building a more fully-featured image, you want to enable
3210 the WiFi.
3211 The package containing the firmware for the WiFi hardware is always
3212 expected to exist, so it is acceptable for the build process to depend upon
3213 finding the package.
3214 In this case, assuming the package for the firmware was called
3215 <filename>wifidriver-firmware</filename>, you would use the following in the
3216 <filename>.conf</filename> file for the machine:
3217 <literallayout class='monospaced'>
3218 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
3219 </literallayout>
3220 </para>
3221 </glossdef>
3222 </glossentry>
3223
3224 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
3225 <glossdef>
3226 <para></para>
3227 <para>
3228 A list of machine-specific packages to install as part of the
3229 image being built that are not essential for booting the machine.
3230 The image being built has no build dependency on this list of packages.
3231 </para>
3232 <para>
3233 This variable affects only images based on
3234 <filename>packagegroup-base</filename>, which does not include the
3235 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
3236 images.
3237 </para>
3238 <para>
3239 This variable is similar to the
3240 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
3241 variable with the exception that the image being built does not have a build
3242 dependency on the variable's list of packages.
3243 In other words, the image will build if a file in this list is not found.
3244 </para>
3245 <para>
3246 An example is a machine that has WiFi capability but is not essential
3247 For the machine to boot the image.
3248 However, if you are building a more fully-featured image, you want to enable
3249 WiFi.
3250 In this case, the package containing the WiFi kernel module will not be produced
3251 if the WiFi driver is built into the kernel, in which case you still want the
3252 build to succeed instead of failing as a result of the package not being found.
3253 To accomplish this, assuming the package for the module was called
3254 <filename>kernel-module-examplewifi</filename>, you would use the
3255 following in the <filename>.conf</filename> file for the machine:
3256 <literallayout class='monospaced'>
3257 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
3258 </literallayout>
3259 </para>
3260 </glossdef>
3261 </glossentry>
3262
3263 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
3264 <glossdef>
3265 <para>Specifies the list of hardware features the
3266 <link linkend='var-MACHINE'>MACHINE</link> supports.
3267 For example, including the "bluetooth" feature causes the
3268 <filename>bluez</filename> bluetooth daemon to be built and
3269 added to the image.
3270 It also causes the <filename>connman</filename> recipe
3271 to look at <filename>MACHINE_FEATURES</filename> and when it
3272 finds "bluetooth" there it enables the bluetooth
3273 support in ConnMan.
3274 </para>
3275
3276 <para>
3277 For a list of features supported by the Yocto Project as shipped,
3278 see the "<link linkend='ref-features-machine'>Machine</link>" section.
3279 </para>
3280 </glossdef>
3281 </glossentry>
3282
3283 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
3284 <glossdef>
3285 <para>Features to be added to
3286 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
3287 if not also present in
3288 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
3289 </para>
3290
3291 <para>
3292 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
3293 It is not intended to be user-configurable.
3294 It is best to just reference the variable to see which machine features are
3295 being backfilled for all machine configurations.
3296 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
3297 more information.
3298 </para>
3299 </glossdef>
3300 </glossentry>
3301
3302 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
3303 <glossdef>
3304 <para>Features from
3305 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
3306 that should not be backfilled (i.e. added to
3307 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
3308 during the build.
3309 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
3310 more information.
3311 </para>
3312 </glossdef>
3313 </glossentry>
3314
3315 <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
3316 <glossdef>
3317 <para>
3318 Lists overrides specific to the current machine.
3319 By default, this list includes the value
3320 of <filename><link linkend='var-MACHINE'>MACHINE</link></filename>.
3321 You can extend the list to apply variable overrides for
3322 classes of machines.
3323 For example, all QEMU emulated machines (e.g. qemuarm,
3324 qemux86, and so forth) include a common file named
3325 <filename>meta/conf/machine/include/qemu.inc</filename>
3326 that prepends <filename>MACHINEOVERRIDES</filename> with
3327 the following variable override:
3328 <literallayout class='monospaced'>
3329 MACHINEOVERRIDES =. "qemuall:"
3330 </literallayout>
3331 Applying an override like <filename>qemuall</filename>
3332 affects all QEMU emulated machines elsewhere.
3333 Here is an example from the
3334 <filename>connman-conf</filename> recipe:
3335 <literallayout class='monospaced'>
3336 SRC_URI_append_qemuall = "file://wired.config \
3337 file://wired-setup \
3338 "
3339 </literallayout>
3340 </para>
3341 </glossdef>
3342 </glossentry>
3343
3344 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
3345 <glossdef>
3346 <para>The email address of the distribution maintainer.</para>
3347 </glossdef>
3348 </glossentry>
3349
3350 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
3351 <glossdef>
3352 <para>
3353 Specifies additional paths from which the OpenEmbedded
3354 build system gets source code.
3355 When the build system searches for source code, it first
3356 tries the local download directory.
3357 If that location fails, the build system tries locations
3358 defined by
3359 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
3360 the upstream source, and then locations specified by
3361 <filename>MIRRORS</filename> in that order.
3362 </para>
3363
3364 <para>
3365 Assuming your distribution
3366 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
3367 is "poky", the default value for
3368 <filename>MIRRORS</filename> is defined in the
3369 <filename>conf/distro/poky.conf</filename> file in the
3370 <filename>meta-yocto</filename> Git repository.
3371 </para>
3372 </glossdef>
3373 </glossentry>
3374
3375 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
3376 <glossdef>
3377 <para>
3378 Specifies a prefix has been added to
3379 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
3380 of a recipe or package, such as a Multilib version.
3381 The variable is used in places where the prefix needs to be
3382 added to or removed from a the name (e.g. the
3383 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
3384 <filename>MLPREFIX</filename> gets set when a prefix has been
3385 added to <filename>PN</filename>.
3386 </para>
3387 </glossdef>
3388 </glossentry>
3389
3390 <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
3391 <glossdef>
3392 <para>
3393 Controls creation of the <filename>modules-*.tgz</filename>
3394 file.
3395 Set this variable to "0" to disable creation of this
3396 file, which contains all of the kernel modules resulting
3397 from a kernel build.
3398 </para>
3399 </glossdef>
3400 </glossentry>
3401
3402 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
3403 <glossdef>
3404 <para>
3405 Separates files for different machines such that you can build
3406 for multiple target machines using the same output directories.
3407 See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable
3408 for an example.
3409 </para>
3410 </glossdef>
3411 </glossentry>
3412
3413 </glossdiv>
3414
3415 <glossdiv id='var-glossary-n'><title>N</title>
3416
3417 <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
3418 <glossdef>
3419 <para>
3420 A string identifying the host distribution.
3421 Strings consist of the host distributor ID
3422 followed by the release, as reported by the
3423 <filename>lsb_release</filename> tool
3424 or as read from <filename>/etc/lsb-release</filename>.
3425 For example, when running a build on Ubuntu 12.10, the value
3426 is "Ubuntu-12.10".
3427 If this information is unable to be determined, the value
3428 resolves to "Unknown".
3429 </para>
3430 <para>
3431 This variable is used by default to isolate native shared
3432 state packages for different distributions (e.g. to avoid
3433 problems with <filename>glibc</filename> version
3434 incompatibilities).
3435 Additionally, the variable is checked against
3436 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
3437 if that variable is set.
3438 </para>
3439 </glossdef>
3440 </glossentry>
3441
3442 <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
3443 <glossdef>
3444 <para>
3445 Prevents installation of all "recommended-only" packages.
3446 Recommended-only packages are packages installed only
3447 through the
3448 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
3449 variable).
3450 Setting the <filename>NO_RECOMMENDATIONS</filename> variable
3451 to "1" turns this feature on:
3452 <literallayout class='monospaced'>
3453 NO_RECOMMENDATIONS = "1"
3454 </literallayout>
3455 You can set this variable globally in your
3456 <filename>local.conf</filename> file or you can attach it to
3457 a specific image recipe by using the recipe name override:
3458 <literallayout class='monospaced'>
3459 NO_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
3460 </literallayout>
3461 </para>
3462
3463 <para>
3464 It is important to realize that if you choose to not install
3465 packages using this variable and some other packages are
3466 dependent on them (i.e. listed in a recipe's
3467 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
3468 variable), the OpenEmbedded build system ignores your
3469 request and will install the packages to avoid dependency
3470 errors.
3471 <note>
3472 Some recommended packages might be required for certain
3473 system functionality, such as kernel modules.
3474 It is up to you to add packages with
3475 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
3476 variable.
3477 </note>
3478 </para>
3479
3480 <para>
3481 Support for this variable exists only when using the
3482 IPK and RPM packaging backend.
3483 Support does not exist for DEB.
3484 </para>
3485
3486 <para>
3487 See the
3488 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
3489 and the
3490 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
3491 variables for related information.
3492 </para>
3493 </glossdef>
3494 </glossentry>
3495 </glossdiv>
3496
3497 <glossdiv id='var-glossary-o'><title>O</title>
3498
3499 <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
3500 <glossdef>
3501 <para>
3502 When a recipe inherits the
3503 <filename>binconfig.bbclass</filename> class, this variable
3504 specifies additional arguments passed to the "sed" command.
3505 The sed command alters any paths in configuration scripts
3506 that have been set up during compilation.
3507 Inheriting this class results in all paths in these scripts
3508 being changed to point into the
3509 <filename>sysroots/</filename> directory so that all builds
3510 that use the script will use the correct directories
3511 for the cross compiling layout.
3512 </para>
3513
3514 <para>
3515 See the <filename>meta/classes/binconfig.bbclass</filename>
3516 in the
3517 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
3518 for details on how this class applies these additional
3519 sed command arguments.
3520 For general information on the
3521 <filename>binconfig.bbclass</filename> class, see the
3522 "<link linkend='ref-classes-binconfig'>Binary Configuration Scripts - <filename>binconfig.bbclass</filename></link>"
3523 section.
3524 </para>
3525 </glossdef>
3526 </glossentry>
3527
3528 <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
3529 <glossdef>
3530 <para>
3531 An internal variable used to tell the OpenEmbedded build
3532 system what Python modules to import for every Python
3533 function run by the system.
3534 </para>
3535
3536 <note>
3537 Do not set this variable.
3538 It is for internal use only.
3539 </note>
3540 </glossdef>
3541 </glossentry>
3542
3543 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
3544 <glossdef>
3545 <para>
3546 Controls how the OpenEmbedded build system spawns
3547 interactive terminals on the host development system
3548 (e.g. using the BitBake command with the
3549 <filename>-c devshell</filename> command-line option).
3550 For more information, see the
3551 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
3552 in the Yocto Project Development Manual.
3553 </para>
3554
3555 <para>
3556 You can use the following values for the
3557 <filename>OE_TERMINAL</filename> variable:
3558 <literallayout class='monospaced'>
3559 auto
3560 gnome
3561 xfce
3562 rxvt
3563 screen
3564 konsole
3565 none
3566 </literallayout>
3567 <note>Konsole support only works for KDE 3.x.
3568 Also, "auto" is the default behavior for
3569 <filename>OE_TERMINAL</filename></note>
3570 </para>
3571 </glossdef>
3572 </glossentry>
3573
3574 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
3575 <glossdef>
3576 <para>
3577 The directory from which the top-level build environment
3578 setup script is sourced.
3579 The Yocto Project makes two top-level build environment
3580 setup scripts available:
3581 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
3582 and
3583 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
3584 When you run one of these scripts, the
3585 <filename>OEROOT</filename> variable resolves to the
3586 directory that holds the script.
3587 </para>
3588
3589 <para>
3590 For additional information on how this variable is used,
3591 see the initialization scripts.
3592 </para>
3593 </glossdef>
3594 </glossentry>
3595
3596 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
3597 <glossdef>
3598 <para>
3599 Declares the oldest version of the Linux kernel that the
3600 produced binaries must support.
3601 This variable is passed into the build of the Embedded
3602 GNU C Library (<filename>eglibc</filename>).
3603 </para>
3604
3605 <para>
3606 The default for this variable comes from the
3607 <filename>meta/conf/bitbake.conf</filename> configuration
3608 file.
3609 You can override this default by setting the variable
3610 in a custom distribution configuration file.
3611 </para>
3612 </glossdef>
3613 </glossentry>
3614
3615 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
3616 <glossdef>
3617 <para>
3618 BitBake uses <filename>OVERRIDES</filename> to control
3619 what variables are overridden after BitBake parses
3620 recipes and configuration files.
3621 You can find more information on how overrides are handled
3622 in the BitBake Manual that is located at
3623 <filename>bitbake/doc/manual</filename> in the
3624 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
3625 </para>
3626 </glossdef>
3627 </glossentry>
3628 </glossdiv>
3629
3630 <glossdiv id='var-glossary-p'><title>P</title>
3631
3632 <glossentry id='var-P'><glossterm>P</glossterm>
3633 <glossdef>
3634 <para>The recipe name and version.
3635 <filename>P</filename> is comprised of the following:
3636 <literallayout class='monospaced'>
3637 ${PN}-${PV}
3638 </literallayout></para>
3639 </glossdef>
3640 </glossentry>
3641
3642 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
3643 <glossdef>
3644 <para>The architecture of the resulting package or packages.</para>
3645 </glossdef>
3646 </glossentry>
3647
3648 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
3649 <glossdef>
3650 <para>Enables easily adding packages to
3651 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
3652 before <filename>${<link linkend='var-PN'>PN</link>}</filename>
3653 so that the packages can pick up files that would normally be
3654 included in the default package.</para>
3655 </glossdef>
3656 </glossentry>
3657
3658 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
3659 <glossdef>
3660 <para>This variable, which is set in the <filename>local.conf</filename> configuration
3661 file found in the <filename>conf</filename> folder of the
3662 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
3663 specifies the package manager to use when packaging data.
3664 You can provide one or more arguments for the variable with the first
3665 argument being the package manager used to create images:
3666 <literallayout class='monospaced'>
3667 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
3668 </literallayout>
3669 For information on build performance effects as a result of the
3670 package manager use, see
3671 <link linkend='ref-classes-package'>Packaging - <filename>package*.bbclass</filename></link>
3672 in this manual.
3673 </para>
3674 </glossdef>
3675 </glossentry>
3676
3677 <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
3678 <glossdef>
3679 <para>
3680 Lists packages that should not be installed into an image.
3681 For example:
3682 <literallayout class='monospaced'>
3683 PACKAGE_EXCLUDE = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
3684 </literallayout>
3685 You can set this variable globally in your
3686 <filename>local.conf</filename> file or you can attach it to
3687 a specific image recipe by using the recipe name override:
3688 <literallayout class='monospaced'>
3689 PACKAGE_EXCLUDE_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
3690 </literallayout>
3691 </para>
3692
3693 <para>
3694 If you choose to not install
3695 a package using this variable and some other package is
3696 dependent on it (i.e. listed in a recipe's
3697 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
3698 variable), the OpenEmbedded build system generates a fatal
3699 installation error.
3700 Because the build system halts the process with a fatal
3701 error, you can use the variable with an iterative
3702 development process to remove specific components from a
3703 system.
3704 </para>
3705
3706 <para>
3707 Support for this variable exists only when using the
3708 IPK and RPM packaging backend.
3709 Support does not exist for DEB.
3710 </para>
3711
3712 <para>
3713 See the
3714 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
3715 and the
3716 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
3717 variables for related information.
3718 </para>
3719 </glossdef>
3720 </glossentry>
3721
3722 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
3723 <glossdef>
3724 <para>Specifies the list of architectures compatible with the device CPU.
3725 This variable is useful when you build for several different devices that use
3726 miscellaneous processors such as XScale and ARM926-EJS).</para>
3727 </glossdef>
3728 </glossentry>
3729
3730 <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
3731 <glossdef>
3732 <para>
3733 Defines one or more packages to include in an image when
3734 a specific item is included in
3735 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
3736 When setting the value, <filename>PACKAGE_GROUP</filename>
3737 should have the name of the feature item as an override.
3738 Here is an example:
3739 <literallayout class='monospaced'>
3740 PACKAGE_GROUP_widget = "package1 package2"
3741 </literallayout>
3742 In this example, if "widget" were added to
3743 <filename>IMAGE_FEATURES</filename>, "package1" and
3744 "package2" would be included in the image.
3745 <note>
3746 Packages installed by features defined through
3747 <filename>PACKAGE_GROUP</filename> are often package
3748 groups.
3749 While similarly named, you should not confuse the
3750 <filename>PACKAGE_GROUP</filename> variable with
3751 package groups, which are discussed elsewhere in the
3752 documentation.
3753 </note>
3754 </para>
3755 </glossdef>
3756 </glossentry>
3757
3758 <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
3759 <glossdef>
3760 <para>
3761 The final list of packages passed to the package manager
3762 for installation into the image.
3763 Because the package manager controls actual installation
3764 of all packages, the list of packages passed using
3765 <filename>PACKAGE_INSTALL</filename> is not the final list
3766 of packages that are actually installed.
3767 </para>
3768
3769 <para>
3770 This variable is internal to the image construction
3771 code.
3772 Use the
3773 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
3774 variable to specify packages for installation.
3775 </para>
3776 </glossdef>
3777 </glossentry>
3778
3779 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
3780 <glossdef>
3781 <para>
3782 This variable provides a means of enabling or disabling
3783 features of a recipe on a per-recipe basis.
3784 <filename>PACKAGECONFIG</filename> blocks are defined
3785 in recipes when you specify features and then arguments
3786 that define feature behaviors.
3787 Here is the basic block structure:
3788 <literallayout class='monospaced'>
3789 PACKAGECONFIG ??= "f1 f2 f3 ..."
3790 PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1"
3791 PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2"
3792 PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3"
3793 </literallayout>
3794 The <filename>PACKAGECONFIG</filename>
3795 variable itself specifies a space-separated list of the
3796 features to enable.
3797 Following the features, you can determine the behavior of
3798 each feature by providing up to four order-dependent
3799 arguments, which are separated by commas.
3800 You can omit any argument you like but must retain the
3801 separating commas.
3802 The order is important and specifies the following:
3803 <orderedlist>
3804 <listitem><para>Extra arguments
3805 that should be added to the configure script
3806 argument list
3807 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>)
3808 if the feature is enabled.</para></listitem>
3809 <listitem><para>Extra arguments
3810 that should be added to <filename>EXTRA_OECONF</filename>
3811 if the feature is disabled.
3812 </para></listitem>
3813 <listitem><para>Additional build dependencies
3814 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
3815 that should be added if the feature is enabled.
3816 </para></listitem>
3817 <listitem><para>Additional runtime dependencies
3818 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
3819 that should be added if the feature is enabled.
3820 </para></listitem>
3821 </orderedlist>
3822 </para>
3823
3824 <para>
3825 Consider the following
3826 <filename>PACKAGECONFIG</filename> block taken from the
3827 <filename>librsvg</filename> recipe.
3828 In this example the feature is <filename>croco</filename>,
3829 which has three arguments that determine the feature's
3830 behavior.
3831 <literallayout class='monospaced'>
3832 PACKAGECONFIG ??= "croco"
3833 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
3834 </literallayout>
3835 The <filename>--with-croco</filename> and
3836 <filename>libcroco</filename> arguments apply only if
3837 the feature is enabled.
3838 In this case, <filename>--with-croco</filename> is
3839 added to the configure script argument list and
3840 <filename>libcroco</filename> is added to
3841 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
3842 On the other hand, if the feature is disabled say through
3843 a <filename>.bbappend</filename> file in another layer, then
3844 the second argument <filename>--without-croco</filename> is
3845 added to the configure script rather than
3846 <filename>--with-croco</filename>.
3847 </para>
3848
3849 <para>
3850 The basic <filename>PACKAGECONFIG</filename> structure
3851 previously described holds true regardless of whether you
3852 are creating a block or changing a block.
3853 When creating a block, use the structure inside your
3854 recipe.
3855 </para>
3856
3857 <para>
3858 If you want to change an existing
3859 <filename>PACKAGECONFIG</filename> block, you can do so
3860 one of two ways:
3861 <itemizedlist>
3862 <listitem><para><emphasis>Append file:</emphasis>
3863 Create an append file named
3864 <filename>&lt;recipename&gt;.bbappend</filename> in your
3865 layer and override the value of
3866 <filename>PACKAGECONFIG</filename>.
3867 You can either completely override the variable:
3868 <literallayout class='monospaced'>
3869 PACKAGECONFIG="f4 f5"
3870 </literallayout>
3871 Or, you can just amended the variable:
3872 <literallayout class='monospaced'>
3873 PACKAGECONFIG_append = " f4"
3874 </literallayout></para></listitem>
3875 <listitem><para><emphasis>Configuration file:</emphasis>
3876 This method is identical to changing the block
3877 through an append file except you edit your
3878 <filename>local.conf</filename> or
3879 <filename>&lt;mydistro&gt;.conf</filename> file.
3880 As with append files previously described,
3881 you can either completely override the variable:
3882 <literallayout class='monospaced'>
3883 PACKAGECONFIG_pn-&lt;recipename&gt;="f4 f5"
3884 </literallayout>
3885 Or, you can just amended the variable:
3886 <literallayout class='monospaced'>
3887 PACKAGECONFIG_append_pn-&lt;recipename&gt; = " f4"
3888 </literallayout></para></listitem>
3889 </itemizedlist>
3890 </para>
3891 </glossdef>
3892 </glossentry>
3893
3894 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
3895 <glossdef>
3896 <para>The list of packages to be created from the recipe.
3897 The default value is the following:
3898 <literallayout class='monospaced'>
3899 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
3900 </literallayout></para>
3901 </glossdef>
3902 </glossentry>
3903
3904 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
3905 <glossdef>
3906 <para>
3907 A promise that your recipe satisfies runtime dependencies
3908 for optional modules that are found in other recipes.
3909 <filename>PACKAGES_DYNAMIC</filename>
3910 does not actually satisfy the dependencies, it only states that
3911 they should be satisfied.
3912 For example, if a hard, runtime dependency
3913 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
3914 of another package is satisfied
3915 at build time through the <filename>PACKAGES_DYNAMIC</filename>
3916 variable, but a package with the module name is never actually
3917 produced, then the other package will be broken.
3918 Thus, if you attempt to include that package in an image,
3919 you will get a dependency failure from the packaging system
3920 during <filename>do_rootfs</filename>.
3921 </para>
3922 <para>
3923 Typically, if there is a chance that such a situation can
3924 occur and the package that is not created is valid
3925 without the dependency being satisfied, then you should use
3926 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
3927 (a soft runtime dependency) instead of
3928 <filename>RDEPENDS</filename>.
3929 </para>
3930
3931 <para>
3932 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
3933 variable when you are splitting packages, see the
3934 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
3935 in the Yocto Project Development Manual.
3936 </para>
3937 </glossdef>
3938 </glossentry>
3939
3940 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
3941 <glossdef>
3942 <para>
3943 Extra options that are passed to the
3944 <filename>make</filename> command during the
3945 <filename>do_compile</filename> task in order to specify
3946 parallel compilation.
3947 This variable is usually in the form
3948 <filename>-j 4</filename>, where the number
3949 represents the maximum number of parallel threads make can
3950 run.
3951 If you development host supports multiple cores a good
3952 rule of thumb is to set this variable to twice the number
3953 of cores on the host.
3954 <note>
3955 Individual recipes might clear out this variable if
3956 the software being built has problems running its
3957 <filename>make</filename> process in parallel.
3958 </note>
3959 </para>
3960 </glossdef>
3961 </glossentry>
3962
3963 <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
3964 <glossdef>
3965 <para>
3966 Extra options passed to the
3967 <filename>make install</filename> command during the
3968 <filename>do_install</filename> task in order to specify
3969 parallel installation.
3970 This variable defaults to the value of
3971 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
3972 <note>
3973 Individual recipes might clear out this variable if
3974 the software being built has problems running its
3975 <filename>make install</filename> process in parallel.
3976 </note>
3977 </para>
3978 </glossdef>
3979 </glossentry>
3980
3981
3982
3983
3984PARALLEL_MAKEINST with the description ".
3985
3986
3987
3988
3989
3990 <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
3991 <glossdef>
3992 <para>
3993 Determines the action to take when a patch fails.
3994 You can set this variable to one of two values: "noop" and
3995 "user".
3996 </para>
3997
3998 <para>
3999 The default value of "noop" causes the build to simply fail
4000 when the OpenEmbedded build system cannot successfully
4001 apply a patch.
4002 Setting the value to "user" causes the build system to
4003 launch a shell and places you in the right location so that
4004 you can manually resolve the conflicts.
4005 </para>
4006
4007 <para>
4008 Set this variable in your
4009 <filename>local.conf</filename> file.
4010 </para>
4011 </glossdef>
4012 </glossentry>
4013
4014 <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
4015 <glossdef>
4016 <para>
4017 Specifies the utility used to apply patches for a recipe
4018 during <filename>do_patch</filename>.
4019 You can specify one of three utilities: "patch", "quilt", or
4020 "git".
4021 The default utility used is "quilt" except for the
4022 quilt-native recipe itself.
4023 Because the quilt tool is not available at the
4024 time quilt-native is being patched, it uses "patch".
4025 </para>
4026
4027 <para>
4028 If you wish to use an alternative patching tool, set the
4029 variable in the recipe using one of the following:
4030 <literallayout class='monospaced'>
4031 PATCHTOOL = "patch"
4032 PATCHTOOL = "quilt"
4033 PATCHTOOL = "git"
4034 </literallayout>
4035 </para>
4036 </glossdef>
4037 </glossentry>
4038
4039 <glossentry id='var-PE'><glossterm>PE</glossterm>
4040 <glossdef>
4041 <para>
4042 the epoch of the recipe.
4043 By default, this variable is unset.
4044 The field is used to make upgrades possible when the
4045 versioning scheme changes in some backwards incompatible
4046 way.
4047 </para>
4048 </glossdef>
4049 </glossentry>
4050
4051 <glossentry id='var-PF'><glossterm>PF</glossterm>
4052 <glossdef>
4053 <para>Specifies the recipe or package name and includes all version and revision
4054 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
4055 <filename>bash-4.2-r1/</filename>).
4056 This variable is comprised of the following:
4057 <literallayout class='monospaced'>
4058 ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
4059 </literallayout></para>
4060 </glossdef>
4061 </glossentry>
4062
4063 <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
4064 <glossdef>
4065 <para>
4066 Points to the destination directory for files to be
4067 packaged before they are split into individual packages.
4068 This directory defaults to the following:
4069 <literallayout class='monospaced'>
4070 ${WORKDIR}/package
4071 </literallayout>
4072 Do not change this default.
4073 </para>
4074 </glossdef>
4075 </glossentry>
4076
4077 <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
4078 <glossdef>
4079 <para>
4080 Points to a shared, global-state directory that holds data
4081 generated during the packaging process.
4082 During the packaging process, the
4083 <filename>do_packagedata</filename> task packages
4084 data for each recipe and installs it into this temporary,
4085 shared area.
4086 </para>
4087 </glossdef>
4088 </glossentry>
4089
4090 <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
4091 <glossdef>
4092 <para>
4093 Points to the parent directory for files to be packaged
4094 after they have been split into individual packages.
4095 This directory defaults to the following:
4096 <literallayout class='monospaced'>
4097 ${WORKDIR}/packages-split
4098 </literallayout>
4099 Under this directory, the build system creates
4100 directories for each package specified in
4101 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
4102 Do not change this default.
4103 </para>
4104 </glossdef>
4105 </glossentry>
4106
4107 <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
4108 <glossdef>
4109 <para>
4110 Points to a temporary work area used by the
4111 <filename>do_package</filename> task to write output
4112 from the <filename>do_packagedata</filename> task.
4113 The <filename>PKGDESTWORK</filename> location defaults to
4114 the following:
4115 <literallayout class='monospaced'>
4116 ${WORKDIR}/pkgdata
4117 </literallayout>
4118 The <filename>do_packagedata</filename> task then packages
4119 the data in the temporary work area and installs it into a
4120 shared directory pointed to by
4121 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
4122 </para>
4123
4124 <para>
4125 Do not change this default.
4126 </para>
4127 </glossdef>
4128 </glossentry>
4129
4130 <glossentry id='var-PN'><glossterm>PN</glossterm>
4131 <glossdef>
4132 <para>This variable can have two separate functions depending on the context: a recipe
4133 name or a resulting package name.</para>
4134 <para><filename>PN</filename> refers to a recipe name in the context of a file used
4135 by the OpenEmbedded build system as input to create a package.
4136 The name is normally extracted from the recipe file name.
4137 For example, if the recipe is named
4138 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
4139 will be "expat".</para>
4140 <para>
4141 The variable refers to a package name in the context of a file created or produced by the
4142 OpenEmbedded build system.</para>
4143 <para>If applicable, the <filename>PN</filename> variable also contains any special
4144 suffix or prefix.
4145 For example, using <filename>bash</filename> to build packages for the native
4146 machine, <filename>PN</filename> is <filename>bash-native</filename>.
4147 Using <filename>bash</filename> to build packages for the target and for Multilib,
4148 <filename>PN</filename> would be <filename>bash</filename> and
4149 <filename>lib64-bash</filename>, respectively.
4150 </para>
4151 </glossdef>
4152 </glossentry>
4153
4154 <glossentry id='var-PR'><glossterm>PR</glossterm>
4155 <glossdef>
4156 <para>The revision of the recipe.
4157 The default value for this variable is "r0".
4158 </para>
4159 </glossdef>
4160 </glossentry>
4161
4162 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
4163 <glossdef>
4164 <para>
4165 If multiple recipes provide an item, this variable
4166 determines which recipe should be given preference.
4167 You should always suffix the variable with the name of the
4168 provided item, and you should set it to the
4169 <link linkend='var-PN'><filename>PN</filename></link>
4170 of the recipe to which you want to give precedence.
4171 Here is an example:
4172 <literallayout class='monospaced'>
4173 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
4174 </literallayout>
4175 </para>
4176 </glossdef>
4177 </glossentry>
4178
4179 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
4180 <glossdef>
4181 <para>
4182 If there are multiple versions of recipes available, this
4183 variable determines which recipe should be given preference.
4184 You must always suffix the variable with the
4185 <link linkend='var-PN'><filename>PN</filename></link>
4186 you want to select, and you should set to the
4187 <link linkend='var-PV'><filename>PV</filename></link>
4188 accordingly for precedence.
4189 You can use the "<filename>%</filename>" character as a
4190 wildcard to match any number of characters, which can be
4191 useful when specifying versions that contain long revision
4192 numbers that could potentially change.
4193 Here are two examples:
4194 <literallayout class='monospaced'>
4195 PREFERRED_VERSION_python = "2.6.6"
4196 PREFERRED_VERSION_linux-yocto = "3.0+git%"
4197 </literallayout>
4198 </para>
4199 </glossdef>
4200 </glossentry>
4201
4202 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
4203 <glossdef>
4204 <para>
4205 Specifies additional paths from which the OpenEmbedded
4206 build system gets source code.
4207 When the build system searches for source code, it first
4208 tries the local download directory.
4209 If that location fails, the build system tries locations
4210 defined by <filename>PREMIRRORS</filename>, the upstream
4211 source, and then locations specified by
4212 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
4213 in that order.
4214 </para>
4215
4216 <para>
4217 Assuming your distribution
4218 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
4219 is "poky", the default value for
4220 <filename>PREMIRRORS</filename> is defined in the
4221 <filename>conf/distro/poky.conf</filename> file in the
4222 <filename>meta-yocto</filename> Git repository.
4223 </para>
4224
4225 <para>
4226 Typically, you could add a specific server for the
4227 build system to attempt before any others by adding
4228 something like the following to the
4229 <filename>local.conf</filename> configuration file in the
4230 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
4231 <literallayout class='monospaced'>
4232 PREMIRRORS_prepend = "\
4233 git://.*/.* http://www.yoctoproject.org/sources/ \n \
4234 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
4235 http://.*/.* http://www.yoctoproject.org/sources/ \n \
4236 https://.*/.* http://www.yoctoproject.org/sources/ \n"
4237 </literallayout>
4238 These changes cause the build system to intercept
4239 Git, FTP, HTTP, and HTTPS requests and direct them to
4240 the <filename>http://</filename> sources mirror.
4241 You can use <filename>file://</filename> URLs to point
4242 to local directories or network shares as well.
4243 </para>
4244 </glossdef>
4245 </glossentry>
4246
4247 <glossentry id='var-PRINC'><glossterm>PRINC</glossterm>
4248 <glossdef>
4249 <para>Causes the <link linkend='var-PR'><filename>PR</filename></link>
4250 variable of <filename>.bbappend</filename> files to
4251 dynamically increment.
4252 This increment minimizes the impact of layer ordering.</para>
4253 <para>In order to ensure multiple <filename>.bbappend</filename> files can co-exist,
4254 <filename>PRINC</filename> should be self referencing.
4255 This variable defaults to 0.</para>
4256 <para>Following is an example that increments <filename>PR</filename> by two:
4257 <literallayout class='monospaced'>
4258 PRINC := "${@int(PRINC) + 2}"
4259 </literallayout>
4260 It is advisable not to use strings such as ".= '.1'" with the variable because
4261 this usage is very sensitive to layer ordering.
4262 You should avoid explicit assignments as they cannot
4263 adequately represent multiple
4264 <filename>.bbappend</filename> files.</para>
4265 </glossdef>
4266 </glossentry>
4267
4268 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
4269 <glossdef>
4270 <para>
4271 A list of aliases that a recipe also provides.
4272 These aliases are useful for satisfying dependencies of
4273 other recipes during the build (as specified by
4274 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>).
4275 <note>
4276 A recipe's own
4277 <filename><link linkend='var-PN'>PN</link></filename>
4278 is implicitly already in its
4279 <filename>PROVIDES</filename> list.
4280 </note>
4281 </para>
4282 </glossdef>
4283 </glossentry>
4284
4285 <glossentry id='var-PV'><glossterm>PV</glossterm>
4286 <glossdef>
4287 <para>The version of the recipe.
4288 The version is normally extracted from the recipe filename.
4289 For example, if the recipe is named
4290 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename>
4291 will be "2.0.1".
4292 <filename>PV</filename> is generally not overridden within
4293 a recipe unless it is building an unstable (i.e. development) version from a source code repository
4294 (e.g. Git or Subversion).
4295 </para>
4296 </glossdef>
4297 </glossentry>
4298
4299 </glossdiv>
4300
4301<!-- <glossdiv id='var-glossary-q'><title>Q</title>-->
4302<!-- </glossdiv>-->
4303
4304 <glossdiv id='var-glossary-r'><title>R</title>
4305
4306 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
4307 <glossdef>
4308 <para>
4309 The list of packages that conflict with packages.
4310 Note that packages will not be installed if conflicting
4311 packages are not first removed.
4312 </para>
4313
4314 <para>
4315 Like all package-controlling variables, you must always use
4316 them in conjunction with a package name override.
4317 Here is an example:
4318 <literallayout class='monospaced'>
4319 RCONFLICTS_${PN} = "another-conflicting-package-name"
4320 </literallayout>
4321 </para>
4322
4323 <para>
4324 BitBake, which the OpenEmbedded build system uses, supports
4325 specifying versioned dependencies.
4326 Although the syntax varies depending on the packaging
4327 format, BitBake hides these differences from you.
4328 Here is the general syntax to specify versions with
4329 the <filename>RCONFLICTS</filename> variable:
4330 <literallayout class='monospaced'>
4331 RCONFLICTS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
4332 </literallayout>
4333 For <filename>operator</filename>, you can specify the
4334 following:
4335 <literallayout class='monospaced'>
4336 =
4337 &lt;
4338 &gt;
4339 &lt;=
4340 &gt;=
4341 </literallayout>
4342 For example, the following sets up a dependency on version
4343 1.2 or greater of the package <filename>foo</filename>:
4344 <literallayout class='monospaced'>
4345 RCONFLICTS_${PN} = "foo (>= 1.2)"
4346 </literallayout>
4347 </para>
4348 </glossdef>
4349 </glossentry>
4350
4351 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
4352 <glossdef>
4353 <para>
4354 Lists a package's runtime dependencies (i.e. other packages)
4355 that must be installed in order for the built package to run
4356 correctly.
4357 If a package in this list cannot be found during the build,
4358 you will get a build error.
4359 </para>
4360
4361 <para>
4362 When you use the <filename>RDEPENDS</filename> variable
4363 in a recipe, you are essentially stating that the recipe's
4364 <filename>do_build</filename> task depends on the existence
4365 of a specific package.
4366 Consider this simple example for two recipes named "a" and
4367 "b" that produce similarly named packages.
4368 In this example, the <filename>RDEPENDS</filename>
4369 statement appears in the "a" recipe:
4370 <literallayout class='monospaced'>
4371 RDEPENDS_${PN} = "b"
4372 </literallayout>
4373 Here, the dependency is such that the
4374 <filename>do_build</filename> task for recipe "a" depends
4375 on the <filename>do_package_write</filename> task
4376 of recipe "b".
4377 This means the package file for "b" must be available when
4378 the output for recipe "a" has been completely built.
4379 More importantly, package "a" will be marked as depending
4380 on package "b" in a manner that is understood by the
4381 package manager in use (i.e. rpm, opkg, or dpkg).
4382 </para>
4383
4384 <para>
4385 The names of the packages you list within
4386 <filename>RDEPENDS</filename> must be the names of other
4387 packages - they cannot be recipe names.
4388 Although package names and recipe names usually match,
4389 the important point here is that you are
4390 providing package names within the
4391 <filename>RDEPENDS</filename> variable.
4392 For an example of the default list of packages created from
4393 a recipe, see the
4394 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
4395 variable.
4396 </para>
4397
4398 <para>
4399 Because the <filename>RDEPENDS</filename> variable applies
4400 to packages being built, you should always use the variable
4401 in a form with an attached package name.
4402 For example, suppose you are building a development package
4403 that depends on the <filename>perl</filename> package.
4404 In this case, you would use the following
4405 <filename>RDEPENDS</filename> statement:
4406 <literallayout class='monospaced'>
4407 RDEPENDS_${PN}-dev += "perl"
4408 </literallayout>
4409 In the example, the development package depends on
4410 the <filename>perl</filename> package.
4411 Thus, the <filename>RDEPENDS</filename> variable has the
4412 <filename>${PN}-dev</filename> package name as part of the
4413 variable.
4414 </para>
4415
4416 <para>
4417 The package name you attach to the
4418 <filename>RDEPENDS</filename> variable must appear
4419 as it would in the <filename>PACKAGES</filename>
4420 namespace before any renaming of the output package by
4421 classes like <filename>debian.bbclass</filename>.
4422 </para>
4423
4424 <para>
4425 In many cases you do not need to explicitly add
4426 runtime dependencies using
4427 <filename>RDEPENDS</filename> since some automatic
4428 handling occurs:
4429 <itemizedlist>
4430 <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If
4431 a runtime package contains a shared library
4432 (<filename>.so</filename>), the build
4433 processes the library in order to determine other
4434 libraries to which it is dynamically linked.
4435 The build process adds these libraries to
4436 <filename>RDEPENDS</filename> when creating the runtime
4437 package.</para></listitem>
4438 <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If
4439 the package ships a <filename>pkg-config</filename>
4440 information file, the build process uses this file
4441 to add items to the <filename>RDEPENDS</filename>
4442 variable to create the runtime packages.
4443 </para></listitem>
4444 </itemizedlist>
4445 </para>
4446
4447 <para>
4448 BitBake, which the OpenEmbedded build system uses, supports
4449 specifying versioned dependencies.
4450 Although the syntax varies depending on the packaging
4451 format, BitBake hides these differences from you.
4452 Here is the general syntax to specify versions with
4453 the <filename>RDEPENDS</filename> variable:
4454 <literallayout class='monospaced'>
4455 RDEPENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
4456 </literallayout>
4457 For <filename>operator</filename>, you can specify the
4458 following:
4459 <literallayout class='monospaced'>
4460 =
4461 &lt;
4462 &gt;
4463 &lt;=
4464 &gt;=
4465 </literallayout>
4466 For example, the following sets up a dependency on version
4467 1.2 or greater of the package <filename>foo</filename>:
4468 <literallayout class='monospaced'>
4469 RDEPENDS_${PN} = "foo (>= 1.2)"
4470 </literallayout>
4471 </para>
4472
4473 <para>
4474 For information on build-time dependencies, see the
4475 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
4476 variable.
4477 </para>
4478 </glossdef>
4479 </glossentry>
4480
4481 <glossentry id='var-RM_OLD_IMAGE'><glossterm>RM_OLD_IMAGE</glossterm>
4482 <glossdef>
4483 <para>
4484 Reclaims disk space by removing previously built
4485 versions of the same image from the
4486 <filename>images</filename> directory pointed to by the
4487 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
4488 variable.
4489 </para>
4490
4491 <para>
4492 Set this variable to "1" in your
4493 <filename>local.conf</filename> file to remove these
4494 images.
4495 </para>
4496 </glossdef>
4497 </glossentry>
4498
4499 <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
4500 <glossdef>
4501 <para>
4502 With <filename>rm_work</filename> enabled, this
4503 variable specifies a list of recipes whose work directories
4504 should not be removed.
4505 See the "<link linkend='ref-classes-rm-work'>Removing Work Files During the Build - <filename>rm_work.bbclass</filename></link>"
4506 section for more details.
4507 </para>
4508 </glossdef>
4509 </glossentry>
4510
4511 <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
4512 <glossdef>
4513 <para>
4514 Added by classes to run post processing commands once the
4515 OpenEmbedded build system has created the root filesystem.
4516 You can specify shell commands separated by semicolons:
4517 <literallayout class='monospaced'>
4518 ROOTFS_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
4519 </literallayout>
4520 If you need to pass the path to the root filesystem within
4521 the command, you can use
4522 <filename>${IMAGE_ROOTFS}</filename>, which points to
4523 the root filesystem image.
4524 </para>
4525 </glossdef>
4526 </glossentry>
4527
4528 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
4529 <glossdef>
4530 <para>
4531 A list of package name aliases that a package also provides.
4532 These aliases are useful for satisfying runtime dependencies
4533 of other packages both during the build and on the target
4534 (as specified by
4535 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
4536 <note>
4537 A package's own name is implicitly already in its
4538 <filename>RPROVIDES</filename> list.
4539 </note>
4540 </para>
4541 <para>
4542 As with all package-controlling variables, you must always
4543 use the variable in conjunction with a package name override.
4544 Here is an example:
4545 <literallayout class='monospaced'>
4546 RPROVIDES_${PN} = "widget-abi-2"
4547 </literallayout>
4548 </para>
4549 </glossdef>
4550 </glossentry>
4551
4552 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
4553 <glossdef>
4554 <para>
4555 A list of packages that extends the usability of a package
4556 being built.
4557 The package being built does not depend on this list of
4558 packages in order to successfully build, but needs them for
4559 the extended usability.
4560 To specify runtime dependencies for packages, see the
4561 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
4562 variable.
4563 </para>
4564
4565 <para>
4566 The OpenEmbedded build process automatically installs the
4567 list of packages as part of the built package.
4568 However, you can remove these packages later if you want.
4569 If, during the build, a package from the
4570 <filename>RRECOMMENDS</filename> list cannot be
4571 found, the build process continues without an error.
4572 </para>
4573
4574 <para>
4575 You can also prevent packages in the list from being
4576 installed by using several variables.
4577 See the
4578 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
4579 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
4580 and
4581 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
4582 variables for more information.
4583 </para>
4584
4585 <para>
4586 Because the <filename>RRECOMMENDS</filename> variable
4587 applies to packages being built, you should always attach
4588 an override to the variable to specify the particular
4589 package whose usability is being extended.
4590 For example, suppose you are building a development package
4591 that is extended to support wireless functionality.
4592 In this case, you would use the following:
4593 <literallayout class='monospaced'>
4594 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
4595 </literallayout>
4596 In the example, the package name
4597 (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
4598 must appear as it would in the
4599 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
4600 namespace before any renaming of the output package by
4601 classes such as <filename>debian.bbclass</filename>.
4602 </para>
4603
4604 <para>
4605 BitBake, which the OpenEmbedded build system uses, supports
4606 specifying versioned recommends.
4607 Although the syntax varies depending on the packaging
4608 format, BitBake hides these differences from you.
4609 Here is the general syntax to specify versions with
4610 the <filename>RRECOMMENDS</filename> variable:
4611 <literallayout class='monospaced'>
4612 RRECOMMENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
4613 </literallayout>
4614 For <filename>operator</filename>, you can specify the
4615 following:
4616 <literallayout class='monospaced'>
4617 =
4618 &lt;
4619 &gt;
4620 &lt;=
4621 &gt;=
4622 </literallayout>
4623 For example, the following sets up a recommend on version
4624 1.2 or greater of the package <filename>foo</filename>:
4625 <literallayout class='monospaced'>
4626 RRECOMMENDS_${PN} = "foo (>= 1.2)"
4627 </literallayout>
4628 </para>
4629 </glossdef>
4630 </glossentry>
4631
4632 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
4633 <glossdef>
4634 <para>
4635 A list of packages replaced by a package.
4636 The package manager uses this variable to determine which
4637 package should be installed to replace other package(s)
4638 during an upgrade.
4639 In order to also have the other package(s) removed at the
4640 same time, you must add the name of the other
4641 package to the
4642 <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
4643 </para>
4644 <para>
4645 As with all package-controlling variables, you must use
4646 this variable in conjunction with a package name
4647 override.
4648 Here is an example:
4649 <literallayout class='monospaced'>
4650 RREPLACES_${PN} = "other-package-being-replaced"
4651 </literallayout>
4652 </para>
4653
4654 <para>
4655 BitBake, which the OpenEmbedded build system uses, supports
4656 specifying versioned replacements.
4657 Although the syntax varies depending on the packaging
4658 format, BitBake hides these differences from you.
4659 Here is the general syntax to specify versions with
4660 the <filename>RREPLACES</filename> variable:
4661 <literallayout class='monospaced'>
4662 RREPLACES_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
4663 </literallayout>
4664 For <filename>operator</filename>, you can specify the
4665 following:
4666 <literallayout class='monospaced'>
4667 =
4668 &lt;
4669 &gt;
4670 &lt;=
4671 &gt;=
4672 </literallayout>
4673 For example, the following sets up a replacement using
4674 version 1.2 or greater of the package
4675 <filename>foo</filename>:
4676 <literallayout class='monospaced'>
4677 RREPLACES_${PN} = "foo (>= 1.2)"
4678 </literallayout>
4679 </para>
4680 </glossdef>
4681 </glossentry>
4682
4683 <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
4684 <glossdef>
4685 <para>
4686 A list of additional packages that you can suggest for
4687 installation by the package manager at the time a package
4688 is installed.
4689 Not all package managers support this functionality.
4690 </para>
4691 <para>
4692 As with all package-controlling variables, you must always
4693 use this variable in conjunction with a package name
4694 override.
4695 Here is an example:
4696 <literallayout class='monospaced'>
4697 RSUGGESTS_${PN} = "useful-package another-package"
4698 </literallayout>
4699 </para>
4700 </glossdef>
4701 </glossentry>
4702
4703 </glossdiv>
4704
4705 <glossdiv id='var-glossary-s'><title>S</title>
4706
4707 <glossentry id='var-S'><glossterm>S</glossterm>
4708 <glossdef>
4709 <para>
4710 The location in the
4711 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
4712 where unpacked recipe source code resides.
4713 This location is within the working directory
4714 (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>),
4715 which is not static.
4716 The unpacked source location depends on the recipe name
4717 (<filename><link linkend='var-PN'>PN</link></filename>) and
4718 recipe version
4719 (<filename><link linkend='var-PV'>PV</link></filename>) as
4720 follows:
4721 <literallayout class='monospaced'>
4722 ${WORKDIR}/${PN}-${PV}
4723 </literallayout>
4724 As an example, assume a
4725 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
4726 top-level folder named <filename>poky</filename> and a
4727 default Build Directory at <filename>poky/build</filename>.
4728 In this case, the working directory the build system uses
4729 to keep the unpacked recipe for <filename>db</filename>
4730 is the following:
4731 <literallayout class='monospaced'>
4732 ~/poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
4733 </literallayout>
4734 </para>
4735 </glossdef>
4736 </glossentry>
4737
4738 <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
4739 <glossdef>
4740 <para>
4741 A list of the host distribution identifiers that the
4742 build system has been tested against.
4743 Identifiers consist of the host distributor ID
4744 followed by the release,
4745 as reported by the <filename>lsb_release</filename> tool
4746 or as read from <filename>/etc/lsb-release</filename>.
4747 Separate the list items with explicit newline
4748 characters (<filename>\n</filename>).
4749 If <filename>SANITY_TESTED_DISTROS</filename> is not empty
4750 and the current value of
4751 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
4752 does not appear in the list, then the build system reports
4753 a warning that indicates the current host distribution has
4754 not been tested as a build host.
4755 </para>
4756 </glossdef>
4757 </glossentry>
4758
4759 <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
4760 <glossdef>
4761 <para>
4762 The target architecture for the SDK.
4763 Typically, you do not directly set this variable.
4764 Instead, use
4765 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
4766 </para>
4767 </glossdef>
4768 </glossentry>
4769
4770 <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
4771 <glossdef>
4772 <para>
4773 The base name for SDK output files.
4774 The name is derived from the
4775 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
4776 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
4777 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
4778 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
4779 and
4780 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
4781 variables:
4782 <literallayout class='monospaced'>
4783 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
4784 </literallayout>
4785 </para>
4786 </glossdef>
4787 </glossentry>
4788
4789 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
4790 <glossdef>
4791 <para>Equivalent to
4792 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
4793 However, this variable applies to the SDK generated from an
4794 image using the following command:
4795 <literallayout class='monospaced'>
4796 $ bitbake -c populate_sdk imagename
4797 </literallayout>
4798 </para>
4799 </glossdef>
4800 </glossentry>
4801
4802 <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
4803 <glossdef>
4804 <para>
4805 The architecture of the machine that runs Application
4806 Development Toolkit (ADT) items.
4807 In other words, packages are built so that they will run
4808 on the target you specify with the argument.
4809 This implies that you can build out ADT/SDK items that
4810 run on an architecture other than that of your build host.
4811 For example, you can use an x86_64-based build host to
4812 create packages that will run on an i686-based
4813 SDK Machine.
4814 </para>
4815
4816 <para>
4817 You can use "i686" and "x86_64" as possible values for this
4818 variable.
4819 The variable defaults to "i686" and is set in the
4820 <filename>local.conf</filename> file in the
4821 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
4822 <literallayout class='monospaced'>
4823 SDKMACHINE ?= "i686"
4824 </literallayout>
4825 </para>
4826 </glossdef>
4827 </glossentry>
4828
4829 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
4830 <glossdef>
4831 <para>The section in which packages should be categorized.
4832 Package management utilities can make use of this variable.</para>
4833 </glossdef>
4834 </glossentry>
4835
4836 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
4837 <glossdef>
4838 <para>
4839 The variable takes the value of
4840 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
4841 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
4842 In this case the value of
4843 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
4844 </para>
4845 </glossdef>
4846 </glossentry>
4847
4848 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
4849 <glossdef>
4850 <para>
4851 Defines a serial console (TTY) to enable using getty.
4852 Provide a value that specifies the baud rate followed by
4853 the TTY device name separated by a space.
4854 You cannot specify more than one TTY device:
4855 <literallayout class='monospaced'>
4856 SERIAL_CONSOLE = "115200 ttyS0"
4857 </literallayout>
4858 <note>
4859 The <filename>SERIAL_CONSOLE</filename> variable
4860 is deprecated.
4861 Please use the
4862 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
4863 variable.
4864 </note>
4865 </para>
4866 </glossdef>
4867 </glossentry>
4868
4869 <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
4870 <glossdef>
4871 <para>
4872 Defines the serial consoles (TTYs) to enable using getty.
4873 Provide a value that specifies the baud rate followed by
4874 the TTY device name separated by a semicolon.
4875 Use spaces to separate multiple devices:
4876 <literallayout class='monospaced'>
4877 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
4878 </literallayout>
4879 </para>
4880 </glossdef>
4881 </glossentry>
4882
4883 <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
4884 <glossdef>
4885 <para>
4886 Similar to
4887 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
4888 except the device is checked for existence before attempting
4889 to enable it.
4890 This variable is currently only supported with SysVinit
4891 (i.e. not with systemd).
4892 </para>
4893 </glossdef>
4894 </glossentry>
4895
4896 <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
4897 <glossdef>
4898 <para>
4899 A list of recipe dependencies that should not be used to
4900 determine signatures of tasks from one recipe when they
4901 depend on tasks from another recipe.
4902 For example:
4903 <literallayout class='monospaced'>
4904 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
4905 </literallayout>
4906 In this example, <filename>intone</filename> depends on
4907 <filename>mplayer2</filename>.
4908 </para>
4909
4910 <para>
4911 Use of this variable is one mechanism to remove dependencies
4912 that affect task signatures and thus force rebuilds when a
4913 recipe changes.
4914 <caution>
4915 If you add an inappropriate dependency for a recipe
4916 relationship, the software might break during
4917 runtime if the interface of the second recipe was
4918 changed after the first recipe had been built.
4919 </caution>
4920 </para>
4921 </glossdef>
4922 </glossentry>
4923
4924 <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
4925 <glossdef>
4926 <para>
4927 A list of recipes that are completely stable and will
4928 never change.
4929 The ABI for the recipes in the list are presented by
4930 output from the tasks run to build the recipe.
4931 Use of this variable is one way to remove dependencies from
4932 one recipe on another that affect task signatures and
4933 thus force rebuilds when the recipe changes.
4934 <caution>
4935 If you add an inappropriate variable to this list,
4936 the software might break at runtime if the
4937 interface of the recipe was changed after the other
4938 had been built.
4939 </caution>
4940 </para>
4941 </glossdef>
4942 </glossentry>
4943
4944 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
4945 <glossdef>
4946 <para>
4947 Specifies the number of bits for the target system CPU.
4948 The value should be either "32" or "64".
4949 </para>
4950 </glossdef>
4951 </glossentry>
4952
4953 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
4954 <glossdef>
4955 <para>
4956 Specifies the endian byte order of the target system.
4957 The value should be either "le" for little-endian or "be" for big-endian.
4958 </para>
4959 </glossdef>
4960 </glossentry>
4961
4962 <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
4963 <glossdef>
4964 <para>
4965 Groups together machines based upon the same family
4966 of SOC (System On Chip).
4967 You typically set this variable in a common
4968 <filename>.inc</filename> file that you include in the
4969 configuration files of all the machines.
4970 <note>
4971 You must include
4972 <filename>conf/machine/include/soc-family.inc</filename>
4973 for this variable to appear in
4974 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
4975 </note>
4976 </para>
4977 </glossdef>
4978 </glossentry>
4979
4980 <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
4981 <glossdef>
4982 <para>
4983 Defines the suffix for shared libraries used on the
4984 target platform.
4985 By default, this suffix is ".so.*" for all Linux-based
4986 systems and is defined in the
4987 <filename>meta/conf/bitbake.conf</filename> configuration
4988 file.
4989 </para>
4990
4991 <para>
4992 You will see this variable referenced in the default values
4993 of <filename>FILES_${PN}</filename>.
4994 </para>
4995 </glossdef>
4996 </glossentry>
4997
4998 <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
4999 <glossdef>
5000 <para>
5001 Defines the suffix for the development symbolic link
5002 (symlink) for shared libraries on the target platform.
5003 By default, this suffix is ".so" for Linux-based
5004 systems and is defined in the
5005 <filename>meta/conf/bitbake.conf</filename> configuration
5006 file.
5007 </para>
5008
5009 <para>
5010 You will see this variable referenced in the default values
5011 of <filename>FILES_${PN}-dev</filename>.
5012 </para>
5013 </glossdef>
5014 </glossentry>
5015
5016 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
5017 <glossdef>
5018 <para>
5019 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
5020 OpenEmbedded build system to create variants of recipes or packages.
5021 The list specifies the prefixes to strip off during certain circumstances
5022 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
5023 </para>
5024 </glossdef>
5025 </glossentry>
5026
5027 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
5028 <glossdef>
5029 <para>The list of source files - local or remote.
5030 This variable tells the OpenEmbedded build system which bits
5031 to pull in for the build and how to pull them in.
5032 For example, if the recipe or append file only needs to
5033 fetch a tarball from the Internet, the recipe or
5034 append file uses a single <filename>SRC_URI</filename>
5035 entry.
5036 On the other hand, if the recipe or append file needs to
5037 fetch a tarball, apply two patches, and include a custom
5038 file, the recipe or append file would include four
5039 instances of the variable.</para>
5040 <para>The following list explains the available URI protocols:
5041 <itemizedlist>
5042 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
5043 Fetches files, which are usually files shipped with
5044 the
5045 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
5046 from the local machine.
5047 The path is relative to the
5048 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
5049 variable.
5050 Thus, the build system searches, in order, from the
5051 following directories, which are assumed to be a
5052 subdirectories of the directory in which the
5053 recipe file (<filename>.bb</filename>) or
5054 append file (<filename>.bbappend</filename>)
5055 resides:
5056 <itemizedlist>
5057 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
5058 The base recipe name without any special
5059 suffix or version numbers.
5060 </para></listitem>
5061 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
5062 <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
5063 The base recipe name and version but without
5064 any special package name suffix.
5065 </para></listitem>
5066 <listitem><para><emphasis>files -</emphasis>
5067 Files within a directory, which is named
5068 <filename>files</filename> and is also
5069 alongside the recipe or append file.
5070 </para></listitem>
5071 </itemizedlist>
5072 <note>
5073 If you want the build system to pick up files
5074 specified through a
5075 <filename>SRC_URI</filename>
5076 statement from your append file, you need to be
5077 sure to extend the
5078 <filename>FILESPATH</filename>
5079 variable by also using the
5080 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
5081 variable from within your append file.
5082 </note>
5083 </para></listitem>
5084 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
5085 Bazaar revision control repository.</para></listitem>
5086 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
5087 Git revision control repository.</para></listitem>
5088 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
5089 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
5090 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
5091 a repo (Git) repository.</para></listitem>
5092 <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from
5093 an SVK revision control repository.</para></listitem>
5094 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
5095 the Internet using <filename>http</filename>.</para></listitem>
5096 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
5097 from the Internet using <filename>https</filename>.</para></listitem>
5098 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
5099 from the Internet using <filename>ftp</filename>.</para></listitem>
5100 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
5101 a CVS revision control repository.</para></listitem>
5102 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
5103 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
5104 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
5105 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
5106 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
5107 a secure shell.</para></listitem>
5108 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
5109 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
5110 </itemizedlist>
5111 </para>
5112 <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
5113 Here are standard options:
5114 <itemizedlist>
5115 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
5116 the patch or not.
5117 The default action is to apply the patch.</para></listitem>
5118 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
5119 striplevel to use when applying the patch.
5120 The default level is 1.</para></listitem>
5121 <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
5122 the directory in which the patch should be applied.
5123 The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
5124 </para></listitem>
5125 </itemizedlist>
5126 </para>
5127 <para>Here are options specific to recipes building code from a revision control system:
5128 <itemizedlist>
5129 <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
5130 Apply the patch only if
5131 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
5132 is equal to or greater than <filename>mindate</filename>.
5133 </para></listitem>
5134 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
5135 Apply the patch only if <filename>SRCDATE</filename>
5136 is not later than <filename>mindate</filename>.
5137 </para></listitem>
5138 <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
5139 Apply the patch only if <filename>SRCREV</filename>
5140 is equal to or greater than <filename>minrev</filename>.
5141 </para></listitem>
5142 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
5143 Apply the patch only if <filename>SRCREV</filename>
5144 is not later than <filename>maxrev</filename>.
5145 </para></listitem>
5146 <listitem><para><emphasis><filename>rev</filename> -</emphasis>
5147 Apply the patch only if <filename>SRCREV</filename>
5148 is equal to <filename>rev</filename>.
5149 </para></listitem>
5150 <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
5151 Apply the patch only if <filename>SRCREV</filename>
5152 is not equal to <filename>rev</filename>.
5153 </para></listitem>
5154 </itemizedlist>
5155 </para>
5156 <para>Here are some additional options worth mentioning:
5157 <itemizedlist>
5158 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
5159 whether or not to unpack the file if it is an archive.
5160 The default action is to unpack the file.</para></listitem>
5161 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
5162 (or extracts its contents) into the specified
5163 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
5164 This option is useful for unusual tarballs or other archives that
5165 do not have their files already in a subdirectory within the archive.
5166 </para></listitem>
5167 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
5168 name to be used for association with <filename>SRC_URI</filename> checksums
5169 when you have more than one file specified in <filename>SRC_URI</filename>.
5170 </para></listitem>
5171 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
5172 the filename used when storing the downloaded file.</para></listitem>
5173 </itemizedlist>
5174 </para>
5175 </glossdef>
5176 </glossentry>
5177
5178 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
5179 <glossdef>
5180 <para></para>
5181 <para>
5182 By default, the OpenEmbedded build system automatically detects whether
5183 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
5184 contains files that are machine-specific.
5185 If so, the build system automatically changes
5186 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
5187 Setting this variable to "0" disables this behavior.
5188 </para>
5189 </glossdef>
5190 </glossentry>
5191
5192 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
5193 <glossdef>
5194 <para>
5195 The date of the source code used to build the package.
5196 This variable applies only if the source was fetched from a Source Code Manager (SCM).
5197 </para>
5198 </glossdef>
5199 </glossentry>
5200
5201 <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
5202 <glossdef>
5203 <para>
5204 Returns the version string of the current package.
5205 This string is used to help define the value of
5206 <link linkend='var-PV'><filename>PV</filename></link>.
5207 </para>
5208
5209 <para>
5210 The <filename>SRCPV</filename> variable is defined in the
5211 <filename>meta/conf/bitbake.conf</filename> configuration
5212 file in the
5213 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
5214 as follows:
5215 <literallayout class='monospaced'>
5216 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
5217 </literallayout>
5218 </para>
5219
5220 <para>
5221 Recipes that need to define <filename>PV</filename> do so
5222 with the help of the <filename>SRCPV</filename>.
5223 For example, the <filename>ofono</filename> recipe
5224 (<filename>ofono_git.bb</filename>) located in
5225 <filename>meta/recipes-connectivity</filename> in the
5226 Source Directory defines <filename>PV</filename> as
5227 follows:
5228 <literallayout class='monospaced'>
5229 PV = "1.5.0+git${SRCPV}"
5230 </literallayout>
5231 </para>
5232 </glossdef>
5233 </glossentry>
5234
5235 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
5236 <glossdef>
5237 <para>
5238 The revision of the source code used to build the package.
5239 This variable applies to Subversion, Git, Mercurial and Bazaar
5240 only.
5241 Note that if you wish to build a fixed revision and you wish
5242 to avoid performing a query on the remote repository every time
5243 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
5244 full revision identifier and not just a tag.
5245 </para>
5246 </glossdef>
5247 </glossentry>
5248
5249 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
5250 <glossdef>
5251 <para>The directory for the shared state cache.</para>
5252 </glossdef>
5253 </glossentry>
5254
5255 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
5256 <glossdef>
5257 <para>
5258 Configures the OpenEmbedded build system to search other
5259 mirror locations for prebuilt cache data objects before
5260 building out the data.
5261 This variable works like fetcher
5262 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
5263 and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
5264 and points to the cache locations to check for the shared
5265 objects.
5266 </para>
5267
5268 <para>
5269 You can specify a filesystem directory or a remote URL such
5270 as HTTP or FTP.
5271 The locations you specify need to contain the shared state
5272 cache (sstate-cache) results from previous builds.
5273 The sstate-cache you point to can also be from builds on
5274 other machines.
5275 </para>
5276
5277 <para>
5278 If a mirror uses the same structure as
5279 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
5280 you need to add
5281 "PATH" at the end as shown in the examples below.
5282 The build system substitutes the correct path within the
5283 directory structure.
5284 <literallayout class='monospaced'>
5285 SSTATE_MIRRORS ?= "\
5286 file://.* http://someserver.tld/share/sstate/PATH \n \
5287 file://.* file:///some/local/dir/sstate/PATH"
5288 </literallayout>
5289 </para>
5290 </glossdef>
5291 </glossentry>
5292
5293 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
5294 <glossdef>
5295 <para>
5296 The directory with kernel headers that are required to build out-of-tree
5297 modules.
5298 </para>
5299 </glossdef>
5300 </glossentry>
5301
5302 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
5303 <glossdef>
5304 <para>
5305 Specifies the base path used to create recipe stamp files.
5306 The path to an actual stamp file is constructed by evaluating this
5307 string and then appending additional information.
5308 Currently, the default assignment for <filename>STAMP</filename>
5309 as set in the <filename>meta/conf/bitbake.conf</filename> file
5310 is:
5311 <literallayout class='monospaced'>
5312 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
5313 </literallayout>
5314 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
5315 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
5316 <link linkend='var-PN'><filename>PN</filename></link>,
5317 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
5318 <link linkend='var-PV'><filename>PV</filename></link>, and
5319 <link linkend='var-PR'><filename>PR</filename></link> for related variable
5320 information.
5321 </para>
5322 </glossdef>
5323 </glossentry>
5324
5325 <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
5326 <glossdef>
5327 <para>
5328 Specifies the base directory in which the OpenEmbedded
5329 build system places stamps.
5330 The default directory is
5331 <filename>${TMPDIR}/stamps</filename>.
5332 </para>
5333 </glossdef>
5334 </glossentry>
5335
5336 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
5337 <glossdef>
5338 <para>The short (72 characters or less) summary of the binary package for packaging
5339 systems such as <filename>opkg</filename>, <filename>rpm</filename> or
5340 <filename>dpkg</filename>.
5341 By default, <filename>SUMMARY</filename> is used to define
5342 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
5343 variable if <filename>DESCRIPTION</filename> is not set
5344 in the recipe.
5345 </para>
5346 </glossdef>
5347 </glossentry>
5348
5349 <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
5350 <glossdef>
5351 <para>
5352 A list of functions to execute after files are staged into
5353 the sysroot.
5354 These functions are usually used to apply additional
5355 processing on the staged files, or to stage additional
5356 files.
5357 </para>
5358 </glossdef>
5359 </glossentry>
5360
5361 </glossdiv>
5362
5363 <glossdiv id='var-glossary-t'><title>T</title>
5364
5365 <glossentry id='var-T'><glossterm>T</glossterm>
5366 <glossdef>
5367 <para>This variable points to a directory were BitBake places
5368 temporary files, which consist mostly of task logs and
5369 scripts, when building a particular recipe.
5370 The variable is typically set as follows:
5371 <literallayout class='monospaced'>
5372 T = "${WORKDIR}/temp"
5373 </literallayout>
5374 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
5375 is the directory into which BitBake unpacks and builds the
5376 recipe.
5377 The default <filename>bitbake.conf</filename> file sets this variable.</para>
5378 <para>The <filename>T</filename> variable is not to be confused with
5379 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
5380 which points to the root of the directory tree where BitBake
5381 places the output of an entire build.
5382 </para>
5383 </glossdef>
5384 </glossentry>
5385
5386 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
5387 <glossdef>
5388 <para>
5389 The target machine's architecture.
5390 The OpenEmbedded build system supports many
5391 architectures.
5392 Here is an example list of architectures supported.
5393 This list is by no means complete as the architecture
5394 is configurable:
5395 <literallayout class='monospaced'>
5396 arm
5397 i586
5398 x86_64
5399 powerpc
5400 powerpc64
5401 mips
5402 mipsel
5403 </literallayout>
5404 </para>
5405 </glossdef>
5406 </glossentry>
5407
5408 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
5409 <glossdef>
5410 <para>
5411 Flags passed to the C compiler for the target system.
5412 This variable evaluates to the same as
5413 <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>.
5414 </para>
5415 </glossdef>
5416 </glossentry>
5417
5418
5419 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
5420 <glossdef>
5421 <para>Specifies the method for handling FPU code.
5422 For FPU-less targets, which include most ARM CPUs, the variable must be
5423 set to "soft".
5424 If not, the kernel emulation gets used, which results in a performance penalty.</para>
5425 </glossdef>
5426 </glossentry>
5427
5428 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
5429 <glossdef>
5430 <para>Specifies the target's operating system.
5431 The variable can be set to "linux" for <filename>eglibc</filename>-based systems and
5432 to "linux-uclibc" for <filename>uclibc</filename>.
5433 For ARM/EABI targets, there are also "linux-gnueabi" and
5434 "linux-uclibc-gnueabi" values possible.</para>
5435 </glossdef>
5436 </glossentry>
5437
5438 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
5439 <glossdef>
5440 <para>
5441 Specifies which variant of the GNU standard C library (<filename>libc</filename>)
5442 to use during the build process.
5443 This variable replaces <filename>POKYLIBC</filename>, which is no longer
5444 supported.
5445 </para>
5446 <para>
5447 You can select <filename>eglibc</filename> or <filename>uclibc</filename>.
5448 <note>
5449 This release of the Yocto Project does not support the
5450 <filename>glibc</filename> implementation of <filename>libc</filename>.
5451 </note>
5452 </para>
5453 </glossdef>
5454 </glossentry>
5455
5456 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
5457 <glossdef>
5458 <para>
5459 The toolchain selector.
5460 This variable replaces <filename>POKYMODE</filename>, which is no longer
5461 supported.
5462 </para>
5463 <para>
5464 The <filename>TCMODE</filename> variable selects the external toolchain
5465 built using the OpenEmbedded build system or a few supported combinations of
5466 the upstream GCC or CodeSourcery Labs toolchain.
5467 The variable identifies the <filename>tcmode-*</filename> files used in
5468 the <filename>meta/conf/distro/include</filename> directory, which is found in the
5469 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
5470 </para>
5471 <para>
5472 By default, <filename>TCMODE</filename> is set to "default", which
5473 chooses the <filename>tcmode-default.inc</filename> file.
5474 The variable is similar to
5475 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, which controls
5476 the variant of the GNU standard C library (<filename>libc</filename>)
5477 used during the build process: <filename>eglibc</filename> or <filename>uclibc</filename>.
5478 </para>
5479 </glossdef>
5480 </glossentry>
5481
5482 <glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm>
5483 <glossdef>
5484 <para>
5485 Automatically runs the series of automated tests for
5486 images when an image is successfully built.
5487 <note>
5488 Currently, there is only support for running these tests
5489 under QEMU.
5490 </note>
5491 These tests are written in Python making use of the
5492 <filename>unittest</filename> module, and the majority of
5493 them run commands on the target system over
5494 <filename>ssh</filename>.
5495 You can set this variable to "1" in your
5496 <filename>local.conf</filename> file in the
5497 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
5498 to have the OpenEmbedded build system automatically run
5499 these tests after an image successfully builds:
5500 <literallayout class='monospaced'>
5501 TEST_IMAGE = "1"
5502 </literallayout>
5503 For more information on enabling, running, and writing
5504 these tests, see the
5505 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
5506 section in the Yocto Project Development Manual and the
5507 "<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>"
5508 section.
5509 </para>
5510 </glossdef>
5511 </glossentry>
5512
5513 <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
5514 <glossdef>
5515 <para>
5516 The time in seconds allowed for an image to boot before
5517 automated runtime tests begin to run against an
5518 image.
5519 The default timeout period to allow the boot process to
5520 reach the login prompt is 500 seconds.
5521 You can specify a different value in the
5522 <filename>local.conf</filename> file.
5523 </para>
5524
5525 <para>
5526 For more information on testing images, see the
5527 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
5528 section in the Yocto Project Development Manual.
5529 </para>
5530 </glossdef>
5531 </glossentry>
5532
5533 <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
5534 <glossdef>
5535 <para>
5536 An ordered list of tests (modules) to run against
5537 an image when performing automated runtime testing.
5538 </para>
5539
5540 <para>
5541 The OpenEmbedded build system provides a core set of tests
5542 that can be used against images.
5543 <note>
5544 Currently, there is only support for running these tests
5545 under QEMU.
5546 </note>
5547 Tests include <filename>ping</filename>,
5548 <filename>ssh</filename>, <filename>df</filename> among
5549 others.
5550 You can add your own tests to the list of tests by
5551 appending <filename>TEST_SUITES</filename> as follows:
5552 <literallayout class='monospaced'>
5553 TEST_SUITES_append = " mytest"
5554 </literallayout>
5555 Alternatively, you can provide the "auto" option to
5556 have all applicable tests run against the image.
5557 <literallayout class='monospaced'>
5558 TEST_SUITES_append = " auto"
5559 </literallayout>
5560 Using this option causes the build system to automatically
5561 run tests that are applicable to the image.
5562 Tests that are not applicable are skipped.
5563 </para>
5564
5565 <para>
5566 The order in which tests are run is important.
5567 Tests that depend on another test must appear later in the
5568 list than the test on which they depend.
5569 For example, if you append the list of tests with two
5570 tests (<filename>test_A</filename> and
5571 <filename>test_B</filename>) where
5572 <filename>test_B</filename> is dependent on
5573 <filename>test_A</filename>, then you must order the tests
5574 as follows:
5575 <literallayout class='monospaced'>
5576 TEST_SUITES = " test_A test_B"
5577 </literallayout>
5578 </para>
5579
5580 <para>
5581 For more information on testing images, see the
5582 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
5583 section in the Yocto Project Development Manual.
5584 </para>
5585 </glossdef>
5586 </glossentry>
5587
5588 <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
5589 <glossdef>
5590 <para>
5591 The directory in which the file BitBake is currently
5592 parsing is located.
5593 Do not manually set this variable.
5594 </para>
5595 </glossdef>
5596 </glossentry>
5597
5598 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
5599 <glossdef>
5600 <para>
5601 This variable is the base directory the OpenEmbedded
5602 build system uses for all build output and intermediate
5603 files (other than the shared state cache).
5604 By default, the <filename>TMPDIR</filename> variable points
5605 to <filename>tmp</filename> within the
5606 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
5607 </para>
5608
5609 <para>
5610 If you want to establish this directory in a location other
5611 than the default, you can uncomment and edit the following
5612 statement in the
5613 <filename>conf/local.conf</filename> file in the
5614 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
5615 <literallayout class='monospaced'>
5616 #TMPDIR = "${TOPDIR}/tmp"
5617 </literallayout>
5618 </para>
5619 </glossdef>
5620 </glossentry>
5621
5622 <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
5623 <glossdef>
5624 <para>
5625 This variable lists packages the OpenEmbedded build system
5626 uses when building an SDK, which contains a
5627 cross-development environment.
5628 The packages specified by this variable are part of the
5629 toolchain set that runs on the
5630 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
5631 and each package should usually have the prefix
5632 "nativesdk-".
5633 When building an SDK using
5634 <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>,
5635 a default list of packages is set in this variable, but
5636 you can add additional packages to the list.
5637 </para>
5638
5639 <para>
5640 For background information on cross-development toolchains
5641 in the Yocto Project development environment, see the
5642 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
5643 section.
5644 For information on setting up a cross-development
5645 environment, see the
5646 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
5647 section in the Yocto Project Application Developer's Guide.
5648 </para>
5649 </glossdef>
5650 </glossentry>
5651
5652 <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
5653 <glossdef>
5654 <para>
5655 This variable lists packages the OpenEmbedded build system
5656 uses when it creates the target part of an SDK
5657 (i.e. the part built for the target hardware), which
5658 includes libraries and headers.
5659 </para>
5660
5661 <para>
5662 For background information on cross-development toolchains
5663 in the Yocto Project development environment, see the
5664 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
5665 section.
5666 For information on setting up a cross-development
5667 environment, see the
5668 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
5669 section in the Yocto Project Application Developer's Guide.
5670 </para>
5671 </glossdef>
5672 </glossentry>
5673
5674 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
5675 <glossdef>
5676 <para>
5677 This variable points to the
5678 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
5679 BitBake automatically sets this variable.
5680 </para>
5681 </glossdef>
5682 </glossentry>
5683
5684 <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
5685 <glossdef>
5686 <para>
5687 A sanitized version of
5688 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
5689 This variable is used where the architecture is needed in
5690 a value where underscores are not allowed, for example
5691 within package filenames.
5692 In this case, dash characters replace any underscore
5693 characters used in TARGET_ARCH.
5694 </para>
5695
5696 <para>
5697 Do not edit this variable.
5698 </para>
5699 </glossdef>
5700 </glossentry>
5701
5702 <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
5703 <glossdef>
5704 <para>
5705 The package architecture understood by the packaging
5706 system to define the architecture, ABI, and tuning of
5707 output packages.
5708 </para>
5709 </glossdef>
5710 </glossentry>
5711
5712 </glossdiv>
5713
5714 <glossdiv id='var-glossary-u'><title>U</title>
5715
5716 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
5717 <glossdef>
5718 <para>
5719 Specifies the entry point for the U-Boot image.
5720 During U-Boot image creation, the
5721 <filename>UBOOT_ENTRYPOINT</filename> variable is passed
5722 as a command-line parameter to the
5723 <filename>uboot-mkimage</filename> utility.
5724 </para>
5725 </glossdef>
5726 </glossentry>
5727
5728 <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
5729 <glossdef>
5730 <para>
5731 Specifies the load address for the U-Boot image.
5732 During U-Boot image creation, the
5733 <filename>UBOOT_LOADADDRESS</filename> variable is passed
5734 as a command-line parameter to the
5735 <filename>uboot-mkimage</filename> utility.
5736 </para>
5737 </glossdef>
5738 </glossentry>
5739
5740 <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
5741 <glossdef>
5742 <para>
5743 Specifies the value passed on the
5744 <filename>make</filename> command line when building
5745 a U-Boot image.
5746 The value indicates the target platform configuration.
5747 You typically set this variable from the machine
5748 configuration file (i.e.
5749 <filename>conf/machine/&lt;machine_name&gt;.conf</filename>).
5750 </para>
5751 </glossdef>
5752 </glossentry>
5753
5754 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
5755 <glossdef>
5756 <para>
5757 Specifies the target used for building U-Boot.
5758 The target is passed directly as part of the "make" command
5759 (e.g. SPL and AIS).
5760 If you do not specifically set this variable, the
5761 OpenEmbedded build process passes and uses "all" for the
5762 target during the U-Boot building process.
5763 </para>
5764 </glossdef>
5765 </glossentry>
5766
5767 <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
5768 <glossdef>
5769 <para>
5770 A list of classes to globally inherit.
5771 These classes are used by the OpenEmbedded build system
5772 to enable extra features (e.g.
5773 <filename>buildstats</filename>,
5774 <filename>image-mklibs</filename>, and so forth).
5775 </para>
5776
5777 <para>
5778 The default list is set in your
5779 <filename>local.conf</filename> file:
5780 <literallayout class='monospaced'>
5781 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
5782 </literallayout>
5783 For more information, see
5784 <filename>meta-yocto/conf/local.conf.sample</filename> in
5785 the
5786 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
5787 </para>
5788 </glossdef>
5789 </glossentry>
5790
5791 </glossdiv>
5792
5793<!-- <glossdiv id='var-glossary-v'><title>V</title>-->
5794<!-- </glossdiv>-->
5795
5796 <glossdiv id='var-glossary-w'><title>W</title>
5797
5798 <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
5799 <glossdef>
5800 <para>
5801 Specifies the quality assurance checks whose failures are
5802 reported as warnings by the OpenEmbedded build system.
5803 You set this variable in your distribution configuration
5804 file.
5805 For a list of the checks you can control with this variable,
5806 see the
5807 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
5808 section.
5809 </para>
5810 </glossdef>
5811 </glossentry>
5812
5813 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
5814 <glossdef>
5815 <para>
5816 The pathname of the working directory in which the OpenEmbedded build system
5817 builds a recipe.
5818 This directory is located within the
5819 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes
5820 as different packages are built.
5821 </para>
5822
5823 <para>
5824 The actual <filename>WORKDIR</filename> directory depends on several things:
5825 <itemizedlist>
5826 <listitem>The temporary directory - <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link></listitem>
5827 <listitem>The package architecture - <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link></listitem>
5828 <listitem>The target machine - <link linkend='var-MACHINE'><filename>MACHINE</filename></link></listitem>
5829 <listitem>The target operating system - <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link></listitem>
5830 <listitem>The recipe name - <link linkend='var-PN'><filename>PN</filename></link></listitem>
5831 <listitem>The recipe version - <link linkend='var-PV'><filename>PV</filename></link></listitem>
5832 <listitem>The recipe revision - <link linkend='var-PR'><filename>PR</filename></link></listitem>
5833 </itemizedlist>
5834 </para>
5835
5836 <para>
5837 For packages that are not dependent on a particular machine,
5838 <filename>WORKDIR</filename> is defined as follows:
5839 <literallayout class='monospaced'>
5840 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
5841 </literallayout>
5842 As an example, assume a
5843 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level
5844 folder name <filename>poky</filename> and a default
5845 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
5846 at <filename>poky/build</filename>.
5847 In this case, the working directory the build system uses to build
5848 the <filename>v86d</filename> package is the following:
5849 <literallayout class='monospaced'>
5850 ~/poky/build/tmp/work/qemux86-poky-linux/v86d/01.9-r0
5851 </literallayout>
5852 </para>
5853
5854 <para>
5855 For packages that are dependent on a particular machine, <filename>WORKDIR</filename>
5856 is defined slightly different:
5857 <literallayout class='monospaced'>
5858 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
5859 </literallayout>
5860 As an example, again assume a Source Directory top-level folder
5861 named <filename>poky</filename> and a default Build Directory
5862 at <filename>poky/build</filename>.
5863 In this case, the working directory the build system uses to build
5864 the <filename>acl</filename> recipe, which is being built for a
5865 MIPS-based device, is the following:
5866 <literallayout class='monospaced'>
5867 ~/poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2
5868 </literallayout>
5869 </para>
5870 </glossdef>
5871 </glossentry>
5872
5873 </glossdiv>
5874
5875<!-- <glossdiv id='var-glossary-x'><title>X</title>-->
5876<!-- </glossdiv>-->
5877
5878<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
5879<!-- </glossdiv>-->
5880
5881<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
5882<!-- </glossdiv>-->
5883
5884</glossary>
5885</chapter>
5886<!--
5887vim: expandtab tw=80 ts=4
5888-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-24 23:25:30 +0000