summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-variables.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-12-11 12:07:58 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-01-07 14:43:25 +0000
commited0a240e1632682ec4c33341f3e24ad71773cdfc (patch)
tree201557f498b77b9f51fad7e12a6009f74aca4c65 /documentation/ref-manual/ref-variables.xml
parentaf19d889ef320f9625aae42eed6688b5cc739793 (diff)
downloadpoky-ed0a240e1632682ec4c33341f3e24ad71773cdfc.tar.gz
documentation: Rename of poky-ref-manual folder to ref-manual.
Changing the folder that holds the YP Reference Manual to be "ref-manual". This will help with confustion over the manual's intended purpose. (From yocto-docs rev: 1106442964b5080cb0b6b3bd3af32e9407c0f7c1) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/ref-variables.xml')
-rw-r--r--documentation/ref-manual/ref-variables.xml3018
1 files changed, 3018 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..c490fc360d
--- /dev/null
+++ b/documentation/ref-manual/ref-variables.xml
@@ -0,0 +1,3018 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<!-- Dummy chapter -->
6<chapter id='ref-variables-glos'>
7
8<title>Variables Glossary</title>
9
10<para>
11 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
12 of their function and contents.
13</para>
14
15<glossary id='ref-variables-glossary'>
16
17
18 <para>
19 <link linkend='var-ALLOW_EMPTY'>A</link>
20 <link linkend='var-B'>B</link>
21 <link linkend='var-CFLAGS'>C</link>
22 <link linkend='var-D'>D</link>
23 <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link>
24 <link linkend='var-FILES'>F</link>
25<!-- <link linkend='var-glossary-g'>G</link> -->
26 <link linkend='var-HOMEPAGE'>H</link>
27 <link linkend='var-IMAGE_FEATURES'>I</link>
28<!-- <link linkend='var-glossary-j'>J</link> -->
29 <link linkend='var-KBRANCH'>K</link>
30 <link linkend='var-LAYERDIR'>L</link>
31 <link linkend='var-MACHINE'>M</link>
32<!-- <link linkend='var-glossary-n'>N</link> -->
33 <link linkend='var-OE_TERMINAL'>O</link>
34 <link linkend='var-P'>P</link>
35<!-- <link linkend='var-glossary-q'>Q</link> -->
36 <link linkend='var-RCONFLICTS'>R</link>
37 <link linkend='var-S'>S</link>
38 <link linkend='var-T'>T</link>
39<!-- <link linkend='var-glossary-u'>U</link> -->
40<!-- <link linkend='var-glossary-v'>V</link> -->
41 <link linkend='var-WORKDIR'>W</link>
42<!-- <link linkend='var-glossary-x'>X</link> -->
43<!-- <link linkend='var-glossary-y'>Y</link> -->
44<!-- <link linkend='var-glossary-z'>Z</link>-->
45 </para>
46
47 <glossdiv id='var-glossary-a'><title>A</title>
48
49 <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
50 <glossdef>
51 <para>
52 Specifies if an output package should still be produced if it is empty.
53 By default, BitBake does not produce empty packages.
54 This default behavior can cause issues when there is an
55 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
56 some other runtime hard-requirement on the existence of the package.
57 </para>
58
59 <para>
60 Like all package-controlling variables, you must always use them in
61 conjunction with a package name override.
62 Here is an example:
63 <literallayout class='monospaced'>
64 ALLOW_EMPTY_${PN} = "1"
65 </literallayout>
66 </para>
67 </glossdef>
68 </glossentry>
69
70 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
71 <glossdef>
72 <para>The email address used to contact the original author or authors in
73 order to send patches, forward bugs, etc.</para>
74 </glossdef>
75 </glossentry>
76
77 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
78 <glossdef>
79 <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
80 is set to the value of this variable, it specifies that the latest
81 source revision in the repository should be used. Here is an example:
82 <literallayout class='monospaced'>
83 SRCREV = "${AUTOREV}"
84 </literallayout>
85 </para>
86 </glossdef>
87 </glossentry>
88
89 </glossdiv>
90
91 <glossdiv id='var-glossary-b'><title>B</title>
92
93 <glossentry id='var-B'><glossterm>B</glossterm>
94 <glossdef>
95 <para>
96 The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
97 The OpenEmbedded build system places generated objects into the Build Directory
98 during a recipe's build process.
99 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
100 directory:
101 <literallayout class='monospaced'>
102 B = ${WORKDIR}/${BPN}/{PV}/
103 </literallayout>
104 You can separate the (<filename>S</filename>) directory and the directory pointed to
105 by the <filename>B</filename> variable.
106 Most autotools-based recipes support separating these directories.
107 The build system defaults to using separate directories for <filename>gcc</filename>
108 and some kernel recipes.
109 </para>
110 </glossdef>
111 </glossentry>
112
113 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
114 <glossdef>
115 <para>
116 A list of packages not to install despite being recommended by a recipe.
117 Support for this variable exists only when using the
118 <filename>ipk</filename> packaging backend.
119 </para>
120 </glossdef>
121 </glossentry>
122
123 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
124 <glossdef>
125 <para>
126 Monitors disk space and available inodes during the build
127 and allows you to control the build based on these
128 parameters.
129 </para>
130
131 <para>
132 Disk space monitoring is disabled by default.
133 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
134 variable to your <filename>conf/local.conf</filename> file found in the
135 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
136 Use the following form:
137 <literallayout class='monospaced'>
138 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
139
140 where:
141
142 &lt;action&gt; is:
143 ABORT: Immediately abort the build when
144 a threshold is broken.
145 STOPTASKS: Stop the build after the currently
146 executing tasks have finished when
147 a threshold is broken.
148 WARN: Issue a warning but continue the
149 build when a threshold is broken.
150 Subsequent warnings are issued as
151 defined by the
152 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
153 which must be defined in the
154 conf/local.conf file.
155
156 &lt;dir&gt; is:
157 Any directory you choose. You can specify one or
158 more directories to monitor by separating the
159 groupings with a space. If two directories are
160 on the same device, only the first directory
161 is monitored.
162
163 &lt;threshold&gt; is:
164 Either the minimum available disk space,
165 the minimum number of free inodes, or
166 both. You must specify at least one. To
167 omit one or the other, simply omit the value.
168 Specify the threshold using G, M, K for Gbytes,
169 Mbytes, and Kbytes, respectively. If you do
170 not specify G, M, or K, Kbytes is assumed by
171 default. Do not use GB, MB, or KB.
172 </literallayout>
173 </para>
174
175 <para>
176 Here are some examples:
177 <literallayout class='monospaced'>
178 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
179 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
180 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
181 </literallayout>
182 The first example works only if you also provide
183 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
184 in the <filename>conf/local.conf</filename>.
185 This example causes the build system to immediately
186 abort when either the disk space in <filename>${TMPDIR}</filename> drops
187 below 1 Gbyte or the available free inodes drops below
188 100 Kbytes.
189 Because two directories are provided with the variable, the
190 build system also issue a
191 warning when the disk space in the
192 <filename>${SSTATE_DIR}</filename> directory drops
193 below 1 Gbyte or the number of free inodes drops
194 below 100 Kbytes.
195 Subsequent warnings are issued during intervals as
196 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
197 variable.
198 </para>
199
200 <para>
201 The second example stops the build after all currently
202 executing tasks complete when the minimum disk space
203 in the <filename>${TMPDIR}</filename> directory drops
204 below 1 Gbyte.
205 No disk monitoring occurs for the free inodes in this case.
206 </para>
207
208 <para>
209 The final example immediately aborts the build when the
210 number of free inodes in the <filename>${TMPDIR}</filename> directory
211 drops below 100 Kbytes.
212 No disk space monitoring for the directory itself occurs
213 in this case.
214 </para>
215 </glossdef>
216 </glossentry>
217
218 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
219 <glossdef>
220 <para>
221 Defines the disk space and free inode warning intervals.
222 To set these intervals, define the variable in your
223 <filename>conf/local.conf</filename> file in the
224 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
225 </para>
226
227 <para>
228 If you are going to use the
229 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
230 also use the
231 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
232 and define its action as "WARN".
233 During the build, subsequent warnings are issued each time
234 disk space or number of free inodes further reduces by
235 the respective interval.
236 </para>
237
238 <para>
239 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
240 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
241 the "WARN" action, the disk monitoring interval defaults to
242 the following:
243 <literallayout class='monospaced'>
244 BB_DISKMON_WARNINTERVAL = "50M,5K"
245 </literallayout>
246 </para>
247
248 <para>
249 When specifying the variable in your configuration file,
250 use the following form:
251 <literallayout class='monospaced'>
252 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
253
254 where:
255
256 &lt;disk_space_interval&gt; is:
257 An interval of memory expressed in either
258 G, M, or K for Gbytes, Mbytes, or Kbytes,
259 respectively. You cannot use GB, MB, or KB.
260
261 &lt;disk_inode_interval&gt; is:
262 An interval of free inodes expressed in either
263 G, M, or K for Gbytes, Mbytes, or Kbytes,
264 respectively. You cannot use GB, MB, or KB.
265 </literallayout>
266 </para>
267
268 <para>
269 Here is an example:
270 <literallayout class='monospaced'>
271 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
272 BB_DISKMON_WARNINTERVAL = "50M,5K"
273 </literallayout>
274 These variables cause the OpenEmbedded build system to
275 issue subsequent warnings each time the available
276 disk space further reduces by 50 Mbytes or the number
277 of free inodes further reduces by 5 Kbytes in the
278 <filename>${SSTATE_DIR}</filename> directory.
279 Subsequent warnings based on the interval occur each time
280 a respective interval is reached beyond the intial warning
281 (i.e. 1 Gbytes and 100 Kbytes).
282 </para>
283 </glossdef>
284 </glossentry>
285
286 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
287 <glossdef>
288 <para>
289 Allows you to extend a recipe so that it builds variants of the software.
290 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
291 which is a copy of quilt built to run on the build system;
292 "crosses" such as <filename>gcc-cross</filename>,
293 which is a compiler built to run on the build machine but produces binaries
294 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
295 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
296 and "mulitlibs" in the form "<filename>multilib:&lt;multilib_name&gt;</filename>".
297 </para>
298
299 <para>
300 To build a different variant of the recipe with a minimal amount of code, it usually
301 is as simple as adding the following to your recipe:
302 <literallayout class='monospaced'>
303 BBCLASSEXTEND =+ "native nativesdk"
304 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
305 </literallayout>
306 </para>
307 </glossdef>
308 </glossentry>
309
310 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
311 <glossdef>
312 <para>Prevents BitBake from processing recipes and recipe append files.
313 You can use the <filename>BBMASK</filename> variable to "hide"
314 these <filename>.bb</filename> and <filename>.bbappend</filename> files.
315 BitBake ignores any recipe or recipe append files that match the expression.
316 It is as if BitBake does not see them at all.
317 Consequently, matching files are not parsed or otherwise used by
318 BitBake.</para>
319 <para>The value you provide is passed to python's regular expression compiler.
320 For complete syntax information, see python's documentation at
321 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
322 The expression is compared against the full paths to the files.
323 For example, the following uses a complete regular expression to tell
324 BitBake to ignore all recipe and recipe append files in the
325 <filename>.*/meta-ti/recipes-misc/</filename> directory:
326 <literallayout class='monospaced'>
327 BBMASK = ".*/meta-ti/recipes-misc/"
328 </literallayout></para>
329 <para>Use the <filename>BBMASK</filename> variable from within the
330 <filename>conf/local.conf</filename> file found
331 in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.</para>
332 </glossdef>
333 </glossentry>
334
335 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
336 <glossdef>
337 <para>The maximum number of tasks BitBake should run in parallel at any one time.
338 If your host development system supports multiple cores a good rule of thumb
339 is to set this variable to twice the number of cores.</para>
340 </glossdef>
341 </glossentry>
342
343 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
344 <glossdef>
345 <para>Lists the names of configured layers.
346 These names are used to find the other <filename>BBFILE_*</filename>
347 variables.
348 Typically, each layer will append its name to this variable in its
349 <filename>conf/layer.conf</filename> file.
350 </para>
351 </glossdef>
352 </glossentry>
353
354 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
355 <glossdef>
356 <para>Variable that expands to match files from <filename>BBFILES</filename> in a particular layer.
357 This variable is used in the <filename>conf/layer.conf</filename> file and must
358 be suffixed with the name of the specific layer (e.g.
359 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
360 </glossdef>
361 </glossentry>
362
363 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
364 <glossdef>
365 <para>Assigns the priority for recipe files in each layer.</para>
366 <para>This variable is useful in situations where the same recipe appears in
367 more than one layer.
368 Setting this variable allows you to prioritize a
369 layer against other layers that contain the same recipe - effectively
370 letting you control the precedence for the multiple layers.
371 The precedence established through this variable stands regardless of a
372 recipe's version (<filename>PV</filename> variable).
373 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
374 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
375 lower precedence.</para>
376 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
377 precedence.
378 For example, the value 6 has a higher precedence than the value 5.
379 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
380 dependencies (see the
381 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
382 more information.
383 The default priority, if unspecified
384 for a layer with no dependencies, is the lowest defined priority + 1
385 (or 1 if no priorities are defined).</para>
386 <tip>
387 You can use the command <filename>bitbake-layers show_layers</filename> to list
388 all configured layers along with their priorities.
389 </tip>
390 </glossdef>
391 </glossentry>
392
393 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
394 <glossdef>
395 <para>List of recipe files used by BitBake to build software</para>
396 </glossdef>
397 </glossentry>
398
399 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
400 <glossdef>
401 <para>Used by BitBake to locate <filename>.bbclass</filename> and configuration files.
402 This variable is analogous to the <filename>PATH</filename> variable.</para>
403 </glossdef>
404 </glossentry>
405
406 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
407 <glossdef>
408 <para>Variable that controls how BitBake displays logs on build failure.</para>
409 </glossdef>
410 </glossentry>
411
412 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
413 <glossdef>
414 <para>Lists the layers to enable during the build.
415 This variable is defined in the <filename>bblayers.conf</filename> configuration
416 file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
417 Here is an example:
418 <literallayout class='monospaced'>
419 BBLAYERS = " \
420 /home/scottrif/poky/meta \
421 /home/scottrif/poky/meta-yocto \
422 /home/scottrif/poky/meta-yocto-bsp \
423 /home/scottrif/poky/meta-mykernel \
424 "
425
426 BBLAYERS_NON_REMOVABLE ?= " \
427 /home/scottrif/poky/meta \
428 /home/scottrif/poky/meta-yocto \
429 "
430 </literallayout>
431 This example enables four layers, one of which is a custom, user-defined layer
432 named <filename>meta-mykernel</filename>.
433 </para>
434 </glossdef>
435 </glossentry>
436
437 <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm>
438 <glossdef>
439Core layer for images cannot be removed
440 <para>Lists core layers that cannot be removed from the
441 <filename>bblayers.conf</filename> file.
442 In order for BitBake to build your image, your
443 <filename>bblayers.conf</filename> file must include the
444 <filename>meta</filename> and <filename>meta-yocto</filename>
445 core layers.
446 Here is an example that shows these two layers listed in
447 the <filename>BBLAYERS_NON_REMOVABLE</filename> statement:
448 <literallayout class='monospaced'>
449 BBLAYERS = " \
450 /home/scottrif/poky/meta \
451 /home/scottrif/poky/meta-yocto \
452 /home/scottrif/poky/meta-yocto-bsp \
453 /home/scottrif/poky/meta-mykernel \
454 "
455
456 BBLAYERS_NON_REMOVABLE ?= " \
457 /home/scottrif/poky/meta \
458 /home/scottrif/poky/meta-yocto \
459 "
460 </literallayout>
461 </para>
462 </glossdef>
463 </glossentry>
464
465 <glossentry id='var-BP'><glossterm>BP</glossterm>
466 <glossdef>
467 <para>The base recipe name and version but without any special
468 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
469 and so forth).
470 <filename>BP</filename> is comprised of the following:
471 <literallayout class="monospaced">
472 ${BPN}-${PV}
473 </literallayout></para>
474 </glossdef>
475 </glossentry>
476
477 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
478 <glossdef>
479 <para>The bare name of the recipe.
480 This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable
481 but removes common suffixes such as "-native" and "-cross" as well
482 as removes common prefixes such as multilib's "lib64-" and "lib32-".
483 The exact list of suffixes removed is specified by the
484 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable.
485 The exact list of prefixes removed is specified by the
486 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable.
487 Prefixes are removed for multilib and nativesdk cases.</para>
488 </glossdef>
489 </glossentry>
490
491 </glossdiv>
492
493 <glossdiv id='var-glossary-c'><title>C</title>
494
495 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
496 <glossdef>
497 <para>
498 Flags passed to C compiler for the target system.
499 This variable evaluates to the same as
500 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>.
501 </para>
502 </glossdef>
503 </glossentry>
504
505 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
506 <glossdef>
507 <para>A set of features common between
508 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
509 and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
510 See the glossary descriptions for these variables for more information.</para>
511 </glossdef>
512 </glossentry>
513
514 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
515 <glossdef>
516 <para>A regular expression which evaluates to match the machines the recipe
517 works with.
518 It stops recipes being run on machines for which they are not compatible.
519 This is particularly useful with kernels.
520 It also helps to increase parsing speed as further parsing of the recipe is skipped
521 if it is found the current machine is not compatible.</para>
522 </glossdef>
523 </glossentry>
524
525 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
526 <glossdef>
527 <para>
528 Identifies editable or configurable files that are part of a package.
529 If the Package Management System (PMS) is being used to update
530 packages on the target system, it is possible that
531 configuration files you have changed after the original installation
532 and that you now want to remain unchanged are overwritten.
533 In other words, editable files might exist in the package that you do not
534 want reset as part of the package update process.
535 You can use the <filename>CONFFILES</filename> variable to list the files in the
536 package that you wish to prevent the PMS from overwriting during this update process.
537 </para>
538
539 <para>
540 To use the <filename>CONFFILES</filename> variable, provide a package name
541 override that identifies the resulting package.
542 Then, provide a space-separated list of files.
543 Here is an example:
544 <literallayout class='monospaced'>
545 CONFFILES_${PN} += "${sysconfdir}/file1 \
546 ${sysconfdir}/file2 ${sysconfdir}/file3"
547 </literallayout>
548 </para>
549
550 <para>
551 A relationship exists between the <filename>CONFFILES</filename> and
552 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
553 The files listed within <filename>CONFFILES</filename> must be a subset of
554 the files listed within <filename>FILES</filename>.
555 Because the configuration files you provide with <filename>CONFFILES</filename>
556 are simply being identified so that the PMS will not overwrite them,
557 it makes sense that
558 the files must already be included as part of the package through the
559 <filename>FILES</filename> variable.
560 </para>
561
562 <note>
563 When specifying paths as part of the <filename>CONFFILES</filename> variable,
564 it is good practice to use appropriate path variables.
565 For example, <filename>${sysconfdir}</filename> rather than
566 <filename>/etc</filename> or <filename>${bindir}</filename> rather
567 than <filename>/usr/bin</filename>.
568 You can find a list of these variables at the top of the
569 <filename>/meta/conf/bitbake.conf</filename> file in the
570 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
571 </note>
572 </glossdef>
573 </glossentry>
574
575 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
576 <glossdef>
577 <para>
578 A list of files that contains <filename>autoconf</filename> test results relevant
579 to the current build.
580 This variable is used by the Autotools utilities when running
581 <filename>configure</filename>.
582 </para>
583 </glossdef>
584 </glossentry>
585
586 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
587 <glossdef>
588 <para>
589 Specifies the list of packages to be added to the image.
590 This variable should only be set in the <filename>local.conf</filename>
591 configuration file found in the
592 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
593 </para>
594
595 <para>
596 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
597 </para>
598 </glossdef>
599 </glossentry>
600
601 </glossdiv>
602
603 <glossdiv id='var-glossary-d'><title>D</title>
604
605 <glossentry id='var-D'><glossterm>D</glossterm>
606 <glossdef>
607 <para>The destination directory.</para>
608 </glossdef>
609 </glossentry>
610
611 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
612 <glossdef>
613 <para>
614 Specifies to build packages with debugging information.
615 This influences the value of the
616 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
617 variable.
618 </para>
619 </glossdef>
620 </glossentry>
621
622 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
623 <glossdef>
624 <para>
625 The options to pass in
626 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
627 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
628 a system for debugging.
629 This variable defaults to "-O -fno-omit-frame-pointer -g".
630 </para>
631 </glossdef>
632 </glossentry>
633
634 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
635 <glossdef>
636 <para>Specifies the priority of recipes.</para>
637 </glossdef>
638 </glossentry>
639
640 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
641 <glossdef>
642 <para>
643 Lists a recipe's build-time dependencies
644 (i.e. other recipe files).
645 The system ensures that all the dependencies listed
646 have been built and have their contents in the appropriate
647 sysroots before the recipe's configure task is executed.
648 </para>
649 </glossdef>
650 </glossentry>
651
652 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
653 <glossdef>
654 <para>The package description used by package managers.
655 If not set, <filename>DESCRIPTION</filename> takes
656 the value of the
657 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
658 variable.
659 </para>
660 </glossdef>
661 </glossentry>
662
663 <glossentry id='var-DESTDIR'><glossterm>DESTDIR</glossterm>
664 <glossdef>
665 <para>the destination directory.</para>
666 </glossdef>
667 </glossentry>
668
669 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
670 <glossdef>
671 <para>
672 The short name of the distribution.
673 This variable corresponds to a file with the
674 extension <filename>.conf</filename>
675 located in a <filename>conf/distro</filename> directory
676 within the metadata that contains the distribution configuration.
677 The
678 value must not contain spaces, and is typically all lower-case.
679 </para>
680 <para>
681 If the variable is blank, a set of default configuration
682 will be used, which is specified
683 within <filename>meta/conf/distro/defaultsetup.conf</filename>.
684 </para>
685 </glossdef>
686 </glossentry>
687
688 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
689 <glossdef>
690 <para>
691 Specifies a list of distro-specific packages to add to all images.
692 This variable takes affect through
693 <filename>packagegroup-base</filename> so the
694 variable only really applies to the more full-featured
695 images that include <filename>packagegroup-base</filename>.
696 You can use this variable to keep distro policy out of
697 generic images.
698 As with all other distro variables, you set this variable
699 in the distro <filename>.conf</filename> file.
700 </para>
701 </glossdef>
702 </glossentry>
703
704 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
705 <glossdef>
706 <para>
707 Specifies a list of distro-specific packages to add to all images
708 if the packages exist.
709 The packages might not exist or be empty (e.g. kernel modules).
710 The list of packages are automatically installed but can be
711 removed by the user.
712 </para>
713 </glossdef>
714 </glossentry>
715
716 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
717 <glossdef>
718 <para>The features enabled for the distribution.
719 For a list of features supported by the Yocto Project as shipped,
720 see the "<link linkend='ref-features-distro'>Distro</link>"
721 section.
722 </para>
723 </glossdef>
724 </glossentry>
725
726 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
727 <glossdef>
728 <para>Features to be added to
729 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
730 if not also present in
731 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
732 </para>
733
734 <para>
735 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
736 It is not intended to be user-configurable.
737 It is best to just reference the variable to see which distro features are
738 being backfilled for all distro configurations.
739 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
740 more information.
741 </para>
742 </glossdef>
743 </glossentry>
744
745 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
746 <glossdef>
747 <para>Features from
748 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
749 that should not backfilled (i.e. added to
750 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
751 during the build.
752 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
753 more information.
754 </para>
755 </glossdef>
756 </glossentry>
757
758 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
759 <glossdef>
760 <para>The long name of the distribution.</para>
761 </glossdef>
762 </glossentry>
763
764 <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
765 <glossdef>
766 <para>Alias names used for the recipe in various Linux distributions.</para>
767 <para>See the
768 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling
769 a Package Name Alias</ulink>" section in the Yocto Project Development
770 Manual for more information.</para>
771 </glossdef>
772 </glossentry>
773
774 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
775 <glossdef>
776 <para>the version of the distribution.</para>
777 </glossdef>
778 </glossentry>
779
780 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
781 <glossdef>
782 <para>
783 The central download directory used by the build process to store downloads.
784 You can set this directory by defining the <filename>DL_DIR</filename>
785 variable in the <filename>/conf/local.conf</filename> file.
786 This directory is self-maintaining and you should not have
787 to touch it.
788 By default, the directory is <filename>downloads</filename> in the
789 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
790 <literallayout class='monospaced'>
791 #DL_DIR ?= "${TOPDIR}/downloads"
792 </literallayout>
793 To specify a different download directory, simply uncomment the line
794 and provide your directory.
795 </para>
796
797 <para>
798 During a first build, the system downloads many different source code
799 tarballs from various upstream projects.
800 Downloading can take a while, particularly if your network
801 connection is slow.
802 Tarballs are all stored in the directory defined by
803 <filename>DL_DIR</filename> and the build system looks there first
804 to find source tarballs.
805 <note>
806 When wiping and rebuilding, you can preserve this directory to speed
807 up this part of subsequent builds.
808 </note>
809 </para>
810
811 <para>
812 You can safely share this directory between multiple builds on the
813 same development machine.
814 For additional information on how the build process gets source files
815 when working behind a firewall or proxy server, see the
816 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
817 chapter.
818 </para>
819 </glossdef>
820
821 </glossentry>
822 </glossdiv>
823
824 <glossdiv id='var-glossary-e'><title>E</title>
825
826 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
827 <glossdef>
828 <para></para>
829 <para>Variable that controls which locales for <filename>eglibc</filename> are
830 to be generated during the build (useful if the target device has 64Mbytes
831 of RAM or less).</para>
832 </glossdef>
833 </glossentry>
834
835 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
836 <glossdef>
837 <para>
838 Used with file and pathnames to create a prefix for a recipe's
839 version based on the recipe's
840 <link linkend='var-PE'><filename>PE</filename></link> value.
841 If <filename>PE</filename> is set and greater than zero for a recipe,
842 <filename>EXTENDPE</filename> becomes that value (e.g if
843 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
844 becomes "1_").
845 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
846 zero, <filename>EXTENDPE</filename> becomes "".</para>
847 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
848 variable for an example.
849 </para>
850 </glossdef>
851 </glossentry>
852
853 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
854 <glossdef>
855 <para>Allows extra packages to be added to the generated images.
856 You set this variable in the <filename>local.conf</filename>
857 configuration file.
858 Note that some image features are also added using the
859 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
860 variable generally configured in image recipes.
861 You can use this variable to add more features in addition to those.
862 Here are some examples of features you can add:</para>
863 <literallayout class='monospaced'>
864"dbg-pkgs" - Adds -dbg packages for all installed packages
865 including symbol information for debugging and
866 profiling.
867
868"dev-pkgs" - Adds -dev packages for all installed packages.
869 This is useful if you want to develop against
870 the libraries in the image.
871
872"tools-sdk" - Adds development tools such as gcc, make,
873 pkgconfig and so forth.
874
875"tools-debug" - Adds debugging tools such as gdb and
876 strace.
877
878"tools-profile" - Adds profiling tools such as oprofile,
879 exmap, lttng and valgrind (x86 only).
880
881"tools-testapps" - Adds useful testing tools such as
882 ts_print, aplay, arecord and so
883 forth.
884
885"debug-tweaks" - Makes an image suitable for development.
886 For example, ssh root access has a blank
887 password. You should remove this feature
888 before you produce a production image.
889 </literallayout>
890
891 <para>There are other valid features too, see the
892 <link linkend='ref-features-image'>Images</link>
893 section for more details.</para>
894 </glossdef>
895 </glossentry>
896
897 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
898 <glossdef>
899 <para>A list of recipes to be built that do not provide packages to be installed in
900 the root filesystem.
901 </para>
902 <para>Sometimes a recipe is required to build the final image but is not
903 needed in the root filesystem.
904 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
905 list these recipes and thus, specify the dependencies.
906 A typical example is a required bootloader in a machine configuration.
907 </para>
908 <note>
909 To add packages to the root filesystem, see the various
910 <filename>*DEPENDS</filename> and <filename>*RECOMMENDS</filename>
911 variables.
912 </note>
913 </glossdef>
914 </glossentry>
915
916 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
917 <glossdef>
918 <para>Additional <filename>cmake</filename> options.</para>
919 </glossdef>
920 </glossentry>
921
922 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
923 <glossdef>
924 <para>Additional <filename>configure</filename> script options.</para>
925 </glossdef>
926 </glossentry>
927
928 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
929 <glossdef>
930 <para>Additional GNU <filename>make</filename> options.</para>
931 </glossdef>
932 </glossentry>
933
934 </glossdiv>
935
936 <glossdiv id='var-glossary-f'><title>F</title>
937
938 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
939 <glossdef>
940 <para>
941 The list of directories or files that are placed in packages.
942 </para>
943
944 <para>
945 To use the <filename>FILES</filename> variable, provide a package name
946 override that identifies the resulting package.
947 Then, provide a space-separated list of files or paths that identifies the
948 files you want included as part of the resulting package.
949 Here is an example:
950 <literallayout class='monospaced'>
951 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
952 </literallayout>
953 </para>
954
955 <note>
956 When specifying paths as part of the <filename>FILES</filename> variable,
957 it is good practice to use appropriate path variables.
958 For example, <filename>${sysconfdir}</filename> rather than
959 <filename>/etc</filename> or <filename>${bindir}</filename> rather
960 than <filename>/usr/bin</filename>.
961 You can find a list of these variables at the top of the
962 <filename>/meta/conf/bitbake.conf</filename> file in the
963 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
964 </note>
965
966 <para>
967 If some of the files you provide with the <filename>FILES</filename> variable
968 are editable and you know they should not be
969 overwritten during the package update process by the Package Management
970 System (PMS), you can identify these files so that the PMS will not
971 overwrite them.
972 See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename>
973 variable for information on how to identify these files to the PMS.
974 </para>
975
976 </glossdef>
977 </glossentry>
978
979 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
980 <glossdef>
981 <para>
982 Extends the search path the OpenEmbedded build system uses when
983 looking for files and patches as it processes recipes.
984 The directories BitBake uses when it processes recipes is defined by the
985 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> variable.
986 You can add directories to the search path by defining the
987 <filename>FILESEXTRAPATHS</filename> variable.
988 </para>
989
990 <para>
991 To add paths to the search order, provide a list of directories and separate
992 each path using a colon character as follows:
993 <literallayout class='monospaced'>
994 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
995 </literallayout>
996 Typically, you want your directories searched first.
997 To make sure that happens, use <filename>_prepend</filename> and
998 the immediate expansion (<filename>:=</filename>) operator as shown in the
999 previous example.
1000 Finally, to maintain the integrity of the <filename>FILESPATH</filename> variable,
1001 you must include the appropriate beginning or ending (as needed) colon character.
1002 </para>
1003
1004 <para>
1005 The <filename>FILESEXTRAPATHS</filename> variable is intended for use in
1006 <filename>.bbappend</filename> files to include any additional files provided in that layer.
1007 You typically accomplish this with the following:
1008 <literallayout class='monospaced'>
1009 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1010 </literallayout>
1011 </para>
1012 </glossdef>
1013 </glossentry>
1014
1015 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
1016 <glossdef>
1017 <para>
1018 The default set of directories the OpenEmbedded build system uses
1019 when searching for patches and files.
1020 During the build process, BitBake searches each directory in
1021 <filename>FILESPATH</filename> in the specified order when looking for
1022 files and patches specified by each <filename>file://</filename> URI in a recipe.
1023 </para>
1024
1025 <para>
1026 The default value for the <filename>FILESPATH</filename> variable is defined
1027 in the <filename>base.bbclass</filename> class found in
1028 <filename>meta/classes</filename> in the
1029 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
1030 <literallayout class='monospaced'>
1031FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
1032 "${FILE_DIRNAME}/${P}", "${FILE_DIRNAME}/${PN}", \
1033 "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \
1034 "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}"
1035 </literallayout>
1036 Do not hand-edit the <filename>FILESPATH</filename> variable.
1037 If you want to extend the set of pathnames that BitBake uses when searching for
1038 files and patches, use the
1039 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link> variable.
1040 </para>
1041 </glossdef>
1042 </glossentry>
1043
1044 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
1045 <glossdef>
1046 <para>Allows you to define your own file permissions settings table as part of
1047 your configuration for the packaging process.
1048 For example, suppose you need a consistent set of custom permissions for
1049 a set of groups and users across an entire work project.
1050 It is best to do this in the packages themselves but this is not always
1051 possible.
1052 </para>
1053 <para>
1054 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
1055 is located in the <filename>meta/files</filename> folder in the
1056 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1057 If you create your own file permissions setting table, you should place it in your
1058 layer or the distros layer.
1059 </para>
1060 <para>
1061 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
1062 <filename>conf/local.conf</filename> file, which is found in the
1063 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to
1064 point to your custom <filename>fs-perms.txt</filename>.
1065 You can specify more than a single file permissions setting table.
1066 The paths you specify to these files must be defined within the
1067 <filename>BBPATH</filename> variable.
1068 </para>
1069 <para>
1070 For guidance on how to create your own file permissions settings table file,
1071 examine the existing <filename>fs-perms.txt</filename>.
1072 </para>
1073 </glossdef>
1074 </glossentry>
1075
1076 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
1077 <glossdef>
1078 <para>
1079 The options to pass in
1080 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1081 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
1082 when compiling an optimized system.
1083 This variable defaults to
1084 "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
1085 </para>
1086 </glossdef>
1087 </glossentry>
1088
1089 </glossdiv>
1090
1091<!-- <glossdiv id='var-glossary-g'><title>G</title>-->
1092<!-- </glossdiv>-->
1093
1094 <glossdiv id='var-glossary-h'><title>H</title>
1095
1096 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
1097 <glossdef>
1098 <para>Website where more information about the software the recipe is building
1099 can be found.</para>
1100 </glossdef>
1101 </glossentry>
1102
1103 </glossdiv>
1104
1105 <glossdiv id='var-glossary-i'><title>I</title>
1106
1107 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
1108 <glossdef>
1109 <para>The list of features to include in an image.
1110 Typically, you configure this variable in an image recipe.
1111 Note that you can also add extra features to the image by using the
1112 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
1113 See the "<link linkend="ref-features-image">Images</link>" section for the
1114 full list of features that can be included in images built by the
1115 OpenEmbedded build system.</para>
1116 </glossdef>
1117 </glossentry>
1118
1119 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
1120 <glossdef>
1121 <para>Formats of root filesystem images that you want to have created.</para>
1122 </glossdef>
1123 </glossentry>
1124
1125 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
1126 <glossdef>
1127 <para>
1128 Specifies the packages to install into an image.
1129 The <filename>IMAGE_INSTALL</filename> variable is a mechanism for an image
1130 recipe and you should use it with care to avoid ordering issues.
1131 </para>
1132
1133 <para>
1134 Image recipes set <filename>IMAGE_INSTALL</filename> to specify the
1135 packages to install into an image through <filename>image.bbclass</filename>.
1136 Additionally, "helper" classes exist, such as <filename>core-image.bbclass</filename>,
1137 that can take
1138 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> lists
1139 and turn these into auto-generated entries in
1140 <filename>IMAGE_INSTALL</filename> in addition to its default contents.
1141 </para>
1142
1143 <para>
1144 Using <filename>IMAGE_INSTALL</filename> with the <filename>+=</filename>
1145 operator from the <filename>/conf/local.conf</filename> file or from within
1146 an image recipe is not recommended as it can cause ordering issues.
1147 Since <filename>core-image.bbclass</filename> sets <filename>IMAGE_INSTALL</filename>
1148 to a default value using the <filename>?=</filename> operator, using a
1149 <filename>+=</filename> operation against <filename>IMAGE_INSTALL</filename>
1150 will result in unexpected behavior when used in
1151 <filename>/conf/local.conf</filename>.
1152 Furthermore, the same operation from with an image recipe may or may not
1153 succeed depending on the specific situation.
1154 In both these cases, the behavior is contrary to how most users expect
1155 the <filename>+=</filename> operator to work.
1156 </para>
1157
1158 <para>
1159 When you use this variable, it is best to use it as follows:
1160 <literallayout class='monospaced'>
1161 IMAGE_INSTALL_append = " package-name"
1162 </literallayout>
1163 Be sure to include the space between the quotation character and the start of the
1164 package name.
1165 </para>
1166 </glossdef>
1167 </glossentry>
1168
1169 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
1170 <glossdef>
1171 <para>
1172 Defines a multiplier that the build system applies to the initial image
1173 size for cases when the multiplier times the returned disk usage value
1174 for the image is greater than the sum of
1175 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
1176 and
1177 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
1178 The result of the multiplier applied to the initial image size creates
1179 free disk space in the image as overhead.
1180 By default, the build process uses a multiplier of 1.3 for this variable.
1181 This default value results in 30% free disk space added to the image when this
1182 method is used to determine the final generated image size.
1183 You should be aware that post install scripts and the package management
1184 system uses disk space inside this overhead area.
1185 Consequently, the multiplier does not produce an image with
1186 all the theoretical free disk space.
1187 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
1188 for information on how the build system determines the overall image size.
1189 </para>
1190
1191 <para>
1192 The default 30% free disk space typically gives the image enough room to boot
1193 and allows for basic post installs while still leaving a small amount of
1194 free disk space.
1195 If 30% free space is inadequate, you can increase the default value.
1196 For example, the following setting gives you 50% free space added to the image:
1197 <literallayout class='monospaced'>
1198 IMAGE_OVERHEAD_FACTOR = "1.5"
1199 </literallayout>
1200 </para>
1201
1202 <para>
1203 Alternatively, you can ensure a specific amount of free disk space is added
1204 to the image by using
1205 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
1206 the variable.
1207 </para>
1208 </glossdef>
1209 </glossentry>
1210
1211 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
1212 <glossdef>
1213 <para>
1214 Defines additional free disk space created in the image in Kbytes.
1215 By default, this variable is set to "0".
1216 This free disk space is added to the image after the build system determines
1217 the image size as described in
1218 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
1219 </para>
1220
1221 <para>
1222 This variable is particularly useful when you want to ensure that a
1223 specific amount of free disk space is available on a device after an image
1224 is installed and running.
1225 For example, to be sure 5 Gbytes of free disk space is available, set the
1226 variable as follows:
1227 <literallayout class='monospaced'>
1228 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
1229 </literallayout>
1230 </para>
1231 </glossdef>
1232 </glossentry>
1233
1234 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
1235 <glossdef>
1236 <para>
1237 Defines the size in Kbytes for the generated image.
1238 The OpenEmbedded build system determines the final size for the generated
1239 image using an algorithm that takes into account the initial disk space used
1240 for the generated image, a requested size for the image, and requested
1241 additional free disk space to be added to the image.
1242 Programatically, the build system determines the final size of the
1243 generated image as follows:
1244 <literallayout class='monospaced'>
1245 if (image-du * overhead) &lt; rootfs-size:
1246 internal-rootfs-size = rootfs-size + xspace
1247 else:
1248 internal-rootfs-size = (image-du * overhead) + xspace
1249
1250 where:
1251
1252 image-du = Returned value of the du command on
1253 the image.
1254
1255 overhead = IMAGE_OVERHEAD_FACTOR
1256
1257 rootfs-size = IMAGE_ROOTFS_SIZE
1258
1259 internal-rootfs-size = Initial root filesystem
1260 size before any modifications.
1261
1262 xspace = IMAGE_ROOTFS_EXTRA_SPACE
1263 </literallayout>
1264<!-- In the above example, <filename>overhead</filename> is defined by the
1265 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
1266 variable, <filename>xspace</filename> is defined by the
1267 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
1268 variable, and <filename>du</filename> is the results of the disk usage command
1269 on the initially generated image. -->
1270 </para>
1271 </glossdef>
1272 </glossentry>
1273
1274 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
1275 <glossdef>
1276 <para>Helps define the recipe revision for recipes that share
1277 a common <filename>include</filename> file.
1278 You can think of this variable as part of the recipe revision
1279 as set from within an include file.</para>
1280 <para>Suppose, for example, you have a set of recipes that
1281 are used across several projects.
1282 And, within each of those recipes the revision
1283 (its <filename>PR</filename> value) is set accordingly.
1284 In this case, when the revision of those recipes changes
1285 the burden is on you to find all those recipes and
1286 be sure that they get changed to reflect the updated
1287 version of the recipe.
1288 In this scenario, it can get complicated when recipes
1289 used in many places and that provide common functionality
1290 are upgraded to a new revision.</para>
1291 <para>A more efficient way of dealing with this situation is
1292 to set the <filename>INC_PR</filename> variable inside
1293 the <filename>include</filename> files that the recipes
1294 share and then expand the <filename>INC_PR</filename>
1295 variable within the recipes to help
1296 define the recipe revision.
1297 </para>
1298 <para>
1299 The following provides an example that shows how to use
1300 the <filename>INC_PR</filename> variable
1301 given a common <filename>include</filename> file that
1302 defines the variable.
1303 Once the variable is defined in the
1304 <filename>include</filename> file, you can use the
1305 variable to set the <filename>PR</filename> values in
1306 each recipe.
1307 You will notice that when you set a recipe's
1308 <filename>PR</filename> you can provide more granular
1309 revisioning by appending values to the
1310 <filename>INC_PR</filename> variable:
1311 <literallayout class='monospaced'>
1312recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
1313recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
1314recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
1315recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1316 </literallayout>
1317 The first line of the example establishes the baseline
1318 revision to be used for all recipes that use the
1319 <filename>include</filename> file.
1320 The remaining lines in the example are from individual
1321 recipes and show how the <filename>PR</filename> value
1322 is set.</para>
1323 </glossdef>
1324 </glossentry>
1325
1326 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
1327 <glossdef>
1328 <para>
1329 Causes the build to not strip binaries in resulting packages.
1330 </para>
1331 </glossdef>
1332 </glossentry>
1333
1334
1335 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
1336 <glossdef>
1337 <para>
1338 Causes the named class to be inherited at
1339 this point during parsing.
1340 The variable is only valid in configuration files.
1341 </para>
1342 </glossdef>
1343 </glossentry>
1344
1345
1346 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
1347 <glossdef>
1348 <para>
1349 A list of the packages that contain initscripts.
1350 If multiple packages are specified, you need to append the package name
1351 to the other <filename>INITSCRIPT_*</filename> as an override.</para>
1352 <para>
1353 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
1354 The variable is optional and defaults to the <filename>PN</filename> variable.
1355 </para>
1356 </glossdef>
1357 </glossentry>
1358
1359 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
1360 <glossdef>
1361 <para>
1362 The filename of the initscript (as installed to <filename>${etcdir}/init.d)</filename>.
1363 </para>
1364 <para>
1365 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
1366 The variable is Mandatory.
1367 </para>
1368 </glossdef>
1369 </glossentry>
1370
1371 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
1372 <glossdef>
1373 <para>
1374 Specifies the options to pass to <filename>update-rc.d</filename>.
1375 An example is <filename>start 99 5 2 . stop 20 0 1 6 .</filename>, which gives the script a
1376 runlevel of 99, starts the script in initlevels 2 and 5, and
1377 stops the script in levels 0, 1 and 6.
1378 </para>
1379 <para>
1380 The variable is mandatory and is used in recipes when using
1381 <filename>update-rc.d.bbclass</filename>.
1382 </para>
1383 </glossdef>
1384 </glossentry>
1385
1386
1387 </glossdiv>
1388
1389<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
1390<!-- </glossdiv>-->
1391
1392 <glossdiv id='var-glossary-k'><title>K</title>
1393
1394 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
1395 <glossdef>
1396 <para>
1397 A regular expression used by the build process to explicitly identify the kernel
1398 branch that is validated, patched and configured during a build.
1399 The <filename>KBRANCH</filename> variable is optional.
1400 You can use it to trigger checks to ensure the exact kernel branch you want is
1401 being used by the build process.
1402 </para>
1403
1404 <para>
1405 Values for this variable are set in the kernel's recipe file and the kernel's
1406 append file.
1407 For example, if you are using the Yocto Project kernel that is based on the
1408 Linux 3.4 kernel, the kernel recipe file is the
1409 <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename> file.
1410 Following is the default value for <filename>KBRANCH</filename> and the default
1411 override for the architectures the Yocto Project supports:
1412 <literallayout class='monospaced'>
1413 KBRANCH_DEFAULT = "standard/base"
1414 KBRANCH = "${KBRANCH_DEFAULT}"
1415 </literallayout>
1416 This branch exists in the <filename>linux-yocto-3.4</filename> kernel Git
1417 repository <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>.
1418 </para>
1419
1420 <para>
1421 This variable is also used from the kernel's append file to identify the kernel
1422 branch specific to a particular machine or target hardware.
1423 The kernel's append file is located in the BSP layer for a given machine.
1424 For example, the kernel append file for the Crown Bay BSP is in the
1425 <filename>meta-intel</filename> Git repository and is named
1426 <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>.
1427 Here are the related statements from the append file:
1428 <literallayout class='monospaced'>
1429 COMPATIBLE_MACHINE_crownbay = "crownbay"
1430 KMACHINE_crownbay = "crownbay"
1431 KBRANCH_crownbay = "standard/crownbay"
1432
1433 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
1434 KMACHINE_crownbay-noemgd = "crownbay"
1435 KBRANCH_crownbay-noemgd = "standard/crownbay"
1436 </literallayout>
1437 The <filename>KBRANCH_*</filename> statements identify the kernel branch to
1438 use when building for the Crown Bay BSP.
1439 In this case there are two identical statements: one for each type of
1440 Crown Bay machine.
1441 </para>
1442 </glossdef>
1443 </glossentry>
1444
1445 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
1446 <glossdef>
1447 <para>Includes additional metadata from the Yocto Project kernel Git repository.
1448 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
1449 metadata is provided through
1450 the <filename>KMACHINE</filename> and <filename>KBRANCH</filename> variables.
1451 You can use the <filename>KERNEL_FEATURES</filename> variable to further
1452 add metadata for all BSPs.</para>
1453 <para>The metadata you add through this variable includes config fragments and
1454 features descriptions,
1455 which usually includes patches as well as config fragments.
1456 You typically override the <filename>KERNEL_FEATURES</filename> variable
1457 for a specific machine.
1458 In this way, you can provide validated, but optional, sets of kernel
1459 configurations and features.</para>
1460 <para>For example, the following adds <filename>netfilter</filename> to all
1461 the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>
1462 machine:
1463 <literallayout class='monospaced'>
1464 # Add netfilter to all linux-yocto kernels
1465 KERNEL_FEATURES="features/netfilter"
1466
1467 # Add sound support to the qemux86 machine
1468 KERNEL_FEATURES_append_qemux86=" cfg/sound"
1469 </literallayout></para>
1470 </glossdef>
1471 </glossentry>
1472
1473 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
1474 <glossdef>
1475 <para>The type of kernel to build for a device, usually set by the
1476 machine configuration files and defaults to "zImage".
1477 This variable is used
1478 when building the kernel and is passed to <filename>make</filename> as the target to
1479 build.</para>
1480 </glossdef>
1481 </glossentry>
1482
1483 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
1484 <glossdef>
1485 <para>
1486 The machine as known by the kernel.
1487 Sometimes the machine name used by the kernel does not match the machine name
1488 used by the OpenEmbedded build system.
1489 For example, the machine name that the OpenEmbedded build system understands as
1490 <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel.
1491 The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
1492 For cases like these, the <filename>KMACHINE</filename> variable maps the
1493 kernel machine name to the OpenEmbedded build system machine name.
1494 </para>
1495
1496 <para>
1497 Kernel machine names are initially defined in the
1498 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Yocto Linux Kernel</ulink> in
1499 the <filename>meta</filename> branch.
1500 From the <filename>meta</filename> branch, look in
1501 the <filename>meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</filename> file.
1502 For example, from the <filename>meta</filename> branch in the
1503 <filename>linux-yocto-3.0</filename> kernel, the
1504 <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file
1505 has the following:
1506 <literallayout class='monospaced'>
1507 define KMACHINE cedartrail
1508 define KTYPE standard
1509 define KARCH i386
1510
1511 include ktypes/standard
1512 branch cedartrail
1513
1514 include cedartrail.scc
1515 </literallayout>
1516 You can see that the kernel understands the machine name for the Cedar Trail BSP as
1517 <filename>cedartrail</filename>.
1518 </para>
1519
1520 <para>
1521 If you look in the Cedar Trail BSP layer in the <filename>meta-intel</filename> source
1522 repository at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>,
1523 you will find the following statements among others:
1524 <literallayout class='monospaced'>
1525 COMPATIBLE_MACHINE_cedartrail = "cedartrail"
1526 KMACHINE_cedartrail = "cedartrail"
1527 KBRANCH_cedartrail = "yocto/standard/cedartrail"
1528 KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
1529 KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
1530
1531 COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
1532 KMACHINE_cedartrail-nopvr = "cedartrail"
1533 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
1534 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
1535 </literallayout>
1536 The <filename>KMACHINE</filename> statements in the kernel's append file make sure that
1537 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
1538 names.
1539 </para>
1540
1541 <para>
1542 This append file uses two <filename>KMACHINE</filename> statements.
1543 The first is not really necessary but does ensure that the machine known to the
1544 OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
1545 in the kernel also known as <filename>cedartrail</filename>:
1546 <literallayout class='monospaced'>
1547 KMACHINE_cedartrail = "cedartrail"
1548 </literallayout>
1549 </para>
1550
1551 <para>
1552 The second statement is a good example of why the <filename>KMACHINE</filename> variable
1553 is needed.
1554 In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename>
1555 machine name to refer to the Cedar Trail BSP that does not support the propriatory
1556 PowerVR driver.
1557 The kernel, however, uses the machine name <filename>cedartrail</filename>.
1558 Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to
1559 the kernel's <filename>cedartrail</filename> name:
1560 <literallayout class='monospaced'>
1561 KMACHINE_cedartrail-nopvr = "cedartrail"
1562 </literallayout>
1563 </para>
1564
1565 <para>
1566 BSPs that ship with the Yocto Project release provide all mappings between the Yocto
1567 Project kernel machine names and the OpenEmbedded machine names.
1568 Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine
1569 name you use is different than that used in the kernel.
1570 </para>
1571 </glossdef>
1572 </glossentry>
1573
1574 </glossdiv>
1575
1576 <glossdiv id='var-glossary-l'><title>L</title>
1577
1578 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
1579 <glossdef>
1580 <para>Lists the layers that this recipe depends upon, separated by spaces.
1581 Optionally, you can specify a specific layer version for a dependency
1582 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
1583 to be compared against <filename>LAYERVERSION_anotherlayer</filename> in this case).
1584 An error will be produced if any dependency is missing or
1585 the version numbers do not match exactly (if specified).
1586 This variable is used in the <filename>conf/layer.conf</filename> file
1587 and must be suffixed with the name of the specific layer (e.g.
1588 <filename>LAYERDEPENDS_mylayer</filename>).</para>
1589 </glossdef>
1590 </glossentry>
1591
1592 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
1593 <glossdef>
1594 <para>When used inside the <filename>layer.conf</filename> configuration
1595 file, this variable provides the path of the current layer.
1596 This variable requires immediate expansion
1597 (see the BitBake manual) as lazy expansion can result in
1598 the expansion happening in the wrong directory and therefore
1599 giving the wrong value.</para>
1600 </glossdef>
1601 </glossentry>
1602
1603 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
1604 <glossdef>
1605 <para>Optionally specifies the version of a layer as a single number.
1606 You can use this within <filename>LAYERDEPENDS</filename> for another layer in order to
1607 depend on a specific version of the layer.
1608 This variable is used in the <filename>conf/layer.conf</filename> file
1609 and must be suffixed with the name of the specific layer (e.g.
1610 <filename>LAYERVERSION_mylayer</filename>).</para>
1611 </glossdef>
1612 </glossentry>
1613
1614 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
1615 <glossdef>
1616 <para>Checksums of the license text in the recipe source code.</para>
1617 <para>This variable tracks changes in license text of the source
1618 code files.
1619 If the license text is changed, it will trigger a build
1620 failure, which gives the developer an opportunity to review any
1621 license change.</para>
1622 <para>
1623 This variable must be defined for all recipes (unless <filename>LICENSE</filename>
1624 is set to "CLOSED")</para>
1625 <para>For more information, see the
1626 <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
1627 Tracking License Changes</link> section</para>
1628 </glossdef>
1629 </glossentry>
1630
1631 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
1632 <glossdef>
1633 <para>
1634 The list of source licenses for the recipe.
1635 Follow these rules:
1636 <itemizedlist>
1637 <listitem><para>Do not use spaces within individual
1638 license names.</para></listitem>
1639 <listitem><para>Separate license names using
1640 | (pipe) when there is a choice between licenses.
1641 </para></listitem>
1642 <listitem><para>Separate license names using
1643 &amp; (ampersand) when multiple licenses exist
1644 that cover different parts of the source.
1645 </para></listitem>
1646 <listitem><para>You can use spaces between license
1647 names.</para></listitem>
1648 </itemizedlist>
1649 </para>
1650
1651 <para>
1652 Here are some examples:
1653 <literallayout class='monospaced'>
1654 LICENSE = "LGPLv2.1 | GPLv3"
1655 LICENSE = "MPL-1 &amp; LGPLv2.1"
1656 LICENSE = "GPLv2+"
1657 </literallayout>
1658 The first example is from the recipes for Qt, which the user
1659 may choose to distribute under either the LGPL version
1660 2.1 or GPL version 3.
1661 The second example is from Cairo where two licenses cover
1662 different parts of the source code.
1663 The final example is from <filename>sysstat</filename>,
1664 which presents a single license.
1665 </para>
1666 </glossdef>
1667 </glossentry>
1668
1669 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
1670 <glossdef>
1671 <para>Path to additional licenses used during the build.
1672 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
1673 to define the directory that holds common license text used during the build.
1674 The <filename>LICENSE_PATH</filename> variable allows you to extend that
1675 location to other areas that have additional licenses:
1676 <literallayout class='monospaced'>
1677 LICENSE_PATH += "/path/to/additional/common/licenses"
1678 </literallayout></para>
1679 </glossdef>
1680 </glossentry>
1681
1682 </glossdiv>
1683
1684 <glossdiv id='var-glossary-m'><title>M</title>
1685
1686 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
1687 <glossdef>
1688 <para>
1689 Specifies the target device for which the image is built.
1690 You define <filename>MACHINE</filename> in the
1691 <filename>local.conf</filename> file found in the
1692 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1693 By default, <filename>MACHINE</filename> is set to
1694 "qemux86", which is an x86-based architecture machine to
1695 be emulated using QEMU:
1696 <literallayout class='monospaced'>
1697 MACHINE ?= "qemux86"
1698 </literallayout>
1699 The variable corresponds to a machine configuration file of the
1700 same name, through which machine-specific configurations are set.
1701 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
1702 exists the corresponding <filename>qemux86.conf</filename> machine
1703 configuration file, which can be found in the
1704 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
1705 in <filename>meta/conf/machine</filename>.
1706 </para>
1707
1708 <para>
1709 The list of machines supported by the Yocto Project as
1710 shipped include the following:
1711 <literallayout class='monospaced'>
1712 MACHINE ?= "qemuarm"
1713 MACHINE ?= "qemumips"
1714 MACHINE ?= "qemuppc"
1715 MACHINE ?= "qemux86"
1716 MACHINE ?= "qemux86-64"
1717 MACHINE ?= "atom-pc"
1718 MACHINE ?= "beagleboard"
1719 MACHINE ?= "mpc8315e-rdb"
1720 MACHINE ?= "routerstationpro"
1721 </literallayout>
1722 The last four are Yocto Project reference hardware boards, which
1723 are provided in the <filename>meta-yocto-bsp</filename> layer.
1724 <note>Adding additional Board Support Package (BSP) layers
1725 to your configuration adds new possible settings for
1726 <filename>MACHINE</filename>.
1727 </note>
1728 </para>
1729 </glossdef>
1730 </glossentry>
1731
1732 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
1733 <glossdef>
1734 <para></para>
1735 <para>
1736 A list of required machine-specific packages to install as part of
1737 the image being built.
1738 The build process depends on these packages being present.
1739 Furthermore, because this is a "machine essential" variable, the list of
1740 packages are essential for the machine to boot.
1741 The impact of this variable affects images based on
1742 <filename>packagegroup-core-boot</filename>,
1743 including the <filename>core-image-minimal</filename> image.
1744 </para>
1745 <para>
1746 This variable is similar to the
1747 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
1748 variable with the exception that the image being built has a build
1749 dependency on the variable's list of packages.
1750 In other words, the image will not build if a file in this list is not found.
1751 </para>
1752 <para>
1753 As an example, suppose the machine for which you are building requires
1754 <filename>example-init</filename> to be run during boot to initialize the hardware.
1755 In this case, you would use the following in the machine's
1756 <filename>.conf</filename> configuration file:
1757 <literallayout class='monospaced'>
1758 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
1759 </literallayout>
1760 </para>
1761 </glossdef>
1762 </glossentry>
1763
1764 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
1765 <glossdef>
1766 <para></para>
1767 <para>
1768 A list of recommended machine-specific packages to install as part of
1769 the image being built.
1770 The build process does not depend on these packages being present.
1771 However, because this is a "machine essential" variable, the list of
1772 packages are essential for the machine to boot.
1773 The impact of this variable affects images based on
1774 <filename>packagegroup-core-boot</filename>,
1775 including the <filename>core-image-minimal</filename> image.
1776 </para>
1777 <para>
1778 This variable is similar to the
1779 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
1780 variable with the exception that the image being built does not have a build
1781 dependency on the variable's list of packages.
1782 In other words, the image will still build if a package in this list is not found.
1783 Typically, this variable is used to handle essential kernel modules, whose
1784 functionality may be selected to be built into the kernel rather than as a module,
1785 in which case a package will not be produced.
1786 </para>
1787 <para>
1788 Consider an example where you have a custom kernel where a specific touchscreen
1789 driver is required for the machine to be usable.
1790 However, the driver can be built as a module or
1791 into the kernel depending on the kernel configuration.
1792 If the driver is built as a module, you want it to be installed.
1793 But, when the driver is built into the kernel, you still want the
1794 build to succeed.
1795 This variable sets up a "recommends" relationship so that in the latter case,
1796 the build will not fail due to the missing package.
1797 To accomplish this, assuming the package for the module was called
1798 <filename>kernel-module-ab123</filename>, you would use the
1799 following in the machine's <filename>.conf</filename> configuration
1800 file:
1801 <literallayout class='monospaced'>
1802 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
1803 </literallayout>
1804 </para>
1805 <para>
1806 Some examples of these machine essentials are flash, screen, keyboard, mouse,
1807 or touchscreen drivers (depending on the machine).
1808 </para>
1809 </glossdef>
1810 </glossentry>
1811
1812 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
1813 <glossdef>
1814 <para>
1815 A list of machine-specific packages to install as part of the
1816 image being built that are not essential for the machine to boot.
1817 However, the build process for more fully-featured images
1818 depends on the packages being present.
1819 </para>
1820 <para>
1821 This variable affects all images based on
1822 <filename>packagegroup-base</filename>, which does not include the
1823 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
1824 images.
1825 </para>
1826 <para>
1827 The variable is similar to the
1828 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
1829 variable with the exception that the image being built has a build
1830 dependency on the variable's list of packages.
1831 In other words, the image will not build if a file in this list is not found.
1832 </para>
1833 <para>
1834 An example is a machine that has WiFi capability but is not essential
1835 For the machine to boot the image.
1836 However, if you are building a more fully-featured image, you want to enable
1837 the WiFi.
1838 The package containing the firmware for the WiFi hardware is always
1839 expected to exist, so it is acceptable for the build process to depend upon
1840 finding the package.
1841 In this case, assuming the package for the firmware was called
1842 <filename>wifidriver-firmware</filename>, you would use the following in the
1843 <filename>.conf</filename> file for the machine:
1844 <literallayout class='monospaced'>
1845 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
1846 </literallayout>
1847 </para>
1848 </glossdef>
1849 </glossentry>
1850
1851 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
1852 <glossdef>
1853 <para></para>
1854 <para>
1855 A list of machine-specific packages to install as part of the
1856 image being built that are not essential for booting the machine.
1857 The image being built has no build dependency on this list of packages.
1858 </para>
1859 <para>
1860 This variable affects only images based on
1861 <filename>packagegroup-base</filename>, which does not include the
1862 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
1863 images.
1864 </para>
1865 <para>
1866 This variable is similar to the
1867 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
1868 variable with the exception that the image being built does not have a build
1869 dependency on the variable's list of packages.
1870 In other words, the image will build if a file in this list is not found.
1871 </para>
1872 <para>
1873 An example is a machine that has WiFi capability but is not essential
1874 For the machine to boot the image.
1875 However, if you are building a more fully-featured image, you want to enable
1876 WiFi.
1877 In this case, the package containing the WiFi kernel module will not be produced
1878 if the WiFi driver is built into the kernel, in which case you still want the
1879 build to succeed instead of failing as a result of the package not being found.
1880 To accomplish this, assuming the package for the module was called
1881 <filename>kernel-module-examplewifi</filename>, you would use the
1882 following in the <filename>.conf</filename> file for the machine:
1883 <literallayout class='monospaced'>
1884 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
1885 </literallayout>
1886 </para>
1887 </glossdef>
1888 </glossentry>
1889
1890 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
1891 <glossdef>
1892 <para>Specifies the list of hardware features the
1893 <link linkend='var-MACHINE'>MACHINE</link> supports.
1894 For example, including the "bluetooth" feature causes the
1895 <filename>bluez</filename> bluetooth daemon to be built and
1896 added to the image.
1897 It also causes the <filename>connman</filename> recipe
1898 to look at <filename>MACHINE_FEATURES</filename> and when it
1899 finds "bluetooth" there it enables the bluetooth
1900 support in ConnMan.
1901 </para>
1902
1903 <para>
1904 For a list of features supported by the Yocto Project as shipped,
1905 see the "<link linkend='ref-features-machine'>Machine</link>" section.
1906 </para>
1907 </glossdef>
1908 </glossentry>
1909
1910 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
1911 <glossdef>
1912 <para>Features to be added to
1913 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
1914 if not also present in
1915 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
1916 </para>
1917
1918 <para>
1919 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
1920 It is not intended to be user-configurable.
1921 It is best to just reference the variable to see which machine features are
1922 being backfilled for all machine configurations.
1923 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1924 more information.
1925 </para>
1926 </glossdef>
1927 </glossentry>
1928
1929 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
1930 <glossdef>
1931 <para>Features from
1932 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
1933 that should not be backfilled (i.e. added to
1934 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
1935 during the build.
1936 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1937 more information.
1938 </para>
1939 </glossdef>
1940 </glossentry>
1941
1942 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
1943 <glossdef>
1944 <para>The email address of the distribution maintainer.</para>
1945 </glossdef>
1946 </glossentry>
1947
1948 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
1949 <glossdef>
1950 <para>
1951 Specifies a prefix has been added to
1952 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
1953 of a recipe or package, such as a multilib version.
1954 The variable is used in places where the prefix needs to be
1955 added to or removed from a the name (e.g. the
1956 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
1957 <filename>MLPREFIX</filename> gets set when a prefix has been
1958 added to <filename>PN</filename>.
1959 </para>
1960 </glossdef>
1961 </glossentry>
1962
1963 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
1964 <glossdef>
1965 <para>
1966 Separates files for different machines such that you can build
1967 for multiple target machines using the same output directories.
1968 See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable
1969 for an example.
1970 </para>
1971 </glossdef>
1972 </glossentry>
1973
1974 </glossdiv>
1975
1976<!-- <glossdiv id='var-glossary-n'><title>N</title>-->
1977<!-- </glossdiv>-->
1978
1979 <glossdiv id='var-glossary-o'><title>O</title>
1980
1981 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
1982 <glossdef>
1983 <para>
1984 Controls how the OpenEmbedded build system spawns
1985 interactive terminals on the host development system
1986 (e.g. using the BitBake command with the
1987 <filename>-c devshell</filename> command-line option).
1988 For more information, see the
1989 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
1990 in the Yocto Project Development Manual.
1991 </para>
1992
1993 <para>
1994 You can use the following values for the
1995 <filename>OE_TERMINAL</filename> variable:
1996 <literallayout class='monospaced'>
1997 auto
1998 gnome
1999 xfce
2000 rxvt
2001 screen
2002 konsole
2003 none
2004 </literallayout>
2005 <note>Konsole support only works for KDE 3.x.
2006 Also, "auto" is the default behavior for
2007 <filename>OE_TERMINAL</filename></note>
2008 </para>
2009 </glossdef>
2010 </glossentry>
2011 </glossdiv>
2012
2013 <glossdiv id='var-glossary-p'><title>P</title>
2014
2015 <glossentry id='var-P'><glossterm>P</glossterm>
2016 <glossdef>
2017 <para>The recipe name and version.
2018 <filename>P</filename> is comprised of the following:
2019 <literallayout class='monospaced'>
2020 ${PN}-${PV}
2021 </literallayout></para>
2022 </glossdef>
2023 </glossentry>
2024
2025 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
2026 <glossdef>
2027 <para>The architecture of the resulting package or packages.</para>
2028 </glossdef>
2029 </glossentry>
2030
2031 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
2032 <glossdef>
2033 <para>Enables easily adding packages to
2034 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
2035 before <filename>${PN}</filename> so that the packages can pick
2036 up files that would normally be included in the default package.</para>
2037 </glossdef>
2038 </glossentry>
2039
2040 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
2041 <glossdef>
2042 <para>This variable, which is set in the <filename>local.conf</filename> configuration
2043 file found in the <filename>conf</filename> folder of the
2044 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
2045 specifies the package manager to use when packaging data.
2046 You can provide one or more arguments for the variable with the first
2047 argument being the package manager used to create images:
2048 <literallayout class='monospaced'>
2049 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
2050 </literallayout>
2051 For information on build performance effects as a result of the
2052 package manager use, see
2053 <link linkend='ref-classes-package'>Packaging - <filename>package*.bbclass</filename></link>
2054 in this manual.
2055 </para>
2056 </glossdef>
2057 </glossentry>
2058
2059 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
2060 <glossdef>
2061 <para>Specifies the list of architectures compatible with the device CPU.
2062 This variable is useful when you build for several different devices that use
2063 miscellaneous processors such as XScale and ARM926-EJS).</para>
2064 </glossdef>
2065 </glossentry>
2066
2067 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
2068 <glossdef>
2069 <para>
2070 This variable provides a means of enabling or disabling
2071 features of a recipe on a per-recipe basis.
2072 The <filename>PACKAGECONFIG</filename>
2073 variable itself specifies a space-separated list of the
2074 features to enable.
2075 The features themselves are specified as flags on the
2076 <filename>PACKAGECONFIG</filename> variable.
2077 You can provide up to four arguments, which are separated by
2078 commas, to determine the behavior of each feature
2079 when it is enabled or disabled.
2080 You can omit any argument you like but must retain the
2081 separating commas.
2082 The arguments specify the following:
2083 <orderedlist>
2084 <listitem><para>Extra arguments
2085 that should be added to the configure script argument list
2086 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>)
2087 if the feature is enabled.</para></listitem>
2088 <listitem><para>Extra arguments
2089 that should be added to <filename>EXTRA_OECONF</filename>
2090 if the feature is disabled.
2091 </para></listitem>
2092 <listitem><para>Additional build dependencies
2093 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
2094 that should be added if the feature is enabled.
2095 </para></listitem>
2096 <listitem><para>Additional runtime dependencies
2097 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
2098 that should be added if the feature is enabled.
2099 </para></listitem>
2100 </orderedlist>
2101 </para>
2102
2103 <para>
2104 Consider the following example taken from the
2105 <filename>librsvg</filename> recipe.
2106 In this example the feature is <filename>croco</filename>, which
2107 has three arguments that determine the feature's behavior.
2108 <literallayout class='monospaced'>
2109 PACKAGECONFIG ??= "croco"
2110 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
2111 </literallayout>
2112 The <filename>--with-croco</filename> and
2113 <filename>libcroco</filename> arguments apply only if
2114 the feature is enabled.
2115 In this case, <filename>--with-croco</filename> is
2116 added to the configure script argument list and
2117 <filename>libcroco</filename> is added to
2118 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
2119 On the other hand, if the feature is disabled say through
2120 a <filename>.bbappend</filename> file in another layer, then
2121 the second argument <filename>--without-croco</filename> is
2122 added to the configure script rather than
2123 <filename>--with-croco</filename>.
2124 </para>
2125 </glossdef>
2126 </glossentry>
2127
2128 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
2129 <glossdef>
2130 <para>The list of packages to be created from the recipe.
2131 The default value is the following:
2132 <literallayout class='monospaced'>
2133 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
2134 </literallayout></para>
2135 </glossdef>
2136 </glossentry>
2137
2138 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
2139 <glossdef>
2140 <para>
2141 A promise that your recipe satisfies runtime dependencies
2142 for optional modules that are found in other recipes.
2143 <filename>PACKAGES_DYNAMIC</filename>
2144 does not actually satisfy the dependencies, it only states that
2145 they should be satisfied.
2146 For example, if a hard, runtime dependency
2147 (<filename>RDEPENDS</filename>) of another package is satisfied
2148 at build time through the <filename>PACKAGES_DYNAMIC</filename>
2149 variable, but a package with the module name is never actually
2150 produced, then the other package will be broken.
2151 Thus, if you attempt to include that package in an image,
2152 you will get a dependency failure from the packaging system
2153 during <filename>do_rootfs</filename>.
2154 Typically, if there is a chance that such a situation can
2155 occur and the package that is not created is valid
2156 without the dependency being satisfied, then you should use
2157 <filename>RRECOMMENDS</filename> (a soft runtime dependency)
2158 instead of <filename>RDEPENDS</filename>.
2159 </para>
2160
2161 <para>
2162 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
2163 variable when you are splitting packages, see the
2164 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
2165 in the Yocto Project Development Manual.
2166 </para>
2167 </glossdef>
2168 </glossentry>
2169
2170 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
2171 <glossdef>
2172 <para>Specifies extra options that are passed to the <filename>make</filename> command during the
2173 compile tasks.
2174 This variable is usually in the form <filename>-j 4</filename>, where the number
2175 represents the maximum number of parallel threads make can run.
2176 If you development host supports multiple cores a good rule of thumb is to set
2177 this variable to twice the number of cores on the host.</para>
2178 </glossdef>
2179 </glossentry>
2180
2181 <glossentry id='var-PF'><glossterm>PF</glossterm>
2182 <glossdef>
2183 <para>Specifies the recipe or package name and includes all version and revision
2184 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
2185 <filename>bash-4.2-r1/</filename>).
2186 This variable is comprised of the following:
2187 <literallayout class='monospaced'>
2188 ${PN}-${EXTENDPE}${PV}-${PR}
2189 </literallayout></para>
2190 </glossdef>
2191 </glossentry>
2192
2193 <glossentry id='var-PN'><glossterm>PN</glossterm>
2194 <glossdef>
2195 <para>This variable can have two separate functions depending on the context: a recipe
2196 name or a resulting package name.</para>
2197 <para><filename>PN</filename> refers to a recipe name in the context of a file used
2198 by the OpenEmbedded build system as input to create a package.
2199 The name is normally extracted from the recipe file name.
2200 For example, if the recipe is named
2201 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
2202 will be "expat".</para>
2203 <para>
2204 The variable refers to a package name in the context of a file created or produced by the
2205 OpenEmbedded build system.</para>
2206 <para>If applicable, the <filename>PN</filename> variable also contains any special
2207 suffix or prefix.
2208 For example, using <filename>bash</filename> to build packages for the native
2209 machine, <filename>PN</filename> is <filename>bash-native</filename>.
2210 Using <filename>bash</filename> to build packages for the target and for Multilib,
2211 <filename>PN</filename> would be <filename>bash</filename> and
2212 <filename>lib64-bash</filename>, respectively.
2213 </para>
2214 </glossdef>
2215 </glossentry>
2216
2217 <glossentry id='var-PR'><glossterm>PR</glossterm>
2218 <glossdef>
2219 <para>The revision of the recipe.
2220 The default value for this variable is "r0".
2221 </para>
2222 </glossdef>
2223 </glossentry>
2224
2225 <glossentry id='var-PRINC'><glossterm>PRINC</glossterm>
2226 <glossdef>
2227 <para>Causes the <filename>PR</filename> variable of
2228 <filename>.bbappend</filename> files to dynamically increment.
2229 This increment minimizes the impact of layer ordering.</para>
2230 <para>In order to ensure multiple <filename>.bbappend</filename> files can co-exist,
2231 <filename>PRINC</filename> should be self referencing.
2232 This variable defaults to 0.</para>
2233 <para>Following is an example that increments <filename>PR</filename> by two:
2234 <literallayout class='monospaced'>
2235 PRINC := "${@int(PRINC) + 2}"
2236 </literallayout>
2237 It is adviseable not to use strings such as ".= '.1'" with the variable because
2238 this usage is very sensitive to layer ordering.
2239 Explicit assignments should be avoided as they cannot adequately represent multiple
2240 <filename>.bbappend</filename> files.</para>
2241 </glossdef>
2242 </glossentry>
2243
2244 <glossentry id='var-PV'><glossterm>PV</glossterm>
2245 <glossdef>
2246 <para>The version of the recipe.
2247 The version is normally extracted from the recipe filename.
2248 For example, if the recipe is named
2249 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename>
2250 will be "2.0.1".
2251 <filename>PV</filename> is generally not overridden within
2252 a recipe unless it is building an unstable (i.e. development) version from a source code repository
2253 (e.g. Git or Subversion).
2254 </para>
2255 </glossdef>
2256 </glossentry>
2257
2258 <glossentry id='var-PE'><glossterm>PE</glossterm>
2259 <glossdef>
2260 <para>
2261 the epoch of the recipe.
2262 The default value is "0".
2263 The field is used to make upgrades possible when the versioning scheme changes in
2264 some backwards incompatible way.
2265 </para>
2266 </glossdef>
2267 </glossentry>
2268
2269 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
2270 <glossdef>
2271 <para>
2272 If multiple recipes provide an item, this variable
2273 determines which recipe should be given preference.
2274 The variable must always be suffixed with the name of the
2275 provided item, and should be set to the
2276 <filename>PN</filename> of the recipe
2277 to which you want to give precedence.
2278 Here is an example:
2279 <literallayout class='monospaced'>
2280 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
2281 </literallayout>
2282 </para>
2283 </glossdef>
2284 </glossentry>
2285
2286 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
2287 <glossdef>
2288 <para>
2289 If there are multiple versions of recipes available, this
2290 variable determines which recipe should be given preference.
2291 The variable must always be suffixed with the <filename>PN</filename>
2292 for which to select, and should be set to the
2293 <filename>PV</filename> to which you want to give precedence.
2294 You can use the "<filename>%</filename>" character as a wildcard
2295 to match any number of characters, which can be useful when
2296 specifying versions that contain long revision number that could
2297 potentially change.
2298 Here are two examples:
2299 <literallayout class='monospaced'>
2300 PREFERRED_VERSION_python = "2.6.6"
2301 PREFERRED_VERSION_linux-yocto = "3.0+git%"
2302 </literallayout>
2303 </para>
2304 </glossdef>
2305 </glossentry>
2306
2307 </glossdiv>
2308
2309<!-- <glossdiv id='var-glossary-q'><title>Q</title>-->
2310<!-- </glossdiv>-->
2311
2312 <glossdiv id='var-glossary-r'><title>R</title>
2313
2314 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
2315 <glossdef>
2316 <para>The list of packages that conflict with a package.
2317 Note that the package will not be installed if the conflicting packages are not
2318 first removed.</para>
2319 <para>
2320 Like all package-controlling variables, you must always use them in
2321 conjunction with a package name override.
2322 Here is an example:
2323 <literallayout class='monospaced'>
2324 RCONFLICTS_${PN} = "another-conflicting-package-name"
2325 </literallayout>
2326 </para>
2327 </glossdef>
2328 </glossentry>
2329
2330 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
2331 <glossdef>
2332 <para>
2333 Lists a package's run-time dependencies (i.e. other packages)
2334 that must be installed for the package to be built.
2335 In other words, in order for the package to be built and
2336 run correctly, it depends on the listed packages.
2337 If a package in this list cannot be found, it is probable
2338 that a dependency error would occur before the build.
2339 </para>
2340
2341 <para>
2342 The names of the variables you list with
2343 <filename>RDEPENDS</filename> must be the names of other
2344 packages as listed in the
2345 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
2346 variable.
2347 You should not list recipe names (<filename>PN</filename>).
2348 </para>
2349
2350 <para>
2351 Because the <filename>RDEPENDS</filename> variable applies
2352 to packages being built, you should
2353 always attach a package name to the variable to specify the
2354 particular run-time package that has the dependency.
2355 For example, suppose you are building a development package
2356 that depends on the <filename>perl</filename> package.
2357 In this case, you would use the following
2358 <filename>RDEPENDS</filename> statement:
2359 <literallayout class='monospaced'>
2360 RDEPENDS_${PN}-dev += "perl"
2361 </literallayout>
2362 In the example, the package name
2363 (<filename>${PN}-dev</filename>) must appear as it would
2364 in the
2365 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
2366 namespace before any renaming of the output package by
2367 classes like <filename>debian.bbclass</filename>.
2368 </para>
2369
2370 <para>
2371 In many cases you do not need to explicitly add dependencies
2372 to <filename>RDEPENDS</filename> since some automatic
2373 handling occurs:
2374 <itemizedlist>
2375 <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If
2376 a run-time package contains a shared library
2377 (<filename>.so</filename>), the build
2378 processes the library in order to determine other
2379 libraries to which it is dynamically linked.
2380 The build process adds these libraries to
2381 <filename>RDEPENDS</filename> when creating the run-time
2382 package.</para></listitem>
2383 <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If
2384 the package ships a <filename>pkg-config</filename>
2385 information file, the build process uses this file
2386 to add items to the <filename>RDEPENDS</filename>
2387 variable to create the run-time packages.
2388 </para></listitem>
2389 </itemizedlist>
2390 </para>
2391 </glossdef>
2392 </glossentry>
2393
2394 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
2395 <glossdef>
2396 <para>
2397 A list of packages that extend the usability of a package being
2398 built.
2399 The package being built does not depend on this list of packages in
2400 order to successfully build, but needs them for the extended usability.
2401 To specify runtime dependencies for packages, see the
2402 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variable.
2403 </para>
2404 <para>
2405 The OpenEmbedded build process automatically installs the list of packages
2406 as part of the built package.
2407 However, you can remove them later if you want.
2408 If, during the build, a package from the list cannot be found, the build
2409 process continues without an error.
2410 </para>
2411 <para>
2412 Because the <filename>RRECOMMENDS</filename> variable applies to packages
2413 being built, you should
2414 always attach an override to the variable to specify the particular package
2415 whose usability is being extended.
2416 For example, suppose you are building a development package that is extended
2417 to support wireless functionality.
2418 In this case, you would use the following:
2419 <literallayout class='monospaced'>
2420 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
2421 </literallayout>
2422 In the example, the package name (<filename>${PN}-dev</filename>) must
2423 appear as it would in the
2424 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> namespace before any
2425 renaming of the output package by classes like <filename>debian.bbclass</filename>.
2426 </para>
2427 </glossdef>
2428 </glossentry>
2429
2430 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
2431 <glossdef>
2432 <para>The list of packages that are replaced with this package.</para>
2433 </glossdef>
2434 </glossentry>
2435
2436 </glossdiv>
2437
2438 <glossdiv id='var-glossary-s'><title>S</title>
2439
2440 <glossentry id='var-S'><glossterm>S</glossterm>
2441 <glossdef>
2442 <para>
2443 The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
2444 where unpacked package source code resides.
2445 This location is within the working directory
2446 (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>), which
2447 is not static.
2448 The unpacked source location depends on the package name
2449 (<filename><link linkend='var-PN'>PN</link></filename>) and
2450 package version (<filename><link linkend='var-PV'>PV</link></filename>) as
2451 follows:
2452 <literallayout class='monospaced'>
2453 ${WORKDIR}/${PN}/${PV}
2454 </literallayout>
2455 As an example, assume a
2456 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level
2457 folder named <filename>poky</filename>
2458 and a default <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
2459 at <filename>poky/build</filename>.
2460 In this case, the working directory the build system uses to build
2461 the <filename>db</filename> package is the following:
2462 <literallayout class='monospaced'>
2463 ~/poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
2464 </literallayout>
2465 </para>
2466 </glossdef>
2467 </glossentry>
2468
2469 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
2470 <glossdef>
2471 <para>Equivalent to
2472 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
2473 However, this variable applies to the SDK generated from an image using
2474 <filename>bitbake -c populate_sdk imagename</filename>).
2475 </para>
2476 </glossdef>
2477 </glossentry>
2478
2479 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
2480 <glossdef>
2481 <para>The section in which packages should be categorized.
2482 Package management utilities can make use of this variable.</para>
2483 </glossdef>
2484 </glossentry>
2485
2486 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
2487 <glossdef>
2488 <para>
2489 The variable takes the value of
2490 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
2491 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
2492 In this case the value of
2493 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
2494 </para>
2495 </glossdef>
2496 </glossentry>
2497
2498
2499 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
2500 <glossdef>
2501 <para>The speed and device for the serial port used to attach the serial console.
2502 This variable is given to the kernel as the "console"
2503 parameter and after booting occurs <filename>getty</filename> is started on that port
2504 so remote login is possible.</para>
2505 </glossdef>
2506 </glossentry>
2507
2508 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
2509 <glossdef>
2510 <para>
2511 Specifies the endian byte order of the target system.
2512 The value should be either "le" for little-endian or "be" for big-endian.
2513 </para>
2514 </glossdef>
2515 </glossentry>
2516
2517 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
2518 <glossdef>
2519 <para>
2520 Specifies the number of bits for the target system CPU.
2521 The value should be either "32" or "64".
2522 </para>
2523 </glossdef>
2524 </glossentry>
2525
2526 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
2527 <glossdef>
2528 <para>
2529 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
2530 OpenEmbedded build system to create variants of recipes or packages.
2531 The list specifies the prefixes to strip off during certain circumstances
2532 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
2533 </para>
2534 </glossdef>
2535 </glossentry>
2536
2537 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
2538 <glossdef>
2539 <para>The list of source files - local or remote.
2540 This variable tells the OpenEmbedded build system which bits to pull
2541 in for the build and how to pull them in.
2542 For example, if the recipe only needs to fetch a tarball from the
2543 internet, the recipe uses a single <filename>SRC_URI</filename> entry.
2544 On the other hand, if the recipe needs to fetch a tarball, apply
2545 two patches, and include a custom file, the recipe would include four
2546 instances of the variable.</para>
2547 <para>The following list explains the available URI protocols:
2548 <itemizedlist>
2549 <listitem><para><emphasis><filename>file://</filename> -</emphasis> Fetches files, which is usually
2550 a file shipped with the metadata, from the local machine.
2551 The path is relative to the
2552 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
2553 variable.
2554 Thus, the build system searches, in order, from the following directories,
2555 which are assumed to be a subdirectories of the directory in which the
2556 recipe file resides:
2557 <itemizedlist>
2558 <listitem><para><emphasis><filename>${PN}</filename> -</emphasis> The recipe name
2559 with any special suffix or prefix, if applicable.
2560 For example, using <filename>bash</filename> to build for the native
2561 machine, <filename>PN</filename> is <filename>bash-native</filename>.
2562 Using <filename>bash</filename> to build for the target and for Multilib,
2563 <filename>PN</filename> would be <filename>bash</filename> and
2564 <filename>lib64-bash</filename>, respectively.
2565 </para></listitem>
2566 <listitem><para><emphasis><filename>${PF}</filename> - </emphasis>
2567 <filename>${PN}-${EXTENDPE}${PV}-${PR}</filename>.
2568 The recipe name including all version and revision numbers
2569 (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
2570 <filename>bash-4.2-r1/</filename>).</para></listitem>
2571 <listitem><para><emphasis><filename>${P}</filename> -</emphasis>
2572 <filename>${PN}-${PV}</filename>.
2573 The recipe name and version (i.e. <filename>bash-4.2</filename>).
2574 </para></listitem>
2575 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis> The
2576 base recipe name without any special suffix or version numbers.
2577 </para></listitem>
2578 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
2579 <filename>${BPN}-${PV}</filename>.
2580 The base recipe name and version but without any special
2581 package name suffix.</para></listitem>
2582 <listitem><para><emphasis>Files -</emphasis> Files beneath the directory in which the recipe
2583 resides.</para></listitem>
2584 <listitem><para><emphasis>Directory -</emphasis> The directory itself in which the recipe
2585 resides.</para></listitem>
2586 </itemizedlist></para></listitem>
2587 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
2588 Bazaar revision control repository.</para></listitem>
2589 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
2590 Git revision control repository.</para></listitem>
2591 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
2592 an OSC (OpenSuse Build service) revision control repository.</para></listitem>
2593 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
2594 a repo (Git) repository.</para></listitem>
2595 <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from
2596 an SVK revision control repository.</para></listitem>
2597 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
2598 the Internet using <filename>http</filename>.</para></listitem>
2599 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
2600 from the Internet using <filename>https</filename>.</para></listitem>
2601 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
2602 from the Internet using <filename>ftp</filename>.</para></listitem>
2603 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
2604 a CVS revision control repository.</para></listitem>
2605 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
2606 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
2607 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
2608 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
2609 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
2610 a secure shell.</para></listitem>
2611 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
2612 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
2613 </itemizedlist>
2614 </para>
2615 <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
2616 Here are standard options:
2617 <itemizedlist>
2618 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
2619 the patch or not.
2620 The default action is to apply the patch.</para></listitem>
2621 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
2622 striplevel to use when applying the patch.
2623 The default level is 1.</para></listitem>
2624 </itemizedlist>
2625 </para>
2626 <para>Here are options specific to recipes building code from a revision control system:
2627 <itemizedlist>
2628 <listitem><para><emphasis><filename>mindate</filename> -</emphasis> Only applies
2629 the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
2630 is equal to or greater than <filename>mindate</filename>.</para></listitem>
2631 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis> Only applies
2632 the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
2633 is not later than <filename>mindate</filename>.</para></listitem>
2634 <listitem><para><emphasis><filename>minrev</filename> -</emphasis> Only applies
2635 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2636 is equal to or greater than <filename>minrev</filename>.</para></listitem>
2637 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis> Only applies
2638 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2639 is not later than <filename>maxrev</filename>.</para></listitem>
2640 <listitem><para><emphasis><filename>rev</filename> -</emphasis> Only applies the
2641 patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2642 is equal to <filename>rev</filename>.</para></listitem>
2643 <listitem><para><emphasis><filename>notrev</filename> -</emphasis> Only applies
2644 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2645 is not equal to <filename>rev</filename>.</para></listitem>
2646 </itemizedlist>
2647 </para>
2648 <para>Here are some additional options worth mentioning:
2649 <itemizedlist>
2650 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
2651 whether or not to unpack the file if it is an archive.
2652 The default action is to upack the file.</para></listitem>
2653 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
2654 (or extracts its contents) into the specified
2655 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
2656 This option is useful for unusual tarballs or other archives that
2657 don't have their files already in a subdirectory within the archive.
2658 </para></listitem>
2659 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
2660 name to be used for association with <filename>SRC_URI</filename> checksums
2661 when you have more than one file specified in <filename>SRC_URI</filename>.
2662 </para></listitem>
2663 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
2664 the filename used when storing the downloaded file.</para></listitem>
2665 </itemizedlist>
2666 </para>
2667 </glossdef>
2668 </glossentry>
2669
2670 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
2671 <glossdef>
2672 <para></para>
2673 <para>
2674 By default, the OpenEmbedded build system automatically detects whether
2675 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
2676 contains files that are machine-specific.
2677 If so, the build system automatically changes
2678 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
2679 Setting this variable to "0" disables this behavior.
2680 </para>
2681 </glossdef>
2682 </glossentry>
2683
2684 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
2685 <glossdef>
2686 <para>
2687 The date of the source code used to build the package.
2688 This variable applies only if the source was fetched from a Source Code Manager (SCM).
2689 </para>
2690 </glossdef>
2691 </glossentry>
2692
2693 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
2694 <glossdef>
2695 <para>
2696 The revision of the source code used to build the package.
2697 This variable applies to Subversion, Git, Mercurial and Bazaar
2698 only.
2699 Note that if you wish to build a fixed revision and you wish
2700 to avoid performing a query on the remote repository every time
2701 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
2702 full revision identifier and not just a tag.
2703 </para>
2704 </glossdef>
2705 </glossentry>
2706
2707 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
2708 <glossdef>
2709 <para>The directory for the shared state.</para>
2710 </glossdef>
2711 </glossentry>
2712
2713 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
2714 <glossdef>
2715 <para>
2716 Configures the OpenEmbedded build system to search other
2717 mirror locations for prebuilt cache data objects before
2718 building out the data.
2719 This variable works like fetcher
2720 <filename>MIRRORS</filename>/<filename>PREMIRRORS</filename>
2721 and points to the cache locations to check for the shared
2722 objects.
2723 </para>
2724
2725 <para>
2726 You can specify a filesystem directory or a remote URL such
2727 as HTTP or FTP.
2728 The locations you specify need to contain the shared state
2729 cache (sstate-cache) results from previous builds.
2730 The sstate-cache you point to can also be from builds on
2731 other machines.
2732 </para>
2733
2734 <para>
2735 If a mirror uses the same structure as
2736 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
2737 you need to add
2738 "PATH" at the end as shown in the examples below.
2739 The build system substitues the correct path within the
2740 directory structure.
2741 <literallayout class='monospaced'>
2742 SSTATE_MIRRORS ?= "\
2743 file://.* http://someserver.tld/share/sstate/PATH \n \
2744 file://.* file:///some/local/dir/sstate/PATH"
2745 </literallayout>
2746 </para>
2747 </glossdef>
2748 </glossentry>
2749
2750 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
2751 <glossdef>
2752 <para>
2753 The directory with kernel headers that are required to build out-of-tree
2754 modules.
2755 </para>
2756 </glossdef>
2757 </glossentry>
2758
2759 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
2760 <glossdef>
2761 <para>
2762 Specifies the base path used to create recipe stamp files.
2763 The path to an actual stamp file is constructed by evaluating this
2764 string and then appending additional information.
2765 Currently, the default assignment for <filename>STAMP</filename>
2766 as set in the <filename>meta/conf/bitbake.conf</filename> file
2767 is:
2768 <literallayout class='monospaced'>
2769 STAMP = "${TMPDIR}/stamps/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
2770 </literallayout>
2771 See <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
2772 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
2773 <link linkend='var-PN'><filename>PN</filename></link>,
2774 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
2775 <link linkend='var-PV'><filename>PV</filename></link>, and
2776 <link linkend='var-PR'><filename>PR</filename></link> for related variable
2777 information.
2778 </para>
2779 </glossdef>
2780 </glossentry>
2781
2782 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
2783 <glossdef>
2784 <para>The short (72 characters or less) summary of the binary package for packaging
2785 systems such as <filename>opkg</filename>, <filename>rpm</filename> or
2786 <filename>dpkg</filename>.
2787 By default, <filename>SUMMARY</filename> is used to define
2788 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
2789 variable if <filename>DESCRIPTION</filename> is not set
2790 in the recipe.
2791 </para>
2792 </glossdef>
2793 </glossentry>
2794
2795 </glossdiv>
2796
2797 <glossdiv id='var-glossary-t'><title>T</title>
2798
2799 <glossentry id='var-T'><glossterm>T</glossterm>
2800 <glossdef>
2801 <para>This variable points to a directory were Bitbake places temporary
2802 files when building a particular package.
2803 It is typically set as follows:
2804 <literallayout class='monospaced'>
2805 T = ${WORKDIR}/temp
2806 </literallayout>
2807 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
2808 is the directory into which Bitbake unpacks and builds the package.
2809 The default <filename>bitbake.conf</filename> file sets this variable.</para>
2810 <para>The <filename>T</filename> variable is not to be confused with
2811 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
2812 which points to the root of the directory tree where Bitbake
2813 places the output of an entire build.
2814 </para>
2815 </glossdef>
2816 </glossentry>
2817
2818 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
2819 <glossdef>
2820 <para>The architecture of the device being built.
2821 While a number of values are possible, the OpenEmbedded build system primarily supports
2822 <filename>arm</filename> and <filename>i586</filename>.</para>
2823 </glossdef>
2824 </glossentry>
2825
2826 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
2827 <glossdef>
2828 <para>
2829 Flags passed to the C compiler for the target system.
2830 This variable evaluates to the same as
2831 <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>.
2832 </para>
2833 </glossdef>
2834 </glossentry>
2835
2836
2837 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
2838 <glossdef>
2839 <para>Specifies the method for handling FPU code.
2840 For FPU-less targets, which include most ARM CPUs, the variable must be
2841 set to "soft".
2842 If not, the kernel emulation gets used, which results in a performance penalty.</para>
2843 </glossdef>
2844 </glossentry>
2845
2846 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
2847 <glossdef>
2848 <para>Specifies the target's operating system.
2849 The variable can be set to "linux" for <filename>eglibc</filename>-based systems and
2850 to "linux-uclibc" for <filename>uclibc</filename>.
2851 For ARM/EABI targets, there are also "linux-gnueabi" and
2852 "linux-uclibc-gnueabi" values possible.</para>
2853 </glossdef>
2854 </glossentry>
2855
2856 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
2857 <glossdef>
2858 <para>
2859 Specifies which variant of the GNU standard C library (<filename>libc</filename>)
2860 to use during the build process.
2861 This variable replaces <filename>POKYLIBC</filename>, which is no longer
2862 supported.
2863 </para>
2864 <para>
2865 You can select <filename>eglibc</filename> or <filename>uclibc</filename>.
2866 <note>
2867 This release of the Yocto Project does not support the
2868 <filename>glibc</filename> implementation of <filename>libc</filename>.
2869 </note>
2870 </para>
2871 </glossdef>
2872 </glossentry>
2873
2874 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
2875 <glossdef>
2876 <para>
2877 The toolchain selector.
2878 This variable replaces <filename>POKYMODE</filename>, which is no longer
2879 supported.
2880 </para>
2881 <para>
2882 The <filename>TCMODE</filename> variable selects the external toolchain
2883 built using the OpenEmbedded build system or a few supported combinations of
2884 the upstream GCC or CodeSourcery Labs toolchain.
2885 The variable identifies the <filename>tcmode-*</filename> files used in
2886 the <filename>meta/conf/distro/include</filename> directory, which is found in the
2887 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2888 </para>
2889 <para>
2890 By default, <filename>TCMODE</filename> is set to "default", which
2891 chooses the <filename>tcmode-default.inc</filename> file.
2892 The variable is similar to
2893 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, which controls
2894 the variant of the GNU standard C library (<filename>libc</filename>)
2895 used during the build process: <filename>eglibc</filename> or <filename>uclibc</filename>.
2896 </para>
2897 </glossdef>
2898 </glossentry>
2899
2900 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
2901 <glossdef>
2902 <para>
2903 This variable is the temporary directory the OpenEmbedded build system
2904 uses when it does its work building images.
2905 By default, the <filename>TMPDIR</filename> variable is named
2906 <filename>tmp</filename> within the
2907 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2908 </para>
2909
2910 <para>
2911 If you want to establish this directory in a location other than the
2912 default, you can uncomment the following statement in the
2913 <filename>conf/local.conf</filename> file in the
2914 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
2915 <literallayout class='monospaced'>
2916 #TMPDIR = "${TOPDIR}/tmp"
2917 </literallayout>
2918 </para>
2919 </glossdef>
2920 </glossentry>
2921
2922 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
2923 <glossdef>
2924 <para>
2925 This variable is the
2926 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2927 BitBake automatically sets this variable.
2928 The OpenEmbedded build system uses the Build Directory when building images.
2929 </para>
2930 </glossdef>
2931 </glossentry>
2932
2933 </glossdiv>
2934
2935<!-- <glossdiv id='var-glossary-u'><title>U</title>-->
2936<!-- </glossdiv>-->
2937
2938<!-- <glossdiv id='var-glossary-v'><title>V</title>-->
2939<!-- </glossdiv>-->
2940
2941 <glossdiv id='var-glossary-w'><title>W</title>
2942
2943 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
2944 <glossdef>
2945 <para>
2946 The pathname of the working directory in which the OpenEmbedded build system
2947 builds a recipe.
2948 This directory is located within the
2949 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes
2950 as different packages are built.
2951 </para>
2952
2953 <para>
2954 The actual <filename>WORKDIR</filename> directory depends on several things:
2955 <itemizedlist>
2956 <listitem>The temporary directory - <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link></listitem>
2957 <listitem>The package architecture - <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link></listitem>
2958 <listitem>The target machine - <link linkend='var-MACHINE'><filename>MACHINE</filename></link></listitem>
2959 <listitem>The target operating system - <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link></listitem>
2960 <listitem>The recipe name - <link linkend='var-PN'><filename>PN</filename></link></listitem>
2961 <listitem>The recipe version - <link linkend='var-PV'><filename>PV</filename></link></listitem>
2962 <listitem>The recipe revision - <link linkend='var-PR'><filename>PR</filename></link></listitem>
2963 </itemizedlist>
2964 </para>
2965
2966 <para>
2967 For packages that are not dependent on a particular machine,
2968 <filename>WORKDIR</filename> is defined as follows:
2969 <literallayout class='monospaced'>
2970 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
2971 </literallayout>
2972 As an example, assume a
2973 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level
2974 folder name <filename>poky</filename> and a default
2975 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
2976 at <filename>poky/build</filename>.
2977 In this case, the working directory the build system uses to build
2978 the <filename>v86d</filename> package is the following:
2979 <literallayout class='monospaced'>
2980 ~/poky/build/tmp/work/qemux86-poky-linux/v86d/01.9-r0
2981 </literallayout>
2982 </para>
2983
2984 <para>
2985 For packages that are dependent on a particular machine, <filename>WORKDIR</filename>
2986 is defined slightly different:
2987 <literallayout class='monospaced'>
2988 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
2989 </literallayout>
2990 As an example, again assume a Source Directory top-level folder
2991 named <filename>poky</filename> and a default Build Directory
2992 at <filename>poky/build</filename>.
2993 In this case, the working directory the build system uses to build
2994 the <filename>acl</filename> recipe, which is being built for a
2995 MIPS-based device, is the following:
2996 <literallayout class='monospaced'>
2997 ~/poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2
2998 </literallayout>
2999 </para>
3000 </glossdef>
3001 </glossentry>
3002
3003 </glossdiv>
3004
3005<!-- <glossdiv id='var-glossary-x'><title>X</title>-->
3006<!-- </glossdiv>-->
3007
3008<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
3009<!-- </glossdiv>-->
3010
3011<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
3012<!-- </glossdiv>-->
3013
3014</glossary>
3015</chapter>
3016<!--
3017vim: expandtab tw=80 ts=4
3018-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-13 20:01:16 +0000