summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-variables.xml
diff options
context:
space:
mode:
authorTudor Florea <tudor.florea@enea.com>2014-10-16 03:05:19 +0200
committerTudor Florea <tudor.florea@enea.com>2014-10-16 03:05:19 +0200
commitc527fd1f14c27855a37f2e8ac5346ce8d940ced2 (patch)
treebb002c1fdf011c41dbd2f0927bed23ecb5f83c97 /documentation/ref-manual/ref-variables.xml
downloadpoky-daisy-140929.tar.gz
initial commit for Enea Linux 4.0-140929daisy-140929
Migrated from the internal git server on the daisy-enea-point-release branch Signed-off-by: Tudor Florea <tudor.florea@enea.com>
Diffstat (limited to 'documentation/ref-manual/ref-variables.xml')
-rw-r--r--documentation/ref-manual/ref-variables.xml8419
1 files changed, 8419 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
new file mode 100644
index 0000000000..4ff1a21323
--- /dev/null
+++ b/documentation/ref-manual/ref-variables.xml
@@ -0,0 +1,8419 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<!-- Dummy chapter -->
6<chapter id='ref-variables-glos'>
7
8<title>Variables Glossary</title>
9
10<para>
11 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
12 of their function and contents.
13</para>
14
15<glossary id='ref-variables-glossary'>
16
17
18 <para>
19 <link linkend='var-ALLOW_EMPTY'>A</link>
20 <link linkend='var-B'>B</link>
21 <link linkend='var-CFLAGS'>C</link>
22 <link linkend='var-D'>D</link>
23 <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link>
24 <link linkend='var-FEATURE_PACKAGES'>F</link>
25 <link linkend='var-GROUPADD_PARAM'>G</link>
26 <link linkend='var-HOMEPAGE'>H</link>
27 <link linkend='var-ICECC_DISABLED'>I</link>
28<!-- <link linkend='var-glossary-j'>J</link> -->
29 <link linkend='var-KARCH'>K</link>
30 <link linkend='var-LABELS'>L</link>
31 <link linkend='var-MACHINE'>M</link>
32<!-- <link linkend='var-glossary-n'>N</link> -->
33 <link linkend='var-OE_BINCONFIG_EXTRA_MANGLE'>O</link>
34 <link linkend='var-P'>P</link>
35 <link linkend='var-QMAKE_PROFILES'>Q</link>
36 <link linkend='var-RCONFLICTS'>R</link>
37 <link linkend='var-S'>S</link>
38 <link linkend='var-T'>T</link>
39 <link linkend='var-UBOOT_CONFIG'>U</link>
40<!-- <link linkend='var-glossary-v'>V</link> -->
41 <link linkend='var-WARN_QA'>W</link>
42<!-- <link linkend='var-glossary-x'>X</link> -->
43<!-- <link linkend='var-glossary-y'>Y</link> -->
44<!-- <link linkend='var-glossary-z'>Z</link>-->
45 </para>
46
47 <glossdiv id='var-glossary-a'><title>A</title>
48
49 <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
50 <glossdef>
51 <para>
52 Specifies if an output package should still be produced if it is empty.
53 By default, BitBake does not produce empty packages.
54 This default behavior can cause issues when there is an
55 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
56 some other hard runtime requirement on the existence of the package.
57 </para>
58
59 <para>
60 Like all package-controlling variables, you must always use them in
61 conjunction with a package name override, as in:
62 <literallayout class='monospaced'>
63 ALLOW_EMPTY_${PN} = "1"
64 ALLOW_EMPTY_${PN}-dev = "1"
65 ALLOW_EMPTY_${PN}-staticdev = "1"
66 </literallayout>
67 </para>
68 </glossdef>
69 </glossentry>
70
71 <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
72 <glossdef>
73 <para>
74 Lists commands in a package that need an alternative
75 binary naming scheme.
76 Sometimes the same command is provided in multiple packages.
77 When this occurs, the OpenEmbedded build system needs to
78 use the alternatives system to create a different binary
79 naming scheme so the commands can co-exist.
80 </para>
81
82 <para>
83 To use the variable, list out the package's commands
84 that also exist as part of another package.
85 For example, if the <filename>busybox</filename> package
86 has four commands that also exist as part of another
87 package, you identify them as follows:
88 <literallayout class='monospaced'>
89 ALTERNATIVE_busybox = "sh sed test bracket"
90 </literallayout>
91 For more information on the alternatives system, see the
92 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
93 section.
94 </para>
95 </glossdef>
96 </glossentry>
97
98 <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
99 <glossdef>
100 <para>
101 Used by the alternatives system to map duplicated commands
102 to actual locations.
103 For example, if the <filename>bracket</filename> command
104 provided by the <filename>busybox</filename> package is
105 duplicated through another package, you must use the
106 <filename>ALTERNATIVE_LINK_NAME</filename> variable to
107 specify the actual location:
108 <literallayout class='monospaced'>
109 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
110 </literallayout>
111 In this example, the binary for the
112 <filename>bracket</filename> command (i.e.
113 <filename>[</filename>) from the
114 <filename>busybox</filename> package resides in
115 <filename>/usr/bin/</filename>.
116 <note>
117 If <filename>ALTERNATIVE_LINK_NAME</filename> is not
118 defined, it defaults to
119 <filename>${bindir}/&lt;name&gt;</filename>.
120 </note>
121 </para>
122
123 <para>
124 For more information on the alternatives system, see the
125 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
126 section.
127 </para>
128 </glossdef>
129 </glossentry>
130
131 <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
132 <glossdef>
133 <para>
134 Used by the alternatives system to create default
135 priorities for duplicated commands.
136 You can use the variable to create a single default
137 regardless of the command name or package, a default for
138 specific duplicated commands regardless of the package, or
139 a default for specific commands tied to particular packages.
140 Here are the available syntax forms:
141 <literallayout class='monospaced'>
142 ALTERNATIVE_PRIORITY = "&lt;priority&gt;"
143 ALTERNATIVE_PRIORITY[&lt;name&gt;] = "&lt;priority&gt;"
144 ALTERNATIVE_PRIORITY_&lt;pkg&gt;[&lt;name&gt;] = "&lt;priority&gt;"
145 </literallayout>
146 </para>
147
148 <para>
149 For more information on the alternatives system, see the
150 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
151 section.
152 </para>
153 </glossdef>
154 </glossentry>
155
156 <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
157 <glossdef>
158 <para>
159 Used by the alternatives system to create default link
160 locations for duplicated commands.
161 You can use the variable to create a single default
162 location for all duplicated commands regardless of the
163 command name or package, a default for
164 specific duplicated commands regardless of the package, or
165 a default for specific commands tied to particular packages.
166 Here are the available syntax forms:
167 <literallayout class='monospaced'>
168 ALTERNATIVE_TARGET = "&lt;target&gt;"
169 ALTERNATIVE_TARGET[&lt;name&gt;] = "&lt;target&gt;"
170 ALTERNATIVE_TARGET_&lt;pkg&gt;[&lt;name&gt;] = "&lt;target&gt;"
171 </literallayout>
172 <note>
173 <para>
174 If <filename>ALTERNATIVE_TARGET</filename> is not
175 defined, it inherits the value from the
176 <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
177 variable.
178 </para>
179
180 <para>
181 If <filename>ALTERNATIVE_LINK_NAME</filename> and
182 <filename>ALTERNATIVE_TARGET</filename> are the
183 same, the target for
184 <filename>ALTERNATIVE_TARGET</filename>
185 has "<filename>.{BPN}</filename>" appended to it.
186 </para>
187
188 <para>
189 Finally, if the file referenced has not been
190 renamed, the alternatives system will rename it to
191 avoid the need to rename alternative files in the
192 <filename>do_install</filename> task while
193 retaining support for the command if necessary.
194 </para>
195 </note>
196 </para>
197
198 <para>
199 For more information on the alternatives system, see the
200 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
201 section.
202 </para>
203 </glossdef>
204 </glossentry>
205
206 <glossentry id='var-APPEND'><glossterm>APPEND</glossterm>
207 <glossdef>
208 <para>
209 An override list of append strings for each
210 <link linkend='var-LABELS'><filename>LABEL</filename></link>.
211 </para>
212
213 <para>
214 See the
215 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
216 class for more information on how this variable is used.
217 </para>
218 </glossdef>
219 </glossentry>
220
221 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
222 <glossdef>
223 <para>The email address used to contact the original author
224 or authors in order to send patches and forward bugs.</para>
225 </glossdef>
226 </glossentry>
227
228 <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm>AUTO_SYSLINUXMENU</glossterm>
229 <glossdef>
230 <para>
231 Enables creating an automatic menu.
232 You must set this in your recipe.
233 The
234 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
235 class checks this variable.
236 </para>
237 </glossdef>
238 </glossentry>
239
240 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
241 <glossdef>
242 <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
243 is set to the value of this variable, it specifies to use the latest
244 source revision in the repository.
245 Here is an example:
246 <literallayout class='monospaced'>
247 SRCREV = "${AUTOREV}"
248 </literallayout>
249 </para>
250 </glossdef>
251 </glossentry>
252
253 </glossdiv>
254
255 <glossdiv id='var-glossary-b'><title>B</title>
256
257 <glossentry id='var-B'><glossterm>B</glossterm>
258 <glossdef>
259 <para>
260 The directory within the
261 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
262 in which the OpenEmbedded build system places generated
263 objects during a recipe's build process.
264 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
265 directory, which is defined as:
266 <literallayout class='monospaced'>
267 S = "${WORKDIR}/${BP}/"
268 </literallayout>
269 You can separate the (<filename>S</filename>) directory
270 and the directory pointed to by the <filename>B</filename>
271 variable.
272 Most Autotools-based recipes support separating these
273 directories.
274 The build system defaults to using separate directories for
275 <filename>gcc</filename> and some kernel recipes.
276 </para>
277 </glossdef>
278 </glossentry>
279
280 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
281 <glossdef>
282 <para>
283 Lists "recommended-only" packages to not install.
284 Recommended-only packages are packages installed only
285 through the
286 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
287 variable.
288 You can prevent any of these "recommended" packages from
289 being installed by listing them with the
290 <filename>BAD_RECOMMENDATIONS</filename> variable:
291 <literallayout class='monospaced'>
292 BAD_RECOMMENDATIONS = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
293 </literallayout>
294 You can set this variable globally in your
295 <filename>local.conf</filename> file or you can attach it to
296 a specific image recipe by using the recipe name override:
297 <literallayout class='monospaced'>
298 BAD_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
299 </literallayout>
300 </para>
301
302 <para>
303 It is important to realize that if you choose to not install
304 packages using this variable and some other packages are
305 dependent on them (i.e. listed in a recipe's
306 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
307 variable), the OpenEmbedded build system ignores your
308 request and will install the packages to avoid dependency
309 errors.
310 </para>
311
312 <para>
313 Support for this variable exists only when using the
314 IPK and RPM packaging backend.
315 Support does not exist for DEB.
316 </para>
317
318 <para>
319 See the
320 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
321 and the
322 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
323 variables for related information.
324 </para>
325 </glossdef>
326 </glossentry>
327
328 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
329 <glossdef>
330 <para>
331 Defines how BitBake handles situations where an append
332 file (<filename>.bbappend</filename>) has no
333 corresponding recipe file (<filename>.bb</filename>).
334 This condition often occurs when layers get out of sync
335 (e.g. <filename>oe-core</filename> bumps a
336 recipe version and the old recipe no longer exists and the
337 other layer has not been updated to the new version
338 of the recipe yet).
339 </para>
340
341 <para>
342 The default fatal behavior is safest because it is
343 the sane reaction given something is out of sync.
344 It is important to realize when your changes are no longer
345 being applied.
346 </para>
347
348 <para>
349 You can change the default behavior by setting this
350 variable to "1", "yes", or "true"
351 in your <filename>local.conf</filename> file, which is
352 located in the
353 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
354 Here is an example:
355 <literallayout class='monospaced'>
356 BB_DANGLINGAPPENDS_WARNONLY = "1"
357 </literallayout>
358 </para>
359 </glossdef>
360 </glossentry>
361
362 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
363 <glossdef>
364 <para>
365 Monitors disk space and available inodes during the build
366 and allows you to control the build based on these
367 parameters.
368 </para>
369
370 <para>
371 Disk space monitoring is disabled by default.
372 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
373 variable to your <filename>conf/local.conf</filename> file found in the
374 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
375 Use the following form:
376 <literallayout class='monospaced'>
377 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
378
379 where:
380
381 &lt;action&gt; is:
382 ABORT: Immediately abort the build when
383 a threshold is broken.
384 STOPTASKS: Stop the build after the currently
385 executing tasks have finished when
386 a threshold is broken.
387 WARN: Issue a warning but continue the
388 build when a threshold is broken.
389 Subsequent warnings are issued as
390 defined by the
391 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
392 which must be defined in the
393 conf/local.conf file.
394
395 &lt;dir&gt; is:
396 Any directory you choose. You can specify one or
397 more directories to monitor by separating the
398 groupings with a space. If two directories are
399 on the same device, only the first directory
400 is monitored.
401
402 &lt;threshold&gt; is:
403 Either the minimum available disk space,
404 the minimum number of free inodes, or
405 both. You must specify at least one. To
406 omit one or the other, simply omit the value.
407 Specify the threshold using G, M, K for Gbytes,
408 Mbytes, and Kbytes, respectively. If you do
409 not specify G, M, or K, Kbytes is assumed by
410 default. Do not use GB, MB, or KB.
411 </literallayout>
412 </para>
413
414 <para>
415 Here are some examples:
416 <literallayout class='monospaced'>
417 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
418 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
419 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
420 </literallayout>
421 The first example works only if you also provide
422 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
423 in the <filename>conf/local.conf</filename>.
424 This example causes the build system to immediately
425 abort when either the disk space in <filename>${TMPDIR}</filename> drops
426 below 1 Gbyte or the available free inodes drops below
427 100 Kbytes.
428 Because two directories are provided with the variable, the
429 build system also issue a
430 warning when the disk space in the
431 <filename>${SSTATE_DIR}</filename> directory drops
432 below 1 Gbyte or the number of free inodes drops
433 below 100 Kbytes.
434 Subsequent warnings are issued during intervals as
435 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
436 variable.
437 </para>
438
439 <para>
440 The second example stops the build after all currently
441 executing tasks complete when the minimum disk space
442 in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
443 directory drops below 1 Gbyte.
444 No disk monitoring occurs for the free inodes in this case.
445 </para>
446
447 <para>
448 The final example immediately aborts the build when the
449 number of free inodes in the <filename>${TMPDIR}</filename> directory
450 drops below 100 Kbytes.
451 No disk space monitoring for the directory itself occurs
452 in this case.
453 </para>
454 </glossdef>
455 </glossentry>
456
457 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
458 <glossdef>
459 <para>
460 Defines the disk space and free inode warning intervals.
461 To set these intervals, define the variable in your
462 <filename>conf/local.conf</filename> file in the
463 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
464 </para>
465
466 <para>
467 If you are going to use the
468 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
469 also use the
470 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
471 and define its action as "WARN".
472 During the build, subsequent warnings are issued each time
473 disk space or number of free inodes further reduces by
474 the respective interval.
475 </para>
476
477 <para>
478 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
479 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
480 the "WARN" action, the disk monitoring interval defaults to
481 the following:
482 <literallayout class='monospaced'>
483 BB_DISKMON_WARNINTERVAL = "50M,5K"
484 </literallayout>
485 </para>
486
487 <para>
488 When specifying the variable in your configuration file,
489 use the following form:
490 <literallayout class='monospaced'>
491 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
492
493 where:
494
495 &lt;disk_space_interval&gt; is:
496 An interval of memory expressed in either
497 G, M, or K for Gbytes, Mbytes, or Kbytes,
498 respectively. You cannot use GB, MB, or KB.
499
500 &lt;disk_inode_interval&gt; is:
501 An interval of free inodes expressed in either
502 G, M, or K for Gbytes, Mbytes, or Kbytes,
503 respectively. You cannot use GB, MB, or KB.
504 </literallayout>
505 </para>
506
507 <para>
508 Here is an example:
509 <literallayout class='monospaced'>
510 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
511 BB_DISKMON_WARNINTERVAL = "50M,5K"
512 </literallayout>
513 These variables cause the OpenEmbedded build system to
514 issue subsequent warnings each time the available
515 disk space further reduces by 50 Mbytes or the number
516 of free inodes further reduces by 5 Kbytes in the
517 <filename>${SSTATE_DIR}</filename> directory.
518 Subsequent warnings based on the interval occur each time
519 a respective interval is reached beyond the initial warning
520 (i.e. 1 Gbytes and 100 Kbytes).
521 </para>
522 </glossdef>
523 </glossentry>
524
525 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
526 <glossdef>
527 <para>
528 Causes tarballs of the Git repositories, including the
529 Git metadata, to be placed in the
530 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
531 directory.
532 </para>
533
534 <para>
535 For performance reasons, creating and placing tarballs of
536 the Git repositories is not the default action by the
537 OpenEmbedded build system.
538 <literallayout class='monospaced'>
539 BB_GENERATE_MIRROR_TARBALLS = "1"
540 </literallayout>
541 Set this variable in your <filename>local.conf</filename>
542 file in the
543 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
544 </para>
545 </glossdef>
546 </glossentry>
547
548 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
549 <glossdef>
550 <para>
551 The maximum number of tasks BitBake should run in parallel
552 at any one time.
553 If your host development system supports multiple cores,
554 a good rule of thumb is to set this variable to twice the
555 number of cores.
556 </para>
557
558 <para>
559 The default value for <filename>BB_NUMBER_THREADS</filename>
560 is equal to the number of cores your build system has.
561 </para>
562 </glossdef>
563 </glossentry>
564
565 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
566 <glossdef>
567 <para>
568 Allows you to extend a recipe so that it builds variants of the software.
569 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
570 which is a copy of Quilt built to run on the build system;
571 "crosses" such as <filename>gcc-cross</filename>,
572 which is a compiler built to run on the build machine but produces binaries
573 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
574 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
575 and "mulitlibs" in the form "<filename>multilib:&lt;multilib_name&gt;</filename>".
576 </para>
577
578 <para>
579 To build a different variant of the recipe with a minimal amount of code, it usually
580 is as simple as adding the following to your recipe:
581 <literallayout class='monospaced'>
582 BBCLASSEXTEND =+ "native nativesdk"
583 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
584 </literallayout>
585 </para>
586 </glossdef>
587 </glossentry>
588
589 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
590 <glossdef>
591 <para>Lists the names of configured layers.
592 These names are used to find the other <filename>BBFILE_*</filename>
593 variables.
594 Typically, each layer will append its name to this variable in its
595 <filename>conf/layer.conf</filename> file.
596 </para>
597 </glossdef>
598 </glossentry>
599
600 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
601 <glossdef>
602 <para>Variable that expands to match files from
603 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
604 in a particular layer.
605 This variable is used in the <filename>conf/layer.conf</filename> file and must
606 be suffixed with the name of the specific layer (e.g.
607 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
608 </glossdef>
609 </glossentry>
610
611 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
612 <glossdef>
613 <para>Assigns the priority for recipe files in each layer.</para>
614 <para>This variable is useful in situations where the same recipe appears in
615 more than one layer.
616 Setting this variable allows you to prioritize a
617 layer against other layers that contain the same recipe - effectively
618 letting you control the precedence for the multiple layers.
619 The precedence established through this variable stands regardless of a
620 recipe's version
621 (<link linkend='var-PV'><filename>PV</filename></link> variable).
622 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
623 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
624 lower precedence.</para>
625 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
626 precedence.
627 For example, the value 6 has a higher precedence than the value 5.
628 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
629 dependencies (see the
630 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
631 more information.
632 The default priority, if unspecified
633 for a layer with no dependencies, is the lowest defined priority + 1
634 (or 1 if no priorities are defined).</para>
635 <tip>
636 You can use the command <filename>bitbake-layers show-layers</filename> to list
637 all configured layers along with their priorities.
638 </tip>
639 </glossdef>
640 </glossentry>
641
642 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
643 <glossdef>
644 <para>List of recipe files used by BitBake to build software.</para>
645 </glossdef>
646 </glossentry>
647
648 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
649 <glossdef>
650 <para>Variable that controls how BitBake displays logs on build failure.</para>
651 </glossdef>
652 </glossentry>
653
654 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
655 <glossdef>
656 <para>Lists the layers to enable during the build.
657 This variable is defined in the <filename>bblayers.conf</filename> configuration
658 file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
659 Here is an example:
660 <literallayout class='monospaced'>
661 BBLAYERS = " \
662 /home/scottrif/poky/meta \
663 /home/scottrif/poky/meta-yocto \
664 /home/scottrif/poky/meta-yocto-bsp \
665 /home/scottrif/poky/meta-mykernel \
666 "
667
668 BBLAYERS_NON_REMOVABLE ?= " \
669 /home/scottrif/poky/meta \
670 /home/scottrif/poky/meta-yocto \
671 "
672 </literallayout>
673 This example enables four layers, one of which is a custom, user-defined layer
674 named <filename>meta-mykernel</filename>.
675 </para>
676 </glossdef>
677 </glossentry>
678
679 <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm>
680 <glossdef>
681 <para>Lists core layers that cannot be removed from the
682 <filename>bblayers.conf</filename> file during a build
683 using the
684 <ulink url='https://www.yoctoproject.org/tools-resources/projects/hob'>Hob</ulink>.
685 <note>
686 When building an image outside of Hob, this variable
687 is ignored.
688 </note>
689 In order for BitBake to build your image using Hob, your
690 <filename>bblayers.conf</filename> file must include the
691 <filename>meta</filename> and <filename>meta-yocto</filename>
692 core layers.
693 Here is an example that shows these two layers listed in
694 the <filename>BBLAYERS_NON_REMOVABLE</filename> statement:
695 <literallayout class='monospaced'>
696 BBLAYERS = " \
697 /home/scottrif/poky/meta \
698 /home/scottrif/poky/meta-yocto \
699 /home/scottrif/poky/meta-yocto-bsp \
700 /home/scottrif/poky/meta-mykernel \
701 "
702
703 BBLAYERS_NON_REMOVABLE ?= " \
704 /home/scottrif/poky/meta \
705 /home/scottrif/poky/meta-yocto \
706 "
707 </literallayout>
708 </para>
709 </glossdef>
710 </glossentry>
711
712 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
713 <glossdef>
714 <para>
715 Prevents BitBake from processing recipes and recipe
716 append files.
717 Use the <filename>BBMASK</filename> variable from within the
718 <filename>conf/local.conf</filename> file found
719 in the
720 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
721 </para>
722
723 <para>
724 You can use the <filename>BBMASK</filename> variable
725 to "hide" these <filename>.bb</filename> and
726 <filename>.bbappend</filename> files.
727 BitBake ignores any recipe or recipe append files that
728 match the expression.
729 It is as if BitBake does not see them at all.
730 Consequently, matching files are not parsed or otherwise
731 used by BitBake.</para>
732 <para>
733 The value you provide is passed to Python's regular
734 expression compiler.
735 The expression is compared against the full paths to
736 the files.
737 For complete syntax information, see Python's
738 documentation at
739 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
740 </para>
741
742 <para>
743 The following example uses a complete regular expression
744 to tell BitBake to ignore all recipe and recipe append
745 files in the <filename>meta-ti/recipes-misc/</filename>
746 directory:
747 <literallayout class='monospaced'>
748 BBMASK = "meta-ti/recipes-misc/"
749 </literallayout>
750 If you want to mask out multiple directories or recipes,
751 use the vertical bar to separate the regular expression
752 fragments.
753 This next example masks out multiple directories and
754 individual recipes:
755 <literallayout class='monospaced'>
756 BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/"
757 BBMASK .= "|.*meta-oe/recipes-support/"
758 BBMASK .= "|.*openldap"
759 BBMASK .= "|.*opencv"
760 BBMASK .= "|.*lzma"
761 </literallayout>
762 Notice how the vertical bar is used to append the fragments.
763 <note>
764 When specifying a directory name, use the trailing
765 slash character to ensure you match just that directory
766 name.
767 </note>
768 </para>
769 </glossdef>
770 </glossentry>
771
772 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
773 <glossdef>
774 <para>
775 Used by BitBake to locate
776 <filename>.bbclass</filename> and configuration files.
777 This variable is analogous to the
778 <filename>PATH</filename> variable.
779 <note>
780 If you run BitBake from a directory outside of the
781 <ulink url='&YOCTO_DOCS_DEV_URL;build-directory'>Build Directory</ulink>,
782 you must be sure to set
783 <filename>BBPATH</filename> to point to the
784 Build Directory.
785 Set the variable as you would any environment variable
786 and then run BitBake:
787 <literallayout class='monospaced'>
788 $ BBPATH = "&lt;build_directory&gt;"
789 $ export BBPATH
790 $ bitbake &lt;target&gt;
791 </literallayout>
792 </note>
793 </para>
794 </glossdef>
795 </glossentry>
796
797 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
798 <glossdef>
799 <para>
800 Points to the server that runs memory-resident BitBake.
801 This variable is set by the
802 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
803 setup script and should not be hand-edited.
804 The variable is only used when you employ memory-resident
805 BitBake.
806 The setup script exports the value as follows:
807 <literallayout class='monospaced'>
808 export BBSERVER=localhost:$port
809 </literallayout>
810 For more information on how the
811 <filename>BBSERVER</filename> is used, see the
812 <filename>oe-init-build-env-memres</filename> script, which
813 is located in the
814 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
815 </para>
816 </glossdef>
817 </glossentry>
818
819 <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
820 <glossdef>
821 <para>
822 When inheriting <filename>binconfig.bbclass</filename>
823 from a recipe, this variable specifies a wildcard for
824 configuration scripts that need editing.
825 The scripts are edited to correct any paths that have been
826 set up during compilation so that they are correct for
827 use when installed into the sysroot and called by the
828 build processes of other recipes.
829 </para>
830
831 <para>
832 For more information on how this variable works, see
833 <filename>meta/classes/binconfig.bbclass</filename> in the
834 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
835 You can also find general information on the class in the
836 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
837 section.
838 </para>
839 </glossdef>
840 </glossentry>
841
842 <glossentry id='var-BP'><glossterm>BP</glossterm>
843 <glossdef>
844 <para>The base recipe name and version but without any special
845 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
846 and so forth).
847 <filename>BP</filename> is comprised of the following:
848 <literallayout class="monospaced">
849 ${BPN}-${PV}
850 </literallayout></para>
851 </glossdef>
852 </glossentry>
853
854 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
855 <glossdef>
856 <para>The bare name of the recipe.
857 This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable
858 but removes common suffixes such as "-native" and "-cross" as well
859 as removes common prefixes such as multilib's "lib64-" and "lib32-".
860 The exact list of suffixes removed is specified by the
861 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable.
862 The exact list of prefixes removed is specified by the
863 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable.
864 Prefixes are removed for <filename>multilib</filename>
865 and <filename>nativesdk</filename> cases.</para>
866 </glossdef>
867 </glossentry>
868
869 <glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm>
870 <glossdef>
871 <para>
872 Specifies a URL for an upstream bug tracking website for
873 a recipe.
874 The OpenEmbedded build system does not use this variable.
875 Rather, the variable is a useful pointer in case a bug
876 in the software being built needs to be manually reported.
877 </para>
878 </glossdef>
879 </glossentry>
880
881 <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
882 <glossdef>
883 <para>
884 Points to the location of the
885 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
886 You can define this directory indirectly through the
887 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
888 and
889 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
890 scripts by passing in a Build Directory path when you run
891 the scripts.
892 If you run the scripts and do not provide a Build Directory
893 path, the <filename>BUILDDIR</filename> defaults to
894 <filename>build</filename> in the current directory.
895 </para>
896 </glossdef>
897 </glossentry>
898
899 <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>BUILDHISTORY_COMMIT</glossterm>
900 <glossdef>
901 <para>
902 When inheriting the
903 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
904 class, specifies whether or not to commit the build
905 history output in a local Git repository.
906 If set to "1", this local repository will be maintained
907 automatically by the
908 <filename>buildhistory</filename>
909 class and a commit will be created on every
910 build for changes to each top-level subdirectory of the
911 build history output (images, packages, and sdk).
912 If you want to track changes to build history over
913 time, you should set this value to "1".
914 </para>
915
916 <para>
917 By default, the <filename>buildhistory</filename> class
918 does not commit the build history output in a local
919 Git repository:
920 <literallayout class='monospaced'>
921 BUILDHISTORY_COMMIT ?= "0"
922 </literallayout>
923 </para>
924 </glossdef>
925 </glossentry>
926
927 <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>BUILDHISTORY_COMMIT_AUTHOR</glossterm>
928 <glossdef>
929 <para>
930 When inheriting the
931 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
932 class, specifies the author to use for each Git commit.
933 In order for the <filename>BUILDHISTORY_COMMIT_AUTHOR</filename>
934 variable to work, the
935 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
936 variable must be set to "1".
937 </para>
938
939 <para>
940 Git requires that the value you provide for the
941 <filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable
942 takes the form of "name &lt;email@host&gt;".
943 Providing an email address or host that is not valid does
944 not produce an error.
945 </para>
946
947 <para>
948 By default, the <filename>buildhistory</filename> class
949 sets the variable as follows:
950 <literallayout class='monospaced'>
951 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory &lt;buildhistory@${DISTRO}&gt;"
952 </literallayout>
953 </para>
954 </glossdef>
955 </glossentry>
956
957 <glossentry id='var-BUILDHISTORY_DIR'><glossterm>BUILDHISTORY_DIR</glossterm>
958 <glossdef>
959 <para>
960 When inheriting the
961 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
962 class, specifies the directory in which build history
963 information is kept.
964 For more information on how the variable works, see the
965 <filename>buildhistory.class</filename>.
966 </para>
967
968 <para>
969 By default, the <filename>buildhistory</filename> class
970 sets the directory as follows:
971 <literallayout class='monospaced'>
972 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
973 </literallayout>
974 </para>
975 </glossdef>
976 </glossentry>
977
978 <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>BUILDHISTORY_FEATURES</glossterm>
979 <glossdef>
980 <para>
981 When inheriting the
982 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
983 class, specifies the build history features to be enabled.
984 For more information on how build history works, see the
985 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
986 section.
987 </para>
988
989 <para>
990 You can specify three features in the form of a
991 space-separated list:
992 <itemizedlist>
993 <listitem><para><emphasis>image:</emphasis>
994 Analysis of the contents of images, which
995 includes the list of installed packages among other
996 things.
997 </para></listitem>
998 <listitem><para><emphasis>package:</emphasis>
999 Analysis of the contents of individual packages.
1000 </para></listitem>
1001 <listitem><para><emphasis>sdk:</emphasis>
1002 Analysis of the contents of the software
1003 development kit (SDK).
1004 </para></listitem>
1005 </itemizedlist>
1006 </para>
1007
1008 <para>
1009 By default, the <filename>buildhistory</filename> class
1010 enables all three features:
1011 <literallayout class='monospaced'>
1012 BUILDHISTORY_FEATURES ?= "image package sdk"
1013 </literallayout>
1014 </para>
1015 </glossdef>
1016 </glossentry>
1017
1018 <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>BUILDHISTORY_IMAGE_FILES</glossterm>
1019 <glossdef>
1020 <para>
1021 When inheriting the
1022 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1023 class, specifies a list of paths to files copied from the
1024 image contents into the build history directory under
1025 an "image-files" directory in the directory for
1026 the image, so that you can track the contents of each file.
1027 The default is to copy <filename>/etc/passwd</filename>
1028 and <filename>/etc/group</filename>, which allows you to
1029 monitor for changes in user and group entries.
1030 You can modify the list to include any file.
1031 Specifying an invalid path does not produce an error.
1032 Consequently, you can include files that might
1033 not always be present.
1034 </para>
1035
1036 <para>
1037 By default, the <filename>buildhistory</filename> class
1038 provides paths to the following files:
1039 <literallayout class='monospaced'>
1040 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
1041 </literallayout>
1042 </para>
1043 </glossdef>
1044 </glossentry>
1045
1046 <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>BUILDHISTORY_PUSH_REPO</glossterm>
1047 <glossdef>
1048 <para>
1049 When inheriting the
1050 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1051 class, optionally specifies a remote repository
1052 to which build history pushes Git changes.
1053 In order for <filename>BUILDHISTORY_PUSH_REPO</filename>
1054 to work,
1055 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
1056 must be set to "1".
1057 </para>
1058
1059 <para>
1060 The repository should correspond to a remote
1061 address that specifies a repository as understood by
1062 Git, or alternatively to a remote name that you have
1063 set up manually using <filename>git remote</filename>
1064 within the local repository.
1065 </para>
1066
1067 <para>
1068 By default, the <filename>buildhistory</filename> class
1069 sets the variable as follows:
1070 <literallayout class='monospaced'>
1071 BUILDHISTORY_PUSH_REPO ?= ""
1072 </literallayout>
1073 </para>
1074 </glossdef>
1075 </glossentry>
1076
1077 <glossentry id='var-BUILDSTATS_BASE'><glossterm>BUILDSTATS_BASE</glossterm>
1078 <glossdef>
1079 <para>
1080 Points to the location of the directory that holds build
1081 statistics when you use and enable the
1082 <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link>
1083 class.
1084 The <filename>BUILDSTATS_BASE</filename> directory defaults
1085 to
1086 <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/buildstats/</filename>.
1087 </para>
1088 </glossdef>
1089 </glossentry>
1090
1091 <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
1092 <glossdef>
1093 <para>
1094 For the BusyBox recipe, specifies whether to split the
1095 output executable file into two parts: one for features
1096 that require <filename>setuid root</filename>, and one for
1097 the remaining features (i.e. those that do not require
1098 <filename>setuid root</filename>).
1099 </para>
1100
1101 <para>
1102 The <filename>BUSYBOX_SPLIT_SUID</filename> variable
1103 defaults to "1", which results in a single output
1104 executable file.
1105 Set the variable to "0" to split the output file.
1106 </para>
1107 </glossdef>
1108 </glossentry>
1109
1110 </glossdiv>
1111
1112 <glossdiv id='var-glossary-c'><title>C</title>
1113
1114 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
1115 <glossdef>
1116 <para>
1117 Flags passed to the C compiler for the target system.
1118 This variable evaluates to the same as
1119 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>.
1120 </para>
1121
1122 <para>
1123 For information on flags that help with creating more
1124 secure code, see the
1125 "<ulink url='&YOCTO_DOCS_DEV_URL;#making-images-more-secure'>Making Images More Secure</ulink>"
1126 section in the Yocto Project Development Manual.
1127 </para>
1128 </glossdef>
1129 </glossentry>
1130
1131 <glossentry id='var-CLASSOVERRIDE'><glossterm>CLASSOVERRIDE</glossterm>
1132 <glossdef>
1133 <para>
1134 An internal variable specifying the special class override
1135 that should currently apply (e.g. "class-target",
1136 "class-native", and so forth).
1137 The classes that use this variable set it to
1138 appropriate values.
1139 </para>
1140
1141 <para>
1142 You do not normally directly interact with this variable.
1143 The value for the <filename>CLASSOVERRIDE</filename>
1144 variable goes into
1145 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1146 and then can be used as an override.
1147 Here is an example where "python-native" is added to
1148 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1149 only when building for the native case:
1150 <literallayout class='monospaced'>
1151 DEPENDS_append_class-native = " python-native"
1152 </literallayout>
1153 </para>
1154 </glossdef>
1155 </glossentry>
1156
1157 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
1158 <glossdef>
1159 <para>
1160 Provides a list of hardware features that are enabled in
1161 both
1162 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
1163 and
1164 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
1165 This select list of features contains features that make
1166 sense to be controlled both at the machine and distribution
1167 configuration level.
1168 For example, the "bluetooth" feature requires hardware
1169 support but should also be optional at the distribution
1170 level, in case the hardware supports Bluetooth but you
1171 do not ever intend to use it.
1172 </para>
1173
1174 <para>
1175 For more information, see the
1176 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
1177 and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
1178 variables.
1179 </para>
1180 </glossdef>
1181 </glossentry>
1182
1183 <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
1184 <glossdef>
1185 <para>
1186 Points to <filename>meta/files/common-licenses</filename>
1187 in the
1188 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
1189 which is where generic license files reside.
1190 </para>
1191 </glossdef>
1192 </glossentry>
1193
1194 <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
1195 <glossdef>
1196 <para>A regular expression that resolves to one or more hosts
1197 (when the recipe is native) or one or more targets (when
1198 the recipe is non-native) with which a recipe is compatible.
1199 The regular expression is matched against
1200 <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
1201 You can use the variable to stop recipes from being built
1202 for classes of systems with which the recipes are not
1203 compatible.
1204 Stopping these builds is particularly useful with kernels.
1205 The variable also helps to increase parsing speed
1206 since the build system skips parsing recipes not
1207 compatible with the current system.</para>
1208 </glossdef>
1209 </glossentry>
1210
1211 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
1212 <glossdef>
1213 <para>A regular expression that resolves to one or more
1214 target machines with which a recipe is compatible.
1215 The regular expression is matched against
1216 <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
1217 You can use the variable to stop recipes from being built
1218 for machines with which the recipes are not compatible.
1219 Stopping these builds is particularly useful with kernels.
1220 The variable also helps to increase parsing speed
1221 since the build system skips parsing recipes not
1222 compatible with the current machine.</para>
1223 </glossdef>
1224 </glossentry>
1225
1226 <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
1227 <glossdef>
1228 <para>
1229 Defines wildcards to match when installing a list of
1230 complementary packages for all the packages explicitly
1231 (or implicitly) installed in an image.
1232 The resulting list of complementary packages is associated
1233 with an item that can be added to
1234 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
1235 An example usage of this is the "dev-pkgs" item that when
1236 added to <filename>IMAGE_FEATURES</filename> will
1237 install -dev packages (containing headers and other
1238 development files) for every package in the image.
1239 </para>
1240
1241 <para>
1242 To add a new feature item pointing to a wildcard, use a
1243 variable flag to specify the feature item name and
1244 use the value to specify the wildcard.
1245 Here is an example:
1246 <literallayout class='monospaced'>
1247 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
1248 </literallayout>
1249 </para>
1250 </glossdef>
1251 </glossentry>
1252
1253 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
1254 <glossdef>
1255 <para>
1256 Identifies editable or configurable files that are part of a package.
1257 If the Package Management System (PMS) is being used to update
1258 packages on the target system, it is possible that
1259 configuration files you have changed after the original installation
1260 and that you now want to remain unchanged are overwritten.
1261 In other words, editable files might exist in the package that you do not
1262 want reset as part of the package update process.
1263 You can use the <filename>CONFFILES</filename> variable to list the files in the
1264 package that you wish to prevent the PMS from overwriting during this update process.
1265 </para>
1266
1267 <para>
1268 To use the <filename>CONFFILES</filename> variable, provide a package name
1269 override that identifies the resulting package.
1270 Then, provide a space-separated list of files.
1271 Here is an example:
1272 <literallayout class='monospaced'>
1273 CONFFILES_${PN} += "${sysconfdir}/file1 \
1274 ${sysconfdir}/file2 ${sysconfdir}/file3"
1275 </literallayout>
1276 </para>
1277
1278 <para>
1279 A relationship exists between the <filename>CONFFILES</filename> and
1280 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
1281 The files listed within <filename>CONFFILES</filename> must be a subset of
1282 the files listed within <filename>FILES</filename>.
1283 Because the configuration files you provide with <filename>CONFFILES</filename>
1284 are simply being identified so that the PMS will not overwrite them,
1285 it makes sense that
1286 the files must already be included as part of the package through the
1287 <filename>FILES</filename> variable.
1288 </para>
1289
1290 <note>
1291 When specifying paths as part of the <filename>CONFFILES</filename> variable,
1292 it is good practice to use appropriate path variables.
1293 For example, <filename>${sysconfdir}</filename> rather than
1294 <filename>/etc</filename> or <filename>${bindir}</filename> rather
1295 than <filename>/usr/bin</filename>.
1296 You can find a list of these variables at the top of the
1297 <filename>meta/conf/bitbake.conf</filename> file in the
1298 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1299 </note>
1300 </glossdef>
1301 </glossentry>
1302
1303 <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>
1304 <glossdef>
1305 <para>
1306 Identifies the initial RAM disk (initramfs) source files.
1307 The OpenEmbedded build system receives and uses
1308 this kernel Kconfig variable as an environment variable.
1309 By default, the variable is set to null ("").
1310 </para>
1311
1312 <para>
1313 The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be
1314 either a single cpio archive with a
1315 <filename>.cpio</filename> suffix or a
1316 space-separated list of directories and files for building
1317 the initramfs image.
1318 A cpio archive should contain a filesystem archive
1319 to be used as an initramfs image.
1320 Directories should contain a filesystem layout to be
1321 included in the initramfs image.
1322 Files should contain entries according to the format
1323 described by the
1324 <filename>usr/gen_init_cpio</filename> program in the
1325 kernel tree.
1326 </para>
1327
1328 <para>
1329 If you specify multiple directories and files, the
1330 initramfs image will be the aggregate of all of them.
1331 </para>
1332 </glossdef>
1333 </glossentry>
1334
1335 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
1336 <glossdef>
1337 <para>
1338 A list of files that contains <filename>autoconf</filename> test results relevant
1339 to the current build.
1340 This variable is used by the Autotools utilities when running
1341 <filename>configure</filename>.
1342 </para>
1343 </glossdef>
1344 </glossentry>
1345
1346 <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>CONFLICT_DISTRO_FEATURES</glossterm>
1347 <glossdef>
1348 <para>
1349 When a recipe inherits the
1350 <filename>distro_features_check</filename> class, this
1351 variable identifies distribution features that would
1352 be in conflict should the recipe
1353 be built.
1354 In other words, if the
1355 <filename>CONFLICT_DISTRO_FEATURES</filename> variable
1356 lists a feature that also appears in
1357 <filename>DISTRO_FEATURES</filename> within the
1358 current configuration, an error occurs and the
1359 build stops.
1360 </para>
1361 </glossdef>
1362 </glossentry>
1363
1364 <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm>
1365 <glossdef>
1366 <para>
1367 If set to "1" along with the
1368 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
1369 variable, the OpenEmbedded build system copies
1370 into the image the license files, which are located in
1371 <filename>/usr/share/common-licenses</filename>,
1372 for each package.
1373 The license files are placed
1374 in directories within the image itself.
1375 </para>
1376 </glossdef>
1377 </glossentry>
1378
1379 <glossentry id='var-COPY_LIC_MANIFEST'><glossterm>COPY_LIC_MANIFEST</glossterm>
1380 <glossdef>
1381 <para>
1382 If set to "1", the OpenEmbedded build system copies
1383 the license manifest for the image to
1384 <filename>/usr/share/common-licenses/license.manifest</filename>
1385 within the image itself.
1386 </para>
1387 </glossdef>
1388 </glossentry>
1389
1390 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
1391 <glossdef>
1392 <para>
1393 Specifies the list of packages to be added to the image.
1394 You should only set this variable in the
1395 <filename>local.conf</filename> configuration file found
1396 in the
1397 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1398 </para>
1399
1400 <para>
1401 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
1402 </para>
1403 </glossdef>
1404 </glossentry>
1405
1406 <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
1407 <glossdef>
1408 <para>
1409 Specifies the parent directory of the OpenEmbedded
1410 Core Metadata layer (i.e. <filename>meta</filename>).
1411 </para>
1412
1413 <para>
1414 It is an important distinction that
1415 <filename>COREBASE</filename> points to the parent of this
1416 layer and not the layer itself.
1417 Consider an example where you have cloned the Poky Git
1418 repository and retained the <filename>poky</filename>
1419 name for your local copy of the repository.
1420 In this case, <filename>COREBASE</filename> points to
1421 the <filename>poky</filename> folder because it is the
1422 parent directory of the <filename>poky/meta</filename>
1423 layer.
1424 </para>
1425 </glossdef>
1426 </glossentry>
1427
1428 </glossdiv>
1429
1430 <glossdiv id='var-glossary-d'><title>D</title>
1431
1432 <glossentry id='var-D'><glossterm>D</glossterm>
1433 <glossdef>
1434 <para>
1435 The destination directory.
1436 The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1437 where components are installed by the <filename>do_install</filename> task.
1438 This location defaults to:
1439 <literallayout class='monospaced'>
1440 ${WORKDIR}/image
1441 </literallayout>
1442 </para>
1443 </glossdef>
1444 </glossentry>
1445
1446 <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
1447 <glossdef>
1448 <para>
1449 The date and time on which the current build started.
1450 The format is suitable for timestamps.
1451 </para>
1452 </glossdef>
1453 </glossentry>
1454
1455 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
1456 <glossdef>
1457 <para>
1458 Specifies to build packages with debugging information.
1459 This influences the value of the
1460 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
1461 variable.
1462 </para>
1463 </glossdef>
1464 </glossentry>
1465
1466 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
1467 <glossdef>
1468 <para>
1469 The options to pass in
1470 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1471 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
1472 a system for debugging.
1473 This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
1474 </para>
1475 </glossdef>
1476 </glossentry>
1477
1478 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
1479 <glossdef>
1480 <para>
1481 Specifies a weak bias for recipe selection priority.
1482 </para>
1483 <para>
1484 The most common usage of this is variable is to set
1485 it to "-1" within a recipe for a development version of a
1486 piece of software.
1487 Using the variable in this way causes the stable version
1488 of the recipe to build by default in the absence of
1489 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
1490 being used to build the development version.
1491 </para>
1492 <note>
1493 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
1494 is weak and is overridden by
1495 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
1496 if that variable is different between two layers
1497 that contain different versions of the same recipe.
1498 </note>
1499 </glossdef>
1500 </glossentry>
1501
1502 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
1503 <glossdef>
1504 <para>
1505 Lists a recipe's build-time dependencies
1506 (i.e. other recipe files).
1507 The system ensures that all the dependencies listed
1508 have been built and have their contents in the appropriate
1509 sysroots before the recipe's configure task is executed.
1510 </para>
1511
1512 <para>
1513 Consider this simple example for two recipes named "a" and
1514 "b" that produce similarly named packages.
1515 In this example, the <filename>DEPENDS</filename>
1516 statement appears in the "a" recipe:
1517 <literallayout class='monospaced'>
1518 DEPENDS = "b"
1519 </literallayout>
1520 Here, the dependency is such that the
1521 <filename>do_configure</filename> task for recipe "a"
1522 depends on the <filename>do_populate_sysroot</filename>
1523 task of recipe "b".
1524 This means anything that recipe "b" puts into sysroot
1525 is available when recipe "a" is configuring itself.
1526 </para>
1527
1528 <para>
1529 For information on runtime dependencies, see the
1530 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1531 variable.
1532 </para>
1533 </glossdef>
1534 </glossentry>
1535
1536 <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
1537 <glossdef>
1538 <para>
1539 Points to the general area that the OpenEmbedded build
1540 system uses to place images, packages, SDKs and other output
1541 files that are ready to be used outside of the build system.
1542 By default, this directory resides within the
1543 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1544 as <filename>${TMPDIR}/deploy</filename>.
1545 </para>
1546
1547 <para>
1548 For more information on the structure of the Build
1549 Directory, see
1550 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1551 section.
1552 For more detail on the contents of the
1553 <filename>deploy</filename> directory, see the
1554 "<link linkend='images-dev-environment'>Images</link>" and
1555 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1556 sections.
1557 </para>
1558 </glossdef>
1559 </glossentry>
1560
1561 <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
1562 <glossdef>
1563 <para>
1564 Points to the area that the OpenEmbedded build system uses
1565 to place images and other associated output files that are
1566 ready to be deployed onto the target machine.
1567 The directory is machine-specific as it contains the
1568 <filename>${MACHINE}</filename> name.
1569 By default, this directory resides within the
1570 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
1571 as <filename>${DEPLOY_DIR}/images/${MACHINE}/</filename>.
1572 </para>
1573
1574 <para>
1575 For more information on the structure of the Build
1576 Directory, see
1577 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
1578 section.
1579 For more detail on the contents of the
1580 <filename>deploy</filename> directory, see the
1581 "<link linkend='images-dev-environment'>Images</link>" and
1582 "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
1583 sections.
1584 </para>
1585 </glossdef>
1586 </glossentry>
1587
1588 <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm>
1589 <glossdef>
1590 <para>
1591 For recipes that inherit the
1592 <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
1593 class, the <filename>DEPLOYDIR</filename> points to a
1594 temporary work area for deployed files that is set in the
1595 <filename>deploy</filename> class as follows:
1596 <literallayout class='monospaced'>
1597 DEPLOYDIR = "${WORKDIR}/deploy-${<link linkend='var-PN'><filename>PN</filename></link>}"
1598 </literallayout>
1599 Recipes inheriting the <filename>deploy</filename> class
1600 should copy files to be deployed into
1601 <filename>DEPLOYDIR</filename>, and the class will take
1602 care of copying them into
1603 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
1604 afterwards.
1605 </para>
1606 </glossdef>
1607 </glossentry>
1608
1609 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
1610 <glossdef>
1611 <para>The package description used by package managers.
1612 If not set, <filename>DESCRIPTION</filename> takes
1613 the value of the
1614 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
1615 variable.
1616 </para>
1617 </glossdef>
1618 </glossentry>
1619
1620 <glossentry id='var-DISK_SIGNATURE'><glossterm>DISK_SIGNATURE</glossterm>
1621 <glossdef>
1622 <para>
1623 A 32-bit MBR disk signature used by
1624 <filename>directdisk</filename> images.
1625 </para>
1626
1627 <para>
1628 By default, the signature is set to an automatically
1629 generated random value that allows the OpenEmbedded
1630 build system to create a boot loader.
1631 You can override the signature in the image recipe
1632 by setting <filename>DISK_SIGNATURE</filename> to an
1633 8-digit hex string.
1634 You might want to override
1635 <filename>DISK_SIGNATURE</filename> if you want the disk
1636 signature to remain constant between image builds.
1637 </para>
1638
1639 <para>
1640 When using Linux 3.8 or later, you can use
1641 <filename>DISK_SIGNATURE</filename> to specify the root
1642 by UUID to allow the kernel to locate the root device
1643 even if the device name changes due to differences in
1644 hardware configuration.
1645 By default, <filename>SYSLINUX_ROOT</filename> is set
1646 as follows:
1647 <literallayout class='monospaced'>
1648 SYSLINUX_ROOT = "root=/dev/sda2"
1649 </literallayout>
1650 However, you can change this to locate the root device
1651 using the disk signature instead:
1652 <literallayout class='monospaced'>
1653 SYSLINUX_ROOT = "root=PARTUUID=${DISK_SIGNATURE}-02"
1654 </literallayout>
1655 </para>
1656
1657 <para>
1658 As previously mentioned, it is possible to set the
1659 <filename>DISK_SIGNATURE</filename> variable in your
1660 <filename>local.conf</filename> file to a fixed
1661 value if you do not want <filename>syslinux.cfg</filename>
1662 changing for each build.
1663 You might find this useful when you want to upgrade the
1664 root filesystem on a device without having to recreate or
1665 modify the master boot record.
1666 </para>
1667 </glossdef>
1668 </glossentry>
1669
1670 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
1671 <glossdef>
1672 <para>
1673 The short name of the distribution.
1674 This variable corresponds to a distribution
1675 configuration file whose root name is the same as the
1676 variable's argument and whose filename extension is
1677 <filename>.conf</filename>.
1678 For example, the distribution configuration file for the
1679 Poky distribution is named <filename>poky.conf</filename>
1680 and resides in the
1681 <filename>meta-yocto/conf/distro</filename> directory of
1682 the
1683 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1684 </para>
1685
1686 <para>
1687 Within that <filename>poky.conf</filename> file, the
1688 <filename>DISTRO</filename> variable is set as follows:
1689 <literallayout class='monospaced'>
1690 DISTRO = "poky"
1691 </literallayout>
1692 </para>
1693
1694 <para>
1695 Distribution configuration files are located in a
1696 <filename>conf/distro</filename> directory within the
1697 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
1698 that contains the distribution configuration.
1699 The value for <filename>DISTRO</filename> must not contain
1700 spaces, and is typically all lower-case.
1701 <note>
1702 If the <filename>DISTRO</filename> variable is blank, a set
1703 of default configurations are used, which are specified
1704 within
1705 <filename>meta/conf/distro/defaultsetup.conf</filename>
1706 also in the Source Directory.
1707 </note>
1708 </para>
1709 </glossdef>
1710 </glossentry>
1711
1712 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
1713 <glossdef>
1714 <para>
1715 Specifies a list of distro-specific packages to add to all images.
1716 This variable takes affect through
1717 <filename>packagegroup-base</filename> so the
1718 variable only really applies to the more full-featured
1719 images that include <filename>packagegroup-base</filename>.
1720 You can use this variable to keep distro policy out of
1721 generic images.
1722 As with all other distro variables, you set this variable
1723 in the distro <filename>.conf</filename> file.
1724 </para>
1725 </glossdef>
1726 </glossentry>
1727
1728 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
1729 <glossdef>
1730 <para>
1731 Specifies a list of distro-specific packages to add to all images
1732 if the packages exist.
1733 The packages might not exist or be empty (e.g. kernel modules).
1734 The list of packages are automatically installed but you can
1735 remove them.
1736 </para>
1737 </glossdef>
1738 </glossentry>
1739
1740 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
1741 <glossdef>
1742 <para>
1743 The software support you want in your distribution for
1744 various features.
1745 You define your distribution features in the distribution
1746 configuration file.
1747 </para>
1748
1749 <para>
1750 In most cases, the presence or absence of a feature in
1751 <filename>DISTRO_FEATURES</filename> is translated to the
1752 appropriate option supplied to the configure script
1753 during <filename>do_configure</filename> for recipes that
1754 optionally support the feature.
1755 For example, specifying "x11" in
1756 <filename>DISTRO_FEATURES</filename>, causes
1757 every piece of software built for the target that can
1758 optionally support X11 to have its X11 support enabled.
1759 </para>
1760
1761 <para>
1762 Two more examples are Bluetooth and NFS support.
1763 For a more complete list of features that ships with the
1764 Yocto Project and that you can provide with this variable,
1765 see the
1766 "<link linkend='ref-features-distro'>Distro Features</link>"
1767 section.
1768 </para>
1769 </glossdef>
1770 </glossentry>
1771
1772 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
1773 <glossdef>
1774 <para>Features to be added to
1775 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
1776 if not also present in
1777 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
1778 </para>
1779
1780 <para>
1781 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
1782 It is not intended to be user-configurable.
1783 It is best to just reference the variable to see which distro features are
1784 being backfilled for all distro configurations.
1785 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1786 more information.
1787 </para>
1788 </glossdef>
1789 </glossentry>
1790
1791 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
1792 <glossdef>
1793 <para>Features from
1794 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
1795 that should not be backfilled (i.e. added to
1796 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
1797 during the build.
1798 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
1799 more information.
1800 </para>
1801 </glossdef>
1802 </glossentry>
1803
1804 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
1805 <glossdef>
1806 <para>The long name of the distribution.</para>
1807 </glossdef>
1808 </glossentry>
1809
1810 <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
1811 <glossdef>
1812 <para>Alias names used for the recipe in various Linux distributions.</para>
1813 <para>See the
1814 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling
1815 a Package Name Alias</ulink>" section in the Yocto Project Development
1816 Manual for more information.</para>
1817 </glossdef>
1818 </glossentry>
1819
1820 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
1821 <glossdef>
1822 <para>The version of the distribution.</para>
1823 </glossdef>
1824 </glossentry>
1825
1826 <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
1827 <glossdef>
1828 <para>
1829 This variable lists overrides specific to the current
1830 distribution.
1831 By default, the variable list includes the value of the
1832 <filename><link linkend='var-DISTRO'>DISTRO</link></filename>
1833 variable.
1834 You can extend the variable to apply any variable overrides
1835 you want as part of the distribution and are not
1836 already in <filename>OVERRIDES</filename> through
1837 some other means.
1838 </para>
1839 </glossdef>
1840 </glossentry>
1841
1842 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
1843 <glossdef>
1844 <para>
1845 The central download directory used by the build process to
1846 store downloads.
1847 By default, <filename>DL_DIR</filename> gets files
1848 suitable for mirroring for everything except Git
1849 repositories.
1850 If you want tarballs of Git repositories, use the
1851 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
1852 variable.
1853 </para>
1854
1855 <para>
1856 You can set this directory by defining the
1857 <filename>DL_DIR</filename> variable in the
1858 <filename>conf/local.conf</filename> file.
1859 This directory is self-maintaining and you should not have
1860 to touch it.
1861 By default, the directory is <filename>downloads</filename>
1862 in the
1863 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1864 <literallayout class='monospaced'>
1865 #DL_DIR ?= "${TOPDIR}/downloads"
1866 </literallayout>
1867 To specify a different download directory, simply remove
1868 the comment from the line and provide your directory.
1869 </para>
1870
1871 <para>
1872 During a first build, the system downloads many different
1873 source code tarballs from various upstream projects.
1874 Downloading can take a while, particularly if your network
1875 connection is slow.
1876 Tarballs are all stored in the directory defined by
1877 <filename>DL_DIR</filename> and the build system looks there
1878 first to find source tarballs.
1879 <note>
1880 When wiping and rebuilding, you can preserve this
1881 directory to speed up this part of subsequent
1882 builds.
1883 </note>
1884 </para>
1885
1886 <para>
1887 You can safely share this directory between multiple builds
1888 on the same development machine.
1889 For additional information on how the build process gets
1890 source files when working behind a firewall or proxy server,
1891 see this specific question in the
1892 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
1893 chapter.
1894 </para>
1895 </glossdef>
1896
1897 </glossentry>
1898 </glossdiv>
1899
1900 <glossdiv id='var-glossary-e'><title>E</title>
1901
1902 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
1903 <glossdef>
1904 <para></para>
1905 <para>Variable that controls which locales for
1906 <filename>eglibc</filename> are generated during the
1907 build (useful if the target device has 64Mbytes
1908 of RAM or less).</para>
1909 </glossdef>
1910 </glossentry>
1911
1912 <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
1913 <glossdef>
1914 <para>
1915 Specifies the quality assurance checks whose failures are
1916 reported as errors by the OpenEmbedded build system.
1917 You set this variable in your distribution configuration
1918 file.
1919 For a list of the checks you can control with this variable,
1920 see the
1921 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
1922 section.
1923 </para>
1924 </glossdef>
1925 </glossentry>
1926
1927 <glossentry id='var-ERR_REPORT_DIR'><glossterm>ERR_REPORT_DIR</glossterm>
1928 <glossdef>
1929 <para>
1930 When used with the
1931 <link linkend='ref-classes-report-error'><filename>report-error</filename></link>
1932 class, specifies the path used for storing the debug files
1933 created by the
1934 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
1935 which allows you to submit build errors you encounter to a
1936 central database.
1937 By default, the value of this variable is
1938 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
1939 </para>
1940
1941 <para>
1942 You can set <filename>ERR_REPORT_DIR</filename> to the path
1943 you want the error reporting tool to store the debug files
1944 as follows in your <filename>local.conf</filename> file:
1945 <literallayout class='monospaced'>
1946 ERR_REPORT_DIR = "path"
1947 </literallayout>
1948 </para>
1949 </glossdef>
1950 </glossentry>
1951
1952 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
1953 <glossdef>
1954 <para>
1955 Directs BitBake to exclude a recipe from world builds (i.e.
1956 <filename>bitbake world</filename>).
1957 During world builds, BitBake locates, parses and builds all
1958 recipes found in every layer exposed in the
1959 <filename>bblayers.conf</filename> configuration file.
1960 </para>
1961
1962 <para>
1963 To exclude a recipe from a world build using this variable,
1964 set the variable to "1" in the recipe.
1965 </para>
1966
1967 <note>
1968 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
1969 may still be built during a world build in order to satisfy
1970 dependencies of other recipes.
1971 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
1972 only ensures that the recipe is not explicitly added
1973 to the list of build targets in a world build.
1974 </note>
1975 </glossdef>
1976 </glossentry>
1977
1978 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
1979 <glossdef>
1980 <para>
1981 Used with file and pathnames to create a prefix for a recipe's
1982 version based on the recipe's
1983 <link linkend='var-PE'><filename>PE</filename></link> value.
1984 If <filename>PE</filename> is set and greater than zero for a recipe,
1985 <filename>EXTENDPE</filename> becomes that value (e.g if
1986 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
1987 becomes "1_").
1988 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
1989 zero, <filename>EXTENDPE</filename> becomes "".</para>
1990 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
1991 variable for an example.
1992 </para>
1993 </glossdef>
1994 </glossentry>
1995
1996 <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
1997 <glossdef>
1998 <para>
1999 The full package version specification as it appears on the
2000 final packages produced by a recipe.
2001 The variable's value is normally used to fix a runtime
2002 dependency to the exact same version of another package
2003 in the same recipe:
2004 <literallayout class='monospaced'>
2005 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
2006 </literallayout>
2007 </para>
2008
2009 <para>
2010 The dependency relationships are intended to force the
2011 package manager to upgrade these types of packages in
2012 lock-step.
2013 </para>
2014 </glossdef>
2015 </glossentry>
2016
2017 <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
2018 <glossdef>
2019 <para>
2020 If <filename>externalsrc.bbclass</filename> is inherited,
2021 this variable points to the source tree, which is
2022 outside of the OpenEmbedded build system.
2023 When set, this variable sets the
2024 <link linkend='var-S'><filename>S</filename></link>
2025 variable, which is what the OpenEmbedded build system uses
2026 to locate unpacked recipe source code.
2027 </para>
2028
2029 <para>
2030 For more information on
2031 <filename>externalsrc.bbclass</filename>, see the
2032 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
2033 section.
2034 You can also find information on how to use this variable
2035 in the
2036 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
2037 section in the Yocto Project Development Manual.
2038 </para>
2039 </glossdef>
2040 </glossentry>
2041
2042 <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
2043 <glossdef>
2044 <para>
2045 If <filename>externalsrc.bbclass</filename> is inherited,
2046 this variable points to the directory in which the recipe's
2047 source code is built,
2048 which is outside of the OpenEmbedded build system.
2049 When set, this variable sets the
2050 <link linkend='var-B'><filename>B</filename></link>
2051 variable, which is what the OpenEmbedded build system uses
2052 to locate the Build Directory.
2053 </para>
2054
2055 <para>
2056 For more information on
2057 <filename>externalsrc.bbclass</filename>, see the
2058 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
2059 section.
2060 You can also find information on how to use this variable
2061 in the
2062 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
2063 section in the Yocto Project Development Manual.
2064 </para>
2065 </glossdef>
2066 </glossentry>
2067
2068 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
2069 <glossdef>
2070 <para>
2071 The list of additional features to include in an image.
2072 Typically, you configure this variable in your
2073 <filename>local.conf</filename> file, which is found in the
2074 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2075 Although you can use this variable from within a recipe,
2076 best practices dictate that you do not.
2077 <note>
2078 To enable primary features from within the image
2079 recipe, use the
2080 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
2081 variable.
2082 </note>
2083 </para>
2084
2085 <para>
2086 Here are some examples of features you can add:
2087 <literallayout class='monospaced'>
2088"dbg-pkgs" - Adds -dbg packages for all installed packages
2089 including symbol information for debugging and
2090 profiling.
2091
2092"debug-tweaks" - Makes an image suitable for development.
2093 For example, ssh root access has a blank
2094 password. You should remove this feature
2095 before you produce a production image.
2096
2097"dev-pkgs" - Adds -dev packages for all installed packages.
2098 This is useful if you want to develop against
2099 the libraries in the image.
2100
2101"read-only-rootfs" - Creates an image whose root
2102 filesystem is read-only. See the
2103 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
2104 section in the Yocto Project
2105 Development Manual for more
2106 information
2107
2108"tools-debug" - Adds debugging tools such as gdb and
2109 strace.
2110
2111"tools-profile" - Adds profiling tools such as oprofile,
2112 exmap, lttng and valgrind (x86 only).
2113
2114"tools-sdk" - Adds development tools such as gcc, make,
2115 pkgconfig and so forth.
2116
2117"tools-testapps" - Adds useful testing tools such as
2118 ts_print, aplay, arecord and so
2119 forth.
2120
2121 </literallayout>
2122 </para>
2123
2124 <para>
2125 For a complete list of image features that ships with the
2126 Yocto Project, see the
2127 "<link linkend="ref-features-image">Image Features</link>"
2128 section.
2129 </para>
2130
2131 <para>
2132 For an example that shows how to customize your image by
2133 using this variable, see the
2134 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>"
2135 section in the Yocto Project Development Manual.
2136 </para>
2137 </glossdef>
2138 </glossentry>
2139
2140 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
2141 <glossdef>
2142 <para>A list of recipes to build that do not provide packages
2143 for installing into the root filesystem.
2144 </para>
2145 <para>Sometimes a recipe is required to build the final image but is not
2146 needed in the root filesystem.
2147 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
2148 list these recipes and thus specify the dependencies.
2149 A typical example is a required bootloader in a machine configuration.
2150 </para>
2151 <note>
2152 To add packages to the root filesystem, see the various
2153 <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
2154 and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
2155 variables.
2156 </note>
2157 </glossdef>
2158 </glossentry>
2159
2160 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
2161 <glossdef>
2162 <para>Additional <filename>cmake</filename> options.</para>
2163 </glossdef>
2164 </glossentry>
2165
2166 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
2167 <glossdef>
2168 <para>Additional <filename>configure</filename> script options.</para>
2169 </glossdef>
2170 </glossentry>
2171
2172 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
2173 <glossdef>
2174 <para>Additional GNU <filename>make</filename> options.</para>
2175 </glossdef>
2176 </glossentry>
2177
2178 <glossentry id='var-EXTRA_OESCONS'><glossterm>EXTRA_OESCONS</glossterm>
2179 <glossdef>
2180 <para>
2181 When a recipe inherits the
2182 <link linkend='ref-classes-scons'><filename>scons</filename></link>
2183 class, this variable specifies additional configuration
2184 options you want to pass to the
2185 <filename>scons</filename> command line.
2186 </para>
2187 </glossdef>
2188 </glossentry>
2189
2190 <glossentry id='var-EXTRA_QMAKEVARS_POST'><glossterm>EXTRA_QMAKEVARS_POST</glossterm>
2191 <glossdef>
2192 <para>
2193 Configuration variables or options you want to pass to
2194 <filename>qmake</filename>.
2195 Use this variable when the arguments need to be after the
2196 <filename>.pro</filename> file list on the command line.
2197 </para>
2198
2199 <para>
2200 This variable is used with recipes that inherit the
2201 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
2202 class or other classes that inherit
2203 <filename>qmake_base</filename>.
2204 </para>
2205 </glossdef>
2206 </glossentry>
2207
2208 <glossentry id='var-EXTRA_QMAKEVARS_PRE'><glossterm>EXTRA_QMAKEVARS_PRE</glossterm>
2209 <glossdef>
2210 <para>
2211 Configuration variables or options you want to pass to
2212 <filename>qmake</filename>.
2213 Use this variable when the arguments need to be before the
2214 <filename>.pro</filename> file list on the command line.
2215 </para>
2216
2217 <para>
2218 This variable is used with recipes that inherit the
2219 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
2220 class or other classes that inherit
2221 <filename>qmake_base</filename>.
2222 </para>
2223 </glossdef>
2224 </glossentry>
2225
2226 <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm>
2227 <glossdef>
2228 <para>
2229 When a recipe inherits the
2230 <link linkend='ref-classes-extrausers'><filename>extrausers</filename></link>
2231 class, this variable provides image level user and group
2232 operations.
2233 This is a more global method of providing user and group
2234 configuration as compared to using the
2235 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
2236 class, which ties user and group configurations to a
2237 specific recipe.
2238 </para>
2239
2240 <para>
2241 The set list of commands you can configure using the
2242 <filename>EXTRA_USERS_PARAMS</filename> is shown in the
2243 <filename>extrausers</filename> class.
2244 These commands map to the normal Unix commands of the same
2245 names:
2246 <literallayout class='monospaced'>
2247 # EXTRA_USERS_PARAMS = "\
2248 # useradd -p '' tester; \
2249 # groupadd developers; \
2250 # userdel nobody; \
2251 # groupdel -g video; \
2252 # groupmod -g 1020 developers; \
2253 # usermod -s /bin/sh tester; \
2254 # "
2255 </literallayout>
2256 </para>
2257 </glossdef>
2258 </glossentry>
2259
2260 </glossdiv>
2261
2262 <glossdiv id='var-glossary-f'><title>F</title>
2263
2264 <glossentry id='var-FEATURE_PACKAGES'><glossterm>FEATURE_PACKAGES</glossterm>
2265 <glossdef>
2266 <para>
2267 Defines one or more packages to include in an image when
2268 a specific item is included in
2269 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
2270 When setting the value, <filename>FEATURE_PACKAGES</filename>
2271 should have the name of the feature item as an override.
2272 Here is an example:
2273 <literallayout class='monospaced'>
2274 FEATURE_PACKAGES_widget = "package1 package2"
2275 </literallayout>
2276 In this example, if "widget" were added to
2277 <filename>IMAGE_FEATURES</filename>, "package1" and
2278 "package2" would be included in the image.
2279 <note>
2280 Packages installed by features defined through
2281 <filename>FEATURE_PACKAGES</filename> are often package
2282 groups.
2283 While similarly named, you should not confuse the
2284 <filename>FEATURE_PACKAGES</filename> variable with
2285 package groups, which are discussed elsewhere in the
2286 documentation.
2287 </note>
2288 </para>
2289 </glossdef>
2290 </glossentry>
2291
2292 <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm>
2293 <glossdef>
2294 <para>
2295 Points to the base URL of the server and location within
2296 the document-root that provides the metadata and
2297 packages required by OPKG to support runtime package
2298 management of IPK packages.
2299 You set this variable in your
2300 <filename>local.conf</filename> file.
2301 </para>
2302
2303 <para>
2304 Consider the following example:
2305 <literallayout class='monospaced'>
2306 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
2307 </literallayout>
2308 This example assumes you are serving your packages over
2309 HTTP and your databases are located in a directory
2310 named <filename>BOARD-dir</filename>, which is underneath
2311 your HTTP server's document-root.
2312 In this case, the OpenEmbedded build system generates a set
2313 of configuration files for you in your target that work
2314 with the feed.
2315 </para>
2316 </glossdef>
2317 </glossentry>
2318
2319 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
2320 <glossdef>
2321 <para>
2322 The list of directories or files that are placed in packages.
2323 </para>
2324
2325 <para>
2326 To use the <filename>FILES</filename> variable, provide a package name
2327 override that identifies the resulting package.
2328 Then, provide a space-separated list of files or paths that identifies the
2329 files you want included as part of the resulting package.
2330 Here is an example:
2331 <literallayout class='monospaced'>
2332 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
2333 </literallayout>
2334 </para>
2335
2336 <note>
2337 When specifying paths as part of the <filename>FILES</filename> variable,
2338 it is good practice to use appropriate path variables.
2339 For example, use <filename>${sysconfdir}</filename> rather than
2340 <filename>/etc</filename>, or <filename>${bindir}</filename> rather
2341 than <filename>/usr/bin</filename>.
2342 You can find a list of these variables at the top of the
2343 <filename>meta/conf/bitbake.conf</filename> file in the
2344 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2345 </note>
2346
2347 <para>
2348 If some of the files you provide with the <filename>FILES</filename> variable
2349 are editable and you know they should not be
2350 overwritten during the package update process by the Package Management
2351 System (PMS), you can identify these files so that the PMS will not
2352 overwrite them.
2353 See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename>
2354 variable for information on how to identify these files to the PMS.
2355 </para>
2356
2357 </glossdef>
2358 </glossentry>
2359
2360 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
2361 <glossdef>
2362 <para>
2363 Extends the search path the OpenEmbedded build system uses
2364 when looking for files and patches as it processes recipes
2365 and append files.
2366 The default directories BitBake uses when it processes
2367 recipes are initially defined by the
2368 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
2369 variable.
2370 You can extend <filename>FILESPATH</filename> variable
2371 by using <filename>FILESEXTRAPATHS</filename>.
2372 </para>
2373
2374 <para>
2375 Best practices dictate that you accomplish this by using
2376 <filename>FILESEXTRAPATHS</filename> from within a
2377 <filename>.bbappend</filename> file and that you prepend
2378 paths as follows:
2379 <literallayout class='monospaced'>
2380 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
2381 </literallayout>
2382 In the above example, the build system first looks for files
2383 in a directory that has the same name as the corresponding
2384 append file.
2385 <note>
2386 <para>When extending <filename>FILESEXTRAPATHS</filename>,
2387 be sure to use the immediate expansion
2388 (<filename>:=</filename>) operator.
2389 Immediate expansion makes sure that BitBake evaluates
2390 <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
2391 at the time the directive is encountered rather than at
2392 some later time when expansion might result in a
2393 directory that does not contain the files you need.
2394 </para>
2395 <para>Also, include the trailing separating colon
2396 character if you are prepending.
2397 The trailing colon character is necessary because you
2398 are directing BitBake to extend the path by prepending
2399 directories to the search path.</para>
2400 </note>
2401 Here is another common use:
2402 <literallayout class='monospaced'>
2403 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
2404 </literallayout>
2405 In this example, the build system extends the
2406 <filename>FILESPATH</filename> variable to include a
2407 directory named <filename>files</filename> that is in the
2408 same directory as the corresponding append file.
2409 </para>
2410
2411 <para>
2412 Here is a final example that specifically adds three paths:
2413 <literallayout class='monospaced'>
2414 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
2415 </literallayout>
2416 </para>
2417
2418 <para>
2419 By prepending paths in <filename>.bbappend</filename>
2420 files, you allow multiple append files that reside in
2421 different layers but are used for the same recipe to
2422 correctly extend the path.
2423 </para>
2424 </glossdef>
2425 </glossentry>
2426
2427 <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
2428 <glossdef>
2429 <para>
2430 A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
2431 used by the OpenEmbedded build system for creating
2432 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
2433 You can find more information on how overrides are handled
2434 in the BitBake Manual that is located at
2435 <filename>bitbake/doc/manual</filename> in the
2436 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2437 </para>
2438
2439 <para>
2440 By default, the <filename>FILESOVERRIDES</filename>
2441 variable is defined as:
2442 <literallayout class='monospaced'>
2443 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
2444 </literallayout>
2445
2446 <note>
2447 Do not hand-edit the <filename>FILESOVERRIDES</filename>
2448 variable.
2449 The values match up with expected overrides and are
2450 used in an expected manner by the build system.
2451 </note>
2452 </para>
2453 </glossdef>
2454 </glossentry>
2455
2456 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
2457 <glossdef>
2458 <para>
2459 The default set of directories the OpenEmbedded build system
2460 uses when searching for patches and files.
2461 During the build process, BitBake searches each directory in
2462 <filename>FILESPATH</filename> in the specified order when
2463 looking for files and patches specified by each
2464 <filename>file://</filename> URI in a recipe.
2465 </para>
2466
2467 <para>
2468 The default value for the <filename>FILESPATH</filename>
2469 variable is defined in the <filename>base.bbclass</filename>
2470 class found in <filename>meta/classes</filename> in the
2471 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
2472 <literallayout class='monospaced'>
2473 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
2474 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
2475 </literallayout>
2476 <note>
2477 Do not hand-edit the <filename>FILESPATH</filename>
2478 variable.
2479 If you want the build system to look in directories
2480 other than the defaults, extend the
2481 <filename>FILESPATH</filename> variable by using the
2482 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
2483 variable.
2484 </note>
2485 Be aware that the default <filename>FILESPATH</filename>
2486 directories do not map to directories in custom layers
2487 where append files (<filename>.bbappend</filename>)
2488 are used.
2489 If you want the build system to find patches or files
2490 that reside with your append files, you need to extend
2491 the <filename>FILESPATH</filename> variable by using
2492 the
2493 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
2494 variable.
2495 </para>
2496 </glossdef>
2497 </glossentry>
2498
2499 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
2500 <glossdef>
2501 <para>Allows you to define your own file permissions settings table as part of
2502 your configuration for the packaging process.
2503 For example, suppose you need a consistent set of custom permissions for
2504 a set of groups and users across an entire work project.
2505 It is best to do this in the packages themselves but this is not always
2506 possible.
2507 </para>
2508 <para>
2509 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
2510 is located in the <filename>meta/files</filename> folder in the
2511 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2512 If you create your own file permissions setting table, you should place it in your
2513 layer or the distro's layer.
2514 </para>
2515 <para>
2516 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
2517 <filename>conf/local.conf</filename> file, which is found in the
2518 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to
2519 point to your custom <filename>fs-perms.txt</filename>.
2520 You can specify more than a single file permissions setting table.
2521 The paths you specify to these files must be defined within the
2522 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
2523 </para>
2524 <para>
2525 For guidance on how to create your own file permissions settings table file,
2526 examine the existing <filename>fs-perms.txt</filename>.
2527 </para>
2528 </glossdef>
2529 </glossentry>
2530
2531 <glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm>
2532 <glossdef>
2533 <para>
2534 When a recipe inherits the
2535 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
2536 class, this variable identifies packages containing font
2537 files that need to be cached by Fontconfig.
2538 By default, the <filename>fontcache</filename> class assumes
2539 that fonts are in the recipe's main package
2540 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
2541 Use this variable if fonts you need are in a package
2542 other than that main package.
2543 </para>
2544 </glossdef>
2545 </glossentry>
2546
2547 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
2548 <glossdef>
2549 <para>
2550 The options to pass in
2551 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
2552 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
2553 when compiling an optimized system.
2554 This variable defaults to
2555 "-O2 -pipe ${DEBUG_FLAGS}".
2556 </para>
2557 </glossdef>
2558 </glossentry>
2559 </glossdiv>
2560
2561 <glossdiv id='var-glossary-g'><title>G</title>
2562
2563 <glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm>
2564 <glossdef>
2565 <para>
2566 When a recipe inherits the
2567 <filename>useradd</filename> class, this variable
2568 specifies for a package what parameters should be passed
2569 to the <filename>groupadd</filename> command
2570 if you wish to add a group to the system when the package
2571 is installed.
2572 </para>
2573
2574 <para>
2575 Here is an example from the <filename>dbus</filename>
2576 recipe:
2577 <literallayout class='monospaced'>
2578 GROUPADD_PARAM_${PN} = "-r netdev"
2579 </literallayout>
2580 For information on the standard Linux shell command
2581 <filename>groupadd</filename>, see
2582 <ulink url='http://linux.die.net/man/8/groupadd'></ulink>.
2583 </para>
2584 </glossdef>
2585 </glossentry>
2586
2587 <glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm>
2588 <glossdef>
2589 <para>
2590 When a recipe inherits the
2591 <filename>useradd</filename> class, this variable
2592 specifies for a package what parameters should be passed
2593 to the <filename>groupmems</filename> command
2594 if you wish to modify the members of a group when the
2595 package is installed.
2596 </para>
2597
2598 <para>
2599 For information on the standard Linux shell command
2600 <filename>groupmems</filename>, see
2601 <ulink url='http://linux.die.net/man/8/groupmems'></ulink>.
2602 </para>
2603 </glossdef>
2604 </glossentry>
2605
2606 <glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm>
2607 <glossdef>
2608 <para>
2609 Configures the GNU GRand Unified Bootloader (GRUB) to have
2610 graphics and serial in the boot menu.
2611 Set this variable to "1" in your
2612 <filename>local.conf</filename> or distribution
2613 configuration file to enable graphics and serial
2614 in the menu.
2615 </para>
2616
2617 <para>
2618 See the
2619 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2620 class for more information on how this variable is used.
2621 </para>
2622 </glossdef>
2623 </glossentry>
2624
2625 <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm>
2626 <glossdef>
2627 <para>
2628 Additional options to add to the GNU GRand Unified
2629 Bootloader (GRUB) configuration.
2630 Use a semi-colon character (<filename>;</filename>) to
2631 separate multiple options.
2632 </para>
2633
2634 <para>
2635 The <filename>GRUB_OPTS</filename> variable is optional.
2636 See the
2637 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2638 class for more information on how this variable is used.
2639 </para>
2640 </glossdef>
2641 </glossentry>
2642
2643 <glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm>
2644 <glossdef>
2645 <para>
2646 Specifies the timeout before executing the default
2647 <filename>LABEL</filename> in the GNU GRand Unified
2648 Bootloader (GRUB).
2649 </para>
2650
2651 <para>
2652 The <filename>GRUB_TIMEOUT</filename> variable is optional.
2653 See the
2654 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
2655 class for more information on how this variable is used.
2656 </para>
2657 </glossdef>
2658 </glossentry>
2659
2660 <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm>
2661 <glossdef>
2662 <para>
2663 For recipes that inherit the
2664 <link linkend='ref-classes-gtk-immodules-cache'><filename>gtk-immodules-cache</filename></link>
2665 class, this variable specifies the packages that contain the
2666 GTK+ input method modules being installed when the modules
2667 are in packages other than the main package.
2668 </para>
2669 </glossdef>
2670 </glossentry>
2671
2672 </glossdiv>
2673
2674 <glossdiv id='var-glossary-h'><title>H</title>
2675
2676 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
2677 <glossdef>
2678 <para>Website where more information about the software the recipe is building
2679 can be found.</para>
2680 </glossdef>
2681 </glossentry>
2682
2683 <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
2684 <glossdef>
2685 <para>
2686 Specifies the system, including the architecture and the
2687 operating system, for with the build is occurring
2688 in the context of the current
2689 recipe.
2690 The OpenEmbedded build system automatically sets this
2691 variable.
2692 You do not need to set the variable yourself.
2693 </para>
2694
2695 <para>
2696 Here are two examples:
2697 <itemizedlist>
2698 <listitem><para>Given a native recipe on a 32-bit
2699 x86 machine running Linux, the value is
2700 "i686-linux".
2701 </para></listitem>
2702 <listitem><para>Given a recipe being built for a
2703 little-endian MIPS target running Linux,
2704 the value might be "mipsel-linux".
2705 </para></listitem>
2706 </itemizedlist>
2707 </para>
2708 </glossdef>
2709 </glossentry>
2710
2711 </glossdiv>
2712
2713 <glossdiv id='var-glossary-i'><title>I</title>
2714
2715 <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm>
2716 <glossdef>
2717 <para>
2718 Disables or enables the <filename>icecc</filename>
2719 (Icecream) function.
2720 For more information on this function and best practices
2721 for using this variable, see the
2722 "<link linkend='ref-classes-icecc'><filename>icecc.bbclass</filename></link>"
2723 section.
2724 </para>
2725
2726 <para>
2727 Setting this variable to "1" in your
2728 <filename>local.conf</filename> disables the function:
2729 <literallayout class='monospaced'>
2730 ICECC_DISABLED ??= "1"
2731 </literallayout>
2732 To enable the function, set the variable as follows:
2733 <literallayout class='monospaced'>
2734 ICECC_DISABLED = ""
2735 </literallayout>
2736 </para>
2737 </glossdef>
2738 </glossentry>
2739
2740 <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm>
2741 <glossdef>
2742 <para>
2743 Points to the <filename>icecc-create-env</filename> script
2744 that you provide.
2745 This variable is used by the
2746 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2747 class.
2748 You set this variable in your
2749 <filename>local.conf</filename> file.
2750 </para>
2751
2752 <para>
2753 If you do not point to a script that you provide, the
2754 OpenEmbedded build system uses the default script provided
2755 by the <filename>icecc-create-env.bb</filename> recipe,
2756 which is a modified version and not the one that comes with
2757 <filename>icecc</filename>.
2758 </para>
2759 </glossdef>
2760 </glossentry>
2761
2762 <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm>
2763 <glossdef>
2764 <para>
2765 Extra options passed to the <filename>make</filename>
2766 command during the <filename>do_compile</filename> task
2767 that specify parallel compilation.
2768 This variable usually takes the form of
2769 <filename>-j 4</filename>, where the number
2770 represents the maximum number of parallel threads
2771 <filename>make</filename> can run.
2772 <note>
2773 The options passed affect builds on all enabled
2774 machines on the network, which are machines running the
2775 <filename>iceccd</filename> daemon.
2776 </note>
2777 </para>
2778
2779 <para>
2780 If your enabled machines support multiple cores,
2781 coming up with the maximum number of parallel threads
2782 that gives you the best performance could take some
2783 experimentation since machine speed, network lag,
2784 available memory, and existing machine loads can all
2785 affect build time.
2786 Consequently, unlike the
2787 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
2788 variable, there is no rule-of-thumb for setting
2789 <filename>ICECC_PARALLEL_MAKE</filename> to achieve
2790 optimal performance.
2791 </para>
2792
2793 <para>
2794 If you do not set <filename>ICECC_PARALLEL_MAKE</filename>,
2795 the build system does not use it (i.e. the system does
2796 not detect and assign the number of cores as is done with
2797 <filename>PARALLEL_MAKE</filename>).
2798 </para>
2799 </glossdef>
2800 </glossentry>
2801
2802 <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm>
2803 <glossdef>
2804 <para>
2805 The location of the <filename>icecc</filename> binary.
2806 You can set this variable in your
2807 <filename>local.conf</filename> file.
2808 If your <filename>local.conf</filename> file does not define
2809 this variable, the
2810 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2811 class attempts to define it by locating
2812 <filename>icecc</filename> using <filename>which</filename>.
2813 </para>
2814 </glossdef>
2815 </glossentry>
2816
2817 <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm>
2818 <glossdef>
2819 <para>
2820 Identifies user classes that you do not want the
2821 Icecream distributed compile support to consider.
2822 This variable is used by the
2823 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2824 class.
2825 You set this variable in your
2826 <filename>local.conf</filename> file.
2827 </para>
2828
2829 <para>
2830 When you list classes using this variable, you are
2831 "blacklisting" them from distributed compilation across
2832 remote hosts.
2833 Any classes you list will be distributed and compiled
2834 locally.
2835 </para>
2836 </glossdef>
2837 </glossentry>
2838
2839 <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm>
2840 <glossdef>
2841 <para>
2842 Identifies user recipes that you do not want the
2843 Icecream distributed compile support to consider.
2844 This variable is used by the
2845 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2846 class.
2847 You set this variable in your
2848 <filename>local.conf</filename> file.
2849 </para>
2850
2851 <para>
2852 When you list packages using this variable, you are
2853 "blacklisting" them from distributed compilation across
2854 remote hosts.
2855 Any packages you list will be distributed and compiled
2856 locally.
2857 </para>
2858 </glossdef>
2859 </glossentry>
2860
2861 <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm>
2862 <glossdef>
2863 <para>
2864 Identifies user recipes that use an empty
2865 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
2866 variable that you want to force remote distributed
2867 compilation on using the Icecream distributed compile
2868 support.
2869 This variable is used by the
2870 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
2871 class.
2872 You set this variable in your
2873 <filename>local.conf</filename> file.
2874 </para>
2875 </glossdef>
2876 </glossentry>
2877
2878 <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
2879 <glossdef>
2880 <para>
2881 The base name of image output files.
2882 This variable defaults to the recipe name
2883 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
2884 </para>
2885 </glossdef>
2886 </glossentry>
2887
2888 <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
2889 <glossdef>
2890 <para>
2891 A list of classes that all images should inherit.
2892 You typically use this variable to specify the list of
2893 classes that register the different types of images
2894 the OpenEmbedded build system creates.
2895 </para>
2896
2897 <para>
2898 The default value for <filename>IMAGE_CLASSES</filename> is
2899 <filename>image_types</filename>.
2900 You can set this variable in your
2901 <filename>local.conf</filename> or in a distribution
2902 configuration file.
2903 </para>
2904
2905 <para>
2906 For more information, see
2907 <filename>meta/classes/image_types.bbclass</filename> in the
2908 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2909 </para>
2910 </glossdef>
2911 </glossentry>
2912
2913 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
2914 <glossdef>
2915 <para>
2916 The primary list of features to include in an image.
2917 Typically, you configure this variable in an image recipe.
2918 Although you can use this variable from your
2919 <filename>local.conf</filename> file, which is found in the
2920 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
2921 best practices dictate that you do not.
2922 <note>
2923 To enable extra features from outside the image recipe,
2924 use the
2925 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
2926 </note>
2927 For a list of image features that ships with the Yocto
2928 Project, see the
2929 "<link linkend="ref-features-image">Image Features</link>"
2930 section.
2931 </para>
2932
2933 <para>
2934 For an example that shows how to customize your image by
2935 using this variable, see the
2936 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>"
2937 section in the Yocto Project Development Manual.
2938 </para>
2939 </glossdef>
2940 </glossentry>
2941
2942 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
2943 <glossdef>
2944 <para>
2945 Specifies the formats the OpenEmbedded build system uses
2946 during the build when creating the root filesystem.
2947 For example, setting <filename>IMAGE_FSTYPES</filename>
2948 as follows causes the build system to create root
2949 filesystems using two formats: <filename>.ext3</filename>
2950 and <filename>.tar.bz2</filename>:
2951 <literallayout class='monospaced'>
2952 IMAGE_FSTYPES = "ext3 tar.bz2"
2953 </literallayout>
2954 For the complete list of supported image formats from which
2955 you can choose, see
2956 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
2957 </para>
2958
2959 <note>
2960 If you add "live" to <filename>IMAGE_FSTYPES</filename>
2961 inside an image recipe, be sure that you do so prior to the
2962 "inherit image" line of the recipe or the live image will
2963 not build.
2964 </note>
2965
2966 <note>
2967 Due to the way this variable is processed, it is not
2968 possible to update its contents using
2969 <filename>_append</filename> or
2970 <filename>_prepend</filename>. To add one or more
2971 additional options to this variable the
2972 <filename>+=</filename> operator must be used.
2973 </note>
2974 </glossdef>
2975 </glossentry>
2976
2977 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
2978 <glossdef>
2979 <para>
2980 Specifies the packages to install into an image.
2981 The <filename>IMAGE_INSTALL</filename> variable is a
2982 mechanism for an image recipe and you should use it
2983 with care to avoid ordering issues.
2984 <note>
2985 When working with an
2986 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
2987 image, do not use the <filename>IMAGE_INSTALL</filename>
2988 variable to specify packages for installation.
2989 Instead, use the
2990 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
2991 variable, which allows the initial RAM disk (initramfs)
2992 recipe to use a fixed set of packages and not be
2993 affected by <filename>IMAGE_INSTALL</filename>.
2994 </note>
2995 </para>
2996
2997 <para>
2998 Image recipes set <filename>IMAGE_INSTALL</filename>
2999 to specify the packages to install into an image through
3000 <filename>image.bbclass</filename>.
3001 Additionally, "helper" classes exist, such as
3002 <filename>core-image.bbclass</filename>, that can take
3003 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
3004 lists and turn these into auto-generated entries in
3005 <filename>IMAGE_INSTALL</filename> in addition to its
3006 default contents.
3007 </para>
3008
3009 <para>
3010 Using <filename>IMAGE_INSTALL</filename> with the
3011 <filename>+=</filename> operator from the
3012 <filename>/conf/local.conf</filename> file or from within
3013 an image recipe is not recommended as it can cause ordering
3014 issues.
3015 Since <filename>core-image.bbclass</filename> sets
3016 <filename>IMAGE_INSTALL</filename> to a default value using
3017 the <filename>?=</filename> operator, using a
3018 <filename>+=</filename> operation against
3019 <filename>IMAGE_INSTALL</filename> will result in
3020 unexpected behavior when used in
3021 <filename>conf/local.conf</filename>.
3022 Furthermore, the same operation from within an image
3023 recipe may or may not succeed depending on the specific
3024 situation.
3025 In both these cases, the behavior is contrary to how most
3026 users expect the <filename>+=</filename> operator to work.
3027 </para>
3028
3029 <para>
3030 When you use this variable, it is best to use it as follows:
3031 <literallayout class='monospaced'>
3032 IMAGE_INSTALL_append = " package-name"
3033 </literallayout>
3034 Be sure to include the space between the quotation character
3035 and the start of the package name or names.
3036 </para>
3037 </glossdef>
3038 </glossentry>
3039
3040 <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
3041 <glossdef>
3042 <para>
3043 Specifies the list of locales to install into the image
3044 during the root filesystem construction process.
3045 The OpenEmbedded build system automatically splits locale
3046 files, which are used for localization, into separate
3047 packages.
3048 Setting the <filename>IMAGE_LINGUAS</filename> variable
3049 ensures that any locale packages that correspond to packages
3050 already selected for installation into the image are also
3051 installed.
3052 Here is an example:
3053 <literallayout class='monospaced'>
3054 IMAGE_LINGUAS = "pt-br de-de"
3055 </literallayout>
3056 In this example, the build system ensures any Brazilian
3057 Portuguese and German locale files that correspond to
3058 packages in the image are installed (i.e.
3059 <filename>*-locale-pt-br</filename>
3060 and <filename>*-locale-de-de</filename> as well as
3061 <filename>*-locale-pt</filename>
3062 and <filename>*-locale-de</filename>, since some software
3063 packages only provide locale files by language and not by
3064 country-specific language).
3065 </para>
3066 </glossdef>
3067 </glossentry>
3068
3069 <glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm>
3070 <glossdef>
3071 <para>
3072 The manifest file for the image.
3073 This file lists all the installed packages that make up
3074 the image.
3075 The file contains package information on a line-per-package
3076 basis as follows:
3077 <literallayout class='monospaced'>
3078 &lt;packagename&gt; &lt;packagearch&gt; &lt;version&gt;
3079 </literallayout>
3080 </para>
3081
3082 <para>
3083 The
3084 <link linkend='ref-classes-image'><filename>image</filename></link>
3085 class defines the manifest file as follows:
3086 <literallayout class='monospaced'>
3087 IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"
3088 </literallayout>
3089 The location is derived using the
3090 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
3091 and
3092 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>
3093 variables.
3094 You can find information on how the image
3095 is created in the
3096 "<link linkend='image-generation-dev-environment'>Image Generation</link>"
3097 section.
3098 </para>
3099 </glossdef>
3100 </glossentry>
3101
3102 <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
3103 <glossdef>
3104 <para>
3105 The name of the output image files minus the extension.
3106 This variable is derived using the
3107 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
3108 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
3109 and
3110 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
3111 variables:
3112 <literallayout class='monospaced'>
3113 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
3114 </literallayout>
3115 </para>
3116 </glossdef>
3117 </glossentry>
3118
3119 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
3120 <glossdef>
3121 <para>
3122 Defines a multiplier that the build system applies to the initial image
3123 size for cases when the multiplier times the returned disk usage value
3124 for the image is greater than the sum of
3125 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
3126 and
3127 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
3128 The result of the multiplier applied to the initial image size creates
3129 free disk space in the image as overhead.
3130 By default, the build process uses a multiplier of 1.3 for this variable.
3131 This default value results in 30% free disk space added to the image when this
3132 method is used to determine the final generated image size.
3133 You should be aware that post install scripts and the package management
3134 system uses disk space inside this overhead area.
3135 Consequently, the multiplier does not produce an image with
3136 all the theoretical free disk space.
3137 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
3138 for information on how the build system determines the overall image size.
3139 </para>
3140
3141 <para>
3142 The default 30% free disk space typically gives the image enough room to boot
3143 and allows for basic post installs while still leaving a small amount of
3144 free disk space.
3145 If 30% free space is inadequate, you can increase the default value.
3146 For example, the following setting gives you 50% free space added to the image:
3147 <literallayout class='monospaced'>
3148 IMAGE_OVERHEAD_FACTOR = "1.5"
3149 </literallayout>
3150 </para>
3151
3152 <para>
3153 Alternatively, you can ensure a specific amount of free disk space is added
3154 to the image by using the
3155 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
3156 variable.
3157 </para>
3158 </glossdef>
3159 </glossentry>
3160
3161 <glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm>
3162 <glossdef>
3163 <para>
3164 Defines the package type (DEB, RPM, IPK, or TAR) used
3165 by the OpenEmbedded build system.
3166 The variable is defined appropriately by the
3167 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
3168 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
3169 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
3170 or
3171 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
3172 class.
3173 </para>
3174
3175 <para>
3176 The
3177 <link linkend='ref-classes-populate-sdk-*'><filename>package_sdk_base</filename></link>
3178 and
3179 <link linkend='ref-classes-image'><filename>image</filename></link>
3180 classes use the <filename>IMAGE_PKGTYPE</filename> for
3181 packaging up images and SDKs.
3182 </para>
3183
3184 <para>
3185 You should not set the <filename>IMAGE_PKGTYPE</filename>
3186 manually.
3187 Rather, the variable is set indirectly through the
3188 appropriate
3189 <link linkend='ref-classes-package'><filename>package_*</filename></link>
3190 class using the
3191 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3192 variable.
3193 The OpenEmbedded build system uses the first package type
3194 (e.g. DEB, RPM, or IPK) that appears with the variable
3195 <note>
3196 Files using the <filename>.tar</filename> format are
3197 never used as a substitute packaging format for DEB,
3198 RPM, and IPK formatted files for your image or SDK.
3199 </note>
3200 </para>
3201 </glossdef>
3202 </glossentry>
3203
3204 <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
3205 <glossdef>
3206 <para>
3207 Added by classes to run post processing commands once the
3208 OpenEmbedded build system has created the image.
3209 You can specify shell commands separated by semicolons:
3210 <literallayout class='monospaced'>
3211 IMAGE_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
3212 </literallayout>
3213 If you need to pass the path to the root filesystem within
3214 the command, you can use
3215 <filename>${IMAGE_ROOTFS}</filename>, which points to
3216 the root filesystem image.
3217 </para>
3218 </glossdef>
3219 </glossentry>
3220
3221 <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
3222 <glossdef>
3223 <para>
3224 The location of the root filesystem while it is under
3225 construction (i.e. during <filename>do_rootfs</filename>).
3226 This variable is not configurable.
3227 Do not change it.
3228 </para>
3229 </glossdef>
3230 </glossentry>
3231
3232 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
3233 <glossdef>
3234 <para>
3235 Defines additional free disk space created in the image in Kbytes.
3236 By default, this variable is set to "0".
3237 This free disk space is added to the image after the build system determines
3238 the image size as described in
3239 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
3240 </para>
3241
3242 <para>
3243 This variable is particularly useful when you want to ensure that a
3244 specific amount of free disk space is available on a device after an image
3245 is installed and running.
3246 For example, to be sure 5 Gbytes of free disk space is available, set the
3247 variable as follows:
3248 <literallayout class='monospaced'>
3249 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
3250 </literallayout>
3251 </para>
3252
3253 <para>
3254 For example, the Yocto Project Build Appliance specifically requests 40 Gbytes
3255 of extra space with the line:
3256 <literallayout class='monospaced'>
3257 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
3258 </literallayout>
3259 </para>
3260 </glossdef>
3261 </glossentry>
3262
3263 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
3264 <glossdef>
3265 <para>
3266 Defines the size in Kbytes for the generated image.
3267 The OpenEmbedded build system determines the final size for the generated
3268 image using an algorithm that takes into account the initial disk space used
3269 for the generated image, a requested size for the image, and requested
3270 additional free disk space to be added to the image.
3271 Programatically, the build system determines the final size of the
3272 generated image as follows:
3273 <literallayout class='monospaced'>
3274 if (image-du * overhead) &lt; rootfs-size:
3275 internal-rootfs-size = rootfs-size + xspace
3276 else:
3277 internal-rootfs-size = (image-du * overhead) + xspace
3278
3279 where:
3280
3281 image-du = Returned value of the du command on
3282 the image.
3283
3284 overhead = IMAGE_OVERHEAD_FACTOR
3285
3286 rootfs-size = IMAGE_ROOTFS_SIZE
3287
3288 internal-rootfs-size = Initial root filesystem
3289 size before any modifications.
3290
3291 xspace = IMAGE_ROOTFS_EXTRA_SPACE
3292 </literallayout>
3293 See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
3294 and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
3295 variables for related information.
3296<!-- In the above example, <filename>overhead</filename> is defined by the
3297 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
3298 variable, <filename>xspace</filename> is defined by the
3299 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
3300 variable, and <filename>du</filename> is the results of the disk usage command
3301 on the initially generated image. -->
3302 </para>
3303 </glossdef>
3304 </glossentry>
3305
3306 <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm>
3307 <glossdef>
3308 <para>
3309 Specifies a dependency from one image type on another.
3310 Here is an example from the
3311 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
3312 class:
3313 <literallayout class='monospaced'>
3314 IMAGE_TYPEDEP_live = "ext3"
3315 </literallayout>
3316 In the previous example, the variable ensures that when
3317 "live" is listed with the
3318 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
3319 variable, the OpenEmbedded build system produces an
3320 <filename>ext3</filename> image first since one of the
3321 components of the live
3322 image is an <filename>ext3</filename>
3323 formatted partition containing the root
3324 filesystem.
3325 </para>
3326 </glossdef>
3327 </glossentry>
3328
3329 <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
3330 <glossdef>
3331 <para>
3332 Specifies the complete list of supported image types
3333 by default:
3334 <literallayout class='monospaced'>
3335 jffs2
3336 jffs2.sum
3337 cramfs
3338 ext2
3339 ext2.gz
3340 ext2.bz2
3341 ext3
3342 ext3.gz
3343 ext2.lzma
3344 btrfs
3345 live
3346 squashfs
3347 squashfs-xz
3348 ubi
3349 ubifs
3350 tar
3351 tar.gz
3352 tar.bz2
3353 tar.xz
3354 cpio
3355 cpio.gz
3356 cpio.xz
3357 cpio.lzma
3358 vmdk
3359 elf
3360 </literallayout>
3361 For more information on how these types of images, see
3362 <filename>meta/classes/image_types*.bbclass</filename>
3363 in the
3364 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
3365 </para>
3366 </glossdef>
3367 </glossentry>
3368
3369 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
3370 <glossdef>
3371 <para>Helps define the recipe revision for recipes that share
3372 a common <filename>include</filename> file.
3373 You can think of this variable as part of the recipe revision
3374 as set from within an include file.</para>
3375 <para>Suppose, for example, you have a set of recipes that
3376 are used across several projects.
3377 And, within each of those recipes the revision
3378 (its <link linkend='var-PR'><filename>PR</filename></link>
3379 value) is set accordingly.
3380 In this case, when the revision of those recipes changes,
3381 the burden is on you to find all those recipes and
3382 be sure that they get changed to reflect the updated
3383 version of the recipe.
3384 In this scenario, it can get complicated when recipes
3385 that are used in many places and provide common functionality
3386 are upgraded to a new revision.</para>
3387 <para>A more efficient way of dealing with this situation is
3388 to set the <filename>INC_PR</filename> variable inside
3389 the <filename>include</filename> files that the recipes
3390 share and then expand the <filename>INC_PR</filename>
3391 variable within the recipes to help
3392 define the recipe revision.
3393 </para>
3394 <para>
3395 The following provides an example that shows how to use
3396 the <filename>INC_PR</filename> variable
3397 given a common <filename>include</filename> file that
3398 defines the variable.
3399 Once the variable is defined in the
3400 <filename>include</filename> file, you can use the
3401 variable to set the <filename>PR</filename> values in
3402 each recipe.
3403 You will notice that when you set a recipe's
3404 <filename>PR</filename> you can provide more granular
3405 revisioning by appending values to the
3406 <filename>INC_PR</filename> variable:
3407 <literallayout class='monospaced'>
3408recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
3409recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
3410recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
3411recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
3412 </literallayout>
3413 The first line of the example establishes the baseline
3414 revision to be used for all recipes that use the
3415 <filename>include</filename> file.
3416 The remaining lines in the example are from individual
3417 recipes and show how the <filename>PR</filename> value
3418 is set.</para>
3419 </glossdef>
3420 </glossentry>
3421
3422 <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
3423 <glossdef>
3424 <para>
3425 Specifies a space-separated list of license names
3426 (as they would appear in
3427 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
3428 that should be excluded from the build.
3429 Recipes that provide no alternatives to listed incompatible
3430 licenses are not built.
3431 Packages that are individually licensed with the specified
3432 incompatible licenses will be deleted.
3433 </para>
3434
3435 <note>
3436 This functionality is only regularly tested using
3437 the following setting:
3438 <literallayout class='monospaced'>
3439 INCOMPATIBLE_LICENSE = "GPLv3"
3440 </literallayout>
3441 Although you can use other settings, you might be required
3442 to remove dependencies on or provide alternatives to
3443 components that are required to produce a functional system
3444 image.
3445 </note>
3446 </glossdef>
3447 </glossentry>
3448
3449 <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
3450 <glossdef>
3451 <para>
3452 Prevents the default dependencies, namely the C compiler
3453 and standard C library (libc), from being added to
3454 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
3455 This variable is usually used within recipes that do not
3456 require any compilation using the C compiler.
3457 </para>
3458
3459 <para>
3460 Set the variable to "1" to prevent the default dependencies
3461 from being added.
3462 </para>
3463 </glossdef>
3464 </glossentry>
3465
3466 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
3467 <glossdef>
3468 <para>
3469 If set to "1", causes the build to not strip binaries in resulting packages.
3470 </para>
3471 </glossdef>
3472 </glossentry>
3473
3474 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
3475 <glossdef>
3476 <para>
3477 Causes the named class to be inherited at
3478 this point during parsing.
3479 The variable is only valid in configuration files.
3480 </para>
3481 </glossdef>
3482 </glossentry>
3483
3484 <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm>
3485 <glossdef>
3486 <para>
3487 Lists classes that will be inherited at the
3488 distribution level.
3489 It is unlikely that you want to edit this variable.
3490 </para>
3491
3492 <para>
3493 The default value of the variable is set as follows in the
3494 <filename>meta/conf/distro/defaultsetup.conf</filename>
3495 file:
3496 <literallayout class='monospaced'>
3497 INHERIT_DISTRO ?= "debian devshell sstate license"
3498 </literallayout>
3499 </para>
3500 </glossdef>
3501 </glossentry>
3502
3503 <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
3504 <glossdef>
3505 <para>
3506 Defines the format for the output image of an initial
3507 RAM disk (initramfs), which is used during boot.
3508 Supported formats are the same as those supported by the
3509 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
3510 variable.
3511 </para>
3512 </glossdef>
3513 </glossentry>
3514
3515 <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>
3516 <glossdef>
3517 <para>
3518 Causes the OpenEmbedded build system to build an additional
3519 recipe as a dependency to your root filesystem recipe
3520 (e.g. <filename>core-image-sato</filename>).
3521 The additional recipe is used to create an initial RAM disk
3522 (initramfs) that might be needed during the initial boot of
3523 the target system to accomplish such things as loading
3524 kernel modules prior to mounting the root file system.
3525 </para>
3526
3527 <para>
3528 When you set the variable, specify the name of the
3529 initramfs you want created.
3530 The following example, which is set in the
3531 <filename>local.conf</filename> configuration file, causes
3532 a separate recipe to be created that results in an
3533 initramfs image named
3534 <filename>core-image-sato-initramfs.bb</filename> to be
3535 created:
3536 <literallayout class='monospaced'>
3537 INITRAMFS_IMAGE = "core-image-minimal-initramfs"
3538 </literallayout>
3539 By default, the
3540 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
3541 class sets this variable to a null string as follows:
3542 <literallayout class='monospaced'>
3543 INITRAMFS_IMAGE = ""
3544 </literallayout>
3545 </para>
3546
3547 <para>
3548 See the
3549 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
3550 file for additional information.
3551 You can also reference the
3552 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/kernel.bbclass'><filename>kernel.bbclass</filename></ulink>
3553 file to see how the variable is used.
3554 </para>
3555 </glossdef>
3556 </glossentry>
3557
3558 <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
3559 <glossdef>
3560 <para>
3561 Controls whether or not the image recipe specified by
3562 <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link>
3563 is run through an extra pass during kernel compilation
3564 in order to build a single binary that contains both the
3565 kernel image and the initial RAM disk (initramfs).
3566 Using an extra compilation pass ensures that when a kernel
3567 attempts to use an initramfs, it does not encounter
3568 circular dependencies should the initramfs include kernel
3569 modules.
3570 </para>
3571
3572 <para>
3573 The combined binary is deposited into the
3574 <filename>tmp/deploy</filename> directory, which is part
3575 of the
3576 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
3577 </para>
3578
3579 <para>
3580 Setting the variable to "1" in a configuration file causes
3581 the OpenEmbedded build system to make the extra pass during
3582 kernel compilation:
3583 <literallayout class='monospaced'>
3584 INITRAMFS_IMAGE_BUNDLE = "1"
3585 </literallayout>
3586 By default, the
3587 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
3588 class sets this variable to a null string as follows:
3589 <literallayout class='monospaced'>
3590 INITRAMFS_IMAGE_BUNDLE = ""
3591 </literallayout>
3592 <note>
3593 You must set the
3594 <filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in
3595 a configuration file.
3596 You cannot set the variable in a recipe file.
3597 </note>
3598 See the
3599 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
3600 file for additional information.
3601 </para>
3602 </glossdef>
3603 </glossentry>
3604
3605 <glossentry id='var-INITRD'><glossterm>INITRD</glossterm>
3606 <glossdef>
3607 <para>
3608 Indicates a filesystem image to use as an initial RAM
3609 disk (<filename>initrd</filename>).
3610 </para>
3611
3612 <para>
3613 The <filename>INITRD</filename> variable is an optional
3614 variable used with the
3615 <link linkend='ref-classes-bootimg'><filename>buildimg</filename></link>
3616 class.
3617 </para>
3618 </glossdef>
3619 </glossentry>
3620
3621 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
3622 <glossdef>
3623 <para>
3624 The filename of the initialization script as installed to
3625 <filename>${sysconfdir}/init.d</filename>.
3626 </para>
3627 <para>
3628 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
3629 The variable is mandatory.
3630 </para>
3631 </glossdef>
3632 </glossentry>
3633
3634 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
3635 <glossdef>
3636 <para>
3637 A list of the packages that contain initscripts.
3638 If multiple packages are specified, you need to append the package name
3639 to the other <filename>INITSCRIPT_*</filename> as an override.</para>
3640 <para>
3641 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
3642 The variable is optional and defaults to the
3643 <link linkend='var-PN'><filename>PN</filename></link> variable.
3644 </para>
3645 </glossdef>
3646 </glossentry>
3647
3648 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
3649 <glossdef>
3650 <para>
3651 Specifies the options to pass to <filename>update-rc.d</filename>.
3652 Here is an example:
3653 <literallayout class='monospaced'>
3654 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
3655 </literallayout>
3656 In this example, the script has a runlevel of 99,
3657 starts the script in initlevels 2 and 5, and
3658 stops the script in levels 0, 1 and 6.
3659 </para>
3660 <para>
3661 The variable is mandatory and is used in recipes when using
3662 <filename>update-rc.d.bbclass</filename>.
3663 </para>
3664 </glossdef>
3665 </glossentry>
3666
3667 <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
3668 <glossdef>
3669 <para>
3670 Specifies the QA checks to skip for a specific package
3671 within a recipe.
3672 For example, to skip the check for symbolic link
3673 <filename>.so</filename> files in the main package of a
3674 recipe, add the following to the recipe.
3675 The package name override must be used, which in this
3676 example is <filename>${PN}</filename>:
3677 <literallayout class='monospaced'>
3678 INSANE_SKIP_${PN} += "dev-so"
3679 </literallayout>
3680 </para>
3681 <para>
3682 See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
3683 section for a list of the valid QA checks you can
3684 specify using this variable.
3685 </para>
3686 </glossdef>
3687 </glossentry>
3688
3689 <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
3690 <glossdef>
3691 <para>
3692 When the IPK backend is in use and package management
3693 is enabled on the target, you can use this variable to
3694 set up <filename>opkg</filename> in the target image
3695 to point to package feeds on a nominated server.
3696 Once the feed is established, you can perform
3697 installations or upgrades using the package manager
3698 at runtime.
3699 </para>
3700 </glossdef>
3701 </glossentry>
3702
3703<!--
3704 <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
3705 <glossdef>
3706 <para>
3707 An environment variable that defines the directory where
3708 post installation hooks are installed for the
3709 post install environment.
3710 This variable is fixed as follows:
3711 <literallayout class='monospaced'>
3712 ${WORKDIR}/intercept_scripts
3713 </literallayout>
3714 </para>
3715
3716 <para>
3717 After installation of a target's root filesystem,
3718 post installation scripts, which are essentially bash scripts,
3719 are all executed just a single time.
3720 Limiting execution of these scripts minimizes installation
3721 time that would be lengthened due to certain packages
3722 triggering redundant operations.
3723 For example, consider the installation of font packages
3724 as a common example.
3725 Without limiting the execution of post installation scripts,
3726 all font directories would be rescanned to create the
3727 cache after each individual font package was installed.
3728 </para>
3729
3730 <para>
3731 Do not edit the <filename>INTERCEPT_DIR</filename>
3732 variable.
3733 </para>
3734 </glossdef>
3735 </glossentry>
3736-->
3737
3738 </glossdiv>
3739
3740<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
3741<!-- </glossdiv>-->
3742
3743 <glossdiv id='var-glossary-k'><title>K</title>
3744
3745 <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
3746 <glossdef>
3747 <para>
3748 Defines the kernel architecture used when assembling
3749 the configuration.
3750 Architectures supported for this release are:
3751 <literallayout class='monospaced'>
3752 powerpc
3753 i386
3754 x86_64
3755 arm
3756 qemu
3757 mips
3758 </literallayout>
3759 </para>
3760
3761 <para>
3762 You define the <filename>KARCH</filename> variable in the
3763 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
3764 </para>
3765 </glossdef>
3766 </glossentry>
3767
3768 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
3769 <glossdef>
3770 <para>
3771 A regular expression used by the build process to explicitly
3772 identify the kernel branch that is validated, patched
3773 and configured during a build.
3774 The <filename>KBRANCH</filename> variable is optional.
3775 You can use it to trigger checks to ensure the exact kernel
3776 branch you want is being used by the build process.
3777 </para>
3778
3779 <para>
3780 Values for this variable are set in the kernel's recipe
3781 file and the kernel's append file.
3782 For example, if you are using the Yocto Project kernel that
3783 is based on the Linux 3.10 kernel, the kernel recipe file
3784 is the
3785 <filename>meta/recipes-kernel/linux/linux-yocto_3.10.bb</filename>
3786 file.
3787 Following is the default value for <filename>KBRANCH</filename>
3788 and the default override for the architectures the Yocto
3789 Project supports:
3790 <literallayout class='monospaced'>
3791 KBRANCH_DEFAULT = "standard/base"
3792 KBRANCH = "${KBRANCH_DEFAULT}"
3793 </literallayout>
3794 This branch exists in the <filename>linux-yocto-3.10</filename>
3795 kernel Git repository
3796 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.10/refs/heads'></ulink>.
3797 </para>
3798
3799 <para>
3800 This variable is also used from the kernel's append file
3801 to identify the kernel branch specific to a particular
3802 machine or target hardware.
3803 The kernel's append file is located in the BSP layer for
3804 a given machine.
3805 For example, the kernel append file for the Crown Bay BSP is in the
3806 <filename>meta-intel</filename> Git repository and is named
3807 <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend</filename>.
3808 Here are the related statements from the append file:
3809 <literallayout class='monospaced'>
3810 COMPATIBLE_MACHINE_crownbay = "crownbay"
3811 KMACHINE_crownbay = "crownbay"
3812 KBRANCH_crownbay = "standard/crownbay"
3813 KERNEL_FEATURES_append_crownbay = " features/drm-emgd/drm-emgd-1.18 cfg/vesafb"
3814
3815 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
3816 KMACHINE_crownbay-noemgd = "crownbay"
3817 KBRANCH_crownbay-noemgd = "standard/crownbay"
3818 KERNEL_FEATURES_append_crownbay-noemgd = " cfg/vesafb"
3819 </literallayout>
3820 The <filename>KBRANCH_*</filename> statements identify
3821 the kernel branch to use when building for the Crown
3822 Bay BSP.
3823 In this case there are two identical statements: one
3824 for each type of Crown Bay machine.
3825 </para>
3826 </glossdef>
3827 </glossentry>
3828
3829 <glossentry id='var-KBRANCH_DEFAULT'><glossterm>KBRANCH_DEFAULT</glossterm>
3830 <glossdef>
3831 <para>
3832 Defines the Linux kernel source repository's default
3833 branch used to build the Linux kernel.
3834 The <filename>KBRANCH_DEFAULT</filename> value is
3835 the default value for
3836 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>.
3837 Unless you specify otherwise,
3838 <filename>KBRANCH_DEFAULT</filename> initializes to
3839 "master".
3840 </para>
3841 </glossdef>
3842 </glossentry>
3843
3844 <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
3845 <glossdef>
3846 <para>
3847 Specifies additional <filename>make</filename>
3848 command-line arguments the OpenEmbedded build system
3849 passes on when compiling the kernel.
3850 </para>
3851 </glossdef>
3852 </glossentry>
3853
3854 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
3855 <glossdef>
3856 <para>Includes additional metadata from the Yocto Project kernel Git repository.
3857 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
3858 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
3859 is provided through
3860 the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
3861 and <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link> variables.
3862 You can use the <filename>KERNEL_FEATURES</filename> variable to further
3863 add metadata for all BSPs.</para>
3864 <para>The metadata you add through this variable includes config fragments and
3865 features descriptions,
3866 which usually includes patches as well as config fragments.
3867 You typically override the <filename>KERNEL_FEATURES</filename> variable
3868 for a specific machine.
3869 In this way, you can provide validated, but optional, sets of kernel
3870 configurations and features.</para>
3871 <para>For example, the following adds <filename>netfilter</filename> to all
3872 the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>
3873 machine:
3874 <literallayout class='monospaced'>
3875 # Add netfilter to all linux-yocto kernels
3876 KERNEL_FEATURES="features/netfilter"
3877
3878 # Add sound support to the qemux86 machine
3879 KERNEL_FEATURES_append_qemux86=" cfg/sound"
3880 </literallayout></para>
3881 </glossdef>
3882 </glossentry>
3883
3884 <glossentry id='var-KERNEL_IMAGE_BASE_NAME'><glossterm>KERNEL_IMAGE_BASE_NAME</glossterm>
3885 <glossdef>
3886 <para>
3887 The base name of the kernel image.
3888 This variable is set in the
3889 <link linkend='ref-classes-kernel'>kernel</link> class
3890 as follows:
3891 <literallayout class='monospaced'>
3892 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
3893 </literallayout>
3894 See the
3895 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>,
3896 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
3897 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
3898 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
3899 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
3900 and
3901 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
3902 variables for additional information.
3903 </para>
3904 </glossdef>
3905 </glossentry>
3906
3907 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
3908 <glossdef>
3909 <para>The type of kernel to build for a device, usually set by the
3910 machine configuration files and defaults to "zImage".
3911 This variable is used
3912 when building the kernel and is passed to <filename>make</filename> as the target to
3913 build.</para>
3914 </glossdef>
3915 </glossentry>
3916
3917 <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
3918 <glossdef>
3919 <para>
3920 The location of the kernel sources.
3921 This variable is set to the value of the
3922 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
3923 within the <filename>module.bbclass</filename> class.
3924 For information on how this variable is used, see the
3925 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
3926 section.
3927 </para>
3928
3929 <para>
3930 To help maximize compatibility with out-of-tree drivers
3931 used to build modules, the OpenEmbedded build system also
3932 recognizes and uses the
3933 <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
3934 variable, which is identical to the
3935 <filename>KERNEL_PATH</filename> variable.
3936 Both variables are common variables used by external
3937 Makefiles to point to the kernel source directory.
3938 </para>
3939 </glossdef>
3940 </glossentry>
3941
3942 <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
3943 <glossdef>
3944 <para>
3945 The location of the kernel sources.
3946 This variable is set to the value of the
3947 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
3948 within the <filename>module.bbclass</filename> class.
3949 For information on how this variable is used, see the
3950 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
3951 section.
3952 </para>
3953
3954 <para>
3955 To help maximize compatibility with out-of-tree drivers
3956 used to build modules, the OpenEmbedded build system also
3957 recognizes and uses the
3958 <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
3959 variable, which is identical to the
3960 <filename>KERNEL_SRC</filename> variable.
3961 Both variables are common variables used by external
3962 Makefiles to point to the kernel source directory.
3963 </para>
3964 </glossdef>
3965 </glossentry>
3966
3967 <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
3968 <glossdef>
3969 <para>
3970 Provides a short description of a configuration fragment.
3971 You use this variable in the <filename>.scc</filename>
3972 file that describes a configuration fragment file.
3973 Here is the variable used in a file named
3974 <filename>smp.scc</filename> to describe SMP being
3975 enabled:
3976 <literallayout class='monospaced'>
3977 define KFEATURE_DESCRIPTION "Enable SMP"
3978 </literallayout>
3979 </para>
3980 </glossdef>
3981 </glossentry>
3982
3983 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
3984 <glossdef>
3985 <para>
3986 The machine as known by the kernel.
3987 Sometimes the machine name used by the kernel does not match the machine name
3988 used by the OpenEmbedded build system.
3989 For example, the machine name that the OpenEmbedded build system understands as
3990 <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel.
3991 The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
3992 For cases like these, the <filename>KMACHINE</filename> variable maps the
3993 kernel machine name to the OpenEmbedded build system machine name.
3994 </para>
3995
3996 <para>
3997 Kernel machine names are initially defined in the
3998 Yocto Linux Kernel's <filename>meta</filename> branch.
3999 From the <filename>meta</filename> branch, look in
4000 the <filename>meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</filename> file.
4001 For example, from the <filename>meta</filename> branch in the
4002 <filename>linux-yocto-3.0</filename> kernel, the
4003 <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file
4004 has the following:
4005 <literallayout class='monospaced'>
4006 define KMACHINE cedartrail
4007 define KTYPE standard
4008 define KARCH i386
4009
4010 include ktypes/standard
4011 branch cedartrail
4012
4013 include cedartrail.scc
4014 </literallayout>
4015 You can see that the kernel understands the machine name for
4016 the Cedar Trail Board Support Package (BSP) as
4017 <filename>cedartrail</filename>.
4018 </para>
4019
4020 <para>
4021 If you look in the Cedar Trail BSP layer in the
4022 <filename>meta-intel</filename>
4023 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
4024 at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>,
4025 you will find the following statements among others:
4026 <literallayout class='monospaced'>
4027 COMPATIBLE_MACHINE_cedartrail = "cedartrail"
4028 KMACHINE_cedartrail = "cedartrail"
4029 KBRANCH_cedartrail = "yocto/standard/cedartrail"
4030 KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
4031 KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
4032
4033 COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
4034 KMACHINE_cedartrail-nopvr = "cedartrail"
4035 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
4036 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
4037 </literallayout>
4038 The <filename>KMACHINE</filename> statements in the kernel's append file make sure that
4039 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
4040 names.
4041 </para>
4042
4043 <para>
4044 This append file uses two <filename>KMACHINE</filename> statements.
4045 The first is not really necessary but does ensure that the machine known to the
4046 OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
4047 in the kernel also known as <filename>cedartrail</filename>:
4048 <literallayout class='monospaced'>
4049 KMACHINE_cedartrail = "cedartrail"
4050 </literallayout>
4051 </para>
4052
4053 <para>
4054 The second statement is a good example of why the <filename>KMACHINE</filename> variable
4055 is needed.
4056 In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename>
4057 machine name to refer to the Cedar Trail BSP that does not support the proprietary
4058 PowerVR driver.
4059 The kernel, however, uses the machine name <filename>cedartrail</filename>.
4060 Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to
4061 the kernel's <filename>cedartrail</filename> name:
4062 <literallayout class='monospaced'>
4063 KMACHINE_cedartrail-nopvr = "cedartrail"
4064 </literallayout>
4065 </para>
4066
4067 <para>
4068 BSPs that ship with the Yocto Project release provide all mappings between the Yocto
4069 Project kernel machine names and the OpenEmbedded machine names.
4070 Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine
4071 name you use is different than that used in the kernel.
4072 </para>
4073 </glossdef>
4074 </glossentry>
4075
4076 <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
4077 <glossdef>
4078 <para>
4079 Defines the kernel type to be used in assembling the
4080 configuration.
4081 The linux-yocto recipes define "standard", "tiny",
4082 and "preempt-rt" kernel types.
4083 See the
4084 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
4085 section in the Yocto Project Linux Kernel Development
4086 Manual for more information on kernel types.
4087 </para>
4088
4089 <para>
4090 You define the <filename>KTYPE</filename> variable in the
4091 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
4092 The value you use must match the value used for the
4093 <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
4094 value used by the kernel recipe.
4095 </para>
4096 </glossdef>
4097 </glossentry>
4098 </glossdiv>
4099
4100 <glossdiv id='var-glossary-l'><title>L</title>
4101
4102 <glossentry id='var-LABELS'><glossterm>LABELS</glossterm>
4103 <glossdef>
4104 <para>
4105 Provides a list of targets for automatic configuration.
4106 </para>
4107
4108 <para>
4109 See the
4110 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
4111 class for more information on how this variable is used.
4112 </para>
4113 </glossdef>
4114 </glossentry>
4115
4116 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
4117 <glossdef>
4118 <para>Lists the layers that this recipe depends upon, separated by spaces.
4119 Optionally, you can specify a specific layer version for a dependency
4120 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
4121 to be compared against
4122 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>
4123 in this case).
4124 An error will be produced if any dependency is missing or
4125 the version numbers do not match exactly (if specified).
4126 This variable is used in the <filename>conf/layer.conf</filename> file
4127 and must be suffixed with the name of the specific layer (e.g.
4128 <filename>LAYERDEPENDS_mylayer</filename>).</para>
4129 </glossdef>
4130 </glossentry>
4131
4132 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
4133 <glossdef>
4134 <para>When used inside the <filename>layer.conf</filename> configuration
4135 file, this variable provides the path of the current layer.
4136 This variable is not available outside of <filename>layer.conf</filename>
4137 and references are expanded immediately when parsing of the file completes.</para>
4138 </glossdef>
4139 </glossentry>
4140
4141 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
4142 <glossdef>
4143 <para>Optionally specifies the version of a layer as a single number.
4144 You can use this within
4145 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
4146 for another layer in order to depend on a specific version
4147 of the layer.
4148 This variable is used in the <filename>conf/layer.conf</filename> file
4149 and must be suffixed with the name of the specific layer (e.g.
4150 <filename>LAYERVERSION_mylayer</filename>).</para>
4151 </glossdef>
4152 </glossentry>
4153
4154 <glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>
4155 <glossdef>
4156 <para>
4157 Specifies the lead (or primary) compiled library file
4158 (<filename>.so</filename>) that the
4159 <link linkend='ref-classes-debian'><filename>debian</filename></link>
4160 class applies its naming policy to given a recipe that
4161 packages multiple libraries.
4162 </para>
4163
4164 <para>
4165 This variable works in conjunction with the
4166 <filename>debian</filename> class.
4167 </para>
4168 </glossdef>
4169 </glossentry>
4170
4171 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
4172 <glossdef>
4173 <para>Checksums of the license text in the recipe source code.</para>
4174 <para>This variable tracks changes in license text of the source
4175 code files.
4176 If the license text is changed, it will trigger a build
4177 failure, which gives the developer an opportunity to review any
4178 license change.</para>
4179 <para>
4180 This variable must be defined for all recipes (unless
4181 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
4182 is set to "CLOSED")</para>
4183 <para>For more information, see the
4184 <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
4185 Tracking License Changes</link> section</para>
4186 </glossdef>
4187 </glossentry>
4188
4189 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
4190 <glossdef>
4191 <para>
4192 The list of source licenses for the recipe.
4193 Follow these rules:
4194 <itemizedlist>
4195 <listitem><para>Do not use spaces within individual
4196 license names.</para></listitem>
4197 <listitem><para>Separate license names using
4198 | (pipe) when there is a choice between licenses.
4199 </para></listitem>
4200 <listitem><para>Separate license names using
4201 &amp; (ampersand) when multiple licenses exist
4202 that cover different parts of the source.
4203 </para></listitem>
4204 <listitem><para>You can use spaces between license
4205 names.</para></listitem>
4206 <listitem><para>For standard licenses, use the names
4207 of the files in
4208 <filename>meta/files/common-licenses/</filename>
4209 or the
4210 <link linkend='var-SPDXLICENSEMAP'><filename>SPDXLICENSEMAP</filename></link>
4211 flag names defined in
4212 <filename>meta/conf/licenses.conf</filename>.
4213 </para></listitem>
4214 </itemizedlist>
4215 </para>
4216
4217 <para>
4218 Here are some examples:
4219 <literallayout class='monospaced'>
4220 LICENSE = "LGPLv2.1 | GPLv3"
4221 LICENSE = "MPL-1 &amp; LGPLv2.1"
4222 LICENSE = "GPLv2+"
4223 </literallayout>
4224 The first example is from the recipes for Qt, which the user
4225 may choose to distribute under either the LGPL version
4226 2.1 or GPL version 3.
4227 The second example is from Cairo where two licenses cover
4228 different parts of the source code.
4229 The final example is from <filename>sysstat</filename>,
4230 which presents a single license.
4231 </para>
4232
4233 <para>
4234 You can also specify licenses on a per-package basis to
4235 handle situations where components of the output have
4236 different licenses.
4237 For example, a piece of software whose code is
4238 licensed under GPLv2 but has accompanying documentation
4239 licensed under the GNU Free Documentation License 1.2 could
4240 be specified as follows:
4241 <literallayout class='monospaced'>
4242 LICENSE = "GFDL-1.2 &amp; GPLv2"
4243 LICENSE_${PN} = "GPLv2"
4244 LICENSE_${PN}-doc = "GFDL-1.2"
4245 </literallayout>
4246 </para>
4247 </glossdef>
4248 </glossentry>
4249
4250 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
4251 <glossdef>
4252 <para>Path to additional licenses used during the build.
4253 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
4254 to define the directory that holds common license text used during the build.
4255 The <filename>LICENSE_PATH</filename> variable allows you to extend that
4256 location to other areas that have additional licenses:
4257 <literallayout class='monospaced'>
4258 LICENSE_PATH += "/path/to/additional/common/licenses"
4259 </literallayout></para>
4260 </glossdef>
4261 </glossentry>
4262
4263 <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
4264 <glossdef>
4265 <para>
4266 Defines the kernel type to be used in assembling the
4267 configuration.
4268 The linux-yocto recipes define "standard", "tiny", and
4269 "preempt-rt" kernel types.
4270 See the
4271 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
4272 section in the Yocto Project Linux Kernel Development
4273 Manual for more information on kernel types.
4274 </para>
4275
4276 <para>
4277 If you do not specify a
4278 <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
4279 "standard".
4280 Together with
4281 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
4282 the <filename>LINUX_KERNEL_TYPE</filename> variable
4283 defines the search
4284 arguments used by the kernel tools to find the appropriate
4285 description within the kernel
4286 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
4287 with which to build out the sources and configuration.
4288 </para>
4289 </glossdef>
4290 </glossentry>
4291
4292 <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
4293 <glossdef>
4294 <para>The Linux version from <filename>kernel.org</filename>
4295 on which the Linux kernel image being built using the
4296 OpenEmbedded build system is based.
4297 You define this variable in the kernel recipe.
4298 For example, the <filename>linux-yocto-3.4.bb</filename>
4299 kernel recipe found in
4300 <filename>meta/recipes-kernel/linux</filename>
4301 defines the variables as follows:
4302 <literallayout class='monospaced'>
4303 LINUX_VERSION ?= "3.4.24"
4304 </literallayout>
4305 The <filename>LINUX_VERSION</filename> variable is used to
4306 define <link linkend='var-PV'><filename>PV</filename></link>
4307 for the recipe:
4308 <literallayout class='monospaced'>
4309 PV = "${LINUX_VERSION}+git${SRCPV}"
4310 </literallayout></para>
4311 </glossdef>
4312 </glossentry>
4313
4314 <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
4315 <glossdef>
4316 <para>A string extension compiled into the version
4317 string of the Linux kernel built with the OpenEmbedded
4318 build system.
4319 You define this variable in the kernel recipe.
4320 For example, the linux-yocto kernel recipes all define
4321 the variable as follows:
4322 <literallayout class='monospaced'>
4323 LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
4324 </literallayout>
4325 Defining this variable essentially sets the
4326 Linux kernel configuration item
4327 <filename>CONFIG_LOCALVERSION</filename>, which is visible
4328 through the <filename>uname</filename> command.
4329 Here is an example that shows the extension assuming it
4330 was set as previously shown:
4331 <literallayout class='monospaced'>
4332 $ uname -r
4333 3.7.0-rc8-custom
4334 </literallayout>
4335 </para>
4336 </glossdef>
4337 </glossentry>
4338
4339 <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
4340 <glossdef>
4341 <para>
4342 Specifies the directory to which the OpenEmbedded build
4343 system writes overall log files.
4344 The default directory is <filename>${TMPDIR}/log</filename>.
4345 </para>
4346 <para>
4347 For the directory containing logs specific to each task,
4348 see the <link linkend='var-T'><filename>T</filename></link>
4349 variable.
4350 </para>
4351 </glossdef>
4352 </glossentry>
4353
4354 </glossdiv>
4355
4356 <glossdiv id='var-glossary-m'><title>M</title>
4357
4358 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
4359 <glossdef>
4360 <para>
4361 Specifies the target device for which the image is built.
4362 You define <filename>MACHINE</filename> in the
4363 <filename>local.conf</filename> file found in the
4364 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
4365 By default, <filename>MACHINE</filename> is set to
4366 "qemux86", which is an x86-based architecture machine to
4367 be emulated using QEMU:
4368 <literallayout class='monospaced'>
4369 MACHINE ?= "qemux86"
4370 </literallayout>
4371 The variable corresponds to a machine configuration file of the
4372 same name, through which machine-specific configurations are set.
4373 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
4374 exists the corresponding <filename>qemux86.conf</filename> machine
4375 configuration file, which can be found in the
4376 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
4377 in <filename>meta/conf/machine</filename>.
4378 </para>
4379
4380 <para>
4381 The list of machines supported by the Yocto Project as
4382 shipped include the following:
4383 <literallayout class='monospaced'>
4384 MACHINE ?= "qemuarm"
4385 MACHINE ?= "qemumips"
4386 MACHINE ?= "qemuppc"
4387 MACHINE ?= "qemux86"
4388 MACHINE ?= "qemux86-64"
4389 MACHINE ?= "genericx86"
4390 MACHINE ?= "genericx86-64"
4391 MACHINE ?= "beaglebone"
4392 MACHINE ?= "mpc8315e-rdb"
4393 MACHINE ?= "edgerouter"
4394 </literallayout>
4395 The last five are Yocto Project reference hardware boards, which
4396 are provided in the <filename>meta-yocto-bsp</filename> layer.
4397 <note>Adding additional Board Support Package (BSP) layers
4398 to your configuration adds new possible settings for
4399 <filename>MACHINE</filename>.
4400 </note>
4401 </para>
4402 </glossdef>
4403 </glossentry>
4404
4405 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
4406 <glossdef>
4407 <para></para>
4408 <para>
4409 A list of required machine-specific packages to install as part of
4410 the image being built.
4411 The build process depends on these packages being present.
4412 Furthermore, because this is a "machine essential" variable, the list of
4413 packages are essential for the machine to boot.
4414 The impact of this variable affects images based on
4415 <filename>packagegroup-core-boot</filename>,
4416 including the <filename>core-image-minimal</filename> image.
4417 </para>
4418 <para>
4419 This variable is similar to the
4420 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
4421 variable with the exception that the image being built has a build
4422 dependency on the variable's list of packages.
4423 In other words, the image will not build if a file in this list is not found.
4424 </para>
4425 <para>
4426 As an example, suppose the machine for which you are building requires
4427 <filename>example-init</filename> to be run during boot to initialize the hardware.
4428 In this case, you would use the following in the machine's
4429 <filename>.conf</filename> configuration file:
4430 <literallayout class='monospaced'>
4431 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
4432 </literallayout>
4433 </para>
4434 </glossdef>
4435 </glossentry>
4436
4437 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
4438 <glossdef>
4439 <para></para>
4440 <para>
4441 A list of recommended machine-specific packages to install as part of
4442 the image being built.
4443 The build process does not depend on these packages being present.
4444 However, because this is a "machine essential" variable, the list of
4445 packages are essential for the machine to boot.
4446 The impact of this variable affects images based on
4447 <filename>packagegroup-core-boot</filename>,
4448 including the <filename>core-image-minimal</filename> image.
4449 </para>
4450 <para>
4451 This variable is similar to the
4452 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
4453 variable with the exception that the image being built does not have a build
4454 dependency on the variable's list of packages.
4455 In other words, the image will still build if a package in this list is not found.
4456 Typically, this variable is used to handle essential kernel modules, whose
4457 functionality may be selected to be built into the kernel rather than as a module,
4458 in which case a package will not be produced.
4459 </para>
4460 <para>
4461 Consider an example where you have a custom kernel where a specific touchscreen
4462 driver is required for the machine to be usable.
4463 However, the driver can be built as a module or
4464 into the kernel depending on the kernel configuration.
4465 If the driver is built as a module, you want it to be installed.
4466 But, when the driver is built into the kernel, you still want the
4467 build to succeed.
4468 This variable sets up a "recommends" relationship so that in the latter case,
4469 the build will not fail due to the missing package.
4470 To accomplish this, assuming the package for the module was called
4471 <filename>kernel-module-ab123</filename>, you would use the
4472 following in the machine's <filename>.conf</filename> configuration
4473 file:
4474 <literallayout class='monospaced'>
4475 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
4476 </literallayout>
4477 </para>
4478 <para>
4479 Some examples of these machine essentials are flash, screen, keyboard, mouse,
4480 or touchscreen drivers (depending on the machine).
4481 </para>
4482 </glossdef>
4483 </glossentry>
4484
4485 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
4486 <glossdef>
4487 <para>
4488 A list of machine-specific packages to install as part of the
4489 image being built that are not essential for the machine to boot.
4490 However, the build process for more fully-featured images
4491 depends on the packages being present.
4492 </para>
4493 <para>
4494 This variable affects all images based on
4495 <filename>packagegroup-base</filename>, which does not include the
4496 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
4497 images.
4498 </para>
4499 <para>
4500 The variable is similar to the
4501 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
4502 variable with the exception that the image being built has a build
4503 dependency on the variable's list of packages.
4504 In other words, the image will not build if a file in this list is not found.
4505 </para>
4506 <para>
4507 An example is a machine that has WiFi capability but is not
4508 essential for the machine to boot the image.
4509 However, if you are building a more fully-featured image, you want to enable
4510 the WiFi.
4511 The package containing the firmware for the WiFi hardware is always
4512 expected to exist, so it is acceptable for the build process to depend upon
4513 finding the package.
4514 In this case, assuming the package for the firmware was called
4515 <filename>wifidriver-firmware</filename>, you would use the following in the
4516 <filename>.conf</filename> file for the machine:
4517 <literallayout class='monospaced'>
4518 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
4519 </literallayout>
4520 </para>
4521 </glossdef>
4522 </glossentry>
4523
4524 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
4525 <glossdef>
4526 <para></para>
4527 <para>
4528 A list of machine-specific packages to install as part of the
4529 image being built that are not essential for booting the machine.
4530 The image being built has no build dependency on this list of packages.
4531 </para>
4532 <para>
4533 This variable affects only images based on
4534 <filename>packagegroup-base</filename>, which does not include the
4535 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
4536 images.
4537 </para>
4538 <para>
4539 This variable is similar to the
4540 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
4541 variable with the exception that the image being built does not have a build
4542 dependency on the variable's list of packages.
4543 In other words, the image will build if a file in this list is not found.
4544 </para>
4545 <para>
4546 An example is a machine that has WiFi capability but is not essential
4547 For the machine to boot the image.
4548 However, if you are building a more fully-featured image, you want to enable
4549 WiFi.
4550 In this case, the package containing the WiFi kernel module will not be produced
4551 if the WiFi driver is built into the kernel, in which case you still want the
4552 build to succeed instead of failing as a result of the package not being found.
4553 To accomplish this, assuming the package for the module was called
4554 <filename>kernel-module-examplewifi</filename>, you would use the
4555 following in the <filename>.conf</filename> file for the machine:
4556 <literallayout class='monospaced'>
4557 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
4558 </literallayout>
4559 </para>
4560 </glossdef>
4561 </glossentry>
4562
4563 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
4564 <glossdef>
4565 <para>
4566 Specifies the list of hardware features the
4567 <link linkend='var-MACHINE'><filename>MACHINE</filename></link> is capable
4568 of supporting.
4569 For related information on enabling features, see the
4570 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>,
4571 <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>,
4572 and
4573 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
4574 variables.
4575 </para>
4576
4577 <para>
4578 For a list of hardware features supported by the Yocto
4579 Project as shipped, see the
4580 "<link linkend='ref-features-machine'>Machine Features</link>"
4581 section.
4582 </para>
4583 </glossdef>
4584 </glossentry>
4585
4586 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
4587 <glossdef>
4588 <para>Features to be added to
4589 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
4590 if not also present in
4591 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
4592 </para>
4593
4594 <para>
4595 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
4596 It is not intended to be user-configurable.
4597 It is best to just reference the variable to see which machine features are
4598 being backfilled for all machine configurations.
4599 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
4600 more information.
4601 </para>
4602 </glossdef>
4603 </glossentry>
4604
4605 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
4606 <glossdef>
4607 <para>Features from
4608 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
4609 that should not be backfilled (i.e. added to
4610 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
4611 during the build.
4612 See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
4613 more information.
4614 </para>
4615 </glossdef>
4616 </glossentry>
4617
4618 <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
4619 <glossdef>
4620 <para>
4621 Lists overrides specific to the current machine.
4622 By default, this list includes the value
4623 of <filename><link linkend='var-MACHINE'>MACHINE</link></filename>.
4624 You can extend the list to apply variable overrides for
4625 classes of machines.
4626 For example, all QEMU emulated machines (e.g. qemuarm,
4627 qemux86, and so forth) include a common file named
4628 <filename>meta/conf/machine/include/qemu.inc</filename>
4629 that prepends <filename>MACHINEOVERRIDES</filename> with
4630 the following variable override:
4631 <literallayout class='monospaced'>
4632 MACHINEOVERRIDES =. "qemuall:"
4633 </literallayout>
4634 Applying an override like <filename>qemuall</filename>
4635 affects all QEMU emulated machines elsewhere.
4636 Here is an example from the
4637 <filename>connman-conf</filename> recipe:
4638 <literallayout class='monospaced'>
4639 SRC_URI_append_qemuall = "file://wired.config \
4640 file://wired-setup \
4641 "
4642 </literallayout>
4643 </para>
4644 </glossdef>
4645 </glossentry>
4646
4647 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
4648 <glossdef>
4649 <para>The email address of the distribution maintainer.</para>
4650 </glossdef>
4651 </glossentry>
4652
4653 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
4654 <glossdef>
4655 <para>
4656 Specifies additional paths from which the OpenEmbedded
4657 build system gets source code.
4658 When the build system searches for source code, it first
4659 tries the local download directory.
4660 If that location fails, the build system tries locations
4661 defined by
4662 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
4663 the upstream source, and then locations specified by
4664 <filename>MIRRORS</filename> in that order.
4665 </para>
4666
4667 <para>
4668 Assuming your distribution
4669 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
4670 is "poky", the default value for
4671 <filename>MIRRORS</filename> is defined in the
4672 <filename>conf/distro/poky.conf</filename> file in the
4673 <filename>meta-yocto</filename> Git repository.
4674 </para>
4675 </glossdef>
4676 </glossentry>
4677
4678 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
4679 <glossdef>
4680 <para>
4681 Specifies a prefix has been added to
4682 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
4683 of a recipe or package, such as a Multilib version.
4684 The variable is used in places where the prefix needs to be
4685 added to or removed from a the name (e.g. the
4686 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
4687 <filename>MLPREFIX</filename> gets set when a prefix has been
4688 added to <filename>PN</filename>.
4689 </para>
4690 </glossdef>
4691 </glossentry>
4692
4693 <glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm>
4694 <glossdef>
4695 <para>
4696 Lists kernel modules that need to be auto-loaded during
4697 boot.
4698 </para>
4699
4700 <para>
4701 You can use this variable anywhere that it can be
4702 recognized by the kernel recipe or out-of-tree kernel
4703 module recipe (e.g. a machine configuration file, a
4704 distribution configuration file, an append file for the
4705 recipe, or the recipe itself).
4706 </para>
4707
4708 <para>
4709 Specify it as follows:
4710 <literallayout class='monospaced'>
4711 module_autoload_&lt;modname&gt; = "modname1 modname2 modname3"
4712 </literallayout>
4713 You must use the kernel module name override.
4714 </para>
4715
4716 <para>
4717 Including <filename>module_autoload</filename> causes the
4718 OpenEmbedded build system to populate the
4719 <filename>/etc/modules-load.d/modname.conf</filename>
4720 file with the list of modules to be auto-loaded on boot.
4721 The modules appear one-per-line in the file.
4722 Here is an example of the most common use case:
4723 <literallayout class='monospaced'>
4724 module_autoload_modname = "modname"
4725 </literallayout>
4726 </para>
4727
4728 <para>
4729 For information on how to populate the
4730 <filename>modname.conf</filename> file with
4731 <filename>modprobe.d</filename> syntax lines, see the
4732 <link linkend='var-module_conf'><filename>module_conf</filename></link>
4733 variable.
4734 </para>
4735 </glossdef>
4736 </glossentry>
4737
4738 <glossentry id='var-module_conf'><glossterm>module_conf</glossterm>
4739 <glossdef>
4740 <para>
4741 Specifies <filename>modprobe.d</filename> syntax lines
4742 for inclusion in the
4743 <filename>/etc/modprobe.d/modname.conf</filename> file.
4744 </para>
4745
4746 <para>
4747 You can use this variable anywhere that it can be
4748 recognized by the kernel recipe or out-of-tree kernel
4749 module recipe (e.g. a machine configuration file, a
4750 distribution configuration file, an append file for the
4751 recipe, or the recipe itself).
4752 </para>
4753
4754 <para>
4755 Here is the general syntax:
4756 <literallayout class='monospaced'>
4757 module_conf_&lt;modname&gt; = "modprobe.d-syntax"
4758 </literallayout>
4759 You must use the kernel module name override.
4760 </para>
4761
4762 <para>
4763 Run <filename>man modprobe.d</filename> in the shell to
4764 find out more information on the exact syntax for lines
4765 you want to provide with <filename>module_conf</filename>.
4766 </para>
4767
4768 <para>
4769 Including <filename>module_conf</filename> causes the
4770 OpenEmbedded build system to populate the
4771 <filename>/etc/modprobe.d/modname.conf</filename>
4772 file with <filename>modprobe.d</filename> syntax lines.
4773 Here is an example:
4774 <literallayout class='monospaced'>
4775 module_conf_&lt;modname&gt; = "options modname arg1=val1 arg2=val2"
4776 </literallayout>
4777 </para>
4778
4779 <para>
4780 For information on how to specify kernel modules to
4781 auto-load on boot, see the
4782 <link linkend='var-module_autoload'><filename>module_autoload</filename></link>
4783 variable.
4784 </para>
4785 </glossdef>
4786 </glossentry>
4787
4788 <glossentry id='var-MODULE_IMAGE_BASE_NAME'><glossterm>MODULE_IMAGE_BASE_NAME</glossterm>
4789 <glossdef>
4790 <para>
4791 The base name of the kernel modules tarball.
4792 This variable is set in the
4793 <link linkend='ref-classes-kernel'>kernel</link> class
4794 as follows:
4795 <literallayout class='monospaced'>
4796 MODULE_IMAGE_BASE_NAME ?= "modules-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
4797 </literallayout>
4798 See the
4799 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
4800 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
4801 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
4802 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
4803 and
4804 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
4805 variables for additional information.
4806 </para>
4807 </glossdef>
4808 </glossentry>
4809
4810 <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
4811 <glossdef>
4812 <para>
4813 Controls creation of the <filename>modules-*.tgz</filename>
4814 file.
4815 Set this variable to "0" to disable creation of this
4816 file, which contains all of the kernel modules resulting
4817 from a kernel build.
4818 </para>
4819 </glossdef>
4820 </glossentry>
4821
4822 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
4823 <glossdef>
4824 <para>
4825 Separates files for different machines such that you can build
4826 for multiple target machines using the same output directories.
4827 See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable
4828 for an example.
4829 </para>
4830 </glossdef>
4831 </glossentry>
4832
4833 </glossdiv>
4834
4835 <glossdiv id='var-glossary-n'><title>N</title>
4836
4837 <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
4838 <glossdef>
4839 <para>
4840 A string identifying the host distribution.
4841 Strings consist of the host distributor ID
4842 followed by the release, as reported by the
4843 <filename>lsb_release</filename> tool
4844 or as read from <filename>/etc/lsb-release</filename>.
4845 For example, when running a build on Ubuntu 12.10, the value
4846 is "Ubuntu-12.10".
4847 If this information is unable to be determined, the value
4848 resolves to "Unknown".
4849 </para>
4850 <para>
4851 This variable is used by default to isolate native shared
4852 state packages for different distributions (e.g. to avoid
4853 problems with <filename>glibc</filename> version
4854 incompatibilities).
4855 Additionally, the variable is checked against
4856 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
4857 if that variable is set.
4858 </para>
4859 </glossdef>
4860 </glossentry>
4861
4862 <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
4863 <glossdef>
4864 <para>
4865 Prevents installation of all "recommended-only" packages.
4866 Recommended-only packages are packages installed only
4867 through the
4868 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
4869 variable).
4870 Setting the <filename>NO_RECOMMENDATIONS</filename> variable
4871 to "1" turns this feature on:
4872 <literallayout class='monospaced'>
4873 NO_RECOMMENDATIONS = "1"
4874 </literallayout>
4875 You can set this variable globally in your
4876 <filename>local.conf</filename> file or you can attach it to
4877 a specific image recipe by using the recipe name override:
4878 <literallayout class='monospaced'>
4879 NO_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
4880 </literallayout>
4881 </para>
4882
4883 <para>
4884 It is important to realize that if you choose to not install
4885 packages using this variable and some other packages are
4886 dependent on them (i.e. listed in a recipe's
4887 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
4888 variable), the OpenEmbedded build system ignores your
4889 request and will install the packages to avoid dependency
4890 errors.
4891 <note>
4892 Some recommended packages might be required for certain
4893 system functionality, such as kernel modules.
4894 It is up to you to add packages with the
4895 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
4896 variable.
4897 </note>
4898 </para>
4899
4900 <para>
4901 Support for this variable exists only when using the
4902 IPK and RPM packaging backend.
4903 Support does not exist for DEB.
4904 </para>
4905
4906 <para>
4907 See the
4908 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
4909 and the
4910 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
4911 variables for related information.
4912 </para>
4913 </glossdef>
4914 </glossentry>
4915
4916 <glossentry id='var-NOHDD'><glossterm>NOHDD</glossterm>
4917 <glossdef>
4918 <para>
4919 Causes the OpenEmbedded build system to skip building the
4920 <filename>.hddimg</filename> image.
4921 The <filename>NOHDD</filename> variable is used with the
4922 <link linkend='ref-classes-bootimg'><filename>buildimg</filename></link>
4923 class.
4924 Set the variable to "1" to prevent the
4925 <filename>.hddimg</filename> image from being built.
4926 </para>
4927 </glossdef>
4928 </glossentry>
4929
4930 <glossentry id='var-NOISO'><glossterm>NOISO</glossterm>
4931 <glossdef>
4932 <para>
4933 Causes the OpenEmbedded build system to skip building the
4934 ISO image.
4935 The <filename>NOISO</filename> variable is used with the
4936 <link linkend='ref-classes-bootimg'><filename>buildimg</filename></link>
4937 class.
4938 Set the variable to "1" to prevent the ISO image from
4939 being built.
4940 To enable building an ISO image, set the variable to "0".
4941 </para>
4942 </glossdef>
4943 </glossentry>
4944
4945 </glossdiv>
4946
4947 <glossdiv id='var-glossary-o'><title>O</title>
4948
4949 <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
4950 <glossdef>
4951 <para>
4952 When a recipe inherits the
4953 <filename>binconfig.bbclass</filename> class, this variable
4954 specifies additional arguments passed to the "sed" command.
4955 The sed command alters any paths in configuration scripts
4956 that have been set up during compilation.
4957 Inheriting this class results in all paths in these scripts
4958 being changed to point into the
4959 <filename>sysroots/</filename> directory so that all builds
4960 that use the script will use the correct directories
4961 for the cross compiling layout.
4962 </para>
4963
4964 <para>
4965 See the <filename>meta/classes/binconfig.bbclass</filename>
4966 in the
4967 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
4968 for details on how this class applies these additional
4969 sed command arguments.
4970 For general information on the
4971 <filename>binconfig.bbclass</filename> class, see the
4972 "<link linkend='ref-classes-binconfig'>Binary Configuration Scripts - <filename>binconfig.bbclass</filename></link>"
4973 section.
4974 </para>
4975 </glossdef>
4976 </glossentry>
4977
4978 <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
4979 <glossdef>
4980 <para>
4981 An internal variable used to tell the OpenEmbedded build
4982 system what Python modules to import for every Python
4983 function run by the system.
4984 </para>
4985
4986 <note>
4987 Do not set this variable.
4988 It is for internal use only.
4989 </note>
4990 </glossdef>
4991 </glossentry>
4992
4993 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
4994 <glossdef>
4995 <para>
4996 Controls how the OpenEmbedded build system spawns
4997 interactive terminals on the host development system
4998 (e.g. using the BitBake command with the
4999 <filename>-c devshell</filename> command-line option).
5000 For more information, see the
5001 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
5002 in the Yocto Project Development Manual.
5003 </para>
5004
5005 <para>
5006 You can use the following values for the
5007 <filename>OE_TERMINAL</filename> variable:
5008 <literallayout class='monospaced'>
5009 auto
5010 gnome
5011 xfce
5012 rxvt
5013 screen
5014 konsole
5015 none
5016 </literallayout>
5017 <note>Konsole support only works for KDE 3.x.
5018 Also, "auto" is the default behavior for
5019 <filename>OE_TERMINAL</filename></note>
5020 </para>
5021 </glossdef>
5022 </glossentry>
5023
5024 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
5025 <glossdef>
5026 <para>
5027 The directory from which the top-level build environment
5028 setup script is sourced.
5029 The Yocto Project makes two top-level build environment
5030 setup scripts available:
5031 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
5032 and
5033 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
5034 When you run one of these scripts, the
5035 <filename>OEROOT</filename> variable resolves to the
5036 directory that contains the script.
5037 </para>
5038
5039 <para>
5040 For additional information on how this variable is used,
5041 see the initialization scripts.
5042 </para>
5043 </glossdef>
5044 </glossentry>
5045
5046 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
5047 <glossdef>
5048 <para>
5049 Declares the oldest version of the Linux kernel that the
5050 produced binaries must support.
5051 This variable is passed into the build of the Embedded
5052 GNU C Library (<filename>eglibc</filename>).
5053 </para>
5054
5055 <para>
5056 The default for this variable comes from the
5057 <filename>meta/conf/bitbake.conf</filename> configuration
5058 file.
5059 You can override this default by setting the variable
5060 in a custom distribution configuration file.
5061 </para>
5062 </glossdef>
5063 </glossentry>
5064
5065 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
5066 <glossdef>
5067 <para>
5068 BitBake uses <filename>OVERRIDES</filename> to control
5069 what variables are overridden after BitBake parses
5070 recipes and configuration files.
5071 You can find more information on how overrides are handled
5072 in the BitBake Manual that is located at
5073 <filename>bitbake/doc/manual</filename> in the
5074 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
5075 </para>
5076 </glossdef>
5077 </glossentry>
5078 </glossdiv>
5079
5080 <glossdiv id='var-glossary-p'><title>P</title>
5081
5082 <glossentry id='var-P'><glossterm>P</glossterm>
5083 <glossdef>
5084 <para>The recipe name and version.
5085 <filename>P</filename> is comprised of the following:
5086 <literallayout class='monospaced'>
5087 ${PN}-${PV}
5088 </literallayout></para>
5089 </glossdef>
5090 </glossentry>
5091
5092 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
5093 <glossdef>
5094 <para>The architecture of the resulting package or packages.</para>
5095 </glossdef>
5096 </glossentry>
5097
5098 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
5099 <glossdef>
5100 <para>Enables easily adding packages to
5101 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
5102 before <filename>${<link linkend='var-PN'>PN</link>}</filename>
5103 so that those added packages can pick up files that would normally be
5104 included in the default package.</para>
5105 </glossdef>
5106 </glossentry>
5107
5108 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
5109 <glossdef>
5110 <para>
5111 This variable, which is set in the
5112 <filename>local.conf</filename> configuration file found in
5113 the <filename>conf</filename> folder of the
5114 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
5115 specifies the package manager the OpenEmbedded build system
5116 uses when packaging data.
5117 </para>
5118
5119 <para>
5120 You can provide one or more of the following arguments for
5121 the variable:
5122 <literallayout class='monospaced'>
5123 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"
5124 </literallayout>
5125 The build system uses only the first argument in the list
5126 as the package manager when creating your image or SDK.
5127 However, packages will be created using any additional
5128 packaging classes you specify.
5129 For example, if you use the following in your
5130 <filename>local.conf</filename> file:
5131 <literallayout class='monospaced'>
5132 PACKAGE_CLASSES ?= "package_ipk package_tar"
5133 </literallayout>
5134 The OpenEmbedded build system uses the IPK package manager
5135 to create your image or SDK as well as generating
5136 TAR packages.
5137 </para>
5138
5139 <para>
5140 You cannot specify the
5141 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
5142 class first in the list.
5143 Files using the <filename>.tar</filename> format cannot
5144 be used as a substitute packaging format
5145 for DEB, RPM, and IPK formatted files for your image or SDK.
5146 </para>
5147
5148 <para>
5149 For information on packaging and build performance effects
5150 as a result of the package manager in use, see the
5151 "<link linkend='ref-classes-package'><filename>package.bbclass</filename></link>"
5152 section.
5153 </para>
5154 </glossdef>
5155 </glossentry>
5156
5157 <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
5158 <glossdef>
5159 <para>
5160 Lists packages that should not be installed into an image.
5161 For example:
5162 <literallayout class='monospaced'>
5163 PACKAGE_EXCLUDE = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
5164 </literallayout>
5165 You can set this variable globally in your
5166 <filename>local.conf</filename> file or you can attach it to
5167 a specific image recipe by using the recipe name override:
5168 <literallayout class='monospaced'>
5169 PACKAGE_EXCLUDE_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
5170 </literallayout>
5171 </para>
5172
5173 <para>
5174 If you choose to not install
5175 a package using this variable and some other package is
5176 dependent on it (i.e. listed in a recipe's
5177 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
5178 variable), the OpenEmbedded build system generates a fatal
5179 installation error.
5180 Because the build system halts the process with a fatal
5181 error, you can use the variable with an iterative
5182 development process to remove specific components from a
5183 system.
5184 </para>
5185
5186 <para>
5187 Support for this variable exists only when using the
5188 IPK and RPM packaging backend.
5189 Support does not exist for DEB.
5190 </para>
5191
5192 <para>
5193 See the
5194 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
5195 and the
5196 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
5197 variables for related information.
5198 </para>
5199 </glossdef>
5200 </glossentry>
5201
5202 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
5203 <glossdef>
5204 <para>Specifies the list of architectures compatible with the device CPU.
5205 This variable is useful when you build for several different devices that use
5206 miscellaneous processors such as XScale and ARM926-EJS).</para>
5207 </glossdef>
5208 </glossentry>
5209
5210 <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
5211 <glossdef>
5212
5213 <para>
5214 The <filename>PACKAGE_GROUP</filename> variable has been
5215 renamed to
5216 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>.
5217 See the variable description for
5218 <filename>FEATURE_PACKAGES</filename> for information.
5219 </para>
5220
5221 <para>
5222 If if you use the <filename>PACKAGE_GROUP</filename>
5223 variable, the OpenEmbedded build system issues a warning
5224 message.
5225 </para>
5226 </glossdef>
5227 </glossentry>
5228
5229 <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
5230 <glossdef>
5231 <para>
5232 The final list of packages passed to the package manager
5233 for installation into the image.
5234 </para>
5235
5236 <para>
5237 Because the package manager controls actual installation
5238 of all packages, the list of packages passed using
5239 <filename>PACKAGE_INSTALL</filename> is not the final list
5240 of packages that are actually installed.
5241 This variable is internal to the image construction
5242 code.
5243 Consequently, in general, you should use the
5244 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
5245 variable to specify packages for installation.
5246 The exception to this is when working with
5247 the
5248 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
5249 image.
5250 When working with an initial RAM disk (initramfs)
5251 image, use the <filename>PACKAGE_INSTALL</filename>
5252 variable.
5253 </para>
5254 </glossdef>
5255 </glossentry>
5256
5257 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
5258 <glossdef>
5259 <para>
5260 This variable provides a means of enabling or disabling
5261 features of a recipe on a per-recipe basis.
5262 <filename>PACKAGECONFIG</filename> blocks are defined
5263 in recipes when you specify features and then arguments
5264 that define feature behaviors.
5265 Here is the basic block structure:
5266 <literallayout class='monospaced'>
5267 PACKAGECONFIG ??= "f1 f2 f3 ..."
5268 PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1"
5269 PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2"
5270 PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3"
5271 </literallayout>
5272 The <filename>PACKAGECONFIG</filename>
5273 variable itself specifies a space-separated list of the
5274 features to enable.
5275 Following the features, you can determine the behavior of
5276 each feature by providing up to four order-dependent
5277 arguments, which are separated by commas.
5278 You can omit any argument you like but must retain the
5279 separating commas.
5280 The order is important and specifies the following:
5281 <orderedlist>
5282 <listitem><para>Extra arguments
5283 that should be added to the configure script
5284 argument list
5285 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>)
5286 if the feature is enabled.</para></listitem>
5287 <listitem><para>Extra arguments
5288 that should be added to <filename>EXTRA_OECONF</filename>
5289 if the feature is disabled.
5290 </para></listitem>
5291 <listitem><para>Additional build dependencies
5292 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
5293 that should be added if the feature is enabled.
5294 </para></listitem>
5295 <listitem><para>Additional runtime dependencies
5296 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
5297 that should be added if the feature is enabled.
5298 </para></listitem>
5299 </orderedlist>
5300 </para>
5301
5302 <para>
5303 Consider the following
5304 <filename>PACKAGECONFIG</filename> block taken from the
5305 <filename>librsvg</filename> recipe.
5306 In this example the feature is <filename>croco</filename>,
5307 which has three arguments that determine the feature's
5308 behavior.
5309 <literallayout class='monospaced'>
5310 PACKAGECONFIG ??= "croco"
5311 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
5312 </literallayout>
5313 The <filename>--with-croco</filename> and
5314 <filename>libcroco</filename> arguments apply only if
5315 the feature is enabled.
5316 In this case, <filename>--with-croco</filename> is
5317 added to the configure script argument list and
5318 <filename>libcroco</filename> is added to
5319 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
5320 On the other hand, if the feature is disabled say through
5321 a <filename>.bbappend</filename> file in another layer, then
5322 the second argument <filename>--without-croco</filename> is
5323 added to the configure script rather than
5324 <filename>--with-croco</filename>.
5325 </para>
5326
5327 <para>
5328 The basic <filename>PACKAGECONFIG</filename> structure
5329 previously described holds true regardless of whether you
5330 are creating a block or changing a block.
5331 When creating a block, use the structure inside your
5332 recipe.
5333 </para>
5334
5335 <para>
5336 If you want to change an existing
5337 <filename>PACKAGECONFIG</filename> block, you can do so
5338 one of two ways:
5339 <itemizedlist>
5340 <listitem><para><emphasis>Append file:</emphasis>
5341 Create an append file named
5342 <filename>&lt;recipename&gt;.bbappend</filename> in your
5343 layer and override the value of
5344 <filename>PACKAGECONFIG</filename>.
5345 You can either completely override the variable:
5346 <literallayout class='monospaced'>
5347 PACKAGECONFIG="f4 f5"
5348 </literallayout>
5349 Or, you can just append the variable:
5350 <literallayout class='monospaced'>
5351 PACKAGECONFIG_append = " f4"
5352 </literallayout></para></listitem>
5353 <listitem><para><emphasis>Configuration file:</emphasis>
5354 This method is identical to changing the block
5355 through an append file except you edit your
5356 <filename>local.conf</filename> or
5357 <filename>&lt;mydistro&gt;.conf</filename> file.
5358 As with append files previously described,
5359 you can either completely override the variable:
5360 <literallayout class='monospaced'>
5361 PACKAGECONFIG_pn-&lt;recipename&gt;="f4 f5"
5362 </literallayout>
5363 Or, you can just amend the variable:
5364 <literallayout class='monospaced'>
5365 PACKAGECONFIG_append_pn-&lt;recipename&gt; = " f4"
5366 </literallayout></para></listitem>
5367 </itemizedlist>
5368 </para>
5369 </glossdef>
5370 </glossentry>
5371
5372 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
5373 <glossdef>
5374 <para>The list of packages to be created from the recipe.
5375 The default value is the following:
5376 <literallayout class='monospaced'>
5377 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
5378 </literallayout></para>
5379 </glossdef>
5380 </glossentry>
5381
5382 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
5383 <glossdef>
5384 <para>
5385 A promise that your recipe satisfies runtime dependencies
5386 for optional modules that are found in other recipes.
5387 <filename>PACKAGES_DYNAMIC</filename>
5388 does not actually satisfy the dependencies, it only states that
5389 they should be satisfied.
5390 For example, if a hard, runtime dependency
5391 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
5392 of another package is satisfied
5393 at build time through the <filename>PACKAGES_DYNAMIC</filename>
5394 variable, but a package with the module name is never actually
5395 produced, then the other package will be broken.
5396 Thus, if you attempt to include that package in an image,
5397 you will get a dependency failure from the packaging system
5398 during <filename>do_rootfs</filename>.
5399 </para>
5400 <para>
5401 Typically, if there is a chance that such a situation can
5402 occur and the package that is not created is valid
5403 without the dependency being satisfied, then you should use
5404 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
5405 (a soft runtime dependency) instead of
5406 <filename>RDEPENDS</filename>.
5407 </para>
5408
5409 <para>
5410 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
5411 variable when you are splitting packages, see the
5412 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
5413 in the Yocto Project Development Manual.
5414 </para>
5415 </glossdef>
5416 </glossentry>
5417
5418 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
5419 <glossdef>
5420 <para>
5421 Extra options passed to the <filename>make</filename>
5422 command during the <filename>do_compile</filename> task
5423 in order to specify parallel compilation on the local
5424 build host.
5425 This variable is usually in the form "-j &lt;x&gt;",
5426 where x represents the maximum number of parallel threads
5427 <filename>make</filename> can run.
5428 </para>
5429
5430 <para>
5431 If your development host supports multiple cores, a good
5432 rule of thumb is to set this variable to twice the number
5433 of cores on the host.
5434 If you do not set <filename>PARALLEL_MAKE</filename>, it
5435 defaults to the number of cores your build system has.
5436 <note>
5437 Individual recipes might clear out this variable if
5438 the software being built has problems running its
5439 <filename>make</filename> process in parallel.
5440 </note>
5441 </para>
5442 </glossdef>
5443 </glossentry>
5444
5445 <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
5446 <glossdef>
5447 <para>
5448 Extra options passed to the
5449 <filename>make install</filename> command during the
5450 <filename>do_install</filename> task in order to specify
5451 parallel installation.
5452 This variable defaults to the value of
5453 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
5454 <note>
5455 Individual recipes might clear out this variable if
5456 the software being built has problems running its
5457 <filename>make install</filename> process in parallel.
5458 </note>
5459 </para>
5460 </glossdef>
5461 </glossentry>
5462
5463 <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
5464 <glossdef>
5465 <para>
5466 Determines the action to take when a patch fails.
5467 You can set this variable to one of two values: "noop" and
5468 "user".
5469 </para>
5470
5471 <para>
5472 The default value of "noop" causes the build to simply fail
5473 when the OpenEmbedded build system cannot successfully
5474 apply a patch.
5475 Setting the value to "user" causes the build system to
5476 launch a shell and places you in the right location so that
5477 you can manually resolve the conflicts.
5478 </para>
5479
5480 <para>
5481 Set this variable in your
5482 <filename>local.conf</filename> file.
5483 </para>
5484 </glossdef>
5485 </glossentry>
5486
5487 <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
5488 <glossdef>
5489 <para>
5490 Specifies the utility used to apply patches for a recipe
5491 during <filename>do_patch</filename>.
5492 You can specify one of three utilities: "patch", "quilt", or
5493 "git".
5494 The default utility used is "quilt" except for the
5495 quilt-native recipe itself.
5496 Because the quilt tool is not available at the
5497 time quilt-native is being patched, it uses "patch".
5498 </para>
5499
5500 <para>
5501 If you wish to use an alternative patching tool, set the
5502 variable in the recipe using one of the following:
5503 <literallayout class='monospaced'>
5504 PATCHTOOL = "patch"
5505 PATCHTOOL = "quilt"
5506 PATCHTOOL = "git"
5507 </literallayout>
5508 </para>
5509 </glossdef>
5510 </glossentry>
5511
5512 <glossentry id='var-PE'><glossterm>PE</glossterm>
5513 <glossdef>
5514 <para>
5515 The epoch of the recipe.
5516 By default, this variable is unset.
5517 The variable is used to make upgrades possible when the
5518 versioning scheme changes in some backwards incompatible
5519 way.
5520 </para>
5521 </glossdef>
5522 </glossentry>
5523
5524 <glossentry id='var-PF'><glossterm>PF</glossterm>
5525 <glossdef>
5526 <para>Specifies the recipe or package name and includes all version and revision
5527 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
5528 <filename>bash-4.2-r1/</filename>).
5529 This variable is comprised of the following:
5530 <literallayout class='monospaced'>
5531 ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
5532 </literallayout></para>
5533 </glossdef>
5534 </glossentry>
5535
5536 <glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm>
5537 <glossdef>
5538 <para>
5539 When a recipe inherits the
5540 <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link>
5541 class, this variable identifies packages that contain
5542 the pixbuf loaders used with
5543 <filename>gdk-pixbuf</filename>.
5544 By default, the <filename>pixbufcache</filename> class
5545 assumes that the loaders are in the recipe's main package
5546 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
5547 Use this variable if the loaders you need are in a package
5548 other than that main package.
5549 </para>
5550 </glossdef>
5551 </glossentry>
5552
5553 <glossentry id='var-PKG'><glossterm>PKG</glossterm>
5554 <glossdef>
5555 <para>
5556 The name of the resulting package created by the
5557 OpenEmbedded build system.
5558 <note>
5559 When using the <filename>PKG</filename> variable, you
5560 must use a package name override.
5561 </note>
5562 For example, when the
5563 <link linkend='ref-classes-debian'><filename>debian</filename></link>
5564 class renames the output package, it does so by setting
5565 <filename>PKG_&lt;packagename&gt;</filename>.
5566 </para>
5567 </glossdef>
5568 </glossentry>
5569
5570 <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
5571 <glossdef>
5572 <para>
5573 Points to the destination directory for files to be
5574 packaged before they are split into individual packages.
5575 This directory defaults to the following:
5576 <literallayout class='monospaced'>
5577 ${WORKDIR}/package
5578 </literallayout>
5579 Do not change this default.
5580 </para>
5581 </glossdef>
5582 </glossentry>
5583
5584 <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
5585 <glossdef>
5586 <para>
5587 Points to a shared, global-state directory that holds data
5588 generated during the packaging process.
5589 During the packaging process, the
5590 <filename>do_packagedata</filename> task packages
5591 data for each recipe and installs it into this temporary,
5592 shared area.
5593 This directory defaults to the following:
5594 <literallayout class='monospaced'>
5595 ${STAGING_DIR_HOST}/pkgdata
5596 </literallayout>
5597 Do not change this default.
5598 </para>
5599 </glossdef>
5600 </glossentry>
5601
5602 <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
5603 <glossdef>
5604 <para>
5605 Points to the parent directory for files to be packaged
5606 after they have been split into individual packages.
5607 This directory defaults to the following:
5608 <literallayout class='monospaced'>
5609 ${WORKDIR}/packages-split
5610 </literallayout>
5611 Under this directory, the build system creates
5612 directories for each package specified in
5613 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
5614 Do not change this default.
5615 </para>
5616 </glossdef>
5617 </glossentry>
5618
5619 <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
5620 <glossdef>
5621 <para>
5622 Points to a temporary work area used by the
5623 <filename>do_package</filename> task to write output
5624 from the <filename>do_packagedata</filename> task.
5625 The <filename>PKGDESTWORK</filename> location defaults to
5626 the following:
5627 <literallayout class='monospaced'>
5628 ${WORKDIR}/pkgdata
5629 </literallayout>
5630 The <filename>do_packagedata</filename> task then packages
5631 the data in the temporary work area and installs it into a
5632 shared directory pointed to by
5633 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
5634 </para>
5635
5636 <para>
5637 Do not change this default.
5638 </para>
5639 </glossdef>
5640 </glossentry>
5641
5642 <glossentry id='var-PKGE'><glossterm>PKGE</glossterm>
5643 <glossdef>
5644 <para>
5645 The epoch of the output package built by the
5646 OpenEmbedded build system.
5647 By default, <filename>PKGE</filename> is set to
5648 <link linkend='var-PE'><filename>PE</filename></link>.
5649 </para>
5650 </glossdef>
5651 </glossentry>
5652
5653 <glossentry id='var-PKGR'><glossterm>PKGR</glossterm>
5654 <glossdef>
5655 <para>
5656 The revision of the output package built by the
5657 OpenEmbedded build system.
5658 By default, <filename>PKGR</filename> is set to
5659 <link linkend='var-PR'><filename>PR</filename></link>.
5660 </para>
5661 </glossdef>
5662 </glossentry>
5663
5664 <glossentry id='var-PKGV'><glossterm>PKGV</glossterm>
5665 <glossdef>
5666 <para>
5667 The version of the output package built by the
5668 OpenEmbedded build system.
5669 By default, <filename>PKGV</filename> is set to
5670 <link linkend='var-PV'><filename>PV</filename></link>.
5671 </para>
5672 </glossdef>
5673 </glossentry>
5674
5675 <glossentry id='var-PN'><glossterm>PN</glossterm>
5676 <glossdef>
5677 <para>This variable can have two separate functions depending on the context: a recipe
5678 name or a resulting package name.</para>
5679 <para><filename>PN</filename> refers to a recipe name in the context of a file used
5680 by the OpenEmbedded build system as input to create a package.
5681 The name is normally extracted from the recipe file name.
5682 For example, if the recipe is named
5683 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
5684 will be "expat".</para>
5685 <para>
5686 The variable refers to a package name in the context of a file created or produced by the
5687 OpenEmbedded build system.</para>
5688 <para>If applicable, the <filename>PN</filename> variable also contains any special
5689 suffix or prefix.
5690 For example, using <filename>bash</filename> to build packages for the native
5691 machine, <filename>PN</filename> is <filename>bash-native</filename>.
5692 Using <filename>bash</filename> to build packages for the target and for Multilib,
5693 <filename>PN</filename> would be <filename>bash</filename> and
5694 <filename>lib64-bash</filename>, respectively.
5695 </para>
5696 </glossdef>
5697 </glossentry>
5698
5699 <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>
5700 <glossdef>
5701 <para>
5702 Lists recipes you do not want the OpenEmbedded build system
5703 to build.
5704 This variable works in conjunction with the
5705 <link linkend='ref-classes-blacklist'><filename>blacklist</filename></link>
5706 class, which the recipe must inherit globally.
5707 </para>
5708
5709 <para>
5710 To prevent a recipe from being built, inherit the class
5711 globally and use the variable in your
5712 <filename>local.conf</filename> file.
5713 Here is an example that prevents
5714 <filename>myrecipe</filename> from being built:
5715 <literallayout class='monospaced'>
5716 INHERIT += "blacklist"
5717 PNBLACKLIST[myrecipe] = "Not supported by our organization."
5718 </literallayout>
5719 </para>
5720 </glossdef>
5721 </glossentry>
5722
5723 <glossentry id='var-PR'><glossterm>PR</glossterm>
5724 <glossdef>
5725 <para>
5726 The revision of the recipe.
5727 The default value for this variable is "r0".
5728 </para>
5729 </glossdef>
5730 </glossentry>
5731
5732 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
5733 <glossdef>
5734 <para>
5735 If multiple recipes provide an item, this variable
5736 determines which recipe should be given preference.
5737 You should always suffix the variable with the name of the
5738 provided item, and you should set it to the
5739 <link linkend='var-PN'><filename>PN</filename></link>
5740 of the recipe to which you want to give precedence.
5741 Some examples:
5742 <literallayout class='monospaced'>
5743 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
5744 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
5745 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
5746 </literallayout>
5747 </para>
5748 </glossdef>
5749 </glossentry>
5750
5751 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
5752 <glossdef>
5753 <para>
5754 If there are multiple versions of recipes available, this
5755 variable determines which recipe should be given preference.
5756 You must always suffix the variable with the
5757 <link linkend='var-PN'><filename>PN</filename></link>
5758 you want to select, and you should set the
5759 <link linkend='var-PV'><filename>PV</filename></link>
5760 accordingly for precedence.
5761 You can use the "<filename>%</filename>" character as a
5762 wildcard to match any number of characters, which can be
5763 useful when specifying versions that contain long revision
5764 numbers that could potentially change.
5765 Here are two examples:
5766 <literallayout class='monospaced'>
5767 PREFERRED_VERSION_python = "2.7.3"
5768 PREFERRED_VERSION_linux-yocto = "3.10%"
5769 </literallayout>
5770 </para>
5771 </glossdef>
5772 </glossentry>
5773
5774 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
5775 <glossdef>
5776 <para>
5777 Specifies additional paths from which the OpenEmbedded
5778 build system gets source code.
5779 When the build system searches for source code, it first
5780 tries the local download directory.
5781 If that location fails, the build system tries locations
5782 defined by <filename>PREMIRRORS</filename>, the upstream
5783 source, and then locations specified by
5784 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
5785 in that order.
5786 </para>
5787
5788 <para>
5789 Assuming your distribution
5790 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
5791 is "poky", the default value for
5792 <filename>PREMIRRORS</filename> is defined in the
5793 <filename>conf/distro/poky.conf</filename> file in the
5794 <filename>meta-yocto</filename> Git repository.
5795 </para>
5796
5797 <para>
5798 Typically, you could add a specific server for the
5799 build system to attempt before any others by adding
5800 something like the following to the
5801 <filename>local.conf</filename> configuration file in the
5802 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
5803 <literallayout class='monospaced'>
5804 PREMIRRORS_prepend = "\
5805 git://.*/.* http://www.yoctoproject.org/sources/ \n \
5806 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
5807 http://.*/.* http://www.yoctoproject.org/sources/ \n \
5808 https://.*/.* http://www.yoctoproject.org/sources/ \n"
5809 </literallayout>
5810 These changes cause the build system to intercept
5811 Git, FTP, HTTP, and HTTPS requests and direct them to
5812 the <filename>http://</filename> sources mirror.
5813 You can use <filename>file://</filename> URLs to point
5814 to local directories or network shares as well.
5815 </para>
5816 </glossdef>
5817 </glossentry>
5818
5819 <glossentry id='var-PRINC'><glossterm>PRINC</glossterm>
5820 <glossdef>
5821
5822 <para>
5823 The <filename>PRINC</filename> variable has been deprecated
5824 and triggers a warning if detected during a build.
5825 For
5826 <link linkend='var-PR'><filename>PR</filename></link>
5827 increments on changes, use the PR service instead.
5828 You can find out more about this service in the
5829 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
5830 section in the Yocto Project Development Manual.
5831 </para>
5832<!--
5833
5834 <para>
5835 Causes the
5836 <link linkend='var-PR'><filename>PR</filename></link>
5837 variable of <filename>.bbappend</filename> files to
5838 dynamically increment.
5839 This increment minimizes the impact of layer ordering.
5840 </para>
5841
5842 <para>
5843 In order to ensure multiple <filename>.bbappend</filename>
5844 files can co-exist,
5845 <filename>PRINC</filename> should be self-referencing.
5846 This variable defaults to 0.
5847 </para>
5848
5849 <para>
5850 Following is an example that increments
5851 <filename>PR</filename> by two:
5852 <literallayout class='monospaced'>
5853 PRINC := "${@int(PRINC) + 2}"
5854 </literallayout>
5855 It is advisable not to use strings such as ".= '.1'" with the variable because
5856 this usage is very sensitive to layer ordering.
5857 You should avoid explicit assignments as they cannot
5858 adequately represent multiple
5859 <filename>.bbappend</filename> files.
5860 </para>
5861-->
5862 </glossdef>
5863 </glossentry>
5864
5865 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
5866 <glossdef>
5867 <para>
5868 A list of aliases that a recipe also provides.
5869 These aliases are useful for satisfying dependencies of
5870 other recipes during the build (as specified by
5871 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>).
5872 <note>
5873 A recipe's own
5874 <filename><link linkend='var-PN'>PN</link></filename>
5875 is implicitly already in its
5876 <filename>PROVIDES</filename> list.
5877 </note>
5878 </para>
5879 </glossdef>
5880 </glossentry>
5881
5882 <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
5883 <glossdef>
5884 <para>
5885 The network based
5886 <link linkend='var-PR'><filename>PR</filename></link>
5887 service host and port.
5888 </para>
5889
5890 <para>
5891 The <filename>conf/local.conf.sample.extended</filename>
5892 configuration file in the
5893 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
5894 shows how the <filename>PRSERV_HOST</filename> variable is
5895 set:
5896 <literallayout class='monospaced'>
5897 PRSERV_HOST = "localhost:0"
5898 </literallayout>
5899 You must set the variable if you want to automatically
5900 start a local
5901 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.
5902 You can set <filename>PRSERV_HOST</filename> to other
5903 values to use a remote PR service.
5904 </para>
5905 </glossdef>
5906 </glossentry>
5907
5908 <glossentry id='var-PV'><glossterm>PV</glossterm>
5909 <glossdef>
5910 <para>
5911 The version of the recipe.
5912 The version is normally extracted from the recipe filename.
5913 For example, if the recipe is named
5914 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename>
5915 will be "2.0.1".
5916 <filename>PV</filename> is generally not overridden within
5917 a recipe unless it is building an unstable (i.e. development) version from a source code repository
5918 (e.g. Git or Subversion).
5919 </para>
5920 </glossdef>
5921 </glossentry>
5922
5923 <glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>
5924 <glossdef>
5925 <para>
5926 When used by recipes that inherit the
5927 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
5928 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
5929 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
5930 or
5931 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
5932 classes, denotes the Application Binary Interface (ABI)
5933 currently in use for Python.
5934 By default, the ABI is "m".
5935 You do not have to set this variable as the OpenEmbedded
5936 build system sets it for you.
5937 </para>
5938
5939 <para>
5940 The OpenEmbedded build system uses the ABI to construct
5941 directory names used when installing the Python headers
5942 and libraries in sysroot
5943 (e.g. <filename>.../python3.3m/...</filename>).
5944 </para>
5945
5946 <para>
5947 Recipes that inherit the
5948 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>
5949 class during cross-builds also use this variable to
5950 locate the headers and libraries of the appropriate Python
5951 that the extension is targeting.
5952 </para>
5953 </glossdef>
5954 </glossentry>
5955
5956 <glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>
5957 <glossdef>
5958 <para>
5959 When used by recipes that inherit the
5960 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
5961 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
5962 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
5963 or
5964 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
5965 classes, specifies the major Python version being built.
5966 For Python 2.x, <filename>PYTHON_PN</filename> would
5967 be "python2". For Python 3.x, the variable would be
5968 "python3".
5969 You do not have to set this variable as the
5970 OpenEmbedded build system automatically sets it for you.
5971 </para>
5972
5973 <para>
5974 The variable allows recipes to use common infrastructure
5975 such as the following:
5976 <literallayout class='monospaced'>
5977 DEPENDS += "${PYTHON_PN}-native"
5978 </literallayout>
5979 In the previous example, the version of the dependency
5980 is <filename>PYTHON_PN</filename>.
5981 </para>
5982 </glossdef>
5983 </glossentry>
5984
5985 </glossdiv>
5986
5987 <glossdiv id='var-glossary-q'><title>Q</title>
5988
5989 <glossentry id='var-QMAKE_PROFILES'><glossterm>QMAKE_PROFILES</glossterm>
5990 <glossdef>
5991 <para>
5992 Specifies your own subset of <filename>.pro</filename>
5993 files to be built for use with
5994 <filename>qmake</filename>.
5995 If you do not set this variable, all
5996 <filename>.pro</filename> files in the directory pointed to
5997 by <link linkend='var-S'><filename>S</filename></link>
5998 will be built by default.
5999 </para>
6000
6001 <para>
6002 This variable is used with recipes that inherit the
6003 <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link>
6004 class or other classes that inherit
6005 <filename>qmake_base</filename>.
6006 </para>
6007 </glossdef>
6008 </glossentry>
6009
6010 </glossdiv>
6011
6012 <glossdiv id='var-glossary-r'><title>R</title>
6013
6014 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
6015 <glossdef>
6016 <para>
6017 The list of packages that conflict with packages.
6018 Note that packages will not be installed if conflicting
6019 packages are not first removed.
6020 </para>
6021
6022 <para>
6023 Like all package-controlling variables, you must always use
6024 them in conjunction with a package name override.
6025 Here is an example:
6026 <literallayout class='monospaced'>
6027 RCONFLICTS_${PN} = "another-conflicting-package-name"
6028 </literallayout>
6029 </para>
6030
6031 <para>
6032 BitBake, which the OpenEmbedded build system uses, supports
6033 specifying versioned dependencies.
6034 Although the syntax varies depending on the packaging
6035 format, BitBake hides these differences from you.
6036 Here is the general syntax to specify versions with
6037 the <filename>RCONFLICTS</filename> variable:
6038 <literallayout class='monospaced'>
6039 RCONFLICTS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6040 </literallayout>
6041 For <filename>operator</filename>, you can specify the
6042 following:
6043 <literallayout class='monospaced'>
6044 =
6045 &lt;
6046 &gt;
6047 &lt;=
6048 &gt;=
6049 </literallayout>
6050 For example, the following sets up a dependency on version
6051 1.2 or greater of the package <filename>foo</filename>:
6052 <literallayout class='monospaced'>
6053 RCONFLICTS_${PN} = "foo (>= 1.2)"
6054 </literallayout>
6055 </para>
6056 </glossdef>
6057 </glossentry>
6058
6059 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
6060 <glossdef>
6061 <para>
6062 Lists a package's runtime dependencies (i.e. other packages)
6063 that must be installed in order for the built package to run
6064 correctly.
6065 If a package in this list cannot be found during the build,
6066 you will get a build error.
6067 </para>
6068
6069 <para>
6070 When you use the <filename>RDEPENDS</filename> variable
6071 in a recipe, you are essentially stating that the recipe's
6072 <filename>do_build</filename> task depends on the existence
6073 of a specific package.
6074 Consider this simple example for two recipes named "a" and
6075 "b" that produce similarly named IPK packages.
6076 In this example, the <filename>RDEPENDS</filename>
6077 statement appears in the "a" recipe:
6078 <literallayout class='monospaced'>
6079 RDEPENDS_${PN} = "b"
6080 </literallayout>
6081 Here, the dependency is such that the
6082 <filename>do_build</filename> task for recipe "a" depends
6083 on the <filename>do_package_write_ipk</filename> task
6084 of recipe "b".
6085 This means the package file for "b" must be available when
6086 the output for recipe "a" has been completely built.
6087 More importantly, package "a" will be marked as depending
6088 on package "b" in a manner that is understood by the
6089 package manager.
6090 </para>
6091
6092 <para>
6093 The names of the packages you list within
6094 <filename>RDEPENDS</filename> must be the names of other
6095 packages - they cannot be recipe names.
6096 Although package names and recipe names usually match,
6097 the important point here is that you are
6098 providing package names within the
6099 <filename>RDEPENDS</filename> variable.
6100 For an example of the default list of packages created from
6101 a recipe, see the
6102 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
6103 variable.
6104 </para>
6105
6106 <para>
6107 Because the <filename>RDEPENDS</filename> variable applies
6108 to packages being built, you should always use the variable
6109 in a form with an attached package name.
6110 For example, suppose you are building a development package
6111 that depends on the <filename>perl</filename> package.
6112 In this case, you would use the following
6113 <filename>RDEPENDS</filename> statement:
6114 <literallayout class='monospaced'>
6115 RDEPENDS_${PN}-dev += "perl"
6116 </literallayout>
6117 In the example, the development package depends on
6118 the <filename>perl</filename> package.
6119 Thus, the <filename>RDEPENDS</filename> variable has the
6120 <filename>${PN}-dev</filename> package name as part of the
6121 variable.
6122 </para>
6123
6124 <para>
6125 The package name you attach to the
6126 <filename>RDEPENDS</filename> variable must appear
6127 as it would in the <filename>PACKAGES</filename>
6128 namespace before any renaming of the output package by
6129 classes like <filename>debian.bbclass</filename>.
6130 </para>
6131
6132 <para>
6133 In many cases you do not need to explicitly add
6134 runtime dependencies using
6135 <filename>RDEPENDS</filename> since some automatic
6136 handling occurs:
6137 <itemizedlist>
6138 <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If
6139 a runtime package contains a shared library
6140 (<filename>.so</filename>), the build
6141 processes the library in order to determine other
6142 libraries to which it is dynamically linked.
6143 The build process adds these libraries to
6144 <filename>RDEPENDS</filename> when creating the runtime
6145 package.</para></listitem>
6146 <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If
6147 the package ships a <filename>pkg-config</filename>
6148 information file, the build process uses this file
6149 to add items to the <filename>RDEPENDS</filename>
6150 variable to create the runtime packages.
6151 </para></listitem>
6152 </itemizedlist>
6153 </para>
6154
6155 <para>
6156 BitBake, which the OpenEmbedded build system uses, supports
6157 specifying versioned dependencies.
6158 Although the syntax varies depending on the packaging
6159 format, BitBake hides these differences from you.
6160 Here is the general syntax to specify versions with
6161 the <filename>RDEPENDS</filename> variable:
6162 <literallayout class='monospaced'>
6163 RDEPENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6164 </literallayout>
6165 For <filename>operator</filename>, you can specify the
6166 following:
6167 <literallayout class='monospaced'>
6168 =
6169 &lt;
6170 &gt;
6171 &lt;=
6172 &gt;=
6173 </literallayout>
6174 For example, the following sets up a dependency on version
6175 1.2 or greater of the package <filename>foo</filename>:
6176 <literallayout class='monospaced'>
6177 RDEPENDS_${PN} = "foo (>= 1.2)"
6178 </literallayout>
6179 </para>
6180
6181 <para>
6182 For information on build-time dependencies, see the
6183 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
6184 variable.
6185 </para>
6186 </glossdef>
6187 </glossentry>
6188
6189 <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm>
6190 <glossdef>
6191 <para>
6192 When a recipe inherits the
6193 <filename>distro_features_check</filename> class, this
6194 variable identifies distribution features that must
6195 exist in the current configuration in order for the
6196 OpenEmbedded build system to build the recipe.
6197 In other words, if the
6198 <filename>REQUIRED_DISTRO_FEATURES</filename> variable
6199 lists a feature that does not appear in
6200 <filename>DISTRO_FEATURES</filename> within the
6201 current configuration, an error occurs and the
6202 build stops.
6203 </para>
6204 </glossdef>
6205 </glossentry>
6206
6207 <glossentry id='var-RM_OLD_IMAGE'><glossterm>RM_OLD_IMAGE</glossterm>
6208 <glossdef>
6209 <para>
6210 Reclaims disk space by removing previously built
6211 versions of the same image from the
6212 <filename>images</filename> directory pointed to by the
6213 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
6214 variable.
6215 </para>
6216
6217 <para>
6218 Set this variable to "1" in your
6219 <filename>local.conf</filename> file to remove these
6220 images.
6221 </para>
6222 </glossdef>
6223 </glossentry>
6224
6225 <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
6226 <glossdef>
6227 <para>
6228 With <filename>rm_work</filename> enabled, this
6229 variable specifies a list of recipes whose work directories
6230 should not be removed.
6231 See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
6232 section for more details.
6233 </para>
6234 </glossdef>
6235 </glossentry>
6236
6237 <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm>
6238 <glossdef>
6239 <para>
6240 Defines the root home directory.
6241 By default, this directory is set as follows in the
6242 BitBake configuration file:
6243 <literallayout class='monospaced'>
6244 ROOT_HOME ??= "/home/root"
6245 </literallayout>
6246 <note>
6247 This default value is likely used because some
6248 embedded solutions prefer to have a read-only root
6249 filesystem and prefer to keep writeable data in one
6250 place.
6251 </note>
6252 </para>
6253
6254 <para>
6255 You can override the default by setting the variable
6256 in any layer or in the <filename>local.conf</filename> file.
6257 Because the default is set using a "weak" assignment
6258 (i.e. "??="), you can use either of the following forms
6259 to define your override:
6260 <literallayout class='monospaced'>
6261 ROOT_HOME = "/root"
6262 ROOT_HOME ?= "/root"
6263 </literallayout>
6264 These override examples use <filename>/root</filename>,
6265 which is probably the most commonly used override.
6266 </para>
6267 </glossdef>
6268 </glossentry>
6269
6270 <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>
6271 <glossdef>
6272 <para>
6273 Indicates a filesystem image to include as the root
6274 filesystem.
6275 </para>
6276
6277 <para>
6278 The <filename>ROOTFS</filename> variable is an optional
6279 variable used with the
6280 <link linkend='ref-classes-bootimg'><filename>buildimg</filename></link>
6281 class.
6282 </para>
6283 </glossdef>
6284 </glossentry>
6285
6286 <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
6287 <glossdef>
6288 <para>
6289 Added by classes to run post processing commands once the
6290 OpenEmbedded build system has created the root filesystem.
6291 You can specify shell commands separated by semicolons:
6292 <literallayout class='monospaced'>
6293 ROOTFS_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
6294 </literallayout>
6295 If you need to pass the path to the root filesystem within
6296 the command, you can use
6297 <filename>${IMAGE_ROOTFS}</filename>, which points to
6298 the root filesystem image.
6299 </para>
6300 </glossdef>
6301 </glossentry>
6302
6303 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
6304 <glossdef>
6305 <para>
6306 A list of package name aliases that a package also provides.
6307 These aliases are useful for satisfying runtime dependencies
6308 of other packages both during the build and on the target
6309 (as specified by
6310 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
6311 <note>
6312 A package's own name is implicitly already in its
6313 <filename>RPROVIDES</filename> list.
6314 </note>
6315 </para>
6316 <para>
6317 As with all package-controlling variables, you must always
6318 use the variable in conjunction with a package name override.
6319 Here is an example:
6320 <literallayout class='monospaced'>
6321 RPROVIDES_${PN} = "widget-abi-2"
6322 </literallayout>
6323 </para>
6324 </glossdef>
6325 </glossentry>
6326
6327 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
6328 <glossdef>
6329 <para>
6330 A list of packages that extends the usability of a package
6331 being built.
6332 The package being built does not depend on this list of
6333 packages in order to successfully build, but needs them for
6334 the extended usability.
6335 To specify runtime dependencies for packages, see the
6336 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
6337 variable.
6338 </para>
6339
6340 <para>
6341 The OpenEmbedded build process automatically installs the
6342 list of packages as part of the built package.
6343 However, you can remove these packages later if you want.
6344 If, during the build, a package from the
6345 <filename>RRECOMMENDS</filename> list cannot be
6346 found, the build process continues without an error.
6347 </para>
6348
6349 <para>
6350 You can also prevent packages in the list from being
6351 installed by using several variables.
6352 See the
6353 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
6354 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
6355 and
6356 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
6357 variables for more information.
6358 </para>
6359
6360 <para>
6361 Because the <filename>RRECOMMENDS</filename> variable
6362 applies to packages being built, you should always attach
6363 an override to the variable to specify the particular
6364 package whose usability is being extended.
6365 For example, suppose you are building a development package
6366 that is extended to support wireless functionality.
6367 In this case, you would use the following:
6368 <literallayout class='monospaced'>
6369 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
6370 </literallayout>
6371 In the example, the package name
6372 (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
6373 must appear as it would in the
6374 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
6375 namespace before any renaming of the output package by
6376 classes such as <filename>debian.bbclass</filename>.
6377 </para>
6378
6379 <para>
6380 BitBake, which the OpenEmbedded build system uses, supports
6381 specifying versioned recommends.
6382 Although the syntax varies depending on the packaging
6383 format, BitBake hides these differences from you.
6384 Here is the general syntax to specify versions with
6385 the <filename>RRECOMMENDS</filename> variable:
6386 <literallayout class='monospaced'>
6387 RRECOMMENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6388 </literallayout>
6389 For <filename>operator</filename>, you can specify the
6390 following:
6391 <literallayout class='monospaced'>
6392 =
6393 &lt;
6394 &gt;
6395 &lt;=
6396 &gt;=
6397 </literallayout>
6398 For example, the following sets up a recommend on version
6399 1.2 or greater of the package <filename>foo</filename>:
6400 <literallayout class='monospaced'>
6401 RRECOMMENDS_${PN} = "foo (>= 1.2)"
6402 </literallayout>
6403 </para>
6404 </glossdef>
6405 </glossentry>
6406
6407 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
6408 <glossdef>
6409 <para>
6410 A list of packages replaced by a package.
6411 The package manager uses this variable to determine which
6412 package should be installed to replace other package(s)
6413 during an upgrade.
6414 In order to also have the other package(s) removed at the
6415 same time, you must add the name of the other
6416 package to the
6417 <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
6418 </para>
6419 <para>
6420 As with all package-controlling variables, you must use
6421 this variable in conjunction with a package name
6422 override.
6423 Here is an example:
6424 <literallayout class='monospaced'>
6425 RREPLACES_${PN} = "other-package-being-replaced"
6426 </literallayout>
6427 </para>
6428
6429 <para>
6430 BitBake, which the OpenEmbedded build system uses, supports
6431 specifying versioned replacements.
6432 Although the syntax varies depending on the packaging
6433 format, BitBake hides these differences from you.
6434 Here is the general syntax to specify versions with
6435 the <filename>RREPLACES</filename> variable:
6436 <literallayout class='monospaced'>
6437 RREPLACES_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
6438 </literallayout>
6439 For <filename>operator</filename>, you can specify the
6440 following:
6441 <literallayout class='monospaced'>
6442 =
6443 &lt;
6444 &gt;
6445 &lt;=
6446 &gt;=
6447 </literallayout>
6448 For example, the following sets up a replacement using
6449 version 1.2 or greater of the package
6450 <filename>foo</filename>:
6451 <literallayout class='monospaced'>
6452 RREPLACES_${PN} = "foo (>= 1.2)"
6453 </literallayout>
6454 </para>
6455 </glossdef>
6456 </glossentry>
6457
6458 <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
6459 <glossdef>
6460 <para>
6461 A list of additional packages that you can suggest for
6462 installation by the package manager at the time a package
6463 is installed.
6464 Not all package managers support this functionality.
6465 </para>
6466 <para>
6467 As with all package-controlling variables, you must always
6468 use this variable in conjunction with a package name
6469 override.
6470 Here is an example:
6471 <literallayout class='monospaced'>
6472 RSUGGESTS_${PN} = "useful-package another-package"
6473 </literallayout>
6474 </para>
6475 </glossdef>
6476 </glossentry>
6477
6478 </glossdiv>
6479
6480 <glossdiv id='var-glossary-s'><title>S</title>
6481
6482 <glossentry id='var-S'><glossterm>S</glossterm>
6483 <glossdef>
6484 <para>
6485 The location in the
6486 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
6487 where unpacked recipe source code resides.
6488 This location is within the work directory
6489 (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>),
6490 which is not static.
6491 The unpacked source location depends on the recipe name
6492 (<filename><link linkend='var-PN'>PN</link></filename>) and
6493 recipe version
6494 (<filename><link linkend='var-PV'>PV</link></filename>) as
6495 follows:
6496 <literallayout class='monospaced'>
6497 ${WORKDIR}/${PN}-${PV}
6498 </literallayout>
6499 As an example, assume a
6500 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
6501 top-level folder named <filename>poky</filename> and a
6502 default Build Directory at <filename>poky/build</filename>.
6503 In this case, the work directory the build system uses
6504 to keep the unpacked recipe for <filename>db</filename>
6505 is the following:
6506 <literallayout class='monospaced'>
6507 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
6508 </literallayout>
6509 </para>
6510 </glossdef>
6511 </glossentry>
6512
6513 <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
6514 <glossdef>
6515 <para>
6516 A list of the host distribution identifiers that the
6517 build system has been tested against.
6518 Identifiers consist of the host distributor ID
6519 followed by the release,
6520 as reported by the <filename>lsb_release</filename> tool
6521 or as read from <filename>/etc/lsb-release</filename>.
6522 Separate the list items with explicit newline
6523 characters (<filename>\n</filename>).
6524 If <filename>SANITY_TESTED_DISTROS</filename> is not empty
6525 and the current value of
6526 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
6527 does not appear in the list, then the build system reports
6528 a warning that indicates the current host distribution has
6529 not been tested as a build host.
6530 </para>
6531 </glossdef>
6532 </glossentry>
6533
6534 <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
6535 <glossdef>
6536 <para>
6537 The target architecture for the SDK.
6538 Typically, you do not directly set this variable.
6539 Instead, use
6540 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
6541 </para>
6542 </glossdef>
6543 </glossentry>
6544
6545 <glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>
6546 <glossdef>
6547 <para>
6548 The directory set up and used by the
6549 <link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link>
6550 to which the SDK is deployed.
6551 The <filename>populate_sdk_base</filename> class defines
6552 <filename>SDK_DEPLOY</filename> as follows:
6553 <literallayout class='monospaced'>
6554 SDK_DEPLOY = "${<link linkend='var-TMPDIR'>TMPDIR</link>}/deploy/sdk"
6555 </literallayout>
6556 </para>
6557 </glossdef>
6558 </glossentry>
6559
6560 <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm>
6561 <glossdef>
6562 <para>
6563 The parent directory used by the OpenEmbedded build system
6564 when creating SDK output.
6565 The
6566 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
6567 class defines the variable as follows:
6568 <literallayout class='monospaced'>
6569 SDK_DIR = "${<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>}/sdk"
6570 </literallayout>
6571 <note>
6572 The <filename>SDK_DIR</filename> directory is a
6573 temporary directory as it is part of
6574 <filename>WORKDIR</filename>.
6575 The final output directory is
6576 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
6577 </note>
6578 </para>
6579 </glossdef>
6580 </glossentry>
6581
6582 <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
6583 <glossdef>
6584 <para>
6585 The base name for SDK output files.
6586 The name is derived from the
6587 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
6588 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
6589 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
6590 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
6591 and
6592 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
6593 variables:
6594 <literallayout class='monospaced'>
6595 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
6596 </literallayout>
6597 </para>
6598 </glossdef>
6599 </glossentry>
6600
6601 <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>
6602 <glossdef>
6603 <para>
6604 The location used by the OpenEmbedded build system when
6605 creating SDK output.
6606 The
6607 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
6608 class defines the variable as follows:
6609 <literallayout class='monospaced'>
6610 SDK_OUTPUT = "${<link linkend='var-SDK_DIR'>SDK_DIR</link>}/image"
6611 </literallayout>
6612 <note>
6613 The <filename>SDK_OUTPUT</filename> directory is a
6614 temporary directory as it is part of
6615 <filename>WORKDIR</filename> by way of
6616 <filename>SDK_DIR</filename>.
6617 The final output directory is
6618 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
6619 </note>
6620
6621 </para>
6622 </glossdef>
6623 </glossentry>
6624
6625 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
6626 <glossdef>
6627 <para>Equivalent to
6628 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
6629 However, this variable applies to the SDK generated from an
6630 image using the following command:
6631 <literallayout class='monospaced'>
6632 $ bitbake -c populate_sdk imagename
6633 </literallayout>
6634 </para>
6635 </glossdef>
6636 </glossentry>
6637
6638 <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
6639 <glossdef>
6640 <para>
6641 The architecture of the machine that runs Application
6642 Development Toolkit (ADT) items.
6643 In other words, packages are built so that they will run
6644 on the target you specify with the argument.
6645 This implies that you can build out ADT/SDK items that
6646 run on an architecture other than that of your build host.
6647 For example, you can use an x86_64-based build host to
6648 create packages that will run on an i686-based
6649 SDK Machine.
6650 </para>
6651
6652 <para>
6653 You can use "i686" and "x86_64" as possible values for this
6654 variable.
6655 The variable defaults to "i686" and is set in the
6656 <filename>local.conf</filename> file in the
6657 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
6658 <literallayout class='monospaced'>
6659 SDKMACHINE ?= "i686"
6660 </literallayout>
6661 <note>
6662 You cannot set the <filename>SDKMACHINE</filename>
6663 variable in your distribution configuration file.
6664 If you do, the configuration will not take affect.
6665 </note>
6666 </para>
6667 </glossdef>
6668 </glossentry>
6669
6670 <glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>
6671 <glossdef>
6672 <para>
6673 Defines the path offered to the user for installation
6674 of the SDK that is generated by the OpenEmbedded build
6675 system.
6676 The path appears as the default location for installing
6677 the SDK when you run the SDK's installation script.
6678 You can override the offered path when you run the
6679 script.
6680 </para>
6681 </glossdef>
6682 </glossentry>
6683
6684 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
6685 <glossdef>
6686 <para>The section in which packages should be categorized.
6687 Package management utilities can make use of this variable.</para>
6688 </glossdef>
6689 </glossentry>
6690
6691 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
6692 <glossdef>
6693 <para>
6694 The variable takes the value of
6695 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
6696 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
6697 In this case the value of
6698 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
6699 </para>
6700 </glossdef>
6701 </glossentry>
6702
6703 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
6704 <glossdef>
6705 <para>
6706 Defines a serial console (TTY) to enable using getty.
6707 Provide a value that specifies the baud rate followed by
6708 the TTY device name separated by a space.
6709 You cannot specify more than one TTY device:
6710 <literallayout class='monospaced'>
6711 SERIAL_CONSOLE = "115200 ttyS0"
6712 </literallayout>
6713 <note>
6714 The <filename>SERIAL_CONSOLE</filename> variable
6715 is deprecated.
6716 Please use the
6717 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
6718 variable.
6719 </note>
6720 </para>
6721 </glossdef>
6722 </glossentry>
6723
6724 <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
6725 <glossdef>
6726 <para>
6727 Defines the serial consoles (TTYs) to enable using getty.
6728 Provide a value that specifies the baud rate followed by
6729 the TTY device name separated by a semicolon.
6730 Use spaces to separate multiple devices:
6731 <literallayout class='monospaced'>
6732 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
6733 </literallayout>
6734 </para>
6735 </glossdef>
6736 </glossentry>
6737
6738 <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
6739 <glossdef>
6740 <para>
6741 Similar to
6742 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
6743 except the device is checked for existence before attempting
6744 to enable it.
6745 This variable is currently only supported with SysVinit
6746 (i.e. not with systemd).
6747 </para>
6748 </glossdef>
6749 </glossentry>
6750
6751 <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
6752 <glossdef>
6753 <para>
6754 A list of recipe dependencies that should not be used to
6755 determine signatures of tasks from one recipe when they
6756 depend on tasks from another recipe.
6757 For example:
6758 <literallayout class='monospaced'>
6759 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
6760 </literallayout>
6761 In this example, <filename>intone</filename> depends on
6762 <filename>mplayer2</filename>.
6763 </para>
6764
6765 <para>
6766 Use of this variable is one mechanism to remove dependencies
6767 that affect task signatures and thus force rebuilds when a
6768 recipe changes.
6769 <note><title>Caution</title>
6770 If you add an inappropriate dependency for a recipe
6771 relationship, the software might break during
6772 runtime if the interface of the second recipe was
6773 changed after the first recipe had been built.
6774 </note>
6775 </para>
6776 </glossdef>
6777 </glossentry>
6778
6779 <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
6780 <glossdef>
6781 <para>
6782 A list of recipes that are completely stable and will
6783 never change.
6784 The ABI for the recipes in the list are presented by
6785 output from the tasks run to build the recipe.
6786 Use of this variable is one way to remove dependencies from
6787 one recipe on another that affect task signatures and
6788 thus force rebuilds when the recipe changes.
6789 <note><title>Caution</title>
6790 If you add an inappropriate variable to this list,
6791 the software might break at runtime if the
6792 interface of the recipe was changed after the other
6793 had been built.
6794 </note>
6795 </para>
6796 </glossdef>
6797 </glossentry>
6798
6799 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
6800 <glossdef>
6801 <para>
6802 Specifies the number of bits for the target system CPU.
6803 The value should be either "32" or "64".
6804 </para>
6805 </glossdef>
6806 </glossentry>
6807
6808 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
6809 <glossdef>
6810 <para>
6811 Specifies the endian byte order of the target system.
6812 The value should be either "le" for little-endian or "be" for big-endian.
6813 </para>
6814 </glossdef>
6815 </glossentry>
6816
6817 <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
6818 <glossdef>
6819 <para>
6820 Groups together machines based upon the same family
6821 of SOC (System On Chip).
6822 You typically set this variable in a common
6823 <filename>.inc</filename> file that you include in the
6824 configuration files of all the machines.
6825 <note>
6826 You must include
6827 <filename>conf/machine/include/soc-family.inc</filename>
6828 for this variable to appear in
6829 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
6830 </note>
6831 </para>
6832 </glossdef>
6833 </glossentry>
6834
6835 <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
6836 <glossdef>
6837 <para>
6838 Defines the suffix for shared libraries used on the
6839 target platform.
6840 By default, this suffix is ".so.*" for all Linux-based
6841 systems and is defined in the
6842 <filename>meta/conf/bitbake.conf</filename> configuration
6843 file.
6844 </para>
6845
6846 <para>
6847 You will see this variable referenced in the default values
6848 of <filename>FILES_${PN}</filename>.
6849 </para>
6850 </glossdef>
6851 </glossentry>
6852
6853 <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
6854 <glossdef>
6855 <para>
6856 Defines the suffix for the development symbolic link
6857 (symlink) for shared libraries on the target platform.
6858 By default, this suffix is ".so" for Linux-based
6859 systems and is defined in the
6860 <filename>meta/conf/bitbake.conf</filename> configuration
6861 file.
6862 </para>
6863
6864 <para>
6865 You will see this variable referenced in the default values
6866 of <filename>FILES_${PN}-dev</filename>.
6867 </para>
6868 </glossdef>
6869 </glossentry>
6870
6871 <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm>
6872 <glossdef>
6873 <para>
6874 Defines your own
6875 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
6876 from which to first fetch source before attempting to fetch
6877 from the upstream specified in
6878 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
6879 </para>
6880
6881 <para>
6882 To use this variable, you must globally inherit the
6883 <link linkend='ref-classes-own-mirrors'><filename>own-mirrors</filename></link>
6884 class and then provide the URL to your mirrors.
6885 Here is an example:
6886 <literallayout class='monospaced'>
6887 INHERIT += "own-mirrors"
6888 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
6889 </literallayout>
6890 <note>
6891 You can specify only a single URL in
6892 <filename>SOURCE_MIRROR_URL</filename>.
6893 </note>
6894 </para>
6895 </glossdef>
6896 </glossentry>
6897
6898 <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>
6899 <glossdef>
6900 <para>
6901 Maps commonly used license names to their SPDX counterparts
6902 found in <filename>meta/files/common-licenses/</filename>.
6903 For the default <filename>SPDXLICENSEMAP</filename>
6904 mappings, see the
6905 <filename>meta/conf/licenses.conf</filename> file.
6906 </para>
6907
6908 <para>
6909 For additional information, see the
6910 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
6911 variable.
6912 </para>
6913 </glossdef>
6914 </glossentry>
6915
6916 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
6917 <glossdef>
6918 <para>
6919 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
6920 OpenEmbedded build system to create variants of recipes or packages.
6921 The list specifies the prefixes to strip off during certain circumstances
6922 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
6923 </para>
6924 </glossdef>
6925 </glossentry>
6926
6927 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
6928 <glossdef>
6929 <para>The list of source files - local or remote.
6930 This variable tells the OpenEmbedded build system which bits
6931 to pull in for the build and how to pull them in.
6932 For example, if the recipe or append file only needs to
6933 fetch a tarball from the Internet, the recipe or
6934 append file uses a single <filename>SRC_URI</filename>
6935 entry.
6936 On the other hand, if the recipe or append file needs to
6937 fetch a tarball, apply two patches, and include a custom
6938 file, the recipe or append file would include four
6939 instances of the variable.</para>
6940 <para>The following list explains the available URI protocols:
6941 <itemizedlist>
6942 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
6943 Fetches files, which are usually files shipped with
6944 the
6945 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
6946 from the local machine.
6947 The path is relative to the
6948 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
6949 variable.
6950 Thus, the build system searches, in order, from the
6951 following directories, which are assumed to be a
6952 subdirectories of the directory in which the
6953 recipe file (<filename>.bb</filename>) or
6954 append file (<filename>.bbappend</filename>)
6955 resides:
6956 <itemizedlist>
6957 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
6958 The base recipe name without any special
6959 suffix or version numbers.
6960 </para></listitem>
6961 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
6962 <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
6963 The base recipe name and version but without
6964 any special package name suffix.
6965 </para></listitem>
6966 <listitem><para><emphasis>files -</emphasis>
6967 Files within a directory, which is named
6968 <filename>files</filename> and is also
6969 alongside the recipe or append file.
6970 </para></listitem>
6971 </itemizedlist>
6972 <note>
6973 If you want the build system to pick up files
6974 specified through a
6975 <filename>SRC_URI</filename>
6976 statement from your append file, you need to be
6977 sure to extend the
6978 <filename>FILESPATH</filename>
6979 variable by also using the
6980 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
6981 variable from within your append file.
6982 </note>
6983 </para></listitem>
6984 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
6985 Bazaar revision control repository.</para></listitem>
6986 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
6987 Git revision control repository.</para></listitem>
6988 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
6989 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
6990 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
6991 a repo (Git) repository.</para></listitem>
6992 <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from
6993 an SVK revision control repository.</para></listitem>
6994 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
6995 the Internet using <filename>http</filename>.</para></listitem>
6996 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
6997 from the Internet using <filename>https</filename>.</para></listitem>
6998 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
6999 from the Internet using <filename>ftp</filename>.</para></listitem>
7000 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
7001 a CVS revision control repository.</para></listitem>
7002 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
7003 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
7004 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
7005 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
7006 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
7007 a secure shell.</para></listitem>
7008 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
7009 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
7010 </itemizedlist>
7011 </para>
7012 <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
7013 Here are standard options:
7014 <itemizedlist>
7015 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
7016 the patch or not.
7017 The default action is to apply the patch.</para></listitem>
7018 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
7019 striplevel to use when applying the patch.
7020 The default level is 1.</para></listitem>
7021 <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
7022 the directory in which the patch should be applied.
7023 The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
7024 </para></listitem>
7025 </itemizedlist>
7026 </para>
7027 <para>Here are options specific to recipes building code from a revision control system:
7028 <itemizedlist>
7029 <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
7030 Apply the patch only if
7031 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
7032 is equal to or greater than <filename>mindate</filename>.
7033 </para></listitem>
7034 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
7035 Apply the patch only if <filename>SRCDATE</filename>
7036 is not later than <filename>mindate</filename>.
7037 </para></listitem>
7038 <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
7039 Apply the patch only if <filename>SRCREV</filename>
7040 is equal to or greater than <filename>minrev</filename>.
7041 </para></listitem>
7042 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
7043 Apply the patch only if <filename>SRCREV</filename>
7044 is not later than <filename>maxrev</filename>.
7045 </para></listitem>
7046 <listitem><para><emphasis><filename>rev</filename> -</emphasis>
7047 Apply the patch only if <filename>SRCREV</filename>
7048 is equal to <filename>rev</filename>.
7049 </para></listitem>
7050 <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
7051 Apply the patch only if <filename>SRCREV</filename>
7052 is not equal to <filename>rev</filename>.
7053 </para></listitem>
7054 </itemizedlist>
7055 </para>
7056 <para>Here are some additional options worth mentioning:
7057 <itemizedlist>
7058 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
7059 whether or not to unpack the file if it is an archive.
7060 The default action is to unpack the file.</para></listitem>
7061 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
7062 (or extracts its contents) into the specified
7063 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
7064 This option is useful for unusual tarballs or other archives that
7065 do not have their files already in a subdirectory within the archive.
7066 </para></listitem>
7067 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
7068 name to be used for association with <filename>SRC_URI</filename> checksums
7069 when you have more than one file specified in <filename>SRC_URI</filename>.
7070 </para></listitem>
7071 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
7072 the filename used when storing the downloaded file.</para></listitem>
7073 </itemizedlist>
7074 </para>
7075 </glossdef>
7076 </glossentry>
7077
7078 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
7079 <glossdef>
7080 <para></para>
7081 <para>
7082 By default, the OpenEmbedded build system automatically detects whether
7083 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
7084 contains files that are machine-specific.
7085 If so, the build system automatically changes
7086 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
7087 Setting this variable to "0" disables this behavior.
7088 </para>
7089 </glossdef>
7090 </glossentry>
7091
7092 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
7093 <glossdef>
7094 <para>
7095 The date of the source code used to build the package.
7096 This variable applies only if the source was fetched from a Source Code Manager (SCM).
7097 </para>
7098 </glossdef>
7099 </glossentry>
7100
7101 <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
7102 <glossdef>
7103 <para>
7104 Returns the version string of the current package.
7105 This string is used to help define the value of
7106 <link linkend='var-PV'><filename>PV</filename></link>.
7107 </para>
7108
7109 <para>
7110 The <filename>SRCPV</filename> variable is defined in the
7111 <filename>meta/conf/bitbake.conf</filename> configuration
7112 file in the
7113 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
7114 as follows:
7115 <literallayout class='monospaced'>
7116 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
7117 </literallayout>
7118 </para>
7119
7120 <para>
7121 Recipes that need to define <filename>PV</filename> do so
7122 with the help of the <filename>SRCPV</filename>.
7123 For example, the <filename>ofono</filename> recipe
7124 (<filename>ofono_git.bb</filename>) located in
7125 <filename>meta/recipes-connectivity</filename> in the
7126 Source Directory defines <filename>PV</filename> as
7127 follows:
7128 <literallayout class='monospaced'>
7129 PV = "0.12-git${SRCPV}"
7130 </literallayout>
7131 </para>
7132 </glossdef>
7133 </glossentry>
7134
7135 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
7136 <glossdef>
7137 <para>
7138 The revision of the source code used to build the package.
7139 This variable applies to Subversion, Git, Mercurial and Bazaar
7140 only.
7141 Note that if you wish to build a fixed revision and you wish
7142 to avoid performing a query on the remote repository every time
7143 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
7144 full revision identifier and not just a tag.
7145 </para>
7146 </glossdef>
7147 </glossentry>
7148
7149 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
7150 <glossdef>
7151 <para>The directory for the shared state cache.</para>
7152 </glossdef>
7153 </glossentry>
7154
7155 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
7156 <glossdef>
7157 <para>
7158 Configures the OpenEmbedded build system to search other
7159 mirror locations for prebuilt cache data objects before
7160 building out the data.
7161 This variable works like fetcher
7162 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
7163 and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
7164 and points to the cache locations to check for the shared
7165 objects.
7166 </para>
7167
7168 <para>
7169 You can specify a filesystem directory or a remote URL such
7170 as HTTP or FTP.
7171 The locations you specify need to contain the shared state
7172 cache (sstate-cache) results from previous builds.
7173 The sstate-cache you point to can also be from builds on
7174 other machines.
7175 </para>
7176
7177 <para>
7178 If a mirror uses the same structure as
7179 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
7180 you need to add
7181 "PATH" at the end as shown in the examples below.
7182 The build system substitutes the correct path within the
7183 directory structure.
7184 <literallayout class='monospaced'>
7185 SSTATE_MIRRORS ?= "\
7186 file://.* http://someserver.tld/share/sstate/PATH \n \
7187 file://.* file:///some/local/dir/sstate/PATH"
7188 </literallayout>
7189 </para>
7190 </glossdef>
7191 </glossentry>
7192
7193 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
7194 <glossdef>
7195 <para>
7196 The directory with kernel headers that are required to build out-of-tree
7197 modules.
7198 </para>
7199 </glossdef>
7200 </glossentry>
7201
7202 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
7203 <glossdef>
7204 <para>
7205 Specifies the base path used to create recipe stamp files.
7206 The path to an actual stamp file is constructed by evaluating this
7207 string and then appending additional information.
7208 Currently, the default assignment for <filename>STAMP</filename>
7209 as set in the <filename>meta/conf/bitbake.conf</filename> file
7210 is:
7211 <literallayout class='monospaced'>
7212 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
7213 </literallayout>
7214 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
7215 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
7216 <link linkend='var-PN'><filename>PN</filename></link>,
7217 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
7218 <link linkend='var-PV'><filename>PV</filename></link>, and
7219 <link linkend='var-PR'><filename>PR</filename></link> for related variable
7220 information.
7221 </para>
7222 </glossdef>
7223 </glossentry>
7224
7225 <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
7226 <glossdef>
7227 <para>
7228 Specifies the base directory in which the OpenEmbedded
7229 build system places stamps.
7230 The default directory is
7231 <filename>${TMPDIR}/stamps</filename>.
7232 </para>
7233 </glossdef>
7234 </glossentry>
7235
7236 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
7237 <glossdef>
7238 <para>The short (72 characters or less) summary of the binary package for packaging
7239 systems such as <filename>opkg</filename>, <filename>rpm</filename> or
7240 <filename>dpkg</filename>.
7241 By default, <filename>SUMMARY</filename> is used to define
7242 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
7243 variable if <filename>DESCRIPTION</filename> is not set
7244 in the recipe.
7245 </para>
7246 </glossdef>
7247 </glossentry>
7248
7249 <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm>
7250 <glossdef>
7251 <para>
7252 Specifies the kernel boot default console.
7253 If you want to use a console other than the default,
7254 set this variable in your recipe as follows where "X" is
7255 the console number you want to use:
7256 <literallayout class='monospaced'>
7257 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
7258 </literallayout>
7259 </para>
7260
7261 <para>
7262 The
7263 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7264 class initially sets this variable to null but then checks
7265 for a value later.
7266 </para>
7267 </glossdef>
7268 </glossentry>
7269
7270 <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm>
7271 <glossdef>
7272 <para>
7273 Lists additional options to add to the syslinux file.
7274 You need to set this variable in your recipe.
7275 If you want to list multiple options, separate the options
7276 with a semicolon character (<filename>;</filename>).
7277 </para>
7278
7279 <para>
7280 The
7281 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7282 class uses this variable to create a set of options.
7283 </para>
7284 </glossdef>
7285 </glossentry>
7286
7287 <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm>
7288 <glossdef>
7289 <para>
7290 Specifies the alternate serial port or turns it off.
7291 To turn off serial, set this variable to an empty string
7292 in your recipe.
7293 The variable's default value is set in the
7294 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7295 as follows:
7296 <literallayout class='monospaced'>
7297 SYSLINUX_SERIAL ?= "0 115200"
7298 </literallayout>
7299 The class checks for and uses the variable as needed. </para>
7300 </glossdef>
7301 </glossentry>
7302
7303 <glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm>
7304 <glossdef>
7305 <para>
7306 An <filename>.LSS</filename> file used as the background
7307 for the VGA boot menu when you are using the boot menu.
7308 You need to set this variable in your recipe.
7309 </para>
7310
7311 <para>
7312 The
7313 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7314 class checks for this variable and if found, the
7315 OpenEmbedded build system installs the splash screen.
7316 </para>
7317 </glossdef>
7318 </glossentry>
7319
7320 <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>
7321 <glossdef>
7322 <para>
7323 Specifies the alternate console=tty... kernel boot argument.
7324 The variable's default value is set in the
7325 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
7326 as follows:
7327 <literallayout class='monospaced'>
7328 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
7329 </literallayout>
7330 The class checks for and uses the variable as needed.
7331 </para>
7332 </glossdef>
7333 </glossentry>
7334
7335 <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
7336 <glossdef>
7337 <para>
7338 A list of functions to execute after files are staged into
7339 the sysroot.
7340 These functions are usually used to apply additional
7341 processing on the staged files, or to stage additional
7342 files.
7343 </para>
7344 </glossdef>
7345 </glossentry>
7346
7347 <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>
7348 <glossdef>
7349 <para>
7350 For recipes that inherit the
7351 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
7352 class, this variable specifies whether the service you have
7353 specified in
7354 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
7355 should be started automatically or not.
7356 By default, the service is enabled to automatically start
7357 at boot time.
7358 The default setting is in the
7359 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
7360 class as follows:
7361 <literallayout class='monospaced'>
7362 SYSTEMD_AUTO_ENABLE ??= "enable"
7363 </literallayout>
7364 You can disable the service by setting the variable to
7365 "disable".
7366 </para>
7367 </glossdef>
7368 </glossentry>
7369
7370 <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>
7371 <glossdef>
7372 <para>
7373 For recipes that inherit the
7374 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
7375 class, this variable locates the systemd unit files when
7376 they are not found in the main recipe's package.
7377 By default, the
7378 <filename>SYSTEMD_PACKAGES</filename> variable is set
7379 such that the systemd unit files are assumed to reside in
7380 the recipes main package:
7381 <literallayout class='monospaced'>
7382 SYSTEMD_PACKAGES ?= "${PN}"
7383 </literallayout>
7384 If these unit files are not in this recipe's main
7385 package, you need to use
7386 <filename>SYSTEMD_PACKAGES</filename> to list the package
7387 or packages in which the build system can find the systemd
7388 unit files.
7389 </para>
7390 </glossdef>
7391 </glossentry>
7392
7393 <glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm>
7394 <glossdef>
7395 <para>
7396 For recipes that inherit the
7397 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
7398 class, this variable specifies the systemd service name for
7399 a package.
7400 </para>
7401
7402 <para>
7403 When you specify this file in your recipe, use a package
7404 name override to indicate the package to which the value
7405 applies.
7406 Here is an example from the connman recipe:
7407 <literallayout class='monospaced'>
7408 SYSTEMD_SERVICE_${PN} = "connman.service"
7409 </literallayout>
7410 </para>
7411 </glossdef>
7412 </glossentry>
7413
7414 </glossdiv>
7415
7416 <glossdiv id='var-glossary-t'><title>T</title>
7417
7418 <glossentry id='var-T'><glossterm>T</glossterm>
7419 <glossdef>
7420 <para>This variable points to a directory were BitBake places
7421 temporary files, which consist mostly of task logs and
7422 scripts, when building a particular recipe.
7423 The variable is typically set as follows:
7424 <literallayout class='monospaced'>
7425 T = "${WORKDIR}/temp"
7426 </literallayout>
7427 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
7428 is the directory into which BitBake unpacks and builds the
7429 recipe.
7430 The default <filename>bitbake.conf</filename> file sets this variable.</para>
7431 <para>The <filename>T</filename> variable is not to be confused with
7432 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
7433 which points to the root of the directory tree where BitBake
7434 places the output of an entire build.
7435 </para>
7436 </glossdef>
7437 </glossentry>
7438
7439 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
7440 <glossdef>
7441 <para>
7442 The target machine's architecture.
7443 The OpenEmbedded build system supports many
7444 architectures.
7445 Here is an example list of architectures supported.
7446 This list is by no means complete as the architecture
7447 is configurable:
7448 <literallayout class='monospaced'>
7449 arm
7450 i586
7451 x86_64
7452 powerpc
7453 powerpc64
7454 mips
7455 mipsel
7456 </literallayout>
7457 </para>
7458 </glossdef>
7459 </glossentry>
7460
7461 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
7462 <glossdef>
7463 <para>
7464 Flags passed to the C compiler for the target system.
7465 This variable evaluates to the same as
7466 <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>.
7467 </para>
7468 </glossdef>
7469 </glossentry>
7470
7471
7472 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
7473 <glossdef>
7474 <para>Specifies the method for handling FPU code.
7475 For FPU-less targets, which include most ARM CPUs, the variable must be
7476 set to "soft".
7477 If not, the kernel emulation gets used, which results in a performance penalty.</para>
7478 </glossdef>
7479 </glossentry>
7480
7481 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
7482 <glossdef>
7483 <para>Specifies the target's operating system.
7484 The variable can be set to "linux" for <filename>eglibc</filename>-based systems and
7485 to "linux-uclibc" for <filename>uclibc</filename>.
7486 For ARM/EABI targets, there are also "linux-gnueabi" and
7487 "linux-uclibc-gnueabi" values possible.</para>
7488 </glossdef>
7489 </glossentry>
7490
7491 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
7492 <glossdef>
7493 <para>
7494 Specifies the GNU standard C library (<filename>libc</filename>)
7495 variant to use during the build process.
7496 This variable replaces <filename>POKYLIBC</filename>, which is no longer
7497 supported.
7498 </para>
7499 <para>
7500 You can select "eglibc" or "uclibc".
7501 <note>
7502 This release of the Yocto Project does not support the
7503 <filename>glibc</filename> implementation of <filename>libc</filename>.
7504 </note>
7505 </para>
7506 </glossdef>
7507 </glossentry>
7508
7509 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
7510 <glossdef>
7511 <para>
7512 Specifies the toolchain selector.
7513 <filename>TCMODE</filename> controls the characteristics
7514 of the generated packages and images by telling the
7515 OpenEmbedded build system which toolchain profile to use.
7516 By default, the OpenEmbedded build system builds its own
7517 internal toolchain.
7518 The variable's default value is "default", which uses
7519 that internal toolchain.
7520 <note>
7521 If <filename>TCMODE</filename> is set to a value
7522 other than "default", then it is your responsibility
7523 to ensure that the toolchain is compatible with the
7524 default toolchain.
7525 Using older or newer versions of these components
7526 might cause build problems.
7527 See the
7528 <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
7529 for the specific components with which the toolchain
7530 must be compatible.
7531 </note>
7532 </para>
7533
7534 <para>
7535 With additional layers, it is possible to use a pre-compiled
7536 external toolchain.
7537 One example is the Sourcery G++ Toolchain.
7538 The support for this toolchain resides in the separate
7539 <filename>meta-sourcery</filename> layer at
7540 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
7541 You can use <filename>meta-sourcery</filename> as a
7542 template for adding support for other external toolchains.
7543 </para>
7544
7545 <para>
7546 The <filename>TCMODE</filename> variable points the build
7547 system to a file in
7548 <filename>conf/distro/include/tcmode-${TCMODE}.inc</filename>.
7549 Thus, for <filename>meta-sourcery</filename>,
7550 which has <filename>conf/distro/include/tcmode-external-sourcery.inc</filename>,
7551 you would set the variable as follows:
7552 <literallayout class='monospaced'>
7553 TCMODE ?= "external-sourcery"
7554 </literallayout>
7555 </para>
7556
7557 <para>
7558 The variable is similar to
7559 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
7560 which controls the variant of the GNU standard C library
7561 (<filename>libc</filename>) used during the build process:
7562 <filename>eglibc</filename> or <filename>uclibc</filename>.
7563 </para>
7564 </glossdef>
7565 </glossentry>
7566
7567 <glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>
7568 <glossdef>
7569 <para>
7570 The location the OpenEmbedded build system uses to export
7571 tests when the
7572 <link linkend='var-TEST_EXPORT_ONLY'><filename>TEST_EXPORT_ONLY</filename></link>
7573 variable is set to "1".
7574 </para>
7575
7576 <para>
7577 The <filename>TEST_EXPORT_DIR</filename> variable defaults
7578 to <filename>"${TMPDIR}/testimage/${PN}"</filename>.
7579 </para>
7580 </glossdef>
7581 </glossentry>
7582
7583 <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>
7584 <glossdef>
7585 <para>
7586 Specifies to export the tests only.
7587 Set this variable to "1" if you do not want to run the
7588 tests but you want them to be exported in a manner that
7589 you to run them outside of the build system.
7590 </para>
7591 </glossdef>
7592 </glossentry>
7593
7594 <glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm>
7595 <glossdef>
7596 <para>
7597 Automatically runs the series of automated tests for
7598 images when an image is successfully built.
7599 </para>
7600
7601 <para>
7602 These tests are written in Python making use of the
7603 <filename>unittest</filename> module, and the majority of
7604 them run commands on the target system over
7605 <filename>ssh</filename>.
7606 You can set this variable to "1" in your
7607 <filename>local.conf</filename> file in the
7608 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
7609 to have the OpenEmbedded build system automatically run
7610 these tests after an image successfully builds:
7611 <literallayout class='monospaced'>
7612 TEST_IMAGE = "1"
7613 </literallayout>
7614 For more information on enabling, running, and writing
7615 these tests, see the
7616 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
7617 section in the Yocto Project Development Manual and the
7618 "<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>"
7619 section.
7620 </para>
7621 </glossdef>
7622 </glossentry>
7623
7624 <glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm>
7625 <glossdef>
7626 <para>
7627 Holds the SSH log and the boot log for QEMU machines.
7628 The <filename>TEST_LOG_DIR</filename> variable defaults
7629 to <filename>"${WORKDIR}/testimage"</filename>.
7630 <note>
7631 Actual test results reside in the task log
7632 (<filename>log.do_testimage</filename>), which is in
7633 the <filename>${WORKDIR}/temp/</filename> directory.
7634 </note>
7635 </para>
7636 </glossdef>
7637 </glossentry>
7638
7639 <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
7640 <glossdef>
7641 <para>
7642 The time in seconds allowed for an image to boot before
7643 automated runtime tests begin to run against an
7644 image.
7645 The default timeout period to allow the boot process to
7646 reach the login prompt is 500 seconds.
7647 You can specify a different value in the
7648 <filename>local.conf</filename> file.
7649 </para>
7650
7651 <para>
7652 For more information on testing images, see the
7653 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
7654 section in the Yocto Project Development Manual.
7655 </para>
7656 </glossdef>
7657 </glossentry>
7658
7659 <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>
7660 <glossdef>
7661 <para>
7662 The IP address of the build machine (host machine).
7663 This IP address is usually automatically detected.
7664 However, if detection fails, this variable needs to be set
7665 to the IP address of the build machine (i.e. where
7666 the build is taking place).
7667 <note>
7668 The <filename>TEST_SERVER_IP</filename> variable
7669 is only used for a small number of tests such as
7670 the "smart" test suite, which needs to download
7671 packages from <filename>DEPLOY_DIR/rpm</filename>.
7672 </note>
7673 </para>
7674 </glossdef>
7675 </glossentry>
7676
7677 <glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>
7678 <glossdef>
7679 <para>
7680 Specifies the target controller to use when running tests
7681 against a test image.
7682 The default controller to use is "qemu":
7683 <literallayout class='monospaced'>
7684 TEST_TARGET = "qemu"
7685 </literallayout>
7686 A target controller is a class that defines how an
7687 image gets deployed on a target and how a target is started.
7688 A layer can extend the controllers by adding a module
7689 in the layer's <filename>/lib/oeqa/controllers</filename>
7690 directory and by inheriting the
7691 <filename>BaseTarget</filename> class, which is an abstract
7692 class that cannot be used as a value of
7693 <filename>TEST_TARGET</filename>.
7694 </para>
7695
7696 <para>
7697 You can provide the following arguments with
7698 <filename>TEST_TARGET</filename>:
7699 <itemizedlist>
7700 <listitem><para><emphasis>"qemu" and "QemuTarget":</emphasis>
7701 Boots a QEMU image and runs the tests.
7702 See the
7703 "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"
7704 section in the Yocto Project Development Manual for
7705 more information.
7706 </para></listitem>
7707 <listitem><para><emphasis>"simpleremote" and "SimpleRemoteTarget":</emphasis>
7708 Runs the tests on target hardware that is already
7709 up and running.
7710 The hardware can be on the network or it can be
7711 a device running an image on QEMU.
7712 You must also set
7713 <link linkend='var-TEST_TARGET_IP'><filename>TEST_TARGET_IP</filename></link>
7714 when you use "simpleremote" or "SimpleRemoteTarget".
7715 <note>
7716 This argument is defined in
7717 <filename>meta/lib/oeqa/targetcontrol.py</filename>.
7718 The small caps names are kept for compatibility
7719 reasons.
7720 </note>
7721 </para></listitem>
7722 <listitem><para><emphasis>"GummibootTarget":</emphasis>
7723 Automatically deploys and runs tests on an
7724 EFI-enabled machine that has a master image
7725 installed.
7726 <note>
7727 This argument is defined in
7728 <filename>meta/lib/oeqa/controllers/masterimage.py</filename>.
7729 </note>
7730 </para></listitem>
7731 </itemizedlist>
7732 </para>
7733
7734 <para>
7735 For information on running tests on hardware, see the
7736 "<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"
7737 section in the Yocto Project Development Manual.
7738 </para>
7739 </glossdef>
7740 </glossentry>
7741
7742 <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>
7743 <glossdef>
7744 <para>
7745 The IP address of your hardware under test.
7746 The <filename>TEST_TARGET_IP</filename> variable has no
7747 effect when
7748 <link linkend='var-TEST_TARGET'><filename>TEST_TARGET</filename></link>
7749 is set to "qemu".
7750 </para>
7751
7752 <para>
7753 When you specify the IP address, you can also include a
7754 port.
7755 Here is an example:
7756 <literallayout class='monospaced'>
7757 TEST_TARGET_IP = "192.168.1.4:2201"
7758 </literallayout>
7759 Specifying a port is useful when SSH is started on a
7760 non-standard port or in cases when your hardware under test
7761 is behind a firewall or network that is not directly
7762 accessible from your host and you need to do port address
7763 translation.
7764 </para>
7765 </glossdef>
7766 </glossentry>
7767
7768 <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
7769 <glossdef>
7770 <para>
7771 An ordered list of tests (modules) to run against
7772 an image when performing automated runtime testing.
7773 </para>
7774
7775 <para>
7776 The OpenEmbedded build system provides a core set of tests
7777 that can be used against images.
7778 <note>
7779 Currently, there is only support for running these tests
7780 under QEMU.
7781 </note>
7782 Tests include <filename>ping</filename>,
7783 <filename>ssh</filename>, <filename>df</filename> among
7784 others.
7785 You can add your own tests to the list of tests by
7786 appending <filename>TEST_SUITES</filename> as follows:
7787 <literallayout class='monospaced'>
7788 TEST_SUITES_append = " mytest"
7789 </literallayout>
7790 Alternatively, you can provide the "auto" option to
7791 have all applicable tests run against the image.
7792 <literallayout class='monospaced'>
7793 TEST_SUITES_append = " auto"
7794 </literallayout>
7795 Using this option causes the build system to automatically
7796 run tests that are applicable to the image.
7797 Tests that are not applicable are skipped.
7798 </para>
7799
7800 <para>
7801 The order in which tests are run is important.
7802 Tests that depend on another test must appear later in the
7803 list than the test on which they depend.
7804 For example, if you append the list of tests with two
7805 tests (<filename>test_A</filename> and
7806 <filename>test_B</filename>) where
7807 <filename>test_B</filename> is dependent on
7808 <filename>test_A</filename>, then you must order the tests
7809 as follows:
7810 <literallayout class='monospaced'>
7811 TEST_SUITES = " test_A test_B"
7812 </literallayout>
7813 </para>
7814
7815 <para>
7816 For more information on testing images, see the
7817 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
7818 section in the Yocto Project Development Manual.
7819 </para>
7820 </glossdef>
7821 </glossentry>
7822
7823 <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
7824 <glossdef>
7825 <para>
7826 The directory in which the file BitBake is currently
7827 parsing is located.
7828 Do not manually set this variable.
7829 </para>
7830 </glossdef>
7831 </glossentry>
7832
7833 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
7834 <glossdef>
7835 <para>
7836 This variable is the base directory the OpenEmbedded
7837 build system uses for all build output and intermediate
7838 files (other than the shared state cache).
7839 By default, the <filename>TMPDIR</filename> variable points
7840 to <filename>tmp</filename> within the
7841 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
7842 </para>
7843
7844 <para>
7845 If you want to establish this directory in a location other
7846 than the default, you can uncomment and edit the following
7847 statement in the
7848 <filename>conf/local.conf</filename> file in the
7849 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
7850 <literallayout class='monospaced'>
7851 #TMPDIR = "${TOPDIR}/tmp"
7852 </literallayout>
7853 An example use for this scenario is to set
7854 <filename>TMPDIR</filename> to a local disk, which does
7855 not use NFS, while having the Build Directory use NFS.
7856 </para>
7857
7858 <para>
7859 The filesystem used by <filename>TMPDIR</filename> must
7860 have standard filesystem semantics (i.e. mixed-case files
7861 are unique, POSIX file locking, and persistent inodes).
7862 Due to various issues with NFS and bugs in some
7863 implementations, NFS does not meet this minimum
7864 requirement.
7865 Consequently, <filename>TMPDIR</filename> cannot be on
7866 NFS.
7867 </para>
7868 </glossdef>
7869 </glossentry>
7870
7871 <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
7872 <glossdef>
7873 <para>
7874 This variable lists packages the OpenEmbedded build system
7875 uses when building an SDK, which contains a
7876 cross-development environment.
7877 The packages specified by this variable are part of the
7878 toolchain set that runs on the
7879 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
7880 and each package should usually have the prefix
7881 "nativesdk-".
7882 When building an SDK using
7883 <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>,
7884 a default list of packages is set in this variable, but
7885 you can add additional packages to the list.
7886 </para>
7887
7888 <para>
7889 For background information on cross-development toolchains
7890 in the Yocto Project development environment, see the
7891 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
7892 section.
7893 For information on setting up a cross-development
7894 environment, see the
7895 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
7896 section in the Yocto Project Application Developer's Guide.
7897 </para>
7898 </glossdef>
7899 </glossentry>
7900
7901 <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
7902 <glossdef>
7903 <para>
7904 This variable lists packages the OpenEmbedded build system
7905 uses when it creates the target part of an SDK
7906 (i.e. the part built for the target hardware), which
7907 includes libraries and headers.
7908 </para>
7909
7910 <para>
7911 For background information on cross-development toolchains
7912 in the Yocto Project development environment, see the
7913 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
7914 section.
7915 For information on setting up a cross-development
7916 environment, see the
7917 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
7918 section in the Yocto Project Application Developer's Guide.
7919 </para>
7920 </glossdef>
7921 </glossentry>
7922
7923 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
7924 <glossdef>
7925 <para>
7926 The top-level
7927 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
7928 BitBake automatically sets this variable when you
7929 initialize your build environment using either
7930 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
7931 or
7932 <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
7933 </para>
7934 </glossdef>
7935 </glossentry>
7936
7937 <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
7938 <glossdef>
7939 <para>
7940 A sanitized version of
7941 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
7942 This variable is used where the architecture is needed in
7943 a value where underscores are not allowed, for example
7944 within package filenames.
7945 In this case, dash characters replace any underscore
7946 characters used in TARGET_ARCH.
7947 </para>
7948
7949 <para>
7950 Do not edit this variable.
7951 </para>
7952 </glossdef>
7953 </glossentry>
7954
7955 <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
7956 <glossdef>
7957 <para>
7958 The package architecture understood by the packaging
7959 system to define the architecture, ABI, and tuning of
7960 output packages.
7961 </para>
7962 </glossdef>
7963 </glossentry>
7964
7965 </glossdiv>
7966
7967 <glossdiv id='var-glossary-u'><title>U</title>
7968
7969 <glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm>
7970 <glossdef>
7971 <para>
7972 Configures the
7973 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
7974 and can also define
7975 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
7976 for individual cases.
7977 </para>
7978
7979 <para>
7980 Following is an example from the
7981 <filename>meta-fsl-arm</filename> layer.
7982 <literallayout class='monospaced'>
7983 UBOOT_CONFIG ??= "sd"
7984 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
7985 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
7986 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
7987 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
7988 </literallayout>
7989 In this example, "sd" is selected as the configuration
7990 of the possible four for the
7991 <filename>UBOOT_MACHINE</filename>.
7992 The "sd" configuration defines "mx6qsabreauto_config"
7993 as the value for <filename>UBOOT_MACHINE</filename>, while
7994 the "sdcard" specifies the
7995 <filename>IMAGE_FSTYPES</filename> to use for the U-boot
7996 image.
7997 </para>
7998
7999 <para>
8000 For more information on how the
8001 <filename>UBOOT_CONFIG</filename> is handled, see the
8002 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass'><filename>uboot-config</filename></ulink>
8003 class.
8004 </para>
8005 </glossdef>
8006 </glossentry>
8007
8008 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
8009 <glossdef>
8010 <para>
8011 Specifies the entry point for the U-Boot image.
8012 During U-Boot image creation, the
8013 <filename>UBOOT_ENTRYPOINT</filename> variable is passed
8014 as a command-line parameter to the
8015 <filename>uboot-mkimage</filename> utility.
8016 </para>
8017 </glossdef>
8018 </glossentry>
8019
8020 <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
8021 <glossdef>
8022 <para>
8023 Specifies the load address for the U-Boot image.
8024 During U-Boot image creation, the
8025 <filename>UBOOT_LOADADDRESS</filename> variable is passed
8026 as a command-line parameter to the
8027 <filename>uboot-mkimage</filename> utility.
8028 </para>
8029 </glossdef>
8030 </glossentry>
8031
8032 <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>
8033 <glossdef>
8034 <para>
8035 Appends a string to the name of the local version of the
8036 U-Boot image.
8037 For example, assuming the version of the U-Boot image
8038 built was "2013.10, the full version string reported by
8039 U-Boot would be "2013.10-yocto" given the following
8040 statement:
8041 <literallayout class='monospaced'>
8042 UBOOT_LOCALVERSION = "-yocto"
8043 </literallayout>
8044 </para>
8045 </glossdef>
8046 </glossentry>
8047
8048 <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
8049 <glossdef>
8050 <para>
8051 Specifies the value passed on the
8052 <filename>make</filename> command line when building
8053 a U-Boot image.
8054 The value indicates the target platform configuration.
8055 You typically set this variable from the machine
8056 configuration file (i.e.
8057 <filename>conf/machine/&lt;machine_name&gt;.conf</filename>).
8058 </para>
8059 </glossdef>
8060 </glossentry>
8061
8062 <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm>
8063 <glossdef>
8064 <para>
8065 Specifies the target called in the
8066 <filename>Makefile</filename>.
8067 The default target is "all".
8068 </para>
8069 </glossdef>
8070 </glossentry>
8071
8072 <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>
8073 <glossdef>
8074 <para>
8075 Points to the generated U-Boot extension.
8076 For example, <filename>u-boot.sb</filename> has a
8077 <filename>.sb</filename> extension.
8078 </para>
8079
8080 <para>
8081 The default U-Boot extension is
8082 <filename>.bin</filename>
8083 </para>
8084 </glossdef>
8085 </glossentry>
8086
8087 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
8088 <glossdef>
8089 <para>
8090 Specifies the target used for building U-Boot.
8091 The target is passed directly as part of the "make" command
8092 (e.g. SPL and AIS).
8093 If you do not specifically set this variable, the
8094 OpenEmbedded build process passes and uses "all" for the
8095 target during the U-Boot building process.
8096 </para>
8097 </glossdef>
8098 </glossentry>
8099
8100 <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
8101 <glossdef>
8102 <para>
8103 A list of classes to globally inherit.
8104 These classes are used by the OpenEmbedded build system
8105 to enable extra features (e.g.
8106 <filename>buildstats</filename>,
8107 <filename>image-mklibs</filename>, and so forth).
8108 </para>
8109
8110 <para>
8111 The default list is set in your
8112 <filename>local.conf</filename> file:
8113 <literallayout class='monospaced'>
8114 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
8115 </literallayout>
8116 For more information, see
8117 <filename>meta-yocto/conf/local.conf.sample</filename> in
8118 the
8119 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
8120 </para>
8121 </glossdef>
8122 </glossentry>
8123
8124 <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>
8125 <glossdef>
8126 <para>
8127 Forces the OpenEmbedded build system to produce an error
8128 if the user identification (<filename>uid</filename>) and
8129 group identification (<filename>gid</filename>) values
8130 are not defined in <filename>files/passwd</filename>
8131 and <filename>files/group</filename> files.
8132 </para>
8133
8134 <para>
8135 The default behavior for the build system is to dynamically
8136 apply <filename>uid</filename> and
8137 <filename>gid</filename> values.
8138 Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>
8139 variable is by default not set.
8140 If you plan on using statically assigned
8141 <filename>gid</filename> and <filename>uid</filename>
8142 values, you should set
8143 the <filename>USERADD_ERROR_DYNAMIC</filename> variable in
8144 your <filename>local.conf</filename> file as
8145 follows:
8146 <literallayout class='monospaced'>
8147 USERADD_ERROR_DYNAMIC = "1"
8148 </literallayout>
8149 Overriding the default behavior implies you are going to
8150 also take steps to set static <filename>uid</filename> and
8151 <filename>gid</filename> values through use of the
8152 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
8153 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
8154 and
8155 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
8156 variables.
8157 </para>
8158 </glossdef>
8159 </glossentry>
8160
8161 <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>
8162 <glossdef>
8163 <para>
8164 Specifies a password file to use for obtaining static
8165 group identification (<filename>gid</filename>) values
8166 when the OpenEmbedded build system adds a group to the
8167 system during package installation.
8168 </para>
8169
8170 <para>
8171 When applying static group identification
8172 (<filename>gid</filename>) values, the OpenEmbedded build
8173 system looks in
8174 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
8175 for a <filename>files/group</filename> file and then applies
8176 those <filename>uid</filename> values.
8177 Set the variable as follows in your
8178 <filename>local.conf</filename> file:
8179 <literallayout class='monospaced'>
8180 USERADD_GID_TABLES = "files/group"
8181 </literallayout>
8182 </para>
8183
8184 <note>
8185 Setting the
8186 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
8187 variable to "useradd-staticids" causes the build system
8188 to use static <filename>gid</filename> values.
8189 </note>
8190 </glossdef>
8191 </glossentry>
8192
8193 <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>
8194 <glossdef>
8195 <para>
8196 Specifies a password file to use for obtaining static
8197 user identification (<filename>uid</filename>) values
8198 when the OpenEmbedded build system adds a user to the
8199 system during package installation.
8200 </para>
8201
8202 <para>
8203 When applying static user identification
8204 (<filename>uid</filename>) values, the OpenEmbedded build
8205 system looks in
8206 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
8207 for a <filename>files/passwd</filename> file and then applies
8208 those <filename>uid</filename> values.
8209 Set the variable as follows in your
8210 <filename>local.conf</filename> file:
8211 <literallayout class='monospaced'>
8212 USERADD_UID_TABLES = "files/passwd"
8213 </literallayout>
8214 </para>
8215
8216 <note>
8217 Setting the
8218 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
8219 variable to "useradd-staticids" causes the build system
8220 to use static <filename>uid</filename> values.
8221 </note>
8222 </glossdef>
8223 </glossentry>
8224
8225 <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>
8226 <glossdef>
8227 <para>
8228 When a recipe inherits the
8229 <filename>useradd</filename> class, this variable
8230 specifies the individual packages within the recipe that
8231 require users and/or groups to be added.
8232 </para>
8233
8234 <para>
8235 You must set this variable if the recipe inherits the
8236 class.
8237 For example, the following enables adding a user for the
8238 main package in a recipe:
8239 <literallayout class='monospaced'>
8240 USERADD_PACKAGES = "${PN}"
8241 </literallayout>
8242 <note>
8243 If follows that if you are going to use the
8244 <filename>USERADD_PACKAGES</filename> variable,
8245 you need to set one or more of the
8246 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
8247 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
8248 or
8249 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
8250 variables.
8251 </note>
8252 </para>
8253
8254 </glossdef>
8255 </glossentry>
8256
8257 <glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>
8258 <glossdef>
8259 <para>
8260 When a recipe inherits the
8261 <filename>useradd</filename> class, this variable
8262 specifies for a package what parameters should be passed
8263 to the <filename>useradd</filename> command
8264 if you wish to add a user to the system when the package
8265 is installed.
8266 </para>
8267
8268 <para>
8269 Here is an example from the <filename>dbus</filename>
8270 recipe:
8271 <literallayout class='monospaced'>
8272 USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \
8273 --no-create-home --shell /bin/false \
8274 --user-group messagebus"
8275 </literallayout>
8276 For information on the standard Linux shell command
8277 <filename>useradd</filename>, see
8278 <ulink url='http://linux.die.net/man/8/useradd'></ulink>.
8279 </para>
8280 </glossdef>
8281 </glossentry>
8282
8283 <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>
8284 <glossdef>
8285 <para>
8286 When set to "useradd-staticids", causes the
8287 OpenEmbedded build system to base all user and group
8288 additions on a static
8289 <filename>passwd</filename> and
8290 <filename>group</filename> files found in
8291 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
8292 </para>
8293
8294 <para>
8295 To use static user identification (<filename>uid</filename>)
8296 and group identification (<filename>gid</filename>)
8297 values, set the variable
8298 as follows in your <filename>local.conf</filename> file:
8299 <literallayout class='monospaced'>
8300 USERADDEXTENSION = "useradd-staticids"
8301 </literallayout>
8302 <note>
8303 Setting this variable to use static
8304 <filename>uid</filename> and <filename>gid</filename>
8305 values causes the OpenEmbedded build system to employ
8306 the
8307 <link linkend='ref-classes-useradd-staticids'><filename>useradd-staticids</filename></link>
8308 class.
8309 </note>
8310 </para>
8311
8312 <para>
8313 If you use static <filename>uid</filename> and
8314 <filename>gid</filename> information, you must also
8315 specify the <filename>files/passwd</filename> and
8316 <filename>files/group</filename> files by setting the
8317 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
8318 and
8319 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
8320 variables.
8321 Additionally, you should also set the
8322 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
8323 variable.
8324 </para>
8325 </glossdef>
8326 </glossentry>
8327
8328 </glossdiv>
8329
8330<!-- <glossdiv id='var-glossary-v'><title>V</title>-->
8331<!-- </glossdiv>-->
8332
8333 <glossdiv id='var-glossary-w'><title>W</title>
8334
8335 <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
8336 <glossdef>
8337 <para>
8338 Specifies the quality assurance checks whose failures are
8339 reported as warnings by the OpenEmbedded build system.
8340 You set this variable in your distribution configuration
8341 file.
8342 For a list of the checks you can control with this variable,
8343 see the
8344 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
8345 section.
8346 </para>
8347 </glossdef>
8348 </glossentry>
8349
8350 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
8351 <glossdef>
8352 <para>
8353 The pathname of the work directory in which the OpenEmbedded
8354 build system builds a recipe.
8355 This directory is located within the
8356 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
8357 directory structure and is specific to the recipe being
8358 built and the system for which it is being built.
8359 </para>
8360
8361 <para>
8362 The <filename>WORKDIR</filename> directory is defined as
8363 follows:
8364 <literallayout class='monospaced'>
8365 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
8366 </literallayout>
8367 The actual directory depends on several things:
8368 <itemizedlist>
8369 <listitem><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>:
8370 The top-level build output directory</listitem>
8371 <listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>:
8372 The target system identifier</listitem>
8373 <listitem><link linkend='var-PN'><filename>PN</filename></link>:
8374 The recipe name</listitem>
8375 <listitem><link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>:
8376 The epoch - (if
8377 <link linkend='var-PE'><filename>PE</filename></link>
8378 is not specified, which is usually the case for most
8379 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
8380 <listitem><link linkend='var-PV'><filename>PV</filename></link>:
8381 The recipe version</listitem>
8382 <listitem><link linkend='var-PR'><filename>PR</filename></link>:
8383 The recipe revision</listitem>
8384 </itemizedlist>
8385 </para>
8386
8387 <para>
8388 As an example, assume a Source Directory top-level folder
8389 name <filename>poky</filename>, a default Build Directory at
8390 <filename>poky/build</filename>, and a
8391 <filename>qemux86-poky-linux</filename> machine target
8392 system.
8393 Furthermore, suppose your recipe is named
8394 <filename>foo_1.3.0-r0.bb</filename>.
8395 In this case, the work directory the build system uses to
8396 build the package would be as follows:
8397 <literallayout class='monospaced'>
8398 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
8399 </literallayout>
8400 </para>
8401 </glossdef>
8402 </glossentry>
8403
8404 </glossdiv>
8405
8406<!-- <glossdiv id='var-glossary-x'><title>X</title>-->
8407<!-- </glossdiv>-->
8408
8409<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
8410<!-- </glossdiv>-->
8411
8412<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
8413<!-- </glossdiv>-->
8414
8415</glossary>
8416</chapter>
8417<!--
8418vim: expandtab tw=80 ts=4
8419-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-23 10:47:39 +0000