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