diff options
author | Tudor Florea <tudor.florea@enea.com> | 2015-10-09 22:59:03 +0200 |
---|---|---|
committer | Tudor Florea <tudor.florea@enea.com> | 2015-10-09 22:59:03 +0200 |
commit | 972dcfcdbfe75dcfeb777150c136576cf1a71e99 (patch) | |
tree | 97a61cd7e293d7ae9d56ef7ed0f81253365bb026 /documentation/ref-manual/ref-variables.xml | |
download | poky-972dcfcdbfe75dcfeb777150c136576cf1a71e99.tar.gz |
initial commit for Enea Linux 5.0 arm
Signed-off-by: Tudor Florea <tudor.florea@enea.com>
Diffstat (limited to 'documentation/ref-manual/ref-variables.xml')
-rw-r--r-- | documentation/ref-manual/ref-variables.xml | 10284 |
1 files changed, 10284 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml new file mode 100644 index 0000000000..576c91f29a --- /dev/null +++ b/documentation/ref-manual/ref-variables.xml | |||
@@ -0,0 +1,10284 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
4 | |||
5 | <!-- Dummy chapter --> | ||
6 | <chapter id='ref-variables-glos'> | ||
7 | |||
8 | <title>Variables Glossary</title> | ||
9 | |||
10 | <para> | ||
11 | This chapter lists common variables used in the OpenEmbedded build system and gives an overview | ||
12 | of their function and contents. | ||
13 | </para> | ||
14 | |||
15 | <glossary id='ref-variables-glossary'> | ||
16 | |||
17 | |||
18 | <para> | ||
19 | <link linkend='var-ABIEXTENSION'>A</link> | ||
20 | <link linkend='var-B'>B</link> | ||
21 | <link linkend='var-CFLAGS'>C</link> | ||
22 | <link linkend='var-D'>D</link> | ||
23 | <link linkend='var-EFI_PROVIDER'>E</link> | ||
24 | <link linkend='var-FEATURE_PACKAGES'>F</link> | ||
25 | <link linkend='var-GLIBC_GENERATE_LOCALES'>G</link> | ||
26 | <link linkend='var-HOMEPAGE'>H</link> | ||
27 | <link linkend='var-ICECC_DISABLED'>I</link> | ||
28 | <!-- <link linkend='var-glossary-j'>J</link> --> | ||
29 | <link linkend='var-KARCH'>K</link> | ||
30 | <link linkend='var-LABELS'>L</link> | ||
31 | <link linkend='var-MACHINE'>M</link> | ||
32 | <!-- <link linkend='var-glossary-n'>N</link> --> | ||
33 | <link linkend='var-OE_BINCONFIG_EXTRA_MANGLE'>O</link> | ||
34 | <link linkend='var-P'>P</link> | ||
35 | <link linkend='var-QMAKE_PROFILES'>Q</link> | ||
36 | <link linkend='var-RCONFLICTS'>R</link> | ||
37 | <link linkend='var-S'>S</link> | ||
38 | <link linkend='var-T'>T</link> | ||
39 | <link linkend='var-UBOOT_CONFIG'>U</link> | ||
40 | <!-- <link linkend='var-glossary-v'>V</link> --> | ||
41 | <link linkend='var-WARN_QA'>W</link> | ||
42 | <!-- <link linkend='var-glossary-x'>X</link> --> | ||
43 | <!-- <link linkend='var-glossary-y'>Y</link> --> | ||
44 | <!-- <link linkend='var-glossary-z'>Z</link>--> | ||
45 | </para> | ||
46 | |||
47 | <glossdiv id='var-glossary-a'><title>A</title> | ||
48 | |||
49 | <glossentry id='var-ABIEXTENSION'><glossterm>ABIEXTENSION</glossterm> | ||
50 | <glossdef> | ||
51 | <para> | ||
52 | Extension to the Application Binary Interface (ABI) | ||
53 | field of the GNU canonical architecture name | ||
54 | (e.g. "eabi"). | ||
55 | </para> | ||
56 | |||
57 | <para> | ||
58 | ABI extensions are set in the machine include files. | ||
59 | For example, the | ||
60 | <filename>meta/conf/machine/include/arm/arch-arm.inc</filename> | ||
61 | file sets the following extension: | ||
62 | <literallayout class='monospaced'> | ||
63 | ABIEXTENSION = "eabi" | ||
64 | </literallayout> | ||
65 | </para> | ||
66 | </glossdef> | ||
67 | </glossentry> | ||
68 | |||
69 | <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm> | ||
70 | <glossdef> | ||
71 | <para> | ||
72 | Specifies if an output package should still be produced if it is empty. | ||
73 | By default, BitBake does not produce empty packages. | ||
74 | This default behavior can cause issues when there is an | ||
75 | <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or | ||
76 | some other hard runtime requirement on the existence of the package. | ||
77 | </para> | ||
78 | |||
79 | <para> | ||
80 | Like all package-controlling variables, you must always use them in | ||
81 | conjunction with a package name override, as in: | ||
82 | <literallayout class='monospaced'> | ||
83 | ALLOW_EMPTY_${PN} = "1" | ||
84 | ALLOW_EMPTY_${PN}-dev = "1" | ||
85 | ALLOW_EMPTY_${PN}-staticdev = "1" | ||
86 | </literallayout> | ||
87 | </para> | ||
88 | </glossdef> | ||
89 | </glossentry> | ||
90 | |||
91 | <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm> | ||
92 | <glossdef> | ||
93 | <para> | ||
94 | Lists commands in a package that need an alternative | ||
95 | binary naming scheme. | ||
96 | Sometimes the same command is provided in multiple packages. | ||
97 | When this occurs, the OpenEmbedded build system needs to | ||
98 | use the alternatives system to create a different binary | ||
99 | naming scheme so the commands can co-exist. | ||
100 | </para> | ||
101 | |||
102 | <para> | ||
103 | To use the variable, list out the package's commands | ||
104 | that also exist as part of another package. | ||
105 | For example, if the <filename>busybox</filename> package | ||
106 | has four commands that also exist as part of another | ||
107 | package, you identify them as follows: | ||
108 | <literallayout class='monospaced'> | ||
109 | ALTERNATIVE_busybox = "sh sed test bracket" | ||
110 | </literallayout> | ||
111 | For more information on the alternatives system, see the | ||
112 | "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>" | ||
113 | section. | ||
114 | </para> | ||
115 | </glossdef> | ||
116 | </glossentry> | ||
117 | |||
118 | <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm> | ||
119 | <glossdef> | ||
120 | <para> | ||
121 | Used by the alternatives system to map duplicated commands | ||
122 | to actual locations. | ||
123 | For example, if the <filename>bracket</filename> command | ||
124 | provided by the <filename>busybox</filename> package is | ||
125 | duplicated through another package, you must use the | ||
126 | <filename>ALTERNATIVE_LINK_NAME</filename> variable to | ||
127 | specify the actual location: | ||
128 | <literallayout class='monospaced'> | ||
129 | ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/[" | ||
130 | </literallayout> | ||
131 | In this example, the binary for the | ||
132 | <filename>bracket</filename> command (i.e. | ||
133 | <filename>[</filename>) from the | ||
134 | <filename>busybox</filename> package resides in | ||
135 | <filename>/usr/bin/</filename>. | ||
136 | <note> | ||
137 | If <filename>ALTERNATIVE_LINK_NAME</filename> is not | ||
138 | defined, it defaults to | ||
139 | <filename>${bindir}/<replaceable>name</replaceable></filename>. | ||
140 | </note> | ||
141 | </para> | ||
142 | |||
143 | <para> | ||
144 | For more information on the alternatives system, see the | ||
145 | "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>" | ||
146 | section. | ||
147 | </para> | ||
148 | </glossdef> | ||
149 | </glossentry> | ||
150 | |||
151 | <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm> | ||
152 | <glossdef> | ||
153 | <para> | ||
154 | Used by the alternatives system to create default | ||
155 | priorities for duplicated commands. | ||
156 | You can use the variable to create a single default | ||
157 | regardless of the command name or package, a default for | ||
158 | specific duplicated commands regardless of the package, or | ||
159 | a default for specific commands tied to particular packages. | ||
160 | Here are the available syntax forms: | ||
161 | <literallayout class='monospaced'> | ||
162 | ALTERNATIVE_PRIORITY = "<replaceable>priority</replaceable>" | ||
163 | ALTERNATIVE_PRIORITY[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>" | ||
164 | ALTERNATIVE_PRIORITY_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>" | ||
165 | </literallayout> | ||
166 | </para> | ||
167 | |||
168 | <para> | ||
169 | For more information on the alternatives system, see the | ||
170 | "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>" | ||
171 | section. | ||
172 | </para> | ||
173 | </glossdef> | ||
174 | </glossentry> | ||
175 | |||
176 | <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm> | ||
177 | <glossdef> | ||
178 | <para> | ||
179 | Used by the alternatives system to create default link | ||
180 | locations for duplicated commands. | ||
181 | You can use the variable to create a single default | ||
182 | location for all duplicated commands regardless of the | ||
183 | command name or package, a default for | ||
184 | specific duplicated commands regardless of the package, or | ||
185 | a default for specific commands tied to particular packages. | ||
186 | Here are the available syntax forms: | ||
187 | <literallayout class='monospaced'> | ||
188 | ALTERNATIVE_TARGET = "<replaceable>target</replaceable>" | ||
189 | ALTERNATIVE_TARGET[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>" | ||
190 | ALTERNATIVE_TARGET_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>" | ||
191 | </literallayout> | ||
192 | <note> | ||
193 | <para> | ||
194 | If <filename>ALTERNATIVE_TARGET</filename> is not | ||
195 | defined, it inherits the value from the | ||
196 | <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link> | ||
197 | variable. | ||
198 | </para> | ||
199 | |||
200 | <para> | ||
201 | If <filename>ALTERNATIVE_LINK_NAME</filename> and | ||
202 | <filename>ALTERNATIVE_TARGET</filename> are the | ||
203 | same, the target for | ||
204 | <filename>ALTERNATIVE_TARGET</filename> | ||
205 | has "<filename>.{BPN}</filename>" appended to it. | ||
206 | </para> | ||
207 | |||
208 | <para> | ||
209 | Finally, if the file referenced has not been | ||
210 | renamed, the alternatives system will rename it to | ||
211 | avoid the need to rename alternative files in the | ||
212 | <link linkend='ref-tasks-install'><filename>do_install</filename></link> | ||
213 | task while | ||
214 | retaining support for the command if necessary. | ||
215 | </para> | ||
216 | </note> | ||
217 | </para> | ||
218 | |||
219 | <para> | ||
220 | For more information on the alternatives system, see the | ||
221 | "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>" | ||
222 | section. | ||
223 | </para> | ||
224 | </glossdef> | ||
225 | </glossentry> | ||
226 | |||
227 | <glossentry id='var-APPEND'><glossterm>APPEND</glossterm> | ||
228 | <glossdef> | ||
229 | <para> | ||
230 | An override list of append strings for each | ||
231 | <link linkend='var-LABELS'><filename>LABEL</filename></link>. | ||
232 | </para> | ||
233 | |||
234 | <para> | ||
235 | See the | ||
236 | <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link> | ||
237 | class for more information on how this variable is used. | ||
238 | </para> | ||
239 | </glossdef> | ||
240 | </glossentry> | ||
241 | |||
242 | <glossentry id='var-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm> | ||
243 | <glossdef> | ||
244 | <para> | ||
245 | Lists recipe names | ||
246 | (<link linkend='var-PN'><filename>PN</filename></link> | ||
247 | values) BitBake does not attempt to build. | ||
248 | Instead, BitBake assumes these recipes have already been | ||
249 | built. | ||
250 | </para> | ||
251 | |||
252 | <para> | ||
253 | In OpenEmbedded Core, <filename>ASSUME_PROVIDED</filename> | ||
254 | mostly specifies native tools that should not be built. | ||
255 | An example is <filename>git-native</filename>, which when | ||
256 | specified, allows for the Git binary from the host to be | ||
257 | used rather than building <filename>git-native</filename>. | ||
258 | </para> | ||
259 | </glossdef> | ||
260 | </glossentry> | ||
261 | |||
262 | <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm> | ||
263 | <glossdef> | ||
264 | <para>The email address used to contact the original author | ||
265 | or authors in order to send patches and forward bugs.</para> | ||
266 | </glossdef> | ||
267 | </glossentry> | ||
268 | |||
269 | <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm>AUTO_SYSLINUXMENU</glossterm> | ||
270 | <glossdef> | ||
271 | <para> | ||
272 | Enables creating an automatic menu. | ||
273 | You must set this in your recipe. | ||
274 | The | ||
275 | <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link> | ||
276 | class checks this variable. | ||
277 | </para> | ||
278 | </glossdef> | ||
279 | </glossentry> | ||
280 | |||
281 | <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm> | ||
282 | <glossdef> | ||
283 | <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename> | ||
284 | is set to the value of this variable, it specifies to use the latest | ||
285 | source revision in the repository. | ||
286 | Here is an example: | ||
287 | <literallayout class='monospaced'> | ||
288 | SRCREV = "${AUTOREV}" | ||
289 | </literallayout> | ||
290 | </para> | ||
291 | </glossdef> | ||
292 | </glossentry> | ||
293 | |||
294 | <glossentry id='var-AVAILTUNES'><glossterm>AVAILTUNES</glossterm> | ||
295 | <glossdef> | ||
296 | <para> | ||
297 | The list of defined CPU and Application Binary Interface | ||
298 | (ABI) tunings (i.e. "tunes") available for use by the | ||
299 | OpenEmbedded build system. | ||
300 | </para> | ||
301 | |||
302 | <para> | ||
303 | The list simply presents the tunes that are available. | ||
304 | Not all tunes may be compatible with a particular | ||
305 | machine configuration, or with each other in a | ||
306 | <ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Multilib</ulink> | ||
307 | configuration. | ||
308 | </para> | ||
309 | |||
310 | <para> | ||
311 | To add a tune to the list, be sure to append it with | ||
312 | spaces using the "+=" BitBake operator. | ||
313 | Do not simply replace the list by using the "=" operator. | ||
314 | See the | ||
315 | "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>" | ||
316 | section in the BitBake User Manual for more information. | ||
317 | </para> | ||
318 | </glossdef> | ||
319 | </glossentry> | ||
320 | |||
321 | |||
322 | </glossdiv> | ||
323 | |||
324 | <glossdiv id='var-glossary-b'><title>B</title> | ||
325 | |||
326 | <glossentry id='var-B'><glossterm>B</glossterm> | ||
327 | <glossdef> | ||
328 | <para> | ||
329 | The directory within the | ||
330 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> | ||
331 | in which the OpenEmbedded build system places generated | ||
332 | objects during a recipe's build process. | ||
333 | By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link> | ||
334 | directory, which is defined as: | ||
335 | <literallayout class='monospaced'> | ||
336 | S = "${WORKDIR}/${BP}/" | ||
337 | </literallayout> | ||
338 | You can separate the (<filename>S</filename>) directory | ||
339 | and the directory pointed to by the <filename>B</filename> | ||
340 | variable. | ||
341 | Most Autotools-based recipes support separating these | ||
342 | directories. | ||
343 | The build system defaults to using separate directories for | ||
344 | <filename>gcc</filename> and some kernel recipes. | ||
345 | </para> | ||
346 | </glossdef> | ||
347 | </glossentry> | ||
348 | |||
349 | <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm> | ||
350 | <glossdef> | ||
351 | <para> | ||
352 | Lists "recommended-only" packages to not install. | ||
353 | Recommended-only packages are packages installed only | ||
354 | through the | ||
355 | <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> | ||
356 | variable. | ||
357 | You can prevent any of these "recommended" packages from | ||
358 | being installed by listing them with the | ||
359 | <filename>BAD_RECOMMENDATIONS</filename> variable: | ||
360 | <literallayout class='monospaced'> | ||
361 | BAD_RECOMMENDATIONS = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..." | ||
362 | </literallayout> | ||
363 | You can set this variable globally in your | ||
364 | <filename>local.conf</filename> file or you can attach it to | ||
365 | a specific image recipe by using the recipe name override: | ||
366 | <literallayout class='monospaced'> | ||
367 | BAD_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>" | ||
368 | </literallayout> | ||
369 | </para> | ||
370 | |||
371 | <para> | ||
372 | It is important to realize that if you choose to not install | ||
373 | packages using this variable and some other packages are | ||
374 | dependent on them (i.e. listed in a recipe's | ||
375 | <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> | ||
376 | variable), the OpenEmbedded build system ignores your | ||
377 | request and will install the packages to avoid dependency | ||
378 | errors. | ||
379 | </para> | ||
380 | |||
381 | <para> | ||
382 | Support for this variable exists only when using the | ||
383 | IPK and RPM packaging backend. | ||
384 | Support does not exist for DEB. | ||
385 | </para> | ||
386 | |||
387 | <para> | ||
388 | See the | ||
389 | <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link> | ||
390 | and the | ||
391 | <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link> | ||
392 | variables for related information. | ||
393 | </para> | ||
394 | </glossdef> | ||
395 | </glossentry> | ||
396 | |||
397 | <glossentry id='var-BASE_LIB'><glossterm>BASE_LIB</glossterm> | ||
398 | <glossdef> | ||
399 | <para> | ||
400 | The library directory name for the CPU or Application | ||
401 | Binary Interface (ABI) tune. | ||
402 | The <filename>BASE_LIB</filename> applies only in the | ||
403 | Multilib context. | ||
404 | See the | ||
405 | "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>" | ||
406 | section in the Yocto Project Development Manual for | ||
407 | information on Multilib. | ||
408 | </para> | ||
409 | |||
410 | <para> | ||
411 | The <filename>BASE_LIB</filename> variable is defined in | ||
412 | the machine include files in the | ||
413 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | ||
414 | If Multilib is not being used, the value defaults to "lib". | ||
415 | </para> | ||
416 | </glossdef> | ||
417 | </glossentry> | ||
418 | |||
419 | <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm> | ||
420 | <glossdef> | ||
421 | <para> | ||
422 | Defines how BitBake handles situations where an append | ||
423 | file (<filename>.bbappend</filename>) has no | ||
424 | corresponding recipe file (<filename>.bb</filename>). | ||
425 | This condition often occurs when layers get out of sync | ||
426 | (e.g. <filename>oe-core</filename> bumps a | ||
427 | recipe version and the old recipe no longer exists and the | ||
428 | other layer has not been updated to the new version | ||
429 | of the recipe yet). | ||
430 | </para> | ||
431 | |||
432 | <para> | ||
433 | The default fatal behavior is safest because it is | ||
434 | the sane reaction given something is out of sync. | ||
435 | It is important to realize when your changes are no longer | ||
436 | being applied. | ||
437 | </para> | ||
438 | |||
439 | <para> | ||
440 | You can change the default behavior by setting this | ||
441 | variable to "1", "yes", or "true" | ||
442 | in your <filename>local.conf</filename> file, which is | ||
443 | located in the | ||
444 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: | ||
445 | Here is an example: | ||
446 | <literallayout class='monospaced'> | ||
447 | BB_DANGLINGAPPENDS_WARNONLY = "1" | ||
448 | </literallayout> | ||
449 | </para> | ||
450 | </glossdef> | ||
451 | </glossentry> | ||
452 | |||
453 | <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm> | ||
454 | <glossdef> | ||
455 | <para> | ||
456 | Monitors disk space and available inodes during the build | ||
457 | and allows you to control the build based on these | ||
458 | parameters. | ||
459 | </para> | ||
460 | |||
461 | <para> | ||
462 | Disk space monitoring is disabled by default. | ||
463 | To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename> | ||
464 | variable to your <filename>conf/local.conf</filename> file found in the | ||
465 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
466 | Use the following form: | ||
467 | <literallayout class='monospaced'> | ||
468 | BB_DISKMON_DIRS = "<replaceable>action</replaceable>,<replaceable>dir</replaceable>,<replaceable>threshold</replaceable> [...]" | ||
469 | |||
470 | where: | ||
471 | |||
472 | <replaceable>action</replaceable> is: | ||
473 | ABORT: Immediately abort the build when | ||
474 | a threshold is broken. | ||
475 | STOPTASKS: Stop the build after the currently | ||
476 | executing tasks have finished when | ||
477 | a threshold is broken. | ||
478 | WARN: Issue a warning but continue the | ||
479 | build when a threshold is broken. | ||
480 | Subsequent warnings are issued as | ||
481 | defined by the | ||
482 | <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable, | ||
483 | which must be defined in the | ||
484 | conf/local.conf file. | ||
485 | |||
486 | <replaceable>dir</replaceable> is: | ||
487 | Any directory you choose. You can specify one or | ||
488 | more directories to monitor by separating the | ||
489 | groupings with a space. If two directories are | ||
490 | on the same device, only the first directory | ||
491 | is monitored. | ||
492 | |||
493 | <replaceable>threshold</replaceable> is: | ||
494 | Either the minimum available disk space, | ||
495 | the minimum number of free inodes, or | ||
496 | both. You must specify at least one. To | ||
497 | omit one or the other, simply omit the value. | ||
498 | Specify the threshold using G, M, K for Gbytes, | ||
499 | Mbytes, and Kbytes, respectively. If you do | ||
500 | not specify G, M, or K, Kbytes is assumed by | ||
501 | default. Do not use GB, MB, or KB. | ||
502 | </literallayout> | ||
503 | </para> | ||
504 | |||
505 | <para> | ||
506 | Here are some examples: | ||
507 | <literallayout class='monospaced'> | ||
508 | BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" | ||
509 | BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" | ||
510 | BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" | ||
511 | </literallayout> | ||
512 | The first example works only if you also provide | ||
513 | the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable | ||
514 | in the <filename>conf/local.conf</filename>. | ||
515 | This example causes the build system to immediately | ||
516 | abort when either the disk space in <filename>${TMPDIR}</filename> drops | ||
517 | below 1 Gbyte or the available free inodes drops below | ||
518 | 100 Kbytes. | ||
519 | Because two directories are provided with the variable, the | ||
520 | build system also issue a | ||
521 | warning when the disk space in the | ||
522 | <filename>${SSTATE_DIR}</filename> directory drops | ||
523 | below 1 Gbyte or the number of free inodes drops | ||
524 | below 100 Kbytes. | ||
525 | Subsequent warnings are issued during intervals as | ||
526 | defined by the <filename>BB_DISKMON_WARNINTERVAL</filename> | ||
527 | variable. | ||
528 | </para> | ||
529 | |||
530 | <para> | ||
531 | The second example stops the build after all currently | ||
532 | executing tasks complete when the minimum disk space | ||
533 | in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename> | ||
534 | directory drops below 1 Gbyte. | ||
535 | No disk monitoring occurs for the free inodes in this case. | ||
536 | </para> | ||
537 | |||
538 | <para> | ||
539 | The final example immediately aborts the build when the | ||
540 | number of free inodes in the <filename>${TMPDIR}</filename> directory | ||
541 | drops below 100 Kbytes. | ||
542 | No disk space monitoring for the directory itself occurs | ||
543 | in this case. | ||
544 | </para> | ||
545 | </glossdef> | ||
546 | </glossentry> | ||
547 | |||
548 | <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm> | ||
549 | <glossdef> | ||
550 | <para> | ||
551 | Defines the disk space and free inode warning intervals. | ||
552 | To set these intervals, define the variable in your | ||
553 | <filename>conf/local.conf</filename> file in the | ||
554 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
555 | </para> | ||
556 | |||
557 | <para> | ||
558 | If you are going to use the | ||
559 | <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must | ||
560 | also use the | ||
561 | <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable | ||
562 | and define its action as "WARN". | ||
563 | During the build, subsequent warnings are issued each time | ||
564 | disk space or number of free inodes further reduces by | ||
565 | the respective interval. | ||
566 | </para> | ||
567 | |||
568 | <para> | ||
569 | If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename> | ||
570 | variable and you do use <filename>BB_DISKMON_DIRS</filename> with | ||
571 | the "WARN" action, the disk monitoring interval defaults to | ||
572 | the following: | ||
573 | <literallayout class='monospaced'> | ||
574 | BB_DISKMON_WARNINTERVAL = "50M,5K" | ||
575 | </literallayout> | ||
576 | </para> | ||
577 | |||
578 | <para> | ||
579 | When specifying the variable in your configuration file, | ||
580 | use the following form: | ||
581 | <literallayout class='monospaced'> | ||
582 | BB_DISKMON_WARNINTERVAL = "<replaceable>disk_space_interval</replaceable>,<replaceable>disk_inode_interval</replaceable>" | ||
583 | |||
584 | where: | ||
585 | |||
586 | <replaceable>disk_space_interval</replaceable> is: | ||
587 | An interval of memory expressed in either | ||
588 | G, M, or K for Gbytes, Mbytes, or Kbytes, | ||
589 | respectively. You cannot use GB, MB, or KB. | ||
590 | |||
591 | <replaceable>disk_inode_interval</replaceable> is: | ||
592 | An interval of free inodes expressed in either | ||
593 | G, M, or K for Gbytes, Mbytes, or Kbytes, | ||
594 | respectively. You cannot use GB, MB, or KB. | ||
595 | </literallayout> | ||
596 | </para> | ||
597 | |||
598 | <para> | ||
599 | Here is an example: | ||
600 | <literallayout class='monospaced'> | ||
601 | BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" | ||
602 | BB_DISKMON_WARNINTERVAL = "50M,5K" | ||
603 | </literallayout> | ||
604 | These variables cause the OpenEmbedded build system to | ||
605 | issue subsequent warnings each time the available | ||
606 | disk space further reduces by 50 Mbytes or the number | ||
607 | of free inodes further reduces by 5 Kbytes in the | ||
608 | <filename>${SSTATE_DIR}</filename> directory. | ||
609 | Subsequent warnings based on the interval occur each time | ||
610 | a respective interval is reached beyond the initial warning | ||
611 | (i.e. 1 Gbytes and 100 Kbytes). | ||
612 | </para> | ||
613 | </glossdef> | ||
614 | </glossentry> | ||
615 | |||
616 | <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm> | ||
617 | <glossdef> | ||
618 | <para> | ||
619 | Causes tarballs of the Git repositories, including the | ||
620 | Git metadata, to be placed in the | ||
621 | <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link> | ||
622 | directory. | ||
623 | </para> | ||
624 | |||
625 | <para> | ||
626 | For performance reasons, creating and placing tarballs of | ||
627 | the Git repositories is not the default action by the | ||
628 | OpenEmbedded build system. | ||
629 | <literallayout class='monospaced'> | ||
630 | BB_GENERATE_MIRROR_TARBALLS = "1" | ||
631 | </literallayout> | ||
632 | Set this variable in your <filename>local.conf</filename> | ||
633 | file in the | ||
634 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
635 | </para> | ||
636 | </glossdef> | ||
637 | </glossentry> | ||
638 | |||
639 | <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm> | ||
640 | <glossdef> | ||
641 | <para> | ||
642 | The maximum number of tasks BitBake should run in parallel | ||
643 | at any one time. | ||
644 | If your host development system supports multiple cores, | ||
645 | a good rule of thumb is to set this variable to twice the | ||
646 | number of cores. | ||
647 | </para> | ||
648 | |||
649 | <para> | ||
650 | The default value for <filename>BB_NUMBER_THREADS</filename> | ||
651 | is equal to the number of cores your build system has. | ||
652 | </para> | ||
653 | </glossdef> | ||
654 | </glossentry> | ||
655 | |||
656 | <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm> | ||
657 | <glossdef> | ||
658 | <para> | ||
659 | Allows you to extend a recipe so that it builds variants of the software. | ||
660 | Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>, | ||
661 | which is a copy of Quilt built to run on the build system; | ||
662 | "crosses" such as <filename>gcc-cross</filename>, | ||
663 | which is a compiler built to run on the build machine but produces binaries | ||
664 | that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>; | ||
665 | "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>; | ||
666 | and "mulitlibs" in the form "<filename>multilib:</filename><replaceable>multilib_name</replaceable>". | ||
667 | </para> | ||
668 | |||
669 | <para> | ||
670 | To build a different variant of the recipe with a minimal amount of code, it usually | ||
671 | is as simple as adding the following to your recipe: | ||
672 | <literallayout class='monospaced'> | ||
673 | BBCLASSEXTEND =+ "native nativesdk" | ||
674 | BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>" | ||
675 | </literallayout> | ||
676 | </para> | ||
677 | </glossdef> | ||
678 | </glossentry> | ||
679 | |||
680 | <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm> | ||
681 | <glossdef> | ||
682 | <para>Lists the names of configured layers. | ||
683 | These names are used to find the other <filename>BBFILE_*</filename> | ||
684 | variables. | ||
685 | Typically, each layer will append its name to this variable in its | ||
686 | <filename>conf/layer.conf</filename> file. | ||
687 | </para> | ||
688 | </glossdef> | ||
689 | </glossentry> | ||
690 | |||
691 | <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm> | ||
692 | <glossdef> | ||
693 | <para>Variable that expands to match files from | ||
694 | <link linkend='var-BBFILES'><filename>BBFILES</filename></link> | ||
695 | in a particular layer. | ||
696 | This variable is used in the <filename>conf/layer.conf</filename> file and must | ||
697 | be suffixed with the name of the specific layer (e.g. | ||
698 | <filename>BBFILE_PATTERN_emenlow</filename>).</para> | ||
699 | </glossdef> | ||
700 | </glossentry> | ||
701 | |||
702 | <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm> | ||
703 | <glossdef> | ||
704 | <para>Assigns the priority for recipe files in each layer.</para> | ||
705 | <para>This variable is useful in situations where the same recipe appears in | ||
706 | more than one layer. | ||
707 | Setting this variable allows you to prioritize a | ||
708 | layer against other layers that contain the same recipe - effectively | ||
709 | letting you control the precedence for the multiple layers. | ||
710 | The precedence established through this variable stands regardless of a | ||
711 | recipe's version | ||
712 | (<link linkend='var-PV'><filename>PV</filename></link> variable). | ||
713 | For example, a layer that has a recipe with a higher <filename>PV</filename> value but for | ||
714 | which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a | ||
715 | lower precedence.</para> | ||
716 | <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher | ||
717 | precedence. | ||
718 | For example, the value 6 has a higher precedence than the value 5. | ||
719 | If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer | ||
720 | dependencies (see the | ||
721 | <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for | ||
722 | more information. | ||
723 | The default priority, if unspecified | ||
724 | for a layer with no dependencies, is the lowest defined priority + 1 | ||
725 | (or 1 if no priorities are defined).</para> | ||
726 | <tip> | ||
727 | You can use the command <filename>bitbake-layers show-layers</filename> to list | ||
728 | all configured layers along with their priorities. | ||
729 | </tip> | ||
730 | </glossdef> | ||
731 | </glossentry> | ||
732 | |||
733 | <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm> | ||
734 | <glossdef> | ||
735 | <para>List of recipe files used by BitBake to build software.</para> | ||
736 | </glossdef> | ||
737 | </glossentry> | ||
738 | |||
739 | <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm> | ||
740 | <glossdef> | ||
741 | <para>Variable that controls how BitBake displays logs on build failure.</para> | ||
742 | </glossdef> | ||
743 | </glossentry> | ||
744 | |||
745 | <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm> | ||
746 | <glossdef> | ||
747 | <para>Lists the layers to enable during the build. | ||
748 | This variable is defined in the <filename>bblayers.conf</filename> configuration | ||
749 | file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
750 | Here is an example: | ||
751 | <literallayout class='monospaced'> | ||
752 | BBLAYERS = " \ | ||
753 | /home/scottrif/poky/meta \ | ||
754 | /home/scottrif/poky/meta-yocto \ | ||
755 | /home/scottrif/poky/meta-yocto-bsp \ | ||
756 | /home/scottrif/poky/meta-mykernel \ | ||
757 | " | ||
758 | |||
759 | BBLAYERS_NON_REMOVABLE ?= " \ | ||
760 | /home/scottrif/poky/meta \ | ||
761 | /home/scottrif/poky/meta-yocto \ | ||
762 | " | ||
763 | </literallayout> | ||
764 | This example enables four layers, one of which is a custom, user-defined layer | ||
765 | named <filename>meta-mykernel</filename>. | ||
766 | </para> | ||
767 | </glossdef> | ||
768 | </glossentry> | ||
769 | |||
770 | <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm> | ||
771 | <glossdef> | ||
772 | <para>Lists core layers that cannot be removed from the | ||
773 | <filename>bblayers.conf</filename> file during a build | ||
774 | using the | ||
775 | <ulink url='https://www.yoctoproject.org/tools-resources/projects/hob'>Hob</ulink>. | ||
776 | <note> | ||
777 | When building an image outside of Hob, this variable | ||
778 | is ignored. | ||
779 | </note> | ||
780 | In order for BitBake to build your image using Hob, your | ||
781 | <filename>bblayers.conf</filename> file must include the | ||
782 | <filename>meta</filename> and <filename>meta-yocto</filename> | ||
783 | core layers. | ||
784 | Here is an example that shows these two layers listed in | ||
785 | the <filename>BBLAYERS_NON_REMOVABLE</filename> statement: | ||
786 | <literallayout class='monospaced'> | ||
787 | BBLAYERS = " \ | ||
788 | /home/scottrif/poky/meta \ | ||
789 | /home/scottrif/poky/meta-yocto \ | ||
790 | /home/scottrif/poky/meta-yocto-bsp \ | ||
791 | /home/scottrif/poky/meta-mykernel \ | ||
792 | " | ||
793 | |||
794 | BBLAYERS_NON_REMOVABLE ?= " \ | ||
795 | /home/scottrif/poky/meta \ | ||
796 | /home/scottrif/poky/meta-yocto \ | ||
797 | " | ||
798 | </literallayout> | ||
799 | </para> | ||
800 | </glossdef> | ||
801 | </glossentry> | ||
802 | |||
803 | <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm> | ||
804 | <glossdef> | ||
805 | <para> | ||
806 | Prevents BitBake from processing recipes and recipe | ||
807 | append files. | ||
808 | Use the <filename>BBMASK</filename> variable from within the | ||
809 | <filename>conf/local.conf</filename> file found | ||
810 | in the | ||
811 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
812 | </para> | ||
813 | |||
814 | <para> | ||
815 | You can use the <filename>BBMASK</filename> variable | ||
816 | to "hide" these <filename>.bb</filename> and | ||
817 | <filename>.bbappend</filename> files. | ||
818 | BitBake ignores any recipe or recipe append files that | ||
819 | match the expression. | ||
820 | It is as if BitBake does not see them at all. | ||
821 | Consequently, matching files are not parsed or otherwise | ||
822 | used by BitBake.</para> | ||
823 | <para> | ||
824 | The value you provide is passed to Python's regular | ||
825 | expression compiler. | ||
826 | The expression is compared against the full paths to | ||
827 | the files. | ||
828 | For complete syntax information, see Python's | ||
829 | documentation at | ||
830 | <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>. | ||
831 | </para> | ||
832 | |||
833 | <para> | ||
834 | The following example uses a complete regular expression | ||
835 | to tell BitBake to ignore all recipe and recipe append | ||
836 | files in the <filename>meta-ti/recipes-misc/</filename> | ||
837 | directory: | ||
838 | <literallayout class='monospaced'> | ||
839 | BBMASK = "meta-ti/recipes-misc/" | ||
840 | </literallayout> | ||
841 | If you want to mask out multiple directories or recipes, | ||
842 | use the vertical bar to separate the regular expression | ||
843 | fragments. | ||
844 | This next example masks out multiple directories and | ||
845 | individual recipes: | ||
846 | <literallayout class='monospaced'> | ||
847 | BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/" | ||
848 | BBMASK .= "|.*meta-oe/recipes-support/" | ||
849 | BBMASK .= "|.*openldap" | ||
850 | BBMASK .= "|.*opencv" | ||
851 | BBMASK .= "|.*lzma" | ||
852 | </literallayout> | ||
853 | Notice how the vertical bar is used to append the fragments. | ||
854 | <note> | ||
855 | When specifying a directory name, use the trailing | ||
856 | slash character to ensure you match just that directory | ||
857 | name. | ||
858 | </note> | ||
859 | </para> | ||
860 | </glossdef> | ||
861 | </glossentry> | ||
862 | |||
863 | <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm> | ||
864 | <glossdef> | ||
865 | <para> | ||
866 | Used by BitBake to locate | ||
867 | <filename>.bbclass</filename> and configuration files. | ||
868 | This variable is analogous to the | ||
869 | <filename>PATH</filename> variable. | ||
870 | <note> | ||
871 | If you run BitBake from a directory outside of the | ||
872 | <ulink url='&YOCTO_DOCS_DEV_URL;build-directory'>Build Directory</ulink>, | ||
873 | you must be sure to set | ||
874 | <filename>BBPATH</filename> to point to the | ||
875 | Build Directory. | ||
876 | Set the variable as you would any environment variable | ||
877 | and then run BitBake: | ||
878 | <literallayout class='monospaced'> | ||
879 | $ BBPATH = "<replaceable>build_directory</replaceable>" | ||
880 | $ export BBPATH | ||
881 | $ bitbake <replaceable>target</replaceable> | ||
882 | </literallayout> | ||
883 | </note> | ||
884 | </para> | ||
885 | </glossdef> | ||
886 | </glossentry> | ||
887 | |||
888 | <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm> | ||
889 | <glossdef> | ||
890 | <para> | ||
891 | Points to the server that runs memory-resident BitBake. | ||
892 | This variable is set by the | ||
893 | <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link> | ||
894 | setup script and should not be hand-edited. | ||
895 | The variable is only used when you employ memory-resident | ||
896 | BitBake. | ||
897 | The setup script exports the value as follows: | ||
898 | <literallayout class='monospaced'> | ||
899 | export BBSERVER=localhost:$port | ||
900 | </literallayout> | ||
901 | For more information on how the | ||
902 | <filename>BBSERVER</filename> is used, see the | ||
903 | <filename>oe-init-build-env-memres</filename> script, which | ||
904 | is located in the | ||
905 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | ||
906 | </para> | ||
907 | </glossdef> | ||
908 | </glossentry> | ||
909 | |||
910 | <glossentry id='var-BINCONFIG'><glossterm>BINCONFIG</glossterm> | ||
911 | <glossdef> | ||
912 | <para> | ||
913 | When inheriting the | ||
914 | <link linkend='ref-classes-binconfig-disabled'><filename>binconfig-disabled</filename></link> | ||
915 | class, this variable specifies binary configuration | ||
916 | scripts to disable in favor of using | ||
917 | <filename>pkg-config</filename> to query the information. | ||
918 | The <filename>binconfig-disabled</filename> class will | ||
919 | modify the specified scripts to return an error so that | ||
920 | calls to them can be easily found and replaced. | ||
921 | </para> | ||
922 | |||
923 | <para> | ||
924 | To add multiple scripts, separate them by spaces. | ||
925 | Here is an example from the <filename>libpng</filename> | ||
926 | recipe: | ||
927 | <literallayout class='monospaced'> | ||
928 | BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config" | ||
929 | </literallayout> | ||
930 | </para> | ||
931 | </glossdef> | ||
932 | </glossentry> | ||
933 | |||
934 | <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm> | ||
935 | <glossdef> | ||
936 | <para> | ||
937 | When inheriting the | ||
938 | <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link> | ||
939 | class, this variable specifies a wildcard for | ||
940 | configuration scripts that need editing. | ||
941 | The scripts are edited to correct any paths that have been | ||
942 | set up during compilation so that they are correct for | ||
943 | use when installed into the sysroot and called by the | ||
944 | build processes of other recipes. | ||
945 | </para> | ||
946 | |||
947 | <para> | ||
948 | For more information on how this variable works, see | ||
949 | <filename>meta/classes/binconfig.bbclass</filename> in the | ||
950 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | ||
951 | You can also find general information on the class in the | ||
952 | "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>" | ||
953 | section. | ||
954 | </para> | ||
955 | </glossdef> | ||
956 | </glossentry> | ||
957 | |||
958 | <glossentry id='var-BP'><glossterm>BP</glossterm> | ||
959 | <glossdef> | ||
960 | <para>The base recipe name and version but without any special | ||
961 | recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>, | ||
962 | and so forth). | ||
963 | <filename>BP</filename> is comprised of the following: | ||
964 | <literallayout class="monospaced"> | ||
965 | ${BPN}-${PV} | ||
966 | </literallayout></para> | ||
967 | </glossdef> | ||
968 | </glossentry> | ||
969 | |||
970 | <glossentry id='var-BPN'><glossterm>BPN</glossterm> | ||
971 | <glossdef> | ||
972 | <para>The bare name of the recipe. | ||
973 | This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable | ||
974 | but removes common suffixes such as "-native" and "-cross" as well | ||
975 | as removes common prefixes such as multilib's "lib64-" and "lib32-". | ||
976 | The exact list of suffixes removed is specified by the | ||
977 | <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable. | ||
978 | The exact list of prefixes removed is specified by the | ||
979 | <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable. | ||
980 | Prefixes are removed for <filename>multilib</filename> | ||
981 | and <filename>nativesdk</filename> cases.</para> | ||
982 | </glossdef> | ||
983 | </glossentry> | ||
984 | |||
985 | <glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm> | ||
986 | <glossdef> | ||
987 | <para> | ||
988 | Specifies a URL for an upstream bug tracking website for | ||
989 | a recipe. | ||
990 | The OpenEmbedded build system does not use this variable. | ||
991 | Rather, the variable is a useful pointer in case a bug | ||
992 | in the software being built needs to be manually reported. | ||
993 | </para> | ||
994 | </glossdef> | ||
995 | </glossentry> | ||
996 | |||
997 | <glossentry id='var-BUILD_CFLAGS'><glossterm>BUILD_CFLAGS</glossterm> | ||
998 | <glossdef> | ||
999 | <para> | ||
1000 | Specifies the flags to pass to the C compiler when building | ||
1001 | for the build host. | ||
1002 | When building in the <filename>-native</filename> context, | ||
1003 | <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link> | ||
1004 | is set to the value of this variable by default. | ||
1005 | </para> | ||
1006 | </glossdef> | ||
1007 | </glossentry> | ||
1008 | |||
1009 | <glossentry id='var-BUILD_CPPFLAGS'><glossterm>BUILD_CPPFLAGS</glossterm> | ||
1010 | <glossdef> | ||
1011 | <para> | ||
1012 | Specifies the flags to pass to the C pre-processor | ||
1013 | (i.e. to both the C and the C++ compilers) when building | ||
1014 | for the build host. | ||
1015 | When building in the <filename>native</filename> context, | ||
1016 | <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link> | ||
1017 | is set to the value of this variable by default. | ||
1018 | </para> | ||
1019 | </glossdef> | ||
1020 | </glossentry> | ||
1021 | |||
1022 | <glossentry id='var-BUILD_CXXFLAGS'><glossterm>BUILD_CXXFLAGS</glossterm> | ||
1023 | <glossdef> | ||
1024 | <para> | ||
1025 | Specifies the flags to pass to the C++ compiler when | ||
1026 | building for the build host. | ||
1027 | When building in the <filename>native</filename> context, | ||
1028 | <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link> | ||
1029 | is set to the value of this variable by default. | ||
1030 | </para> | ||
1031 | </glossdef> | ||
1032 | </glossentry> | ||
1033 | |||
1034 | <glossentry id='var-BUILD_LDFLAGS'><glossterm>BUILD_LDFLAGS</glossterm> | ||
1035 | <glossdef> | ||
1036 | <para> | ||
1037 | Specifies the flags to pass to the linker when building | ||
1038 | for the build host. | ||
1039 | When building in the <filename>-native</filename> context, | ||
1040 | <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link> | ||
1041 | is set to the value of this variable by default. | ||
1042 | </para> | ||
1043 | </glossdef> | ||
1044 | </glossentry> | ||
1045 | |||
1046 | <glossentry id='var-BUILD_OPTIMIZATION'><glossterm>BUILD_OPTIMIZATION</glossterm> | ||
1047 | <glossdef> | ||
1048 | <para> | ||
1049 | Specifies the optimization flags passed to the C compiler | ||
1050 | when building for the build host or the SDK. | ||
1051 | The flags are passed through the | ||
1052 | <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link> | ||
1053 | and | ||
1054 | <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link> | ||
1055 | default values. | ||
1056 | </para> | ||
1057 | |||
1058 | <para> | ||
1059 | The default value of the | ||
1060 | <filename>BUILD_OPTIMIZATION</filename> variable is | ||
1061 | "-O2 -pipe". | ||
1062 | </para> | ||
1063 | </glossdef> | ||
1064 | </glossentry> | ||
1065 | |||
1066 | <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm> | ||
1067 | <glossdef> | ||
1068 | <para> | ||
1069 | Points to the location of the | ||
1070 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
1071 | You can define this directory indirectly through the | ||
1072 | <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link> | ||
1073 | and | ||
1074 | <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link> | ||
1075 | scripts by passing in a Build Directory path when you run | ||
1076 | the scripts. | ||
1077 | If you run the scripts and do not provide a Build Directory | ||
1078 | path, the <filename>BUILDDIR</filename> defaults to | ||
1079 | <filename>build</filename> in the current directory. | ||
1080 | </para> | ||
1081 | </glossdef> | ||
1082 | </glossentry> | ||
1083 | |||
1084 | <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>BUILDHISTORY_COMMIT</glossterm> | ||
1085 | <glossdef> | ||
1086 | <para> | ||
1087 | When inheriting the | ||
1088 | <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> | ||
1089 | class, this variable specifies whether or not to commit the | ||
1090 | build history output in a local Git repository. | ||
1091 | If set to "1", this local repository will be maintained | ||
1092 | automatically by the | ||
1093 | <filename>buildhistory</filename> | ||
1094 | class and a commit will be created on every | ||
1095 | build for changes to each top-level subdirectory of the | ||
1096 | build history output (images, packages, and sdk). | ||
1097 | If you want to track changes to build history over | ||
1098 | time, you should set this value to "1". | ||
1099 | </para> | ||
1100 | |||
1101 | <para> | ||
1102 | By default, the <filename>buildhistory</filename> class | ||
1103 | does not commit the build history output in a local | ||
1104 | Git repository: | ||
1105 | <literallayout class='monospaced'> | ||
1106 | BUILDHISTORY_COMMIT ?= "0" | ||
1107 | </literallayout> | ||
1108 | </para> | ||
1109 | </glossdef> | ||
1110 | </glossentry> | ||
1111 | |||
1112 | <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>BUILDHISTORY_COMMIT_AUTHOR</glossterm> | ||
1113 | <glossdef> | ||
1114 | <para> | ||
1115 | When inheriting the | ||
1116 | <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> | ||
1117 | class, this variable specifies the author to use for each | ||
1118 | Git commit. | ||
1119 | In order for the <filename>BUILDHISTORY_COMMIT_AUTHOR</filename> | ||
1120 | variable to work, the | ||
1121 | <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link> | ||
1122 | variable must be set to "1". | ||
1123 | </para> | ||
1124 | |||
1125 | <para> | ||
1126 | Git requires that the value you provide for the | ||
1127 | <filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable | ||
1128 | takes the form of "name <email@host>". | ||
1129 | Providing an email address or host that is not valid does | ||
1130 | not produce an error. | ||
1131 | </para> | ||
1132 | |||
1133 | <para> | ||
1134 | By default, the <filename>buildhistory</filename> class | ||
1135 | sets the variable as follows: | ||
1136 | <literallayout class='monospaced'> | ||
1137 | BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>" | ||
1138 | </literallayout> | ||
1139 | </para> | ||
1140 | </glossdef> | ||
1141 | </glossentry> | ||
1142 | |||
1143 | <glossentry id='var-BUILDHISTORY_DIR'><glossterm>BUILDHISTORY_DIR</glossterm> | ||
1144 | <glossdef> | ||
1145 | <para> | ||
1146 | When inheriting the | ||
1147 | <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> | ||
1148 | class, this variable specifies the directory in which | ||
1149 | build history information is kept. | ||
1150 | For more information on how the variable works, see the | ||
1151 | <filename>buildhistory.class</filename>. | ||
1152 | </para> | ||
1153 | |||
1154 | <para> | ||
1155 | By default, the <filename>buildhistory</filename> class | ||
1156 | sets the directory as follows: | ||
1157 | <literallayout class='monospaced'> | ||
1158 | BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory" | ||
1159 | </literallayout> | ||
1160 | </para> | ||
1161 | </glossdef> | ||
1162 | </glossentry> | ||
1163 | |||
1164 | <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>BUILDHISTORY_FEATURES</glossterm> | ||
1165 | <glossdef> | ||
1166 | <para> | ||
1167 | When inheriting the | ||
1168 | <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> | ||
1169 | class, this variable specifies the build history features | ||
1170 | to be enabled. | ||
1171 | For more information on how build history works, see the | ||
1172 | "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>" | ||
1173 | section. | ||
1174 | </para> | ||
1175 | |||
1176 | <para> | ||
1177 | You can specify three features in the form of a | ||
1178 | space-separated list: | ||
1179 | <itemizedlist> | ||
1180 | <listitem><para><emphasis>image:</emphasis> | ||
1181 | Analysis of the contents of images, which | ||
1182 | includes the list of installed packages among other | ||
1183 | things. | ||
1184 | </para></listitem> | ||
1185 | <listitem><para><emphasis>package:</emphasis> | ||
1186 | Analysis of the contents of individual packages. | ||
1187 | </para></listitem> | ||
1188 | <listitem><para><emphasis>sdk:</emphasis> | ||
1189 | Analysis of the contents of the software | ||
1190 | development kit (SDK). | ||
1191 | </para></listitem> | ||
1192 | </itemizedlist> | ||
1193 | </para> | ||
1194 | |||
1195 | <para> | ||
1196 | By default, the <filename>buildhistory</filename> class | ||
1197 | enables all three features: | ||
1198 | <literallayout class='monospaced'> | ||
1199 | BUILDHISTORY_FEATURES ?= "image package sdk" | ||
1200 | </literallayout> | ||
1201 | </para> | ||
1202 | </glossdef> | ||
1203 | </glossentry> | ||
1204 | |||
1205 | <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>BUILDHISTORY_IMAGE_FILES</glossterm> | ||
1206 | <glossdef> | ||
1207 | <para> | ||
1208 | When inheriting the | ||
1209 | <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> | ||
1210 | class, this variable specifies a list of paths to files | ||
1211 | copied from the | ||
1212 | image contents into the build history directory under | ||
1213 | an "image-files" directory in the directory for | ||
1214 | the image, so that you can track the contents of each file. | ||
1215 | The default is to copy <filename>/etc/passwd</filename> | ||
1216 | and <filename>/etc/group</filename>, which allows you to | ||
1217 | monitor for changes in user and group entries. | ||
1218 | You can modify the list to include any file. | ||
1219 | Specifying an invalid path does not produce an error. | ||
1220 | Consequently, you can include files that might | ||
1221 | not always be present. | ||
1222 | </para> | ||
1223 | |||
1224 | <para> | ||
1225 | By default, the <filename>buildhistory</filename> class | ||
1226 | provides paths to the following files: | ||
1227 | <literallayout class='monospaced'> | ||
1228 | BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group" | ||
1229 | </literallayout> | ||
1230 | </para> | ||
1231 | </glossdef> | ||
1232 | </glossentry> | ||
1233 | |||
1234 | <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>BUILDHISTORY_PUSH_REPO</glossterm> | ||
1235 | <glossdef> | ||
1236 | <para> | ||
1237 | When inheriting the | ||
1238 | <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> | ||
1239 | class, this variable optionally specifies a remote | ||
1240 | repository to which build history pushes Git changes. | ||
1241 | In order for <filename>BUILDHISTORY_PUSH_REPO</filename> | ||
1242 | to work, | ||
1243 | <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link> | ||
1244 | must be set to "1". | ||
1245 | </para> | ||
1246 | |||
1247 | <para> | ||
1248 | The repository should correspond to a remote | ||
1249 | address that specifies a repository as understood by | ||
1250 | Git, or alternatively to a remote name that you have | ||
1251 | set up manually using <filename>git remote</filename> | ||
1252 | within the local repository. | ||
1253 | </para> | ||
1254 | |||
1255 | <para> | ||
1256 | By default, the <filename>buildhistory</filename> class | ||
1257 | sets the variable as follows: | ||
1258 | <literallayout class='monospaced'> | ||
1259 | BUILDHISTORY_PUSH_REPO ?= "" | ||
1260 | </literallayout> | ||
1261 | </para> | ||
1262 | </glossdef> | ||
1263 | </glossentry> | ||
1264 | |||
1265 | <glossentry id='var-BUILDSDK_CFLAGS'><glossterm>BUILDSDK_CFLAGS</glossterm> | ||
1266 | <glossdef> | ||
1267 | <para> | ||
1268 | Specifies the flags to pass to the C compiler when building | ||
1269 | for the SDK. | ||
1270 | When building in the <filename>nativesdk</filename> | ||
1271 | context, | ||
1272 | <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link> | ||
1273 | is set to the value of this variable by default. | ||
1274 | </para> | ||
1275 | </glossdef> | ||
1276 | </glossentry> | ||
1277 | |||
1278 | <glossentry id='var-BUILDSDK_CPPFLAGS'><glossterm>BUILDSDK_CPPFLAGS</glossterm> | ||
1279 | <glossdef> | ||
1280 | <para> | ||
1281 | Specifies the flags to pass to the C pre-processor | ||
1282 | (i.e. to both the C and the C++ compilers) when building | ||
1283 | for the SDK. | ||
1284 | When building in the <filename>nativesdk</filename> | ||
1285 | context, | ||
1286 | <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link> | ||
1287 | is set to the value of this variable by default. | ||
1288 | </para> | ||
1289 | </glossdef> | ||
1290 | </glossentry> | ||
1291 | |||
1292 | <glossentry id='var-BUILDSDK_CXXFLAGS'><glossterm>BUILDSDK_CXXFLAGS</glossterm> | ||
1293 | <glossdef> | ||
1294 | <para> | ||
1295 | Specifies the flags to pass to the C++ compiler when | ||
1296 | building for the SDK. | ||
1297 | When building in the <filename>nativesdk</filename> | ||
1298 | context, | ||
1299 | <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link> | ||
1300 | is set to the value of this variable by default. | ||
1301 | </para> | ||
1302 | </glossdef> | ||
1303 | </glossentry> | ||
1304 | |||
1305 | <glossentry id='var-BUILDSDK_LDFLAGS'><glossterm>BUILDSDK_LDFLAGS</glossterm> | ||
1306 | <glossdef> | ||
1307 | <para> | ||
1308 | Specifies the flags to pass to the linker when building | ||
1309 | for the SDK. | ||
1310 | When building in the <filename>nativesdk-</filename> | ||
1311 | context, | ||
1312 | <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link> | ||
1313 | is set to the value of this variable by default. | ||
1314 | </para> | ||
1315 | </glossdef> | ||
1316 | </glossentry> | ||
1317 | |||
1318 | <glossentry id='var-BUILDSTATS_BASE'><glossterm>BUILDSTATS_BASE</glossterm> | ||
1319 | <glossdef> | ||
1320 | <para> | ||
1321 | Points to the location of the directory that holds build | ||
1322 | statistics when you use and enable the | ||
1323 | <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link> | ||
1324 | class. | ||
1325 | The <filename>BUILDSTATS_BASE</filename> directory defaults | ||
1326 | to | ||
1327 | <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/buildstats/</filename>. | ||
1328 | </para> | ||
1329 | </glossdef> | ||
1330 | </glossentry> | ||
1331 | |||
1332 | <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm> | ||
1333 | <glossdef> | ||
1334 | <para> | ||
1335 | For the BusyBox recipe, specifies whether to split the | ||
1336 | output executable file into two parts: one for features | ||
1337 | that require <filename>setuid root</filename>, and one for | ||
1338 | the remaining features (i.e. those that do not require | ||
1339 | <filename>setuid root</filename>). | ||
1340 | </para> | ||
1341 | |||
1342 | <para> | ||
1343 | The <filename>BUSYBOX_SPLIT_SUID</filename> variable | ||
1344 | defaults to "1", which results in a single output | ||
1345 | executable file. | ||
1346 | Set the variable to "0" to split the output file. | ||
1347 | </para> | ||
1348 | </glossdef> | ||
1349 | </glossentry> | ||
1350 | |||
1351 | </glossdiv> | ||
1352 | |||
1353 | <glossdiv id='var-glossary-c'><title>C</title> | ||
1354 | |||
1355 | <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm> | ||
1356 | <glossdef> | ||
1357 | <para> | ||
1358 | Specifies the flags to pass to the C compiler. | ||
1359 | This variable is exported to an environment | ||
1360 | variable and thus made visible to the software being | ||
1361 | built during the compilation step. | ||
1362 | </para> | ||
1363 | |||
1364 | <para> | ||
1365 | Default initialization for <filename>CFLAGS</filename> | ||
1366 | varies depending on what is being built: | ||
1367 | <itemizedlist> | ||
1368 | <listitem><para> | ||
1369 | <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link> | ||
1370 | when building for the target | ||
1371 | </para></listitem> | ||
1372 | <listitem><para> | ||
1373 | <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link> | ||
1374 | when building for the build host (i.e. | ||
1375 | <filename>-native</filename>) | ||
1376 | </para></listitem> | ||
1377 | <listitem><para> | ||
1378 | <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link> | ||
1379 | when building for an SDK (i.e. | ||
1380 | <filename>nativesdk-</filename>) | ||
1381 | </para></listitem> | ||
1382 | </itemizedlist> | ||
1383 | </para> | ||
1384 | </glossdef> | ||
1385 | </glossentry> | ||
1386 | |||
1387 | <glossentry id='var-CLASSOVERRIDE'><glossterm>CLASSOVERRIDE</glossterm> | ||
1388 | <glossdef> | ||
1389 | <para> | ||
1390 | An internal variable specifying the special class override | ||
1391 | that should currently apply (e.g. "class-target", | ||
1392 | "class-native", and so forth). | ||
1393 | The classes that use this variable set it to | ||
1394 | appropriate values. | ||
1395 | </para> | ||
1396 | |||
1397 | <para> | ||
1398 | You do not normally directly interact with this variable. | ||
1399 | The value for the <filename>CLASSOVERRIDE</filename> | ||
1400 | variable goes into | ||
1401 | <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> | ||
1402 | and then can be used as an override. | ||
1403 | Here is an example where "python-native" is added to | ||
1404 | <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> | ||
1405 | only when building for the native case: | ||
1406 | <literallayout class='monospaced'> | ||
1407 | DEPENDS_append_class-native = " python-native" | ||
1408 | </literallayout> | ||
1409 | </para> | ||
1410 | </glossdef> | ||
1411 | </glossentry> | ||
1412 | |||
1413 | <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm> | ||
1414 | <glossdef> | ||
1415 | <para> | ||
1416 | Provides a list of hardware features that are enabled in | ||
1417 | both | ||
1418 | <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> | ||
1419 | and | ||
1420 | <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. | ||
1421 | This select list of features contains features that make | ||
1422 | sense to be controlled both at the machine and distribution | ||
1423 | configuration level. | ||
1424 | For example, the "bluetooth" feature requires hardware | ||
1425 | support but should also be optional at the distribution | ||
1426 | level, in case the hardware supports Bluetooth but you | ||
1427 | do not ever intend to use it. | ||
1428 | </para> | ||
1429 | |||
1430 | <para> | ||
1431 | For more information, see the | ||
1432 | <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> | ||
1433 | and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> | ||
1434 | variables. | ||
1435 | </para> | ||
1436 | </glossdef> | ||
1437 | </glossentry> | ||
1438 | |||
1439 | <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm> | ||
1440 | <glossdef> | ||
1441 | <para> | ||
1442 | Points to <filename>meta/files/common-licenses</filename> | ||
1443 | in the | ||
1444 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, | ||
1445 | which is where generic license files reside. | ||
1446 | </para> | ||
1447 | </glossdef> | ||
1448 | </glossentry> | ||
1449 | |||
1450 | <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm> | ||
1451 | <glossdef> | ||
1452 | <para>A regular expression that resolves to one or more hosts | ||
1453 | (when the recipe is native) or one or more targets (when | ||
1454 | the recipe is non-native) with which a recipe is compatible. | ||
1455 | The regular expression is matched against | ||
1456 | <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>. | ||
1457 | You can use the variable to stop recipes from being built | ||
1458 | for classes of systems with which the recipes are not | ||
1459 | compatible. | ||
1460 | Stopping these builds is particularly useful with kernels. | ||
1461 | The variable also helps to increase parsing speed | ||
1462 | since the build system skips parsing recipes not | ||
1463 | compatible with the current system.</para> | ||
1464 | </glossdef> | ||
1465 | </glossentry> | ||
1466 | |||
1467 | <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm> | ||
1468 | <glossdef> | ||
1469 | <para>A regular expression that resolves to one or more | ||
1470 | target machines with which a recipe is compatible. | ||
1471 | The regular expression is matched against | ||
1472 | <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>. | ||
1473 | You can use the variable to stop recipes from being built | ||
1474 | for machines with which the recipes are not compatible. | ||
1475 | Stopping these builds is particularly useful with kernels. | ||
1476 | The variable also helps to increase parsing speed | ||
1477 | since the build system skips parsing recipes not | ||
1478 | compatible with the current machine.</para> | ||
1479 | </glossdef> | ||
1480 | </glossentry> | ||
1481 | |||
1482 | <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm> | ||
1483 | <glossdef> | ||
1484 | <para> | ||
1485 | Defines wildcards to match when installing a list of | ||
1486 | complementary packages for all the packages explicitly | ||
1487 | (or implicitly) installed in an image. | ||
1488 | The resulting list of complementary packages is associated | ||
1489 | with an item that can be added to | ||
1490 | <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>. | ||
1491 | An example usage of this is the "dev-pkgs" item that when | ||
1492 | added to <filename>IMAGE_FEATURES</filename> will | ||
1493 | install -dev packages (containing headers and other | ||
1494 | development files) for every package in the image. | ||
1495 | </para> | ||
1496 | |||
1497 | <para> | ||
1498 | To add a new feature item pointing to a wildcard, use a | ||
1499 | variable flag to specify the feature item name and | ||
1500 | use the value to specify the wildcard. | ||
1501 | Here is an example: | ||
1502 | <literallayout class='monospaced'> | ||
1503 | COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev' | ||
1504 | </literallayout> | ||
1505 | </para> | ||
1506 | </glossdef> | ||
1507 | </glossentry> | ||
1508 | |||
1509 | <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm> | ||
1510 | <glossdef> | ||
1511 | <para> | ||
1512 | Identifies editable or configurable files that are part of a package. | ||
1513 | If the Package Management System (PMS) is being used to update | ||
1514 | packages on the target system, it is possible that | ||
1515 | configuration files you have changed after the original installation | ||
1516 | and that you now want to remain unchanged are overwritten. | ||
1517 | In other words, editable files might exist in the package that you do not | ||
1518 | want reset as part of the package update process. | ||
1519 | You can use the <filename>CONFFILES</filename> variable to list the files in the | ||
1520 | package that you wish to prevent the PMS from overwriting during this update process. | ||
1521 | </para> | ||
1522 | |||
1523 | <para> | ||
1524 | To use the <filename>CONFFILES</filename> variable, provide a package name | ||
1525 | override that identifies the resulting package. | ||
1526 | Then, provide a space-separated list of files. | ||
1527 | Here is an example: | ||
1528 | <literallayout class='monospaced'> | ||
1529 | CONFFILES_${PN} += "${sysconfdir}/file1 \ | ||
1530 | ${sysconfdir}/file2 ${sysconfdir}/file3" | ||
1531 | </literallayout> | ||
1532 | </para> | ||
1533 | |||
1534 | <para> | ||
1535 | A relationship exists between the <filename>CONFFILES</filename> and | ||
1536 | <filename><link linkend='var-FILES'>FILES</link></filename> variables. | ||
1537 | The files listed within <filename>CONFFILES</filename> must be a subset of | ||
1538 | the files listed within <filename>FILES</filename>. | ||
1539 | Because the configuration files you provide with <filename>CONFFILES</filename> | ||
1540 | are simply being identified so that the PMS will not overwrite them, | ||
1541 | it makes sense that | ||
1542 | the files must already be included as part of the package through the | ||
1543 | <filename>FILES</filename> variable. | ||
1544 | </para> | ||
1545 | |||
1546 | <note> | ||
1547 | When specifying paths as part of the <filename>CONFFILES</filename> variable, | ||
1548 | it is good practice to use appropriate path variables. | ||
1549 | For example, <filename>${sysconfdir}</filename> rather than | ||
1550 | <filename>/etc</filename> or <filename>${bindir}</filename> rather | ||
1551 | than <filename>/usr/bin</filename>. | ||
1552 | You can find a list of these variables at the top of the | ||
1553 | <filename>meta/conf/bitbake.conf</filename> file in the | ||
1554 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | ||
1555 | </note> | ||
1556 | </glossdef> | ||
1557 | </glossentry> | ||
1558 | |||
1559 | <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm> | ||
1560 | <glossdef> | ||
1561 | <para> | ||
1562 | Identifies the initial RAM disk (initramfs) source files. | ||
1563 | The OpenEmbedded build system receives and uses | ||
1564 | this kernel Kconfig variable as an environment variable. | ||
1565 | By default, the variable is set to null (""). | ||
1566 | </para> | ||
1567 | |||
1568 | <para> | ||
1569 | The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be | ||
1570 | either a single cpio archive with a | ||
1571 | <filename>.cpio</filename> suffix or a | ||
1572 | space-separated list of directories and files for building | ||
1573 | the initramfs image. | ||
1574 | A cpio archive should contain a filesystem archive | ||
1575 | to be used as an initramfs image. | ||
1576 | Directories should contain a filesystem layout to be | ||
1577 | included in the initramfs image. | ||
1578 | Files should contain entries according to the format | ||
1579 | described by the | ||
1580 | <filename>usr/gen_init_cpio</filename> program in the | ||
1581 | kernel tree. | ||
1582 | </para> | ||
1583 | |||
1584 | <para> | ||
1585 | If you specify multiple directories and files, the | ||
1586 | initramfs image will be the aggregate of all of them. | ||
1587 | </para> | ||
1588 | </glossdef> | ||
1589 | </glossentry> | ||
1590 | |||
1591 | <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm> | ||
1592 | <glossdef> | ||
1593 | <para> | ||
1594 | A list of files that contains <filename>autoconf</filename> test results relevant | ||
1595 | to the current build. | ||
1596 | This variable is used by the Autotools utilities when running | ||
1597 | <filename>configure</filename>. | ||
1598 | </para> | ||
1599 | </glossdef> | ||
1600 | </glossentry> | ||
1601 | |||
1602 | <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>CONFLICT_DISTRO_FEATURES</glossterm> | ||
1603 | <glossdef> | ||
1604 | <para> | ||
1605 | When inheriting the | ||
1606 | <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link> | ||
1607 | class, this | ||
1608 | variable identifies distribution features that would | ||
1609 | be in conflict should the recipe | ||
1610 | be built. | ||
1611 | In other words, if the | ||
1612 | <filename>CONFLICT_DISTRO_FEATURES</filename> variable | ||
1613 | lists a feature that also appears in | ||
1614 | <filename>DISTRO_FEATURES</filename> within the | ||
1615 | current configuration, an error occurs and the | ||
1616 | build stops. | ||
1617 | </para> | ||
1618 | </glossdef> | ||
1619 | </glossentry> | ||
1620 | |||
1621 | <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm> | ||
1622 | <glossdef> | ||
1623 | <para> | ||
1624 | If set to "1" along with the | ||
1625 | <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link> | ||
1626 | variable, the OpenEmbedded build system copies | ||
1627 | into the image the license files, which are located in | ||
1628 | <filename>/usr/share/common-licenses</filename>, | ||
1629 | for each package. | ||
1630 | The license files are placed | ||
1631 | in directories within the image itself. | ||
1632 | </para> | ||
1633 | </glossdef> | ||
1634 | </glossentry> | ||
1635 | |||
1636 | <glossentry id='var-COPY_LIC_MANIFEST'><glossterm>COPY_LIC_MANIFEST</glossterm> | ||
1637 | <glossdef> | ||
1638 | <para> | ||
1639 | If set to "1", the OpenEmbedded build system copies | ||
1640 | the license manifest for the image to | ||
1641 | <filename>/usr/share/common-licenses/license.manifest</filename> | ||
1642 | within the image itself. | ||
1643 | </para> | ||
1644 | </glossdef> | ||
1645 | </glossentry> | ||
1646 | |||
1647 | <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm> | ||
1648 | <glossdef> | ||
1649 | <para> | ||
1650 | Specifies the list of packages to be added to the image. | ||
1651 | You should only set this variable in the | ||
1652 | <filename>local.conf</filename> configuration file found | ||
1653 | in the | ||
1654 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
1655 | </para> | ||
1656 | |||
1657 | <para> | ||
1658 | This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported. | ||
1659 | </para> | ||
1660 | </glossdef> | ||
1661 | </glossentry> | ||
1662 | |||
1663 | <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm> | ||
1664 | <glossdef> | ||
1665 | <para> | ||
1666 | Specifies the parent directory of the OpenEmbedded | ||
1667 | Core Metadata layer (i.e. <filename>meta</filename>). | ||
1668 | </para> | ||
1669 | |||
1670 | <para> | ||
1671 | It is an important distinction that | ||
1672 | <filename>COREBASE</filename> points to the parent of this | ||
1673 | layer and not the layer itself. | ||
1674 | Consider an example where you have cloned the Poky Git | ||
1675 | repository and retained the <filename>poky</filename> | ||
1676 | name for your local copy of the repository. | ||
1677 | In this case, <filename>COREBASE</filename> points to | ||
1678 | the <filename>poky</filename> folder because it is the | ||
1679 | parent directory of the <filename>poky/meta</filename> | ||
1680 | layer. | ||
1681 | </para> | ||
1682 | </glossdef> | ||
1683 | </glossentry> | ||
1684 | |||
1685 | <glossentry id='var-CPPFLAGS'><glossterm>CPPFLAGS</glossterm> | ||
1686 | <glossdef> | ||
1687 | <para> | ||
1688 | Specifies the flags to pass to the C pre-processor | ||
1689 | (i.e. to both the C and the C++ compilers). | ||
1690 | This variable is exported to an environment | ||
1691 | variable and thus made visible to the software being | ||
1692 | built during the compilation step. | ||
1693 | </para> | ||
1694 | |||
1695 | <para> | ||
1696 | Default initialization for <filename>CPPFLAGS</filename> | ||
1697 | varies depending on what is being built: | ||
1698 | <itemizedlist> | ||
1699 | <listitem><para> | ||
1700 | <link linkend='var-TARGET_CPPFLAGS'><filename>TARGET_CPPFLAGS</filename></link> | ||
1701 | when building for the target | ||
1702 | </para></listitem> | ||
1703 | <listitem><para> | ||
1704 | <link linkend='var-BUILD_CPPFLAGS'><filename>BUILD_CPPFLAGS</filename></link> | ||
1705 | when building for the build host (i.e. | ||
1706 | <filename>-native</filename>) | ||
1707 | </para></listitem> | ||
1708 | <listitem><para> | ||
1709 | <link linkend='var-BUILDSDK_CPPFLAGS'><filename>BUILDSDK_CPPFLAGS</filename></link> | ||
1710 | when building for an SDK (i.e. | ||
1711 | <filename>nativesdk-</filename>) | ||
1712 | </para></listitem> | ||
1713 | </itemizedlist> | ||
1714 | </para> | ||
1715 | </glossdef> | ||
1716 | </glossentry> | ||
1717 | |||
1718 | <glossentry id='var-CXXFLAGS'><glossterm>CXXFLAGS</glossterm> | ||
1719 | <glossdef> | ||
1720 | <para> | ||
1721 | Specifies the flags to pass to the C++ compiler. | ||
1722 | This variable is exported to an environment | ||
1723 | variable and thus made visible to the software being | ||
1724 | built during the compilation step. | ||
1725 | </para> | ||
1726 | |||
1727 | <para> | ||
1728 | Default initialization for <filename>CXXFLAGS</filename> | ||
1729 | varies depending on what is being built: | ||
1730 | <itemizedlist> | ||
1731 | <listitem><para> | ||
1732 | <link linkend='var-TARGET_CXXFLAGS'><filename>TARGET_CXXFLAGS</filename></link> | ||
1733 | when building for the target | ||
1734 | </para></listitem> | ||
1735 | <listitem><para> | ||
1736 | <link linkend='var-BUILD_CXXFLAGS'><filename>BUILD_CXXFLAGS</filename></link> | ||
1737 | when building for the build host (i.e. | ||
1738 | <filename>-native</filename>) | ||
1739 | </para></listitem> | ||
1740 | <listitem><para> | ||
1741 | <link linkend='var-BUILDSDK_CXXFLAGS'><filename>BUILDSDK_CXXFLAGS</filename></link> | ||
1742 | when building for an SDK (i.e. | ||
1743 | <filename>nativesdk</filename>) | ||
1744 | </para></listitem> | ||
1745 | </itemizedlist> | ||
1746 | </para> | ||
1747 | </glossdef> | ||
1748 | </glossentry> | ||
1749 | |||
1750 | </glossdiv> | ||
1751 | |||
1752 | <glossdiv id='var-glossary-d'><title>D</title> | ||
1753 | |||
1754 | <glossentry id='var-D'><glossterm>D</glossterm> | ||
1755 | <glossdef> | ||
1756 | <para> | ||
1757 | The destination directory. | ||
1758 | The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> | ||
1759 | where components are installed by the | ||
1760 | <link linkend='ref-tasks-install'><filename>do_install</filename></link> | ||
1761 | task. | ||
1762 | This location defaults to: | ||
1763 | <literallayout class='monospaced'> | ||
1764 | ${WORKDIR}/image | ||
1765 | </literallayout> | ||
1766 | </para> | ||
1767 | </glossdef> | ||
1768 | </glossentry> | ||
1769 | |||
1770 | <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm> | ||
1771 | <glossdef> | ||
1772 | <para> | ||
1773 | The date and time on which the current build started. | ||
1774 | The format is suitable for timestamps. | ||
1775 | </para> | ||
1776 | </glossdef> | ||
1777 | </glossentry> | ||
1778 | |||
1779 | <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm> | ||
1780 | <glossdef> | ||
1781 | <para> | ||
1782 | Specifies to build packages with debugging information. | ||
1783 | This influences the value of the | ||
1784 | <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename> | ||
1785 | variable. | ||
1786 | </para> | ||
1787 | </glossdef> | ||
1788 | </glossentry> | ||
1789 | |||
1790 | <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm> | ||
1791 | <glossdef> | ||
1792 | <para> | ||
1793 | The options to pass in | ||
1794 | <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename> | ||
1795 | and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling | ||
1796 | a system for debugging. | ||
1797 | This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe". | ||
1798 | </para> | ||
1799 | </glossdef> | ||
1800 | </glossentry> | ||
1801 | |||
1802 | <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm> | ||
1803 | <glossdef> | ||
1804 | <para> | ||
1805 | Specifies a weak bias for recipe selection priority. | ||
1806 | </para> | ||
1807 | <para> | ||
1808 | The most common usage of this is variable is to set | ||
1809 | it to "-1" within a recipe for a development version of a | ||
1810 | piece of software. | ||
1811 | Using the variable in this way causes the stable version | ||
1812 | of the recipe to build by default in the absence of | ||
1813 | <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename> | ||
1814 | being used to build the development version. | ||
1815 | </para> | ||
1816 | <note> | ||
1817 | The bias provided by <filename>DEFAULT_PREFERENCE</filename> | ||
1818 | is weak and is overridden by | ||
1819 | <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename> | ||
1820 | if that variable is different between two layers | ||
1821 | that contain different versions of the same recipe. | ||
1822 | </note> | ||
1823 | </glossdef> | ||
1824 | </glossentry> | ||
1825 | |||
1826 | <glossentry id='var-DEFAULTTUNE'><glossterm>DEFAULTTUNE</glossterm> | ||
1827 | <glossdef> | ||
1828 | <para> | ||
1829 | The default CPU and Application Binary Interface (ABI) | ||
1830 | tunings (i.e. the "tune") used by the OpenEmbedded build | ||
1831 | system. | ||
1832 | The <filename>DEFAULTTUNE</filename> helps define | ||
1833 | <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>. | ||
1834 | </para> | ||
1835 | |||
1836 | <para> | ||
1837 | The default tune is either implicitly or explicitly set | ||
1838 | by the machine | ||
1839 | (<link linkend='var-MACHINE'><filename>MACHINE</filename></link>). | ||
1840 | However, you can override the setting using available tunes | ||
1841 | as defined with | ||
1842 | <link linkend='var-AVAILTUNES'><filename>AVAILTUNES</filename></link>. | ||
1843 | </para> | ||
1844 | </glossdef> | ||
1845 | </glossentry> | ||
1846 | |||
1847 | <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm> | ||
1848 | <glossdef> | ||
1849 | <para> | ||
1850 | Lists a recipe's build-time dependencies | ||
1851 | (i.e. other recipe files). | ||
1852 | The system ensures that all the dependencies listed | ||
1853 | have been built and have their contents in the appropriate | ||
1854 | sysroots before the recipe's configure task is executed. | ||
1855 | </para> | ||
1856 | |||
1857 | <para> | ||
1858 | Consider this simple example for two recipes named "a" and | ||
1859 | "b" that produce similarly named packages. | ||
1860 | In this example, the <filename>DEPENDS</filename> | ||
1861 | statement appears in the "a" recipe: | ||
1862 | <literallayout class='monospaced'> | ||
1863 | DEPENDS = "b" | ||
1864 | </literallayout> | ||
1865 | Here, the dependency is such that the | ||
1866 | <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> | ||
1867 | task for recipe "a" depends on the | ||
1868 | <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> | ||
1869 | task of recipe "b". | ||
1870 | This means anything that recipe "b" puts into sysroot | ||
1871 | is available when recipe "a" is configuring itself. | ||
1872 | </para> | ||
1873 | |||
1874 | <para> | ||
1875 | For information on runtime dependencies, see the | ||
1876 | <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> | ||
1877 | variable. | ||
1878 | </para> | ||
1879 | </glossdef> | ||
1880 | </glossentry> | ||
1881 | |||
1882 | <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm> | ||
1883 | <glossdef> | ||
1884 | <para> | ||
1885 | Points to the general area that the OpenEmbedded build | ||
1886 | system uses to place images, packages, SDKs and other output | ||
1887 | files that are ready to be used outside of the build system. | ||
1888 | By default, this directory resides within the | ||
1889 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> | ||
1890 | as <filename>${TMPDIR}/deploy</filename>. | ||
1891 | </para> | ||
1892 | |||
1893 | <para> | ||
1894 | For more information on the structure of the Build | ||
1895 | Directory, see | ||
1896 | "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>" | ||
1897 | section. | ||
1898 | For more detail on the contents of the | ||
1899 | <filename>deploy</filename> directory, see the | ||
1900 | "<link linkend='images-dev-environment'>Images</link>" and | ||
1901 | "<link linkend='sdk-dev-environment'>Application Development SDK</link>" | ||
1902 | sections. | ||
1903 | </para> | ||
1904 | </glossdef> | ||
1905 | </glossentry> | ||
1906 | |||
1907 | <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm> | ||
1908 | <glossdef> | ||
1909 | <para> | ||
1910 | Points to the area that the OpenEmbedded build system uses | ||
1911 | to place images and other associated output files that are | ||
1912 | ready to be deployed onto the target machine. | ||
1913 | The directory is machine-specific as it contains the | ||
1914 | <filename>${MACHINE}</filename> name. | ||
1915 | By default, this directory resides within the | ||
1916 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> | ||
1917 | as <filename>${DEPLOY_DIR}/images/${MACHINE}/</filename>. | ||
1918 | </para> | ||
1919 | |||
1920 | <para> | ||
1921 | For more information on the structure of the Build | ||
1922 | Directory, see | ||
1923 | "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>" | ||
1924 | section. | ||
1925 | For more detail on the contents of the | ||
1926 | <filename>deploy</filename> directory, see the | ||
1927 | "<link linkend='images-dev-environment'>Images</link>" and | ||
1928 | "<link linkend='sdk-dev-environment'>Application Development SDK</link>" | ||
1929 | sections. | ||
1930 | </para> | ||
1931 | </glossdef> | ||
1932 | </glossentry> | ||
1933 | |||
1934 | <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm> | ||
1935 | <glossdef> | ||
1936 | <para> | ||
1937 | When inheriting the | ||
1938 | <link linkend='ref-classes-deploy'><filename>deploy</filename></link> | ||
1939 | class, the <filename>DEPLOYDIR</filename> points to a | ||
1940 | temporary work area for deployed files that is set in the | ||
1941 | <filename>deploy</filename> class as follows: | ||
1942 | <literallayout class='monospaced'> | ||
1943 | DEPLOYDIR = "${WORKDIR}/deploy-${<link linkend='var-PN'><filename>PN</filename></link>}" | ||
1944 | </literallayout> | ||
1945 | Recipes inheriting the <filename>deploy</filename> class | ||
1946 | should copy files to be deployed into | ||
1947 | <filename>DEPLOYDIR</filename>, and the class will take | ||
1948 | care of copying them into | ||
1949 | <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link> | ||
1950 | afterwards. | ||
1951 | </para> | ||
1952 | </glossdef> | ||
1953 | </glossentry> | ||
1954 | |||
1955 | <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm> | ||
1956 | <glossdef> | ||
1957 | <para>The package description used by package managers. | ||
1958 | If not set, <filename>DESCRIPTION</filename> takes | ||
1959 | the value of the | ||
1960 | <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link> | ||
1961 | variable. | ||
1962 | </para> | ||
1963 | </glossdef> | ||
1964 | </glossentry> | ||
1965 | |||
1966 | <glossentry id='var-DISK_SIGNATURE'><glossterm>DISK_SIGNATURE</glossterm> | ||
1967 | <glossdef> | ||
1968 | <para> | ||
1969 | A 32-bit MBR disk signature used by | ||
1970 | <filename>directdisk</filename> images. | ||
1971 | </para> | ||
1972 | |||
1973 | <para> | ||
1974 | By default, the signature is set to an automatically | ||
1975 | generated random value that allows the OpenEmbedded | ||
1976 | build system to create a boot loader. | ||
1977 | You can override the signature in the image recipe | ||
1978 | by setting <filename>DISK_SIGNATURE</filename> to an | ||
1979 | 8-digit hex string. | ||
1980 | You might want to override | ||
1981 | <filename>DISK_SIGNATURE</filename> if you want the disk | ||
1982 | signature to remain constant between image builds. | ||
1983 | </para> | ||
1984 | |||
1985 | <para> | ||
1986 | When using Linux 3.8 or later, you can use | ||
1987 | <filename>DISK_SIGNATURE</filename> to specify the root | ||
1988 | by UUID to allow the kernel to locate the root device | ||
1989 | even if the device name changes due to differences in | ||
1990 | hardware configuration. | ||
1991 | By default, <filename>SYSLINUX_ROOT</filename> is set | ||
1992 | as follows: | ||
1993 | <literallayout class='monospaced'> | ||
1994 | SYSLINUX_ROOT = "root=/dev/sda2" | ||
1995 | </literallayout> | ||
1996 | However, you can change this to locate the root device | ||
1997 | using the disk signature instead: | ||
1998 | <literallayout class='monospaced'> | ||
1999 | SYSLINUX_ROOT = "root=PARTUUID=${DISK_SIGNATURE}-02" | ||
2000 | </literallayout> | ||
2001 | </para> | ||
2002 | |||
2003 | <para> | ||
2004 | As previously mentioned, it is possible to set the | ||
2005 | <filename>DISK_SIGNATURE</filename> variable in your | ||
2006 | <filename>local.conf</filename> file to a fixed | ||
2007 | value if you do not want <filename>syslinux.cfg</filename> | ||
2008 | changing for each build. | ||
2009 | You might find this useful when you want to upgrade the | ||
2010 | root filesystem on a device without having to recreate or | ||
2011 | modify the master boot record. | ||
2012 | </para> | ||
2013 | </glossdef> | ||
2014 | </glossentry> | ||
2015 | |||
2016 | <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm> | ||
2017 | <glossdef> | ||
2018 | <para> | ||
2019 | The short name of the distribution. | ||
2020 | This variable corresponds to a distribution | ||
2021 | configuration file whose root name is the same as the | ||
2022 | variable's argument and whose filename extension is | ||
2023 | <filename>.conf</filename>. | ||
2024 | For example, the distribution configuration file for the | ||
2025 | Poky distribution is named <filename>poky.conf</filename> | ||
2026 | and resides in the | ||
2027 | <filename>meta-yocto/conf/distro</filename> directory of | ||
2028 | the | ||
2029 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | ||
2030 | </para> | ||
2031 | |||
2032 | <para> | ||
2033 | Within that <filename>poky.conf</filename> file, the | ||
2034 | <filename>DISTRO</filename> variable is set as follows: | ||
2035 | <literallayout class='monospaced'> | ||
2036 | DISTRO = "poky" | ||
2037 | </literallayout> | ||
2038 | </para> | ||
2039 | |||
2040 | <para> | ||
2041 | Distribution configuration files are located in a | ||
2042 | <filename>conf/distro</filename> directory within the | ||
2043 | <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> | ||
2044 | that contains the distribution configuration. | ||
2045 | The value for <filename>DISTRO</filename> must not contain | ||
2046 | spaces, and is typically all lower-case. | ||
2047 | <note> | ||
2048 | If the <filename>DISTRO</filename> variable is blank, a set | ||
2049 | of default configurations are used, which are specified | ||
2050 | within | ||
2051 | <filename>meta/conf/distro/defaultsetup.conf</filename> | ||
2052 | also in the Source Directory. | ||
2053 | </note> | ||
2054 | </para> | ||
2055 | </glossdef> | ||
2056 | </glossentry> | ||
2057 | |||
2058 | <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm> | ||
2059 | <glossdef> | ||
2060 | <para> | ||
2061 | Specifies a list of distro-specific packages to add to all images. | ||
2062 | This variable takes affect through | ||
2063 | <filename>packagegroup-base</filename> so the | ||
2064 | variable only really applies to the more full-featured | ||
2065 | images that include <filename>packagegroup-base</filename>. | ||
2066 | You can use this variable to keep distro policy out of | ||
2067 | generic images. | ||
2068 | As with all other distro variables, you set this variable | ||
2069 | in the distro <filename>.conf</filename> file. | ||
2070 | </para> | ||
2071 | </glossdef> | ||
2072 | </glossentry> | ||
2073 | |||
2074 | <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm> | ||
2075 | <glossdef> | ||
2076 | <para> | ||
2077 | Specifies a list of distro-specific packages to add to all images | ||
2078 | if the packages exist. | ||
2079 | The packages might not exist or be empty (e.g. kernel modules). | ||
2080 | The list of packages are automatically installed but you can | ||
2081 | remove them. | ||
2082 | </para> | ||
2083 | </glossdef> | ||
2084 | </glossentry> | ||
2085 | |||
2086 | <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm> | ||
2087 | <glossdef> | ||
2088 | <para> | ||
2089 | The software support you want in your distribution for | ||
2090 | various features. | ||
2091 | You define your distribution features in the distribution | ||
2092 | configuration file. | ||
2093 | </para> | ||
2094 | |||
2095 | <para> | ||
2096 | In most cases, the presence or absence of a feature in | ||
2097 | <filename>DISTRO_FEATURES</filename> is translated to the | ||
2098 | appropriate option supplied to the configure script | ||
2099 | during the | ||
2100 | <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> | ||
2101 | task for recipes that optionally support the feature. | ||
2102 | For example, specifying "x11" in | ||
2103 | <filename>DISTRO_FEATURES</filename>, causes | ||
2104 | every piece of software built for the target that can | ||
2105 | optionally support X11 to have its X11 support enabled. | ||
2106 | </para> | ||
2107 | |||
2108 | <para> | ||
2109 | Two more examples are Bluetooth and NFS support. | ||
2110 | For a more complete list of features that ships with the | ||
2111 | Yocto Project and that you can provide with this variable, | ||
2112 | see the | ||
2113 | "<link linkend='ref-features-distro'>Distro Features</link>" | ||
2114 | section. | ||
2115 | </para> | ||
2116 | </glossdef> | ||
2117 | </glossentry> | ||
2118 | |||
2119 | <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm> | ||
2120 | <glossdef> | ||
2121 | <para>Features to be added to | ||
2122 | <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> | ||
2123 | if not also present in | ||
2124 | <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>. | ||
2125 | </para> | ||
2126 | |||
2127 | <para> | ||
2128 | This variable is set in the <filename>meta/conf/bitbake.conf</filename> file. | ||
2129 | It is not intended to be user-configurable. | ||
2130 | It is best to just reference the variable to see which distro features are | ||
2131 | being backfilled for all distro configurations. | ||
2132 | See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for | ||
2133 | more information. | ||
2134 | </para> | ||
2135 | </glossdef> | ||
2136 | </glossentry> | ||
2137 | |||
2138 | <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm> | ||
2139 | <glossdef> | ||
2140 | <para>Features from | ||
2141 | <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename> | ||
2142 | that should not be backfilled (i.e. added to | ||
2143 | <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>) | ||
2144 | during the build. | ||
2145 | See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for | ||
2146 | more information. | ||
2147 | </para> | ||
2148 | </glossdef> | ||
2149 | </glossentry> | ||
2150 | |||
2151 | <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm> | ||
2152 | <glossdef> | ||
2153 | <para>The long name of the distribution.</para> | ||
2154 | </glossdef> | ||
2155 | </glossentry> | ||
2156 | |||
2157 | <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm> | ||
2158 | <glossdef> | ||
2159 | <para>Alias names used for the recipe in various Linux distributions.</para> | ||
2160 | <para>See the | ||
2161 | "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling | ||
2162 | a Package Name Alias</ulink>" section in the Yocto Project Development | ||
2163 | Manual for more information.</para> | ||
2164 | </glossdef> | ||
2165 | </glossentry> | ||
2166 | |||
2167 | <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm> | ||
2168 | <glossdef> | ||
2169 | <para>The version of the distribution.</para> | ||
2170 | </glossdef> | ||
2171 | </glossentry> | ||
2172 | |||
2173 | <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm> | ||
2174 | <glossdef> | ||
2175 | <para> | ||
2176 | This variable lists overrides specific to the current | ||
2177 | distribution. | ||
2178 | By default, the variable list includes the value of the | ||
2179 | <filename><link linkend='var-DISTRO'>DISTRO</link></filename> | ||
2180 | variable. | ||
2181 | You can extend the variable to apply any variable overrides | ||
2182 | you want as part of the distribution and are not | ||
2183 | already in <filename>OVERRIDES</filename> through | ||
2184 | some other means. | ||
2185 | </para> | ||
2186 | </glossdef> | ||
2187 | </glossentry> | ||
2188 | |||
2189 | <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm> | ||
2190 | <glossdef> | ||
2191 | <para> | ||
2192 | The central download directory used by the build process to | ||
2193 | store downloads. | ||
2194 | By default, <filename>DL_DIR</filename> gets files | ||
2195 | suitable for mirroring for everything except Git | ||
2196 | repositories. | ||
2197 | If you want tarballs of Git repositories, use the | ||
2198 | <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link> | ||
2199 | variable. | ||
2200 | </para> | ||
2201 | |||
2202 | <para> | ||
2203 | You can set this directory by defining the | ||
2204 | <filename>DL_DIR</filename> variable in the | ||
2205 | <filename>conf/local.conf</filename> file. | ||
2206 | This directory is self-maintaining and you should not have | ||
2207 | to touch it. | ||
2208 | By default, the directory is <filename>downloads</filename> | ||
2209 | in the | ||
2210 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
2211 | <literallayout class='monospaced'> | ||
2212 | #DL_DIR ?= "${TOPDIR}/downloads" | ||
2213 | </literallayout> | ||
2214 | To specify a different download directory, simply remove | ||
2215 | the comment from the line and provide your directory. | ||
2216 | </para> | ||
2217 | |||
2218 | <para> | ||
2219 | During a first build, the system downloads many different | ||
2220 | source code tarballs from various upstream projects. | ||
2221 | Downloading can take a while, particularly if your network | ||
2222 | connection is slow. | ||
2223 | Tarballs are all stored in the directory defined by | ||
2224 | <filename>DL_DIR</filename> and the build system looks there | ||
2225 | first to find source tarballs. | ||
2226 | <note> | ||
2227 | When wiping and rebuilding, you can preserve this | ||
2228 | directory to speed up this part of subsequent | ||
2229 | builds. | ||
2230 | </note> | ||
2231 | </para> | ||
2232 | |||
2233 | <para> | ||
2234 | You can safely share this directory between multiple builds | ||
2235 | on the same development machine. | ||
2236 | For additional information on how the build process gets | ||
2237 | source files when working behind a firewall or proxy server, | ||
2238 | see this specific question in the | ||
2239 | "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>" | ||
2240 | chapter. | ||
2241 | </para> | ||
2242 | </glossdef> | ||
2243 | </glossentry> | ||
2244 | |||
2245 | <glossentry id='var-DOC_COMPRESS'><glossterm>DOC_COMPRESS</glossterm> | ||
2246 | <glossdef> | ||
2247 | <para> | ||
2248 | When inheriting the | ||
2249 | <link linkend='ref-classes-compress_doc'><filename>compress_doc</filename></link> | ||
2250 | class, this variable sets the compression policy used when | ||
2251 | the OpenEmbedded build system compresses man pages and info | ||
2252 | pages. | ||
2253 | By default, the compression method used is gz (gzip). | ||
2254 | Other policies available are xz and bz2. | ||
2255 | </para> | ||
2256 | |||
2257 | <para> | ||
2258 | For information on policies and on how to use this | ||
2259 | variable, see the comments in the | ||
2260 | <filename>meta/classes/compress_doc.bbclass</filename> file. | ||
2261 | </para> | ||
2262 | </glossdef> | ||
2263 | </glossentry> | ||
2264 | |||
2265 | </glossdiv> | ||
2266 | |||
2267 | <glossdiv id='var-glossary-e'><title>E</title> | ||
2268 | |||
2269 | <glossentry id='var-EFI_PROVIDER'><glossterm>EFI_PROVIDER</glossterm> | ||
2270 | <glossdef> | ||
2271 | <para> | ||
2272 | When building bootable images (i.e. where | ||
2273 | <filename>hddimg</filename> or <filename>vmdk</filename> | ||
2274 | is in | ||
2275 | <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>), | ||
2276 | The <filename>EFI_PROVIDER</filename> variable specifies | ||
2277 | the EFI bootloader to use. | ||
2278 | The default is "grub-efi", but "gummiboot" can be used | ||
2279 | instead. | ||
2280 | </para> | ||
2281 | |||
2282 | <para> | ||
2283 | See the | ||
2284 | <link linkend='ref-classes-gummiboot'><filename>gummiboot</filename></link> | ||
2285 | class for more information. | ||
2286 | </para> | ||
2287 | </glossdef> | ||
2288 | </glossentry> | ||
2289 | |||
2290 | <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm> | ||
2291 | <glossdef> | ||
2292 | <para>Variable that controls which locales for | ||
2293 | <filename>glibc</filename> are generated during the | ||
2294 | build (useful if the target device has 64Mbytes | ||
2295 | of RAM or less).</para> | ||
2296 | </glossdef> | ||
2297 | </glossentry> | ||
2298 | |||
2299 | <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm> | ||
2300 | <glossdef> | ||
2301 | <para> | ||
2302 | Specifies the quality assurance checks whose failures are | ||
2303 | reported as errors by the OpenEmbedded build system. | ||
2304 | You set this variable in your distribution configuration | ||
2305 | file. | ||
2306 | For a list of the checks you can control with this variable, | ||
2307 | see the | ||
2308 | "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>" | ||
2309 | section. | ||
2310 | </para> | ||
2311 | </glossdef> | ||
2312 | </glossentry> | ||
2313 | |||
2314 | <glossentry id='var-ERR_REPORT_DIR'><glossterm>ERR_REPORT_DIR</glossterm> | ||
2315 | <glossdef> | ||
2316 | <para> | ||
2317 | When used with the | ||
2318 | <link linkend='ref-classes-report-error'><filename>report-error</filename></link> | ||
2319 | class, specifies the path used for storing the debug files | ||
2320 | created by the | ||
2321 | <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>, | ||
2322 | which allows you to submit build errors you encounter to a | ||
2323 | central database. | ||
2324 | By default, the value of this variable is | ||
2325 | <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>. | ||
2326 | </para> | ||
2327 | |||
2328 | <para> | ||
2329 | You can set <filename>ERR_REPORT_DIR</filename> to the path | ||
2330 | you want the error reporting tool to store the debug files | ||
2331 | as follows in your <filename>local.conf</filename> file: | ||
2332 | <literallayout class='monospaced'> | ||
2333 | ERR_REPORT_DIR = "<replaceable>path</replaceable>" | ||
2334 | </literallayout> | ||
2335 | </para> | ||
2336 | </glossdef> | ||
2337 | </glossentry> | ||
2338 | |||
2339 | <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm> | ||
2340 | <glossdef> | ||
2341 | <para> | ||
2342 | Directs BitBake to exclude a recipe from world builds (i.e. | ||
2343 | <filename>bitbake world</filename>). | ||
2344 | During world builds, BitBake locates, parses and builds all | ||
2345 | recipes found in every layer exposed in the | ||
2346 | <filename>bblayers.conf</filename> configuration file. | ||
2347 | </para> | ||
2348 | |||
2349 | <para> | ||
2350 | To exclude a recipe from a world build using this variable, | ||
2351 | set the variable to "1" in the recipe. | ||
2352 | </para> | ||
2353 | |||
2354 | <note> | ||
2355 | Recipes added to <filename>EXCLUDE_FROM_WORLD</filename> | ||
2356 | may still be built during a world build in order to satisfy | ||
2357 | dependencies of other recipes. | ||
2358 | Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename> | ||
2359 | only ensures that the recipe is not explicitly added | ||
2360 | to the list of build targets in a world build. | ||
2361 | </note> | ||
2362 | </glossdef> | ||
2363 | </glossentry> | ||
2364 | |||
2365 | <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm> | ||
2366 | <glossdef> | ||
2367 | <para> | ||
2368 | Used with file and pathnames to create a prefix for a recipe's | ||
2369 | version based on the recipe's | ||
2370 | <link linkend='var-PE'><filename>PE</filename></link> value. | ||
2371 | If <filename>PE</filename> is set and greater than zero for a recipe, | ||
2372 | <filename>EXTENDPE</filename> becomes that value (e.g if | ||
2373 | <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename> | ||
2374 | becomes "1_"). | ||
2375 | If a recipe's <filename>PE</filename> is not set (the default) or is equal to | ||
2376 | zero, <filename>EXTENDPE</filename> becomes "".</para> | ||
2377 | <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link> | ||
2378 | variable for an example. | ||
2379 | </para> | ||
2380 | </glossdef> | ||
2381 | </glossentry> | ||
2382 | |||
2383 | <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm> | ||
2384 | <glossdef> | ||
2385 | <para> | ||
2386 | The full package version specification as it appears on the | ||
2387 | final packages produced by a recipe. | ||
2388 | The variable's value is normally used to fix a runtime | ||
2389 | dependency to the exact same version of another package | ||
2390 | in the same recipe: | ||
2391 | <literallayout class='monospaced'> | ||
2392 | RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})" | ||
2393 | </literallayout> | ||
2394 | </para> | ||
2395 | |||
2396 | <para> | ||
2397 | The dependency relationships are intended to force the | ||
2398 | package manager to upgrade these types of packages in | ||
2399 | lock-step. | ||
2400 | </para> | ||
2401 | </glossdef> | ||
2402 | </glossentry> | ||
2403 | |||
2404 | <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm> | ||
2405 | <glossdef> | ||
2406 | <para> | ||
2407 | When inheriting the | ||
2408 | <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link> | ||
2409 | class, this variable points to the source tree, which is | ||
2410 | outside of the OpenEmbedded build system. | ||
2411 | When set, this variable sets the | ||
2412 | <link linkend='var-S'><filename>S</filename></link> | ||
2413 | variable, which is what the OpenEmbedded build system uses | ||
2414 | to locate unpacked recipe source code. | ||
2415 | </para> | ||
2416 | |||
2417 | <para> | ||
2418 | For more information on | ||
2419 | <filename>externalsrc.bbclass</filename>, see the | ||
2420 | "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>" | ||
2421 | section. | ||
2422 | You can also find information on how to use this variable | ||
2423 | in the | ||
2424 | "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>" | ||
2425 | section in the Yocto Project Development Manual. | ||
2426 | </para> | ||
2427 | </glossdef> | ||
2428 | </glossentry> | ||
2429 | |||
2430 | <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm> | ||
2431 | <glossdef> | ||
2432 | <para> | ||
2433 | When inheriting the | ||
2434 | <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link> | ||
2435 | class, this variable points to the directory in which the | ||
2436 | recipe's source code is built, which is outside of the | ||
2437 | OpenEmbedded build system. | ||
2438 | When set, this variable sets the | ||
2439 | <link linkend='var-B'><filename>B</filename></link> | ||
2440 | variable, which is what the OpenEmbedded build system uses | ||
2441 | to locate the Build Directory. | ||
2442 | </para> | ||
2443 | |||
2444 | <para> | ||
2445 | For more information on | ||
2446 | <filename>externalsrc.bbclass</filename>, see the | ||
2447 | "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>" | ||
2448 | section. | ||
2449 | You can also find information on how to use this variable | ||
2450 | in the | ||
2451 | "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>" | ||
2452 | section in the Yocto Project Development Manual. | ||
2453 | </para> | ||
2454 | </glossdef> | ||
2455 | </glossentry> | ||
2456 | |||
2457 | <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm> | ||
2458 | <glossdef> | ||
2459 | <para> | ||
2460 | The list of additional features to include in an image. | ||
2461 | Typically, you configure this variable in your | ||
2462 | <filename>local.conf</filename> file, which is found in the | ||
2463 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
2464 | Although you can use this variable from within a recipe, | ||
2465 | best practices dictate that you do not. | ||
2466 | <note> | ||
2467 | To enable primary features from within the image | ||
2468 | recipe, use the | ||
2469 | <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> | ||
2470 | variable. | ||
2471 | </note> | ||
2472 | </para> | ||
2473 | |||
2474 | <para> | ||
2475 | Here are some examples of features you can add: | ||
2476 | <literallayout class='monospaced'> | ||
2477 | "dbg-pkgs" - Adds -dbg packages for all installed packages | ||
2478 | including symbol information for debugging and | ||
2479 | profiling. | ||
2480 | |||
2481 | "debug-tweaks" - Makes an image suitable for development. | ||
2482 | For example, ssh root access has a blank | ||
2483 | password. You should remove this feature | ||
2484 | before you produce a production image. | ||
2485 | |||
2486 | "dev-pkgs" - Adds -dev packages for all installed packages. | ||
2487 | This is useful if you want to develop against | ||
2488 | the libraries in the image. | ||
2489 | |||
2490 | "read-only-rootfs" - Creates an image whose root | ||
2491 | filesystem is read-only. See the | ||
2492 | "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>" | ||
2493 | section in the Yocto Project | ||
2494 | Development Manual for more | ||
2495 | information | ||
2496 | |||
2497 | "tools-debug" - Adds debugging tools such as gdb and | ||
2498 | strace. | ||
2499 | |||
2500 | "tools-profile" - Adds profiling tools such as oprofile, | ||
2501 | exmap, lttng and valgrind (x86 only). | ||
2502 | |||
2503 | "tools-sdk" - Adds development tools such as gcc, make, | ||
2504 | pkgconfig and so forth. | ||
2505 | |||
2506 | "tools-testapps" - Adds useful testing tools such as | ||
2507 | ts_print, aplay, arecord and so | ||
2508 | forth. | ||
2509 | |||
2510 | </literallayout> | ||
2511 | </para> | ||
2512 | |||
2513 | <para> | ||
2514 | For a complete list of image features that ships with the | ||
2515 | Yocto Project, see the | ||
2516 | "<link linkend="ref-features-image">Image Features</link>" | ||
2517 | section. | ||
2518 | </para> | ||
2519 | |||
2520 | <para> | ||
2521 | For an example that shows how to customize your image by | ||
2522 | using this variable, see the | ||
2523 | "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>" | ||
2524 | section in the Yocto Project Development Manual. | ||
2525 | </para> | ||
2526 | </glossdef> | ||
2527 | </glossentry> | ||
2528 | |||
2529 | <glossentry id='var-EXTRA_IMAGECMD'><glossterm>EXTRA_IMAGECMD</glossterm> | ||
2530 | <glossdef> | ||
2531 | <para> | ||
2532 | Specifies additional options for the image | ||
2533 | creation command that has been specified in | ||
2534 | <link linkend='var-IMAGE_CMD'><filename>IMAGE_CMD</filename></link>. | ||
2535 | When setting this variable, you should | ||
2536 | use an override for the associated type. | ||
2537 | Here is an example: | ||
2538 | <literallayout class='monospaced'> | ||
2539 | EXTRA_IMAGECMD_ext3 ?= "-i 4096" | ||
2540 | </literallayout> | ||
2541 | </para> | ||
2542 | </glossdef> | ||
2543 | </glossentry> | ||
2544 | |||
2545 | <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm> | ||
2546 | <glossdef> | ||
2547 | <para>A list of recipes to build that do not provide packages | ||
2548 | for installing into the root filesystem. | ||
2549 | </para> | ||
2550 | <para>Sometimes a recipe is required to build the final image but is not | ||
2551 | needed in the root filesystem. | ||
2552 | You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to | ||
2553 | list these recipes and thus specify the dependencies. | ||
2554 | A typical example is a required bootloader in a machine configuration. | ||
2555 | </para> | ||
2556 | <note> | ||
2557 | To add packages to the root filesystem, see the various | ||
2558 | <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename> | ||
2559 | and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename> | ||
2560 | variables. | ||
2561 | </note> | ||
2562 | </glossdef> | ||
2563 | </glossentry> | ||
2564 | |||
2565 | <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm> | ||
2566 | <glossdef> | ||
2567 | <para>Additional <filename>cmake</filename> options.</para> | ||
2568 | </glossdef> | ||
2569 | </glossentry> | ||
2570 | |||
2571 | <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm> | ||
2572 | <glossdef> | ||
2573 | <para>Additional <filename>configure</filename> script options.</para> | ||
2574 | </glossdef> | ||
2575 | </glossentry> | ||
2576 | |||
2577 | <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm> | ||
2578 | <glossdef> | ||
2579 | <para>Additional GNU <filename>make</filename> options.</para> | ||
2580 | </glossdef> | ||
2581 | </glossentry> | ||
2582 | |||
2583 | <glossentry id='var-EXTRA_OESCONS'><glossterm>EXTRA_OESCONS</glossterm> | ||
2584 | <glossdef> | ||
2585 | <para> | ||
2586 | When inheriting the | ||
2587 | <link linkend='ref-classes-scons'><filename>scons</filename></link> | ||
2588 | class, this variable specifies additional configuration | ||
2589 | options you want to pass to the | ||
2590 | <filename>scons</filename> command line. | ||
2591 | </para> | ||
2592 | </glossdef> | ||
2593 | </glossentry> | ||
2594 | |||
2595 | <glossentry id='var-EXTRA_QMAKEVARS_POST'><glossterm>EXTRA_QMAKEVARS_POST</glossterm> | ||
2596 | <glossdef> | ||
2597 | <para> | ||
2598 | Configuration variables or options you want to pass to | ||
2599 | <filename>qmake</filename>. | ||
2600 | Use this variable when the arguments need to be after the | ||
2601 | <filename>.pro</filename> file list on the command line. | ||
2602 | </para> | ||
2603 | |||
2604 | <para> | ||
2605 | This variable is used with recipes that inherit the | ||
2606 | <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link> | ||
2607 | class or other classes that inherit | ||
2608 | <filename>qmake_base</filename>. | ||
2609 | </para> | ||
2610 | </glossdef> | ||
2611 | </glossentry> | ||
2612 | |||
2613 | <glossentry id='var-EXTRA_QMAKEVARS_PRE'><glossterm>EXTRA_QMAKEVARS_PRE</glossterm> | ||
2614 | <glossdef> | ||
2615 | <para> | ||
2616 | Configuration variables or options you want to pass to | ||
2617 | <filename>qmake</filename>. | ||
2618 | Use this variable when the arguments need to be before the | ||
2619 | <filename>.pro</filename> file list on the command line. | ||
2620 | </para> | ||
2621 | |||
2622 | <para> | ||
2623 | This variable is used with recipes that inherit the | ||
2624 | <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link> | ||
2625 | class or other classes that inherit | ||
2626 | <filename>qmake_base</filename>. | ||
2627 | </para> | ||
2628 | </glossdef> | ||
2629 | </glossentry> | ||
2630 | |||
2631 | <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm> | ||
2632 | <glossdef> | ||
2633 | <para> | ||
2634 | When inheriting the | ||
2635 | <link linkend='ref-classes-extrausers'><filename>extrausers</filename></link> | ||
2636 | class, this variable provides image level user and group | ||
2637 | operations. | ||
2638 | This is a more global method of providing user and group | ||
2639 | configuration as compared to using the | ||
2640 | <link linkend='ref-classes-useradd'><filename>useradd</filename></link> | ||
2641 | class, which ties user and group configurations to a | ||
2642 | specific recipe. | ||
2643 | </para> | ||
2644 | |||
2645 | <para> | ||
2646 | The set list of commands you can configure using the | ||
2647 | <filename>EXTRA_USERS_PARAMS</filename> is shown in the | ||
2648 | <filename>extrausers</filename> class. | ||
2649 | These commands map to the normal Unix commands of the same | ||
2650 | names: | ||
2651 | <literallayout class='monospaced'> | ||
2652 | # EXTRA_USERS_PARAMS = "\ | ||
2653 | # useradd -p '' tester; \ | ||
2654 | # groupadd developers; \ | ||
2655 | # userdel nobody; \ | ||
2656 | # groupdel -g video; \ | ||
2657 | # groupmod -g 1020 developers; \ | ||
2658 | # usermod -s /bin/sh tester; \ | ||
2659 | # " | ||
2660 | </literallayout> | ||
2661 | </para> | ||
2662 | </glossdef> | ||
2663 | </glossentry> | ||
2664 | |||
2665 | </glossdiv> | ||
2666 | |||
2667 | <glossdiv id='var-glossary-f'><title>F</title> | ||
2668 | |||
2669 | <glossentry id='var-FEATURE_PACKAGES'><glossterm>FEATURE_PACKAGES</glossterm> | ||
2670 | <glossdef> | ||
2671 | <para> | ||
2672 | Defines one or more packages to include in an image when | ||
2673 | a specific item is included in | ||
2674 | <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>. | ||
2675 | When setting the value, <filename>FEATURE_PACKAGES</filename> | ||
2676 | should have the name of the feature item as an override. | ||
2677 | Here is an example: | ||
2678 | <literallayout class='monospaced'> | ||
2679 | FEATURE_PACKAGES_widget = "<replaceable>package1</replaceable> <replaceable>package2</replaceable>" | ||
2680 | </literallayout> | ||
2681 | In this example, if "widget" were added to | ||
2682 | <filename>IMAGE_FEATURES</filename>, <replaceable>package1</replaceable> and | ||
2683 | <replaceable>package2</replaceable> would be included in the image. | ||
2684 | <note> | ||
2685 | Packages installed by features defined through | ||
2686 | <filename>FEATURE_PACKAGES</filename> are often package | ||
2687 | groups. | ||
2688 | While similarly named, you should not confuse the | ||
2689 | <filename>FEATURE_PACKAGES</filename> variable with | ||
2690 | package groups, which are discussed elsewhere in the | ||
2691 | documentation. | ||
2692 | </note> | ||
2693 | </para> | ||
2694 | </glossdef> | ||
2695 | </glossentry> | ||
2696 | |||
2697 | <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm> | ||
2698 | <glossdef> | ||
2699 | <para> | ||
2700 | Points to the base URL of the server and location within | ||
2701 | the document-root that provides the metadata and | ||
2702 | packages required by OPKG to support runtime package | ||
2703 | management of IPK packages. | ||
2704 | You set this variable in your | ||
2705 | <filename>local.conf</filename> file. | ||
2706 | </para> | ||
2707 | |||
2708 | <para> | ||
2709 | Consider the following example: | ||
2710 | <literallayout class='monospaced'> | ||
2711 | FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir" | ||
2712 | </literallayout> | ||
2713 | This example assumes you are serving your packages over | ||
2714 | HTTP and your databases are located in a directory | ||
2715 | named <filename>BOARD-dir</filename>, which is underneath | ||
2716 | your HTTP server's document-root. | ||
2717 | In this case, the OpenEmbedded build system generates a set | ||
2718 | of configuration files for you in your target that work | ||
2719 | with the feed. | ||
2720 | </para> | ||
2721 | </glossdef> | ||
2722 | </glossentry> | ||
2723 | |||
2724 | <glossentry id='var-FILES'><glossterm>FILES</glossterm> | ||
2725 | <glossdef> | ||
2726 | <para> | ||
2727 | The list of directories or files that are placed in packages. | ||
2728 | </para> | ||
2729 | |||
2730 | <para> | ||
2731 | To use the <filename>FILES</filename> variable, provide a | ||
2732 | package name override that identifies the resulting package. | ||
2733 | Then, provide a space-separated list of files or paths | ||
2734 | that identify the files you want included as part of the | ||
2735 | resulting package. | ||
2736 | Here is an example: | ||
2737 | <literallayout class='monospaced'> | ||
2738 | FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile" | ||
2739 | </literallayout> | ||
2740 | </para> | ||
2741 | |||
2742 | <note> | ||
2743 | When specifying paths as part of the | ||
2744 | <filename>FILES</filename> variable, it is good practice | ||
2745 | to use appropriate path variables. | ||
2746 | For example, use <filename>${sysconfdir}</filename> rather | ||
2747 | than <filename>/etc</filename>, or | ||
2748 | <filename>${bindir}</filename> rather than | ||
2749 | <filename>/usr/bin</filename>. | ||
2750 | You can find a list of these variables at the top of the | ||
2751 | <filename>meta/conf/bitbake.conf</filename> file in the | ||
2752 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | ||
2753 | </note> | ||
2754 | |||
2755 | <para> | ||
2756 | If some of the files you provide with the | ||
2757 | <filename>FILES</filename> variable are editable and you | ||
2758 | know they should not be overwritten during the package | ||
2759 | update process by the Package Management System (PMS), you | ||
2760 | can identify these files so that the PMS will not | ||
2761 | overwrite them. | ||
2762 | See the | ||
2763 | <link linkend='var-CONFFILES'><filename>CONFFILES</filename></link> | ||
2764 | variable for information on how to identify these files to | ||
2765 | the PMS. | ||
2766 | </para> | ||
2767 | |||
2768 | </glossdef> | ||
2769 | </glossentry> | ||
2770 | |||
2771 | <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm> | ||
2772 | <glossdef> | ||
2773 | <para> | ||
2774 | Extends the search path the OpenEmbedded build system uses | ||
2775 | when looking for files and patches as it processes recipes | ||
2776 | and append files. | ||
2777 | The default directories BitBake uses when it processes | ||
2778 | recipes are initially defined by the | ||
2779 | <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> | ||
2780 | variable. | ||
2781 | You can extend <filename>FILESPATH</filename> variable | ||
2782 | by using <filename>FILESEXTRAPATHS</filename>. | ||
2783 | </para> | ||
2784 | |||
2785 | <para> | ||
2786 | Best practices dictate that you accomplish this by using | ||
2787 | <filename>FILESEXTRAPATHS</filename> from within a | ||
2788 | <filename>.bbappend</filename> file and that you prepend | ||
2789 | paths as follows: | ||
2790 | <literallayout class='monospaced'> | ||
2791 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
2792 | </literallayout> | ||
2793 | In the above example, the build system first looks for files | ||
2794 | in a directory that has the same name as the corresponding | ||
2795 | append file. | ||
2796 | <note> | ||
2797 | <para>When extending <filename>FILESEXTRAPATHS</filename>, | ||
2798 | be sure to use the immediate expansion | ||
2799 | (<filename>:=</filename>) operator. | ||
2800 | Immediate expansion makes sure that BitBake evaluates | ||
2801 | <link linkend='var-THISDIR'><filename>THISDIR</filename></link> | ||
2802 | at the time the directive is encountered rather than at | ||
2803 | some later time when expansion might result in a | ||
2804 | directory that does not contain the files you need. | ||
2805 | </para> | ||
2806 | <para>Also, include the trailing separating colon | ||
2807 | character if you are prepending. | ||
2808 | The trailing colon character is necessary because you | ||
2809 | are directing BitBake to extend the path by prepending | ||
2810 | directories to the search path.</para> | ||
2811 | </note> | ||
2812 | Here is another common use: | ||
2813 | <literallayout class='monospaced'> | ||
2814 | FILESEXTRAPATHS_prepend := "${THISDIR}/files:" | ||
2815 | </literallayout> | ||
2816 | In this example, the build system extends the | ||
2817 | <filename>FILESPATH</filename> variable to include a | ||
2818 | directory named <filename>files</filename> that is in the | ||
2819 | same directory as the corresponding append file. | ||
2820 | </para> | ||
2821 | |||
2822 | <para> | ||
2823 | Here is a final example that specifically adds three paths: | ||
2824 | <literallayout class='monospaced'> | ||
2825 | FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" | ||
2826 | </literallayout> | ||
2827 | </para> | ||
2828 | |||
2829 | <para> | ||
2830 | By prepending paths in <filename>.bbappend</filename> | ||
2831 | files, you allow multiple append files that reside in | ||
2832 | different layers but are used for the same recipe to | ||
2833 | correctly extend the path. | ||
2834 | </para> | ||
2835 | </glossdef> | ||
2836 | </glossentry> | ||
2837 | |||
2838 | <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm> | ||
2839 | <glossdef> | ||
2840 | <para> | ||
2841 | A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> | ||
2842 | used by the OpenEmbedded build system for creating | ||
2843 | <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>. | ||
2844 | You can find more information on how overrides are handled | ||
2845 | in the | ||
2846 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake Manual</ulink>. | ||
2847 | </para> | ||
2848 | |||
2849 | <para> | ||
2850 | By default, the <filename>FILESOVERRIDES</filename> | ||
2851 | variable is defined as: | ||
2852 | <literallayout class='monospaced'> | ||
2853 | FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}" | ||
2854 | </literallayout> | ||
2855 | |||
2856 | <note> | ||
2857 | Do not hand-edit the <filename>FILESOVERRIDES</filename> | ||
2858 | variable. | ||
2859 | The values match up with expected overrides and are | ||
2860 | used in an expected manner by the build system. | ||
2861 | </note> | ||
2862 | </para> | ||
2863 | </glossdef> | ||
2864 | </glossentry> | ||
2865 | |||
2866 | <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm> | ||
2867 | <glossdef> | ||
2868 | <para> | ||
2869 | The default set of directories the OpenEmbedded build system | ||
2870 | uses when searching for patches and files. | ||
2871 | During the build process, BitBake searches each directory in | ||
2872 | <filename>FILESPATH</filename> in the specified order when | ||
2873 | looking for files and patches specified by each | ||
2874 | <filename>file://</filename> URI in a recipe. | ||
2875 | </para> | ||
2876 | |||
2877 | <para> | ||
2878 | The default value for the <filename>FILESPATH</filename> | ||
2879 | variable is defined in the <filename>base.bbclass</filename> | ||
2880 | class found in <filename>meta/classes</filename> in the | ||
2881 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: | ||
2882 | <literallayout class='monospaced'> | ||
2883 | FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \ | ||
2884 | "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" | ||
2885 | </literallayout> | ||
2886 | <note> | ||
2887 | Do not hand-edit the <filename>FILESPATH</filename> | ||
2888 | variable. | ||
2889 | If you want the build system to look in directories | ||
2890 | other than the defaults, extend the | ||
2891 | <filename>FILESPATH</filename> variable by using the | ||
2892 | <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link> | ||
2893 | variable. | ||
2894 | </note> | ||
2895 | Be aware that the default <filename>FILESPATH</filename> | ||
2896 | directories do not map to directories in custom layers | ||
2897 | where append files (<filename>.bbappend</filename>) | ||
2898 | are used. | ||
2899 | If you want the build system to find patches or files | ||
2900 | that reside with your append files, you need to extend | ||
2901 | the <filename>FILESPATH</filename> variable by using | ||
2902 | the | ||
2903 | <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link> | ||
2904 | variable. | ||
2905 | </para> | ||
2906 | </glossdef> | ||
2907 | </glossentry> | ||
2908 | |||
2909 | <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm> | ||
2910 | <glossdef> | ||
2911 | <para>Allows you to define your own file permissions settings table as part of | ||
2912 | your configuration for the packaging process. | ||
2913 | For example, suppose you need a consistent set of custom permissions for | ||
2914 | a set of groups and users across an entire work project. | ||
2915 | It is best to do this in the packages themselves but this is not always | ||
2916 | possible. | ||
2917 | </para> | ||
2918 | <para> | ||
2919 | By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which | ||
2920 | is located in the <filename>meta/files</filename> folder in the | ||
2921 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | ||
2922 | If you create your own file permissions setting table, you should place it in your | ||
2923 | layer or the distro's layer. | ||
2924 | </para> | ||
2925 | <para> | ||
2926 | You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the | ||
2927 | <filename>conf/local.conf</filename> file, which is found in the | ||
2928 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to | ||
2929 | point to your custom <filename>fs-perms.txt</filename>. | ||
2930 | You can specify more than a single file permissions setting table. | ||
2931 | The paths you specify to these files must be defined within the | ||
2932 | <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable. | ||
2933 | </para> | ||
2934 | <para> | ||
2935 | For guidance on how to create your own file permissions settings table file, | ||
2936 | examine the existing <filename>fs-perms.txt</filename>. | ||
2937 | </para> | ||
2938 | </glossdef> | ||
2939 | </glossentry> | ||
2940 | |||
2941 | <glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm> | ||
2942 | <glossdef> | ||
2943 | <para> | ||
2944 | When inheriting the | ||
2945 | <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link> | ||
2946 | class, this variable identifies packages containing font | ||
2947 | files that need to be cached by Fontconfig. | ||
2948 | By default, the <filename>fontcache</filename> class assumes | ||
2949 | that fonts are in the recipe's main package | ||
2950 | (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>). | ||
2951 | Use this variable if fonts you need are in a package | ||
2952 | other than that main package. | ||
2953 | </para> | ||
2954 | </glossdef> | ||
2955 | </glossentry> | ||
2956 | |||
2957 | <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm> | ||
2958 | <glossdef> | ||
2959 | <para> | ||
2960 | The options to pass in | ||
2961 | <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename> | ||
2962 | and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> | ||
2963 | when compiling an optimized system. | ||
2964 | This variable defaults to | ||
2965 | "-O2 -pipe ${DEBUG_FLAGS}". | ||
2966 | </para> | ||
2967 | </glossdef> | ||
2968 | </glossentry> | ||
2969 | </glossdiv> | ||
2970 | |||
2971 | <glossdiv id='var-glossary-g'><title>G</title> | ||
2972 | |||
2973 | <glossentry id='var-GLIBC_GENERATE_LOCALES'><glossterm>GLIBC_GENERATE_LOCALES</glossterm> | ||
2974 | <glossdef> | ||
2975 | <para> | ||
2976 | Specifies the list of GLIBC locales to generate should you | ||
2977 | not wish generate all LIBC locals, which can be time | ||
2978 | consuming. | ||
2979 | <note> | ||
2980 | If you specifically remove the locale | ||
2981 | <filename>en_US.UTF-8</filename>, you must set | ||
2982 | <link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link> | ||
2983 | appropriately. | ||
2984 | </note> | ||
2985 | You can set <filename>GLIBC_GENERATE_LOCALES</filename> | ||
2986 | in your <filename>local.conf</filename> file. | ||
2987 | By default, all locales are generated. | ||
2988 | <literallayout class='monospaced'> | ||
2989 | GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" | ||
2990 | </literallayout> | ||
2991 | </para> | ||
2992 | </glossdef> | ||
2993 | </glossentry> | ||
2994 | |||
2995 | <glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm> | ||
2996 | <glossdef> | ||
2997 | <para> | ||
2998 | When inheriting the | ||
2999 | <link linkend='ref-classes-useradd'><filename>useradd</filename></link> | ||
3000 | class, this variable | ||
3001 | specifies for a package what parameters should be passed | ||
3002 | to the <filename>groupadd</filename> command | ||
3003 | if you wish to add a group to the system when the package | ||
3004 | is installed. | ||
3005 | </para> | ||
3006 | |||
3007 | <para> | ||
3008 | Here is an example from the <filename>dbus</filename> | ||
3009 | recipe: | ||
3010 | <literallayout class='monospaced'> | ||
3011 | GROUPADD_PARAM_${PN} = "-r netdev" | ||
3012 | </literallayout> | ||
3013 | For information on the standard Linux shell command | ||
3014 | <filename>groupadd</filename>, see | ||
3015 | <ulink url='http://linux.die.net/man/8/groupadd'></ulink>. | ||
3016 | </para> | ||
3017 | </glossdef> | ||
3018 | </glossentry> | ||
3019 | |||
3020 | <glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm> | ||
3021 | <glossdef> | ||
3022 | <para> | ||
3023 | When inheriting the | ||
3024 | <link linkend='ref-classes-useradd'><filename>useradd</filename></link> | ||
3025 | class, this variable | ||
3026 | specifies for a package what parameters should be passed | ||
3027 | to the <filename>groupmems</filename> command | ||
3028 | if you wish to modify the members of a group when the | ||
3029 | package is installed. | ||
3030 | </para> | ||
3031 | |||
3032 | <para> | ||
3033 | For information on the standard Linux shell command | ||
3034 | <filename>groupmems</filename>, see | ||
3035 | <ulink url='http://linux.die.net/man/8/groupmems'></ulink>. | ||
3036 | </para> | ||
3037 | </glossdef> | ||
3038 | </glossentry> | ||
3039 | |||
3040 | <glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm> | ||
3041 | <glossdef> | ||
3042 | <para> | ||
3043 | Configures the GNU GRand Unified Bootloader (GRUB) to have | ||
3044 | graphics and serial in the boot menu. | ||
3045 | Set this variable to "1" in your | ||
3046 | <filename>local.conf</filename> or distribution | ||
3047 | configuration file to enable graphics and serial | ||
3048 | in the menu. | ||
3049 | </para> | ||
3050 | |||
3051 | <para> | ||
3052 | See the | ||
3053 | <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link> | ||
3054 | class for more information on how this variable is used. | ||
3055 | </para> | ||
3056 | </glossdef> | ||
3057 | </glossentry> | ||
3058 | |||
3059 | <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm> | ||
3060 | <glossdef> | ||
3061 | <para> | ||
3062 | Additional options to add to the GNU GRand Unified | ||
3063 | Bootloader (GRUB) configuration. | ||
3064 | Use a semi-colon character (<filename>;</filename>) to | ||
3065 | separate multiple options. | ||
3066 | </para> | ||
3067 | |||
3068 | <para> | ||
3069 | The <filename>GRUB_OPTS</filename> variable is optional. | ||
3070 | See the | ||
3071 | <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link> | ||
3072 | class for more information on how this variable is used. | ||
3073 | </para> | ||
3074 | </glossdef> | ||
3075 | </glossentry> | ||
3076 | |||
3077 | <glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm> | ||
3078 | <glossdef> | ||
3079 | <para> | ||
3080 | Specifies the timeout before executing the default | ||
3081 | <filename>LABEL</filename> in the GNU GRand Unified | ||
3082 | Bootloader (GRUB). | ||
3083 | </para> | ||
3084 | |||
3085 | <para> | ||
3086 | The <filename>GRUB_TIMEOUT</filename> variable is optional. | ||
3087 | See the | ||
3088 | <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link> | ||
3089 | class for more information on how this variable is used. | ||
3090 | </para> | ||
3091 | </glossdef> | ||
3092 | </glossentry> | ||
3093 | |||
3094 | <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm> | ||
3095 | <glossdef> | ||
3096 | <para> | ||
3097 | When inheriting the | ||
3098 | <link linkend='ref-classes-gtk-immodules-cache'><filename>gtk-immodules-cache</filename></link> | ||
3099 | class, this variable specifies the packages that contain the | ||
3100 | GTK+ input method modules being installed when the modules | ||
3101 | are in packages other than the main package. | ||
3102 | </para> | ||
3103 | </glossdef> | ||
3104 | </glossentry> | ||
3105 | |||
3106 | <glossentry id='var-GUMMIBOOT_CFG'><glossterm>GUMMIBOOT_CFG</glossterm> | ||
3107 | <glossdef> | ||
3108 | <para> | ||
3109 | When | ||
3110 | <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> | ||
3111 | is set to "gummiboot", the | ||
3112 | <filename>GUMMIBOOT_CFG</filename> variable specifies the | ||
3113 | configuration file that should be used. | ||
3114 | By default, the | ||
3115 | <link linkend='ref-classes-gummiboot'><filename>gummiboot</filename></link> | ||
3116 | class sets the <filename>GUMMIBOOT_CFG</filename> as | ||
3117 | follows: | ||
3118 | <literallayout class='monospaced'> | ||
3119 | GUMMIBOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf" | ||
3120 | </literallayout> | ||
3121 | </para> | ||
3122 | |||
3123 | <para> | ||
3124 | For information on Gummiboot, see the | ||
3125 | <ulink url='http://freedesktop.org/wiki/Software/gummiboot/'>Gummiboot documentation</ulink>. | ||
3126 | </para> | ||
3127 | </glossdef> | ||
3128 | </glossentry> | ||
3129 | |||
3130 | <glossentry id='var-GUMMIBOOT_ENTRIES'><glossterm>GUMMIBOOT_ENTRIES</glossterm> | ||
3131 | <glossdef> | ||
3132 | <para> | ||
3133 | When | ||
3134 | <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> | ||
3135 | is set to "gummiboot", the | ||
3136 | <filename>GUMMIBOOT_ENTRIES</filename> variable specifies | ||
3137 | a list of entry files | ||
3138 | (<filename>*.conf</filename>) to be installed | ||
3139 | containing one boot entry per file. | ||
3140 | By default, the | ||
3141 | <link linkend='ref-classes-gummiboot'><filename>gummiboot</filename></link> | ||
3142 | class sets the <filename>GUMMIBOOT_ENTRIES</filename> as | ||
3143 | follows: | ||
3144 | <literallayout class='monospaced'> | ||
3145 | GUMMIBOOT_ENTRIES ?= "" | ||
3146 | </literallayout> | ||
3147 | </para> | ||
3148 | |||
3149 | <para> | ||
3150 | For information on Gummiboot, see the | ||
3151 | <ulink url='http://freedesktop.org/wiki/Software/gummiboot/'>Gummiboot documentation</ulink>. | ||
3152 | </para> | ||
3153 | </glossdef> | ||
3154 | </glossentry> | ||
3155 | |||
3156 | <glossentry id='var-GUMMIBOOT_TIMEOUT'><glossterm>GUMMIBOOT_TIMEOUT</glossterm> | ||
3157 | <glossdef> | ||
3158 | <para> | ||
3159 | When | ||
3160 | <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> | ||
3161 | is set to "gummiboot", the | ||
3162 | <filename>GUMMIBOOT_TIMEOUT</filename> variable specifies | ||
3163 | the boot menu timeout in seconds. | ||
3164 | By default, the | ||
3165 | <link linkend='ref-classes-gummiboot'><filename>gummiboot</filename></link> | ||
3166 | class sets the <filename>GUMMIBOOT_TIMEOUT</filename> as | ||
3167 | follows: | ||
3168 | <literallayout class='monospaced'> | ||
3169 | GUMMIBOOT_TIMEOUT ?= "10" | ||
3170 | </literallayout> | ||
3171 | </para> | ||
3172 | |||
3173 | <para> | ||
3174 | For information on Gummiboot, see the | ||
3175 | <ulink url='http://freedesktop.org/wiki/Software/gummiboot/'>Gummiboot documentation</ulink>. | ||
3176 | </para> | ||
3177 | </glossdef> | ||
3178 | </glossentry> | ||
3179 | |||
3180 | </glossdiv> | ||
3181 | |||
3182 | <glossdiv id='var-glossary-h'><title>H</title> | ||
3183 | |||
3184 | <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm> | ||
3185 | <glossdef> | ||
3186 | <para>Website where more information about the software the recipe is building | ||
3187 | can be found.</para> | ||
3188 | </glossdef> | ||
3189 | </glossentry> | ||
3190 | |||
3191 | <glossentry id='var-HOST_CC_ARCH'><glossterm>HOST_CC_ARCH</glossterm> | ||
3192 | <glossdef> | ||
3193 | <para> | ||
3194 | Specifies architecture-specific compiler flags that are | ||
3195 | passed to the C compiler. | ||
3196 | </para> | ||
3197 | |||
3198 | <para> | ||
3199 | Default initialization for <filename>HOST_CC_ARCH</filename> | ||
3200 | varies depending on what is being built: | ||
3201 | <itemizedlist> | ||
3202 | <listitem><para> | ||
3203 | <link linkend='var-TARGET_CC_ARCH'><filename>TARGET_CC_ARCH</filename></link> | ||
3204 | when building for the target | ||
3205 | </para></listitem> | ||
3206 | <listitem><para> | ||
3207 | <filename>BUILD_CC_ARCH</filename> | ||
3208 | when building for the build host (i.e. | ||
3209 | <filename>native</filename>) | ||
3210 | </para></listitem> | ||
3211 | <listitem><para> | ||
3212 | <filename>BUILDSDK_CC_ARCH</filename> | ||
3213 | when building for an SDK (i.e. | ||
3214 | <filename>nativesdk</filename>) | ||
3215 | </para></listitem> | ||
3216 | </itemizedlist> | ||
3217 | </para> | ||
3218 | </glossdef> | ||
3219 | </glossentry> | ||
3220 | |||
3221 | <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm> | ||
3222 | <glossdef> | ||
3223 | <para> | ||
3224 | Specifies the system, including the architecture and the | ||
3225 | operating system, for with the build is occurring | ||
3226 | in the context of the current | ||
3227 | recipe. | ||
3228 | The OpenEmbedded build system automatically sets this | ||
3229 | variable. | ||
3230 | You do not need to set the variable yourself. | ||
3231 | </para> | ||
3232 | |||
3233 | <para> | ||
3234 | Here are two examples: | ||
3235 | <itemizedlist> | ||
3236 | <listitem><para>Given a native recipe on a 32-bit | ||
3237 | x86 machine running Linux, the value is | ||
3238 | "i686-linux". | ||
3239 | </para></listitem> | ||
3240 | <listitem><para>Given a recipe being built for a | ||
3241 | little-endian MIPS target running Linux, | ||
3242 | the value might be "mipsel-linux". | ||
3243 | </para></listitem> | ||
3244 | </itemizedlist> | ||
3245 | </para> | ||
3246 | </glossdef> | ||
3247 | </glossentry> | ||
3248 | |||
3249 | </glossdiv> | ||
3250 | |||
3251 | <glossdiv id='var-glossary-i'><title>I</title> | ||
3252 | |||
3253 | <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm> | ||
3254 | <glossdef> | ||
3255 | <para> | ||
3256 | Disables or enables the <filename>icecc</filename> | ||
3257 | (Icecream) function. | ||
3258 | For more information on this function and best practices | ||
3259 | for using this variable, see the | ||
3260 | "<link linkend='ref-classes-icecc'><filename>icecc.bbclass</filename></link>" | ||
3261 | section. | ||
3262 | </para> | ||
3263 | |||
3264 | <para> | ||
3265 | Setting this variable to "1" in your | ||
3266 | <filename>local.conf</filename> disables the function: | ||
3267 | <literallayout class='monospaced'> | ||
3268 | ICECC_DISABLED ??= "1" | ||
3269 | </literallayout> | ||
3270 | To enable the function, set the variable as follows: | ||
3271 | <literallayout class='monospaced'> | ||
3272 | ICECC_DISABLED = "" | ||
3273 | </literallayout> | ||
3274 | </para> | ||
3275 | </glossdef> | ||
3276 | </glossentry> | ||
3277 | |||
3278 | <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm> | ||
3279 | <glossdef> | ||
3280 | <para> | ||
3281 | Points to the <filename>icecc-create-env</filename> script | ||
3282 | that you provide. | ||
3283 | This variable is used by the | ||
3284 | <link linkend='ref-classes-icecc'><filename>icecc</filename></link> | ||
3285 | class. | ||
3286 | You set this variable in your | ||
3287 | <filename>local.conf</filename> file. | ||
3288 | </para> | ||
3289 | |||
3290 | <para> | ||
3291 | If you do not point to a script that you provide, the | ||
3292 | OpenEmbedded build system uses the default script provided | ||
3293 | by the <filename>icecc-create-env.bb</filename> recipe, | ||
3294 | which is a modified version and not the one that comes with | ||
3295 | <filename>icecc</filename>. | ||
3296 | </para> | ||
3297 | </glossdef> | ||
3298 | </glossentry> | ||
3299 | |||
3300 | <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm> | ||
3301 | <glossdef> | ||
3302 | <para> | ||
3303 | Extra options passed to the <filename>make</filename> | ||
3304 | command during the | ||
3305 | <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> | ||
3306 | task that specify parallel compilation. | ||
3307 | This variable usually takes the form of | ||
3308 | <filename>-j 4</filename>, where the number | ||
3309 | represents the maximum number of parallel threads | ||
3310 | <filename>make</filename> can run. | ||
3311 | <note> | ||
3312 | The options passed affect builds on all enabled | ||
3313 | machines on the network, which are machines running the | ||
3314 | <filename>iceccd</filename> daemon. | ||
3315 | </note> | ||
3316 | </para> | ||
3317 | |||
3318 | <para> | ||
3319 | If your enabled machines support multiple cores, | ||
3320 | coming up with the maximum number of parallel threads | ||
3321 | that gives you the best performance could take some | ||
3322 | experimentation since machine speed, network lag, | ||
3323 | available memory, and existing machine loads can all | ||
3324 | affect build time. | ||
3325 | Consequently, unlike the | ||
3326 | <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link> | ||
3327 | variable, there is no rule-of-thumb for setting | ||
3328 | <filename>ICECC_PARALLEL_MAKE</filename> to achieve | ||
3329 | optimal performance. | ||
3330 | </para> | ||
3331 | |||
3332 | <para> | ||
3333 | If you do not set <filename>ICECC_PARALLEL_MAKE</filename>, | ||
3334 | the build system does not use it (i.e. the system does | ||
3335 | not detect and assign the number of cores as is done with | ||
3336 | <filename>PARALLEL_MAKE</filename>). | ||
3337 | </para> | ||
3338 | </glossdef> | ||
3339 | </glossentry> | ||
3340 | |||
3341 | <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm> | ||
3342 | <glossdef> | ||
3343 | <para> | ||
3344 | The location of the <filename>icecc</filename> binary. | ||
3345 | You can set this variable in your | ||
3346 | <filename>local.conf</filename> file. | ||
3347 | If your <filename>local.conf</filename> file does not define | ||
3348 | this variable, the | ||
3349 | <link linkend='ref-classes-icecc'><filename>icecc</filename></link> | ||
3350 | class attempts to define it by locating | ||
3351 | <filename>icecc</filename> using <filename>which</filename>. | ||
3352 | </para> | ||
3353 | </glossdef> | ||
3354 | </glossentry> | ||
3355 | |||
3356 | <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm> | ||
3357 | <glossdef> | ||
3358 | <para> | ||
3359 | Identifies user classes that you do not want the | ||
3360 | Icecream distributed compile support to consider. | ||
3361 | This variable is used by the | ||
3362 | <link linkend='ref-classes-icecc'><filename>icecc</filename></link> | ||
3363 | class. | ||
3364 | You set this variable in your | ||
3365 | <filename>local.conf</filename> file. | ||
3366 | </para> | ||
3367 | |||
3368 | <para> | ||
3369 | When you list classes using this variable, you are | ||
3370 | "blacklisting" them from distributed compilation across | ||
3371 | remote hosts. | ||
3372 | Any classes you list will be distributed and compiled | ||
3373 | locally. | ||
3374 | </para> | ||
3375 | </glossdef> | ||
3376 | </glossentry> | ||
3377 | |||
3378 | <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm> | ||
3379 | <glossdef> | ||
3380 | <para> | ||
3381 | Identifies user recipes that you do not want the | ||
3382 | Icecream distributed compile support to consider. | ||
3383 | This variable is used by the | ||
3384 | <link linkend='ref-classes-icecc'><filename>icecc</filename></link> | ||
3385 | class. | ||
3386 | You set this variable in your | ||
3387 | <filename>local.conf</filename> file. | ||
3388 | </para> | ||
3389 | |||
3390 | <para> | ||
3391 | When you list packages using this variable, you are | ||
3392 | "blacklisting" them from distributed compilation across | ||
3393 | remote hosts. | ||
3394 | Any packages you list will be distributed and compiled | ||
3395 | locally. | ||
3396 | </para> | ||
3397 | </glossdef> | ||
3398 | </glossentry> | ||
3399 | |||
3400 | <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm> | ||
3401 | <glossdef> | ||
3402 | <para> | ||
3403 | Identifies user recipes that use an empty | ||
3404 | <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link> | ||
3405 | variable that you want to force remote distributed | ||
3406 | compilation on using the Icecream distributed compile | ||
3407 | support. | ||
3408 | This variable is used by the | ||
3409 | <link linkend='ref-classes-icecc'><filename>icecc</filename></link> | ||
3410 | class. | ||
3411 | You set this variable in your | ||
3412 | <filename>local.conf</filename> file. | ||
3413 | </para> | ||
3414 | </glossdef> | ||
3415 | </glossentry> | ||
3416 | |||
3417 | <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm> | ||
3418 | <glossdef> | ||
3419 | <para> | ||
3420 | The base name of image output files. | ||
3421 | This variable defaults to the recipe name | ||
3422 | (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>). | ||
3423 | </para> | ||
3424 | </glossdef> | ||
3425 | </glossentry> | ||
3426 | |||
3427 | <glossentry id='var-IMAGE_BOOT_FILES'><glossterm>IMAGE_BOOT_FILES</glossterm> | ||
3428 | <glossdef> | ||
3429 | <para> | ||
3430 | A space-separated list of files installed into the | ||
3431 | boot partition when preparing an image. | ||
3432 | By default, the files are installed under the same name as | ||
3433 | the source files. | ||
3434 | To change the installed name, separate it from the | ||
3435 | original name with a semi-colon (;). | ||
3436 | Source files need to be located in | ||
3437 | <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>. | ||
3438 | Here are two examples: | ||
3439 | |||
3440 | <literallayout class="monospaced"> | ||
3441 | IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" | ||
3442 | IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" | ||
3443 | </literallayout></para> | ||
3444 | </glossdef> | ||
3445 | </glossentry> | ||
3446 | |||
3447 | <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm> | ||
3448 | <glossdef> | ||
3449 | <para> | ||
3450 | A list of classes that all images should inherit. | ||
3451 | You typically use this variable to specify the list of | ||
3452 | classes that register the different types of images | ||
3453 | the OpenEmbedded build system creates. | ||
3454 | </para> | ||
3455 | |||
3456 | <para> | ||
3457 | The default value for <filename>IMAGE_CLASSES</filename> is | ||
3458 | <filename>image_types</filename>. | ||
3459 | You can set this variable in your | ||
3460 | <filename>local.conf</filename> or in a distribution | ||
3461 | configuration file. | ||
3462 | </para> | ||
3463 | |||
3464 | <para> | ||
3465 | For more information, see | ||
3466 | <filename>meta/classes/image_types.bbclass</filename> in the | ||
3467 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | ||
3468 | </para> | ||
3469 | </glossdef> | ||
3470 | </glossentry> | ||
3471 | |||
3472 | <glossentry id='var-IMAGE_CMD'><glossterm>IMAGE_CMD</glossterm> | ||
3473 | <glossdef> | ||
3474 | <para> | ||
3475 | Specifies the command to create the image file for a | ||
3476 | specific image type, which corresponds to the value set | ||
3477 | set in | ||
3478 | <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>, | ||
3479 | (e.g. <filename>ext3</filename>, | ||
3480 | <filename>btrfs</filename>, and so forth). | ||
3481 | When setting this variable, you should use | ||
3482 | an override for the associated type. | ||
3483 | Here is an example: | ||
3484 | <literallayout class='monospaced'> | ||
3485 | IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \ | ||
3486 | --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \ | ||
3487 | ${EXTRA_IMAGECMD}" | ||
3488 | </literallayout> | ||
3489 | You typically do not need to set this variable unless | ||
3490 | you are adding support for a new image type. | ||
3491 | For more examples on how to set this variable, see the | ||
3492 | <link linkend='ref-classes-image_types'><filename>image_types</filename></link> | ||
3493 | class file, which is | ||
3494 | <filename>meta/classes/image_types.bbclass</filename>. | ||
3495 | </para> | ||
3496 | </glossdef> | ||
3497 | </glossentry> | ||
3498 | |||
3499 | <glossentry id='var-IMAGE_DEVICE_TABLES'><glossterm>IMAGE_DEVICE_TABLES</glossterm> | ||
3500 | <glossdef> | ||
3501 | <para> | ||
3502 | Specifies one or more files that contain custom device | ||
3503 | tables that are passed to the | ||
3504 | <filename>makedevs</filename> command as part of creating | ||
3505 | an image. | ||
3506 | These files list basic device nodes that should be | ||
3507 | created under <filename>/dev</filename> within the image. | ||
3508 | If <filename>IMAGE_DEVICE_TABLES</filename> is not set, | ||
3509 | <filename>files/device_table-minimal.txt</filename> is | ||
3510 | used, which is located by | ||
3511 | <link linkend='var-BBPATH'><filename>BBPATH</filename></link>. | ||
3512 | For details on how you should write device table files, | ||
3513 | see <filename>meta/files/device_table-minimal.txt</filename> | ||
3514 | as an example. | ||
3515 | </para> | ||
3516 | </glossdef> | ||
3517 | </glossentry> | ||
3518 | |||
3519 | <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm> | ||
3520 | <glossdef> | ||
3521 | <para> | ||
3522 | The primary list of features to include in an image. | ||
3523 | Typically, you configure this variable in an image recipe. | ||
3524 | Although you can use this variable from your | ||
3525 | <filename>local.conf</filename> file, which is found in the | ||
3526 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, | ||
3527 | best practices dictate that you do not. | ||
3528 | <note> | ||
3529 | To enable extra features from outside the image recipe, | ||
3530 | use the | ||
3531 | <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable. | ||
3532 | </note> | ||
3533 | For a list of image features that ships with the Yocto | ||
3534 | Project, see the | ||
3535 | "<link linkend="ref-features-image">Image Features</link>" | ||
3536 | section. | ||
3537 | </para> | ||
3538 | |||
3539 | <para> | ||
3540 | For an example that shows how to customize your image by | ||
3541 | using this variable, see the | ||
3542 | "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>" | ||
3543 | section in the Yocto Project Development Manual. | ||
3544 | </para> | ||
3545 | </glossdef> | ||
3546 | </glossentry> | ||
3547 | |||
3548 | <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm> | ||
3549 | <glossdef> | ||
3550 | <para> | ||
3551 | Specifies the formats the OpenEmbedded build system uses | ||
3552 | during the build when creating the root filesystem. | ||
3553 | For example, setting <filename>IMAGE_FSTYPES</filename> | ||
3554 | as follows causes the build system to create root | ||
3555 | filesystems using two formats: <filename>.ext3</filename> | ||
3556 | and <filename>.tar.bz2</filename>: | ||
3557 | <literallayout class='monospaced'> | ||
3558 | IMAGE_FSTYPES = "ext3 tar.bz2" | ||
3559 | </literallayout> | ||
3560 | For the complete list of supported image formats from which | ||
3561 | you can choose, see | ||
3562 | <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>. | ||
3563 | </para> | ||
3564 | |||
3565 | <note> | ||
3566 | If you add "live" to <filename>IMAGE_FSTYPES</filename> | ||
3567 | inside an image recipe, be sure that you do so prior to the | ||
3568 | "inherit image" line of the recipe or the live image will | ||
3569 | not build. | ||
3570 | </note> | ||
3571 | |||
3572 | <note> | ||
3573 | Due to the way this variable is processed, it is not | ||
3574 | possible to update its contents using | ||
3575 | <filename>_append</filename> or | ||
3576 | <filename>_prepend</filename>. To add one or more | ||
3577 | additional options to this variable the | ||
3578 | <filename>+=</filename> operator must be used. | ||
3579 | </note> | ||
3580 | </glossdef> | ||
3581 | </glossentry> | ||
3582 | |||
3583 | <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm> | ||
3584 | <glossdef> | ||
3585 | <para> | ||
3586 | Specifies the packages to install into an image. | ||
3587 | The <filename>IMAGE_INSTALL</filename> variable is a | ||
3588 | mechanism for an image recipe and you should use it | ||
3589 | with care to avoid ordering issues. | ||
3590 | <note> | ||
3591 | When working with an | ||
3592 | <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link> | ||
3593 | image, do not use the <filename>IMAGE_INSTALL</filename> | ||
3594 | variable to specify packages for installation. | ||
3595 | Instead, use the | ||
3596 | <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link> | ||
3597 | variable, which allows the initial RAM disk (initramfs) | ||
3598 | recipe to use a fixed set of packages and not be | ||
3599 | affected by <filename>IMAGE_INSTALL</filename>. | ||
3600 | </note> | ||
3601 | </para> | ||
3602 | |||
3603 | <para> | ||
3604 | Image recipes set <filename>IMAGE_INSTALL</filename> | ||
3605 | to specify the packages to install into an image through | ||
3606 | <filename>image.bbclass</filename>. | ||
3607 | Additionally, "helper" classes exist, such as | ||
3608 | <filename>core-image.bbclass</filename>, that can take | ||
3609 | <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> | ||
3610 | lists and turn these into auto-generated entries in | ||
3611 | <filename>IMAGE_INSTALL</filename> in addition to its | ||
3612 | default contents. | ||
3613 | </para> | ||
3614 | |||
3615 | <para> | ||
3616 | Using <filename>IMAGE_INSTALL</filename> with the | ||
3617 | <filename>+=</filename> operator from the | ||
3618 | <filename>/conf/local.conf</filename> file or from within | ||
3619 | an image recipe is not recommended as it can cause ordering | ||
3620 | issues. | ||
3621 | Since <filename>core-image.bbclass</filename> sets | ||
3622 | <filename>IMAGE_INSTALL</filename> to a default value using | ||
3623 | the <filename>?=</filename> operator, using a | ||
3624 | <filename>+=</filename> operation against | ||
3625 | <filename>IMAGE_INSTALL</filename> will result in | ||
3626 | unexpected behavior when used in | ||
3627 | <filename>conf/local.conf</filename>. | ||
3628 | Furthermore, the same operation from within an image | ||
3629 | recipe may or may not succeed depending on the specific | ||
3630 | situation. | ||
3631 | In both these cases, the behavior is contrary to how most | ||
3632 | users expect the <filename>+=</filename> operator to work. | ||
3633 | </para> | ||
3634 | |||
3635 | <para> | ||
3636 | When you use this variable, it is best to use it as follows: | ||
3637 | <literallayout class='monospaced'> | ||
3638 | IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>" | ||
3639 | </literallayout> | ||
3640 | Be sure to include the space between the quotation character | ||
3641 | and the start of the package name or names. | ||
3642 | </para> | ||
3643 | </glossdef> | ||
3644 | </glossentry> | ||
3645 | |||
3646 | <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm> | ||
3647 | <glossdef> | ||
3648 | <para> | ||
3649 | Specifies the list of locales to install into the image | ||
3650 | during the root filesystem construction process. | ||
3651 | The OpenEmbedded build system automatically splits locale | ||
3652 | files, which are used for localization, into separate | ||
3653 | packages. | ||
3654 | Setting the <filename>IMAGE_LINGUAS</filename> variable | ||
3655 | ensures that any locale packages that correspond to packages | ||
3656 | already selected for installation into the image are also | ||
3657 | installed. | ||
3658 | Here is an example: | ||
3659 | <literallayout class='monospaced'> | ||
3660 | IMAGE_LINGUAS = "pt-br de-de" | ||
3661 | </literallayout> | ||
3662 | In this example, the build system ensures any Brazilian | ||
3663 | Portuguese and German locale files that correspond to | ||
3664 | packages in the image are installed (i.e. | ||
3665 | <filename>*-locale-pt-br</filename> | ||
3666 | and <filename>*-locale-de-de</filename> as well as | ||
3667 | <filename>*-locale-pt</filename> | ||
3668 | and <filename>*-locale-de</filename>, since some software | ||
3669 | packages only provide locale files by language and not by | ||
3670 | country-specific language). | ||
3671 | </para> | ||
3672 | |||
3673 | <para> | ||
3674 | See the | ||
3675 | <link linkend='var-GLIBC_GENERATE_LOCALES'><filename>GLIBC_GENERATE_LOCALES</filename></link> | ||
3676 | variable for information on generating GLIBC locales. | ||
3677 | </para> | ||
3678 | </glossdef> | ||
3679 | </glossentry> | ||
3680 | |||
3681 | <glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm> | ||
3682 | <glossdef> | ||
3683 | <para> | ||
3684 | The manifest file for the image. | ||
3685 | This file lists all the installed packages that make up | ||
3686 | the image. | ||
3687 | The file contains package information on a line-per-package | ||
3688 | basis as follows: | ||
3689 | <literallayout class='monospaced'> | ||
3690 | <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable> | ||
3691 | </literallayout> | ||
3692 | </para> | ||
3693 | |||
3694 | <para> | ||
3695 | The | ||
3696 | <link linkend='ref-classes-image'><filename>image</filename></link> | ||
3697 | class defines the manifest file as follows: | ||
3698 | <literallayout class='monospaced'> | ||
3699 | IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest" | ||
3700 | </literallayout> | ||
3701 | The location is derived using the | ||
3702 | <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link> | ||
3703 | and | ||
3704 | <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link> | ||
3705 | variables. | ||
3706 | You can find information on how the image | ||
3707 | is created in the | ||
3708 | "<link linkend='image-generation-dev-environment'>Image Generation</link>" | ||
3709 | section. | ||
3710 | </para> | ||
3711 | </glossdef> | ||
3712 | </glossentry> | ||
3713 | |||
3714 | <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm> | ||
3715 | <glossdef> | ||
3716 | <para> | ||
3717 | The name of the output image files minus the extension. | ||
3718 | This variable is derived using the | ||
3719 | <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>, | ||
3720 | <link linkend='var-MACHINE'><filename>MACHINE</filename></link>, | ||
3721 | and | ||
3722 | <link linkend='var-DATETIME'><filename>DATETIME</filename></link> | ||
3723 | variables: | ||
3724 | <literallayout class='monospaced'> | ||
3725 | IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}" | ||
3726 | </literallayout> | ||
3727 | </para> | ||
3728 | </glossdef> | ||
3729 | </glossentry> | ||
3730 | |||
3731 | <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm> | ||
3732 | <glossdef> | ||
3733 | <para> | ||
3734 | Defines a multiplier that the build system applies to the initial image | ||
3735 | size for cases when the multiplier times the returned disk usage value | ||
3736 | for the image is greater than the sum of | ||
3737 | <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename> | ||
3738 | and | ||
3739 | <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>. | ||
3740 | The result of the multiplier applied to the initial image size creates | ||
3741 | free disk space in the image as overhead. | ||
3742 | By default, the build process uses a multiplier of 1.3 for this variable. | ||
3743 | This default value results in 30% free disk space added to the image when this | ||
3744 | method is used to determine the final generated image size. | ||
3745 | You should be aware that post install scripts and the package management | ||
3746 | system uses disk space inside this overhead area. | ||
3747 | Consequently, the multiplier does not produce an image with | ||
3748 | all the theoretical free disk space. | ||
3749 | See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename> | ||
3750 | for information on how the build system determines the overall image size. | ||
3751 | </para> | ||
3752 | |||
3753 | <para> | ||
3754 | The default 30% free disk space typically gives the image enough room to boot | ||
3755 | and allows for basic post installs while still leaving a small amount of | ||
3756 | free disk space. | ||
3757 | If 30% free space is inadequate, you can increase the default value. | ||
3758 | For example, the following setting gives you 50% free space added to the image: | ||
3759 | <literallayout class='monospaced'> | ||
3760 | IMAGE_OVERHEAD_FACTOR = "1.5" | ||
3761 | </literallayout> | ||
3762 | </para> | ||
3763 | |||
3764 | <para> | ||
3765 | Alternatively, you can ensure a specific amount of free disk space is added | ||
3766 | to the image by using the | ||
3767 | <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename> | ||
3768 | variable. | ||
3769 | </para> | ||
3770 | </glossdef> | ||
3771 | </glossentry> | ||
3772 | |||
3773 | <glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm> | ||
3774 | <glossdef> | ||
3775 | <para> | ||
3776 | Defines the package type (DEB, RPM, IPK, or TAR) used | ||
3777 | by the OpenEmbedded build system. | ||
3778 | The variable is defined appropriately by the | ||
3779 | <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>, | ||
3780 | <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>, | ||
3781 | <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>, | ||
3782 | or | ||
3783 | <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link> | ||
3784 | class. | ||
3785 | </para> | ||
3786 | |||
3787 | <para> | ||
3788 | The | ||
3789 | <link linkend='ref-classes-populate-sdk-*'><filename>package_sdk_base</filename></link> | ||
3790 | and | ||
3791 | <link linkend='ref-classes-image'><filename>image</filename></link> | ||
3792 | classes use the <filename>IMAGE_PKGTYPE</filename> for | ||
3793 | packaging up images and SDKs. | ||
3794 | </para> | ||
3795 | |||
3796 | <para> | ||
3797 | You should not set the <filename>IMAGE_PKGTYPE</filename> | ||
3798 | manually. | ||
3799 | Rather, the variable is set indirectly through the | ||
3800 | appropriate | ||
3801 | <link linkend='ref-classes-package'><filename>package_*</filename></link> | ||
3802 | class using the | ||
3803 | <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link> | ||
3804 | variable. | ||
3805 | The OpenEmbedded build system uses the first package type | ||
3806 | (e.g. DEB, RPM, or IPK) that appears with the variable | ||
3807 | <note> | ||
3808 | Files using the <filename>.tar</filename> format are | ||
3809 | never used as a substitute packaging format for DEB, | ||
3810 | RPM, and IPK formatted files for your image or SDK. | ||
3811 | </note> | ||
3812 | </para> | ||
3813 | </glossdef> | ||
3814 | </glossentry> | ||
3815 | |||
3816 | <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm> | ||
3817 | <glossdef> | ||
3818 | <para> | ||
3819 | Added by classes to run post processing commands once the | ||
3820 | OpenEmbedded build system has created the image. | ||
3821 | You can specify shell commands separated by semicolons: | ||
3822 | <literallayout class='monospaced'> | ||
3823 | IMAGE_POSTPROCESS_COMMAND += "<replaceable>shell_command</replaceable>; ... " | ||
3824 | </literallayout> | ||
3825 | If you need to pass the path to the root filesystem within | ||
3826 | the command, you can use | ||
3827 | <filename>${IMAGE_ROOTFS}</filename>, which points to | ||
3828 | the root filesystem image. | ||
3829 | </para> | ||
3830 | </glossdef> | ||
3831 | </glossentry> | ||
3832 | |||
3833 | <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm> | ||
3834 | <glossdef> | ||
3835 | <para> | ||
3836 | The location of the root filesystem while it is under | ||
3837 | construction (i.e. during the | ||
3838 | <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> | ||
3839 | task). | ||
3840 | This variable is not configurable. | ||
3841 | Do not change it. | ||
3842 | </para> | ||
3843 | </glossdef> | ||
3844 | </glossentry> | ||
3845 | |||
3846 | <glossentry id='var-IMAGE_ROOTFS_ALIGNMENT'><glossterm>IMAGE_ROOTFS_ALIGNMENT</glossterm> | ||
3847 | <glossdef> | ||
3848 | <para> | ||
3849 | Specifies the alignment for the output image file in | ||
3850 | Kbytes. | ||
3851 | If the size of the image is not a multiple of | ||
3852 | this value, then the size is rounded up to the nearest | ||
3853 | multiple of the value. | ||
3854 | The default value is "1". | ||
3855 | See | ||
3856 | <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link> | ||
3857 | for additional information. | ||
3858 | </para> | ||
3859 | </glossdef> | ||
3860 | </glossentry> | ||
3861 | |||
3862 | <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm> | ||
3863 | <glossdef> | ||
3864 | <para> | ||
3865 | Defines additional free disk space created in the image in Kbytes. | ||
3866 | By default, this variable is set to "0". | ||
3867 | This free disk space is added to the image after the build system determines | ||
3868 | the image size as described in | ||
3869 | <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>. | ||
3870 | </para> | ||
3871 | |||
3872 | <para> | ||
3873 | This variable is particularly useful when you want to ensure that a | ||
3874 | specific amount of free disk space is available on a device after an image | ||
3875 | is installed and running. | ||
3876 | For example, to be sure 5 Gbytes of free disk space is available, set the | ||
3877 | variable as follows: | ||
3878 | <literallayout class='monospaced'> | ||
3879 | IMAGE_ROOTFS_EXTRA_SPACE = "5242880" | ||
3880 | </literallayout> | ||
3881 | </para> | ||
3882 | |||
3883 | <para> | ||
3884 | For example, the Yocto Project Build Appliance specifically requests 40 Gbytes | ||
3885 | of extra space with the line: | ||
3886 | <literallayout class='monospaced'> | ||
3887 | IMAGE_ROOTFS_EXTRA_SPACE = "41943040" | ||
3888 | </literallayout> | ||
3889 | </para> | ||
3890 | </glossdef> | ||
3891 | </glossentry> | ||
3892 | |||
3893 | <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm> | ||
3894 | <glossdef> | ||
3895 | <para> | ||
3896 | Defines the size in Kbytes for the generated image. | ||
3897 | The OpenEmbedded build system determines the final size for the generated | ||
3898 | image using an algorithm that takes into account the initial disk space used | ||
3899 | for the generated image, a requested size for the image, and requested | ||
3900 | additional free disk space to be added to the image. | ||
3901 | Programatically, the build system determines the final size of the | ||
3902 | generated image as follows: | ||
3903 | <literallayout class='monospaced'> | ||
3904 | if (image-du * overhead) < rootfs-size: | ||
3905 | internal-rootfs-size = rootfs-size + xspace | ||
3906 | else: | ||
3907 | internal-rootfs-size = (image-du * overhead) + xspace | ||
3908 | |||
3909 | where: | ||
3910 | |||
3911 | image-du = Returned value of the du command on | ||
3912 | the image. | ||
3913 | |||
3914 | overhead = IMAGE_OVERHEAD_FACTOR | ||
3915 | |||
3916 | rootfs-size = IMAGE_ROOTFS_SIZE | ||
3917 | |||
3918 | internal-rootfs-size = Initial root filesystem | ||
3919 | size before any modifications. | ||
3920 | |||
3921 | xspace = IMAGE_ROOTFS_EXTRA_SPACE | ||
3922 | </literallayout> | ||
3923 | See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link> | ||
3924 | and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link> | ||
3925 | variables for related information. | ||
3926 | <!-- In the above example, <filename>overhead</filename> is defined by the | ||
3927 | <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename> | ||
3928 | variable, <filename>xspace</filename> is defined by the | ||
3929 | <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename> | ||
3930 | variable, and <filename>du</filename> is the results of the disk usage command | ||
3931 | on the initially generated image. --> | ||
3932 | </para> | ||
3933 | </glossdef> | ||
3934 | </glossentry> | ||
3935 | |||
3936 | <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm> | ||
3937 | <glossdef> | ||
3938 | <para> | ||
3939 | Specifies a dependency from one image type on another. | ||
3940 | Here is an example from the | ||
3941 | <link linkend='ref-classes-image-live'><filename>image-live</filename></link> | ||
3942 | class: | ||
3943 | <literallayout class='monospaced'> | ||
3944 | IMAGE_TYPEDEP_live = "ext3" | ||
3945 | </literallayout> | ||
3946 | In the previous example, the variable ensures that when | ||
3947 | "live" is listed with the | ||
3948 | <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> | ||
3949 | variable, the OpenEmbedded build system produces an | ||
3950 | <filename>ext3</filename> image first since one of the | ||
3951 | components of the live | ||
3952 | image is an <filename>ext3</filename> | ||
3953 | formatted partition containing the root | ||
3954 | filesystem. | ||
3955 | </para> | ||
3956 | </glossdef> | ||
3957 | </glossentry> | ||
3958 | |||
3959 | <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm> | ||
3960 | <glossdef> | ||
3961 | <para> | ||
3962 | Specifies the complete list of supported image types | ||
3963 | by default: | ||
3964 | <literallayout class='monospaced'> | ||
3965 | jffs2 | ||
3966 | jffs2.sum | ||
3967 | cramfs | ||
3968 | ext2 | ||
3969 | ext2.gz | ||
3970 | ext2.bz2 | ||
3971 | ext3 | ||
3972 | ext3.gz | ||
3973 | ext2.lzma | ||
3974 | btrfs | ||
3975 | live | ||
3976 | squashfs | ||
3977 | squashfs-xz | ||
3978 | ubi | ||
3979 | ubifs | ||
3980 | tar | ||
3981 | tar.gz | ||
3982 | tar.bz2 | ||
3983 | tar.xz | ||
3984 | cpio | ||
3985 | cpio.gz | ||
3986 | cpio.xz | ||
3987 | cpio.lzma | ||
3988 | vmdk | ||
3989 | elf | ||
3990 | </literallayout> | ||
3991 | For more information about these types of images, see | ||
3992 | <filename>meta/classes/image_types*.bbclass</filename> | ||
3993 | in the | ||
3994 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | ||
3995 | </para> | ||
3996 | </glossdef> | ||
3997 | </glossentry> | ||
3998 | |||
3999 | <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm> | ||
4000 | <glossdef> | ||
4001 | <para>Helps define the recipe revision for recipes that share | ||
4002 | a common <filename>include</filename> file. | ||
4003 | You can think of this variable as part of the recipe revision | ||
4004 | as set from within an include file.</para> | ||
4005 | <para>Suppose, for example, you have a set of recipes that | ||
4006 | are used across several projects. | ||
4007 | And, within each of those recipes the revision | ||
4008 | (its <link linkend='var-PR'><filename>PR</filename></link> | ||
4009 | value) is set accordingly. | ||
4010 | In this case, when the revision of those recipes changes, | ||
4011 | the burden is on you to find all those recipes and | ||
4012 | be sure that they get changed to reflect the updated | ||
4013 | version of the recipe. | ||
4014 | In this scenario, it can get complicated when recipes | ||
4015 | that are used in many places and provide common functionality | ||
4016 | are upgraded to a new revision.</para> | ||
4017 | <para>A more efficient way of dealing with this situation is | ||
4018 | to set the <filename>INC_PR</filename> variable inside | ||
4019 | the <filename>include</filename> files that the recipes | ||
4020 | share and then expand the <filename>INC_PR</filename> | ||
4021 | variable within the recipes to help | ||
4022 | define the recipe revision. | ||
4023 | </para> | ||
4024 | <para> | ||
4025 | The following provides an example that shows how to use | ||
4026 | the <filename>INC_PR</filename> variable | ||
4027 | given a common <filename>include</filename> file that | ||
4028 | defines the variable. | ||
4029 | Once the variable is defined in the | ||
4030 | <filename>include</filename> file, you can use the | ||
4031 | variable to set the <filename>PR</filename> values in | ||
4032 | each recipe. | ||
4033 | You will notice that when you set a recipe's | ||
4034 | <filename>PR</filename> you can provide more granular | ||
4035 | revisioning by appending values to the | ||
4036 | <filename>INC_PR</filename> variable: | ||
4037 | <literallayout class='monospaced'> | ||
4038 | recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" | ||
4039 | recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1" | ||
4040 | recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0" | ||
4041 | recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | ||
4042 | </literallayout> | ||
4043 | The first line of the example establishes the baseline | ||
4044 | revision to be used for all recipes that use the | ||
4045 | <filename>include</filename> file. | ||
4046 | The remaining lines in the example are from individual | ||
4047 | recipes and show how the <filename>PR</filename> value | ||
4048 | is set.</para> | ||
4049 | </glossdef> | ||
4050 | </glossentry> | ||
4051 | |||
4052 | <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm> | ||
4053 | <glossdef> | ||
4054 | <para> | ||
4055 | Specifies a space-separated list of license names | ||
4056 | (as they would appear in | ||
4057 | <link linkend='var-LICENSE'><filename>LICENSE</filename></link>) | ||
4058 | that should be excluded from the build. | ||
4059 | Recipes that provide no alternatives to listed incompatible | ||
4060 | licenses are not built. | ||
4061 | Packages that are individually licensed with the specified | ||
4062 | incompatible licenses will be deleted. | ||
4063 | </para> | ||
4064 | |||
4065 | <note> | ||
4066 | This functionality is only regularly tested using | ||
4067 | the following setting: | ||
4068 | <literallayout class='monospaced'> | ||
4069 | INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" | ||
4070 | </literallayout> | ||
4071 | Although you can use other settings, you might be required | ||
4072 | to remove dependencies on or provide alternatives to | ||
4073 | components that are required to produce a functional system | ||
4074 | image. | ||
4075 | </note> | ||
4076 | </glossdef> | ||
4077 | </glossentry> | ||
4078 | |||
4079 | <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm> | ||
4080 | <glossdef> | ||
4081 | <para> | ||
4082 | Prevents the default dependencies, namely the C compiler | ||
4083 | and standard C library (libc), from being added to | ||
4084 | <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>. | ||
4085 | This variable is usually used within recipes that do not | ||
4086 | require any compilation using the C compiler. | ||
4087 | </para> | ||
4088 | |||
4089 | <para> | ||
4090 | Set the variable to "1" to prevent the default dependencies | ||
4091 | from being added. | ||
4092 | </para> | ||
4093 | </glossdef> | ||
4094 | </glossentry> | ||
4095 | |||
4096 | <glossentry id='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><glossterm>INHIBIT_PACKAGE_DEBUG_SPLIT</glossterm> | ||
4097 | <glossdef> | ||
4098 | |||
4099 | <para> | ||
4100 | Prevents the OpenEmbedded build system from splitting | ||
4101 | out debug information during packaging. | ||
4102 | By default, the build system splits out debugging | ||
4103 | information during the | ||
4104 | <link linkend='ref-tasks-package'><filename>do_package</filename></link> | ||
4105 | task. | ||
4106 | For more information on how debug information is split out, | ||
4107 | see the | ||
4108 | <link linkend='var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></link> | ||
4109 | variable. | ||
4110 | </para> | ||
4111 | |||
4112 | <para> | ||
4113 | To prevent the build system from splitting out | ||
4114 | debug information during packaging, set the | ||
4115 | <filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename> variable | ||
4116 | as follows: | ||
4117 | <literallayout class='monospaced'> | ||
4118 | INHIBIT_PACKAGE_DEBUG_SPLIT = "1" | ||
4119 | </literallayout> | ||
4120 | </para> | ||
4121 | </glossdef> | ||
4122 | </glossentry> | ||
4123 | |||
4124 | <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm> | ||
4125 | <glossdef> | ||
4126 | <para> | ||
4127 | If set to "1", causes the build to not strip binaries in resulting packages. | ||
4128 | </para> | ||
4129 | </glossdef> | ||
4130 | </glossentry> | ||
4131 | |||
4132 | <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm> | ||
4133 | <glossdef> | ||
4134 | <para> | ||
4135 | Causes the named class to be inherited at | ||
4136 | this point during parsing. | ||
4137 | The variable is only valid in configuration files. | ||
4138 | </para> | ||
4139 | </glossdef> | ||
4140 | </glossentry> | ||
4141 | |||
4142 | <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm> | ||
4143 | <glossdef> | ||
4144 | <para> | ||
4145 | Lists classes that will be inherited at the | ||
4146 | distribution level. | ||
4147 | It is unlikely that you want to edit this variable. | ||
4148 | </para> | ||
4149 | |||
4150 | <para> | ||
4151 | The default value of the variable is set as follows in the | ||
4152 | <filename>meta/conf/distro/defaultsetup.conf</filename> | ||
4153 | file: | ||
4154 | <literallayout class='monospaced'> | ||
4155 | INHERIT_DISTRO ?= "debian devshell sstate license" | ||
4156 | </literallayout> | ||
4157 | </para> | ||
4158 | </glossdef> | ||
4159 | </glossentry> | ||
4160 | |||
4161 | <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm> | ||
4162 | <glossdef> | ||
4163 | <para> | ||
4164 | Defines the format for the output image of an initial | ||
4165 | RAM disk (initramfs), which is used during boot. | ||
4166 | Supported formats are the same as those supported by the | ||
4167 | <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> | ||
4168 | variable. | ||
4169 | </para> | ||
4170 | </glossdef> | ||
4171 | </glossentry> | ||
4172 | |||
4173 | <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm> | ||
4174 | <glossdef> | ||
4175 | <para> | ||
4176 | Causes the OpenEmbedded build system to build an additional | ||
4177 | recipe as a dependency to your root filesystem recipe | ||
4178 | (e.g. <filename>core-image-sato</filename>). | ||
4179 | The additional recipe is used to create an initial RAM disk | ||
4180 | (initramfs) that might be needed during the initial boot of | ||
4181 | the target system to accomplish such things as loading | ||
4182 | kernel modules prior to mounting the root file system. | ||
4183 | </para> | ||
4184 | |||
4185 | <para> | ||
4186 | When you set the variable, specify the name of the | ||
4187 | initramfs you want created. | ||
4188 | The following example, which is set in the | ||
4189 | <filename>local.conf</filename> configuration file, causes | ||
4190 | a separate recipe to be created that results in an | ||
4191 | initramfs image named | ||
4192 | <filename>core-image-sato-initramfs.bb</filename> to be | ||
4193 | created: | ||
4194 | <literallayout class='monospaced'> | ||
4195 | INITRAMFS_IMAGE = "core-image-minimal-initramfs" | ||
4196 | </literallayout> | ||
4197 | By default, the | ||
4198 | <link linkend='ref-classes-kernel'><filename>kernel</filename></link> | ||
4199 | class sets this variable to a null string as follows: | ||
4200 | <literallayout class='monospaced'> | ||
4201 | INITRAMFS_IMAGE = "" | ||
4202 | </literallayout> | ||
4203 | </para> | ||
4204 | |||
4205 | <para> | ||
4206 | See the | ||
4207 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink> | ||
4208 | file for additional information. | ||
4209 | You can also reference the | ||
4210 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/kernel.bbclass'><filename>kernel.bbclass</filename></ulink> | ||
4211 | file to see how the variable is used. | ||
4212 | </para> | ||
4213 | </glossdef> | ||
4214 | </glossentry> | ||
4215 | |||
4216 | <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm> | ||
4217 | <glossdef> | ||
4218 | <para> | ||
4219 | Controls whether or not the image recipe specified by | ||
4220 | <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link> | ||
4221 | is run through an extra pass during kernel compilation | ||
4222 | in order to build a single binary that contains both the | ||
4223 | kernel image and the initial RAM disk (initramfs). | ||
4224 | Using an extra compilation pass ensures that when a kernel | ||
4225 | attempts to use an initramfs, it does not encounter | ||
4226 | circular dependencies should the initramfs include kernel | ||
4227 | modules. | ||
4228 | </para> | ||
4229 | |||
4230 | <para> | ||
4231 | The combined binary is deposited into the | ||
4232 | <filename>tmp/deploy</filename> directory, which is part | ||
4233 | of the | ||
4234 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
4235 | </para> | ||
4236 | |||
4237 | <para> | ||
4238 | Setting the variable to "1" in a configuration file causes | ||
4239 | the OpenEmbedded build system to make the extra pass during | ||
4240 | kernel compilation: | ||
4241 | <literallayout class='monospaced'> | ||
4242 | INITRAMFS_IMAGE_BUNDLE = "1" | ||
4243 | </literallayout> | ||
4244 | By default, the | ||
4245 | <link linkend='ref-classes-kernel'><filename>kernel</filename></link> | ||
4246 | class sets this variable to a null string as follows: | ||
4247 | <literallayout class='monospaced'> | ||
4248 | INITRAMFS_IMAGE_BUNDLE = "" | ||
4249 | </literallayout> | ||
4250 | <note> | ||
4251 | You must set the | ||
4252 | <filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in | ||
4253 | a configuration file. | ||
4254 | You cannot set the variable in a recipe file. | ||
4255 | </note> | ||
4256 | See the | ||
4257 | <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink> | ||
4258 | file for additional information. | ||
4259 | </para> | ||
4260 | </glossdef> | ||
4261 | </glossentry> | ||
4262 | |||
4263 | <glossentry id='var-INITRD'><glossterm>INITRD</glossterm> | ||
4264 | <glossdef> | ||
4265 | <para> | ||
4266 | Indicates list of filesystem images to concatenate and use | ||
4267 | as an initial RAM disk (<filename>initrd</filename>). | ||
4268 | </para> | ||
4269 | |||
4270 | <para> | ||
4271 | The <filename>INITRD</filename> variable is an optional | ||
4272 | variable used with the | ||
4273 | <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link> | ||
4274 | class. | ||
4275 | </para> | ||
4276 | </glossdef> | ||
4277 | </glossentry> | ||
4278 | |||
4279 | <glossentry id='var-INITRD_IMAGE'><glossterm>INITRD_IMAGE</glossterm> | ||
4280 | <glossdef> | ||
4281 | <para> | ||
4282 | When building a "live" bootable image (i.e. when | ||
4283 | <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> | ||
4284 | contains "live"), <filename>INITRD_IMAGE</filename> | ||
4285 | specifies the image recipe that should be built | ||
4286 | to provide the initial RAM disk image. | ||
4287 | The default value is "core-image-minimal-initramfs". | ||
4288 | </para> | ||
4289 | |||
4290 | <para> | ||
4291 | See the | ||
4292 | <link linkend='ref-classes-image-live'><filename>image-live</filename></link> | ||
4293 | class for more information. | ||
4294 | </para> | ||
4295 | </glossdef> | ||
4296 | </glossentry> | ||
4297 | |||
4298 | <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm> | ||
4299 | <glossdef> | ||
4300 | <para> | ||
4301 | The filename of the initialization script as installed to | ||
4302 | <filename>${sysconfdir}/init.d</filename>. | ||
4303 | </para> | ||
4304 | <para> | ||
4305 | This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>. | ||
4306 | The variable is mandatory. | ||
4307 | </para> | ||
4308 | </glossdef> | ||
4309 | </glossentry> | ||
4310 | |||
4311 | <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm> | ||
4312 | <glossdef> | ||
4313 | <para> | ||
4314 | A list of the packages that contain initscripts. | ||
4315 | If multiple packages are specified, you need to append the package name | ||
4316 | to the other <filename>INITSCRIPT_*</filename> as an override.</para> | ||
4317 | <para> | ||
4318 | This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>. | ||
4319 | The variable is optional and defaults to the | ||
4320 | <link linkend='var-PN'><filename>PN</filename></link> variable. | ||
4321 | </para> | ||
4322 | </glossdef> | ||
4323 | </glossentry> | ||
4324 | |||
4325 | <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm> | ||
4326 | <glossdef> | ||
4327 | <para> | ||
4328 | Specifies the options to pass to <filename>update-rc.d</filename>. | ||
4329 | Here is an example: | ||
4330 | <literallayout class='monospaced'> | ||
4331 | INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ." | ||
4332 | </literallayout> | ||
4333 | In this example, the script has a runlevel of 99, | ||
4334 | starts the script in initlevels 2 and 5, and | ||
4335 | stops the script in levels 0, 1 and 6. | ||
4336 | </para> | ||
4337 | <para> | ||
4338 | The variable's default value is "defaults", which is | ||
4339 | set in the | ||
4340 | <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link> | ||
4341 | class. | ||
4342 | </para> | ||
4343 | <para> | ||
4344 | The value in | ||
4345 | <filename>INITSCRIPT_PARAMS</filename> is passed through | ||
4346 | to the <filename>update-rc.d</filename> command. | ||
4347 | For more information on valid parameters, please see the | ||
4348 | <filename>update-rc.d</filename> manual page at | ||
4349 | <ulink url='http://www.tin.org/bin/man.cgi?section=8&topic=update-rc.d'></ulink>. | ||
4350 | </para> | ||
4351 | </glossdef> | ||
4352 | </glossentry> | ||
4353 | |||
4354 | <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm> | ||
4355 | <glossdef> | ||
4356 | <para> | ||
4357 | Specifies the QA checks to skip for a specific package | ||
4358 | within a recipe. | ||
4359 | For example, to skip the check for symbolic link | ||
4360 | <filename>.so</filename> files in the main package of a | ||
4361 | recipe, add the following to the recipe. | ||
4362 | The package name override must be used, which in this | ||
4363 | example is <filename>${PN}</filename>: | ||
4364 | <literallayout class='monospaced'> | ||
4365 | INSANE_SKIP_${PN} += "dev-so" | ||
4366 | </literallayout> | ||
4367 | </para> | ||
4368 | <para> | ||
4369 | See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>" | ||
4370 | section for a list of the valid QA checks you can | ||
4371 | specify using this variable. | ||
4372 | </para> | ||
4373 | </glossdef> | ||
4374 | </glossentry> | ||
4375 | |||
4376 | <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm> | ||
4377 | <glossdef> | ||
4378 | <para> | ||
4379 | When the IPK backend is in use and package management | ||
4380 | is enabled on the target, you can use this variable to | ||
4381 | set up <filename>opkg</filename> in the target image | ||
4382 | to point to package feeds on a nominated server. | ||
4383 | Once the feed is established, you can perform | ||
4384 | installations or upgrades using the package manager | ||
4385 | at runtime. | ||
4386 | </para> | ||
4387 | </glossdef> | ||
4388 | </glossentry> | ||
4389 | |||
4390 | <!-- | ||
4391 | <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm> | ||
4392 | <glossdef> | ||
4393 | <para> | ||
4394 | An environment variable that defines the directory where | ||
4395 | post installation hooks are installed for the | ||
4396 | post install environment. | ||
4397 | This variable is fixed as follows: | ||
4398 | <literallayout class='monospaced'> | ||
4399 | ${WORKDIR}/intercept_scripts | ||
4400 | </literallayout> | ||
4401 | </para> | ||
4402 | |||
4403 | <para> | ||
4404 | After installation of a target's root filesystem, | ||
4405 | post installation scripts, which are essentially bash scripts, | ||
4406 | are all executed just a single time. | ||
4407 | Limiting execution of these scripts minimizes installation | ||
4408 | time that would be lengthened due to certain packages | ||
4409 | triggering redundant operations. | ||
4410 | For example, consider the installation of font packages | ||
4411 | as a common example. | ||
4412 | Without limiting the execution of post installation scripts, | ||
4413 | all font directories would be rescanned to create the | ||
4414 | cache after each individual font package was installed. | ||
4415 | </para> | ||
4416 | |||
4417 | <para> | ||
4418 | Do not edit the <filename>INTERCEPT_DIR</filename> | ||
4419 | variable. | ||
4420 | </para> | ||
4421 | </glossdef> | ||
4422 | </glossentry> | ||
4423 | --> | ||
4424 | |||
4425 | </glossdiv> | ||
4426 | |||
4427 | <!-- <glossdiv id='var-glossary-j'><title>J</title>--> | ||
4428 | <!-- </glossdiv>--> | ||
4429 | |||
4430 | <glossdiv id='var-glossary-k'><title>K</title> | ||
4431 | |||
4432 | <glossentry id='var-KARCH'><glossterm>KARCH</glossterm> | ||
4433 | <glossdef> | ||
4434 | <para> | ||
4435 | Defines the kernel architecture used when assembling | ||
4436 | the configuration. | ||
4437 | Architectures supported for this release are: | ||
4438 | <literallayout class='monospaced'> | ||
4439 | powerpc | ||
4440 | i386 | ||
4441 | x86_64 | ||
4442 | arm | ||
4443 | qemu | ||
4444 | mips | ||
4445 | </literallayout> | ||
4446 | </para> | ||
4447 | |||
4448 | <para> | ||
4449 | You define the <filename>KARCH</filename> variable in the | ||
4450 | <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>. | ||
4451 | </para> | ||
4452 | </glossdef> | ||
4453 | </glossentry> | ||
4454 | |||
4455 | <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm> | ||
4456 | <glossdef> | ||
4457 | <para> | ||
4458 | A regular expression used by the build process to explicitly | ||
4459 | identify the kernel branch that is validated, patched | ||
4460 | and configured during a build. | ||
4461 | The <filename>KBRANCH</filename> variable is optional. | ||
4462 | You can use it to trigger checks to ensure the exact kernel | ||
4463 | branch you want is being used by the build process. | ||
4464 | </para> | ||
4465 | |||
4466 | <para> | ||
4467 | Values for this variable are set in the kernel's recipe | ||
4468 | file and the kernel's append file. | ||
4469 | For example, if you are using the Yocto Project kernel that | ||
4470 | is based on the Linux 3.10 kernel, the kernel recipe file | ||
4471 | is the | ||
4472 | <filename>meta/recipes-kernel/linux/linux-yocto_3.10.bb</filename> | ||
4473 | file. | ||
4474 | Following is the default value for <filename>KBRANCH</filename> | ||
4475 | and the default override for the architectures the Yocto | ||
4476 | Project supports: | ||
4477 | <literallayout class='monospaced'> | ||
4478 | KBRANCH_DEFAULT = "standard/base" | ||
4479 | KBRANCH = "${KBRANCH_DEFAULT}" | ||
4480 | </literallayout> | ||
4481 | This branch exists in the <filename>linux-yocto-3.10</filename> | ||
4482 | kernel Git repository | ||
4483 | <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.10/refs/heads'></ulink>. | ||
4484 | </para> | ||
4485 | |||
4486 | <para> | ||
4487 | This variable is also used from the kernel's append file | ||
4488 | to identify the kernel branch specific to a particular | ||
4489 | machine or target hardware. | ||
4490 | The kernel's append file is located in the BSP layer for | ||
4491 | a given machine. | ||
4492 | For example, the kernel append file for the Crown Bay BSP is in the | ||
4493 | <filename>meta-intel</filename> Git repository and is named | ||
4494 | <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend</filename>. | ||
4495 | Here are the related statements from the append file: | ||
4496 | <literallayout class='monospaced'> | ||
4497 | COMPATIBLE_MACHINE_crownbay = "crownbay" | ||
4498 | KMACHINE_crownbay = "crownbay" | ||
4499 | KBRANCH_crownbay = "standard/crownbay" | ||
4500 | KERNEL_FEATURES_append_crownbay = " features/drm-emgd/drm-emgd-1.18 cfg/vesafb" | ||
4501 | |||
4502 | COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd" | ||
4503 | KMACHINE_crownbay-noemgd = "crownbay" | ||
4504 | KBRANCH_crownbay-noemgd = "standard/crownbay" | ||
4505 | KERNEL_FEATURES_append_crownbay-noemgd = " cfg/vesafb" | ||
4506 | </literallayout> | ||
4507 | The <filename>KBRANCH_*</filename> statements identify | ||
4508 | the kernel branch to use when building for the Crown | ||
4509 | Bay BSP. | ||
4510 | In this case there are two identical statements: one | ||
4511 | for each type of Crown Bay machine. | ||
4512 | </para> | ||
4513 | </glossdef> | ||
4514 | </glossentry> | ||
4515 | |||
4516 | <glossentry id='var-KBRANCH_DEFAULT'><glossterm>KBRANCH_DEFAULT</glossterm> | ||
4517 | <glossdef> | ||
4518 | <para> | ||
4519 | Defines the Linux kernel source repository's default | ||
4520 | branch used to build the Linux kernel. | ||
4521 | The <filename>KBRANCH_DEFAULT</filename> value is | ||
4522 | the default value for | ||
4523 | <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>. | ||
4524 | Unless you specify otherwise, | ||
4525 | <filename>KBRANCH_DEFAULT</filename> initializes to | ||
4526 | "master". | ||
4527 | </para> | ||
4528 | </glossdef> | ||
4529 | </glossentry> | ||
4530 | |||
4531 | <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm> | ||
4532 | <glossdef> | ||
4533 | <para> | ||
4534 | Specifies additional <filename>make</filename> | ||
4535 | command-line arguments the OpenEmbedded build system | ||
4536 | passes on when compiling the kernel. | ||
4537 | </para> | ||
4538 | </glossdef> | ||
4539 | </glossentry> | ||
4540 | |||
4541 | <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm> | ||
4542 | <glossdef> | ||
4543 | <para>Includes additional metadata from the Yocto Project kernel Git repository. | ||
4544 | In the OpenEmbedded build system, the default Board Support Packages (BSPs) | ||
4545 | <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> | ||
4546 | is provided through | ||
4547 | the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link> | ||
4548 | and <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link> variables. | ||
4549 | You can use the <filename>KERNEL_FEATURES</filename> variable to further | ||
4550 | add metadata for all BSPs.</para> | ||
4551 | <para>The metadata you add through this variable includes config fragments and | ||
4552 | features descriptions, | ||
4553 | which usually includes patches as well as config fragments. | ||
4554 | You typically override the <filename>KERNEL_FEATURES</filename> variable | ||
4555 | for a specific machine. | ||
4556 | In this way, you can provide validated, but optional, sets of kernel | ||
4557 | configurations and features.</para> | ||
4558 | <para>For example, the following adds <filename>netfilter</filename> to all | ||
4559 | the Yocto Project kernels and adds sound support to the <filename>qemux86</filename> | ||
4560 | machine: | ||
4561 | <literallayout class='monospaced'> | ||
4562 | # Add netfilter to all linux-yocto kernels | ||
4563 | KERNEL_FEATURES="features/netfilter" | ||
4564 | |||
4565 | # Add sound support to the qemux86 machine | ||
4566 | KERNEL_FEATURES_append_qemux86=" cfg/sound" | ||
4567 | </literallayout></para> | ||
4568 | </glossdef> | ||
4569 | </glossentry> | ||
4570 | |||
4571 | <glossentry id='var-KERNEL_IMAGE_BASE_NAME'><glossterm>KERNEL_IMAGE_BASE_NAME</glossterm> | ||
4572 | <glossdef> | ||
4573 | <para> | ||
4574 | The base name of the kernel image. | ||
4575 | This variable is set in the | ||
4576 | <link linkend='ref-classes-kernel'>kernel</link> class | ||
4577 | as follows: | ||
4578 | <literallayout class='monospaced'> | ||
4579 | KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}" | ||
4580 | </literallayout> | ||
4581 | See the | ||
4582 | <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>, | ||
4583 | <link linkend='var-PKGE'><filename>PKGE</filename></link>, | ||
4584 | <link linkend='var-PKGV'><filename>PKGV</filename></link>, | ||
4585 | <link linkend='var-PKGR'><filename>PKGR</filename></link>, | ||
4586 | <link linkend='var-MACHINE'><filename>MACHINE</filename></link>, | ||
4587 | and | ||
4588 | <link linkend='var-DATETIME'><filename>DATETIME</filename></link> | ||
4589 | variables for additional information. | ||
4590 | </para> | ||
4591 | </glossdef> | ||
4592 | </glossentry> | ||
4593 | |||
4594 | <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm> | ||
4595 | <glossdef> | ||
4596 | <para>The type of kernel to build for a device, usually set by the | ||
4597 | machine configuration files and defaults to "zImage". | ||
4598 | This variable is used | ||
4599 | when building the kernel and is passed to <filename>make</filename> as the target to | ||
4600 | build.</para> | ||
4601 | </glossdef> | ||
4602 | </glossentry> | ||
4603 | |||
4604 | <glossentry id='var-KERNEL_MODULE_AUTOLOAD'><glossterm>KERNEL_MODULE_AUTOLOAD</glossterm> | ||
4605 | <glossdef> | ||
4606 | <para> | ||
4607 | Lists kernel modules that need to be auto-loaded during | ||
4608 | boot. | ||
4609 | <note> | ||
4610 | This variable replaces the deprecated | ||
4611 | <link linkend='var-module_autoload'><filename>module_autoload</filename></link> | ||
4612 | variable. | ||
4613 | </note> | ||
4614 | </para> | ||
4615 | |||
4616 | <para> | ||
4617 | You can use the <filename>KERNEL_MODULE_AUTOLOAD</filename> | ||
4618 | variable anywhere that it can be | ||
4619 | recognized by the kernel recipe or by an out-of-tree kernel | ||
4620 | module recipe (e.g. a machine configuration file, a | ||
4621 | distribution configuration file, an append file for the | ||
4622 | recipe, or the recipe itself). | ||
4623 | </para> | ||
4624 | |||
4625 | <para> | ||
4626 | Specify it as follows: | ||
4627 | <literallayout class='monospaced'> | ||
4628 | KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name1</replaceable> <replaceable>module_name2</replaceable> <replaceable>module_name3</replaceable>" | ||
4629 | </literallayout> | ||
4630 | </para> | ||
4631 | |||
4632 | <para> | ||
4633 | Including <filename>KERNEL_MODULE_AUTOLOAD</filename> causes | ||
4634 | the OpenEmbedded build system to populate the | ||
4635 | <filename>/etc/modules-load.d/modname.conf</filename> | ||
4636 | file with the list of modules to be auto-loaded on boot. | ||
4637 | The modules appear one-per-line in the file. | ||
4638 | Here is an example of the most common use case: | ||
4639 | <literallayout class='monospaced'> | ||
4640 | KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name</replaceable>" | ||
4641 | </literallayout> | ||
4642 | </para> | ||
4643 | |||
4644 | <para> | ||
4645 | For information on how to populate the | ||
4646 | <filename>modname.conf</filename> file with | ||
4647 | <filename>modprobe.d</filename> syntax lines, see the | ||
4648 | <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link> | ||
4649 | variable. | ||
4650 | </para> | ||
4651 | </glossdef> | ||
4652 | </glossentry> | ||
4653 | |||
4654 | <glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm>KERNEL_MODULE_PROBECONF</glossterm> | ||
4655 | <glossdef> | ||
4656 | <para> | ||
4657 | Provides a list of modules for which the OpenEmbedded | ||
4658 | build system expects to find | ||
4659 | <filename>module_conf_</filename><replaceable>modname</replaceable> | ||
4660 | values that specify configuration for each of the modules. | ||
4661 | For information on how to provide those module | ||
4662 | configurations, see the | ||
4663 | <link linkend='var-module_conf'><filename>module_conf_*</filename></link> | ||
4664 | variable. | ||
4665 | </para> | ||
4666 | </glossdef> | ||
4667 | </glossentry> | ||
4668 | |||
4669 | <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm> | ||
4670 | <glossdef> | ||
4671 | <para> | ||
4672 | The location of the kernel sources. | ||
4673 | This variable is set to the value of the | ||
4674 | <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link> | ||
4675 | within the | ||
4676 | <link linkend='ref-classes-module'><filename>module</filename></link> | ||
4677 | class. | ||
4678 | For information on how this variable is used, see the | ||
4679 | "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>" | ||
4680 | section. | ||
4681 | </para> | ||
4682 | |||
4683 | <para> | ||
4684 | To help maximize compatibility with out-of-tree drivers | ||
4685 | used to build modules, the OpenEmbedded build system also | ||
4686 | recognizes and uses the | ||
4687 | <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link> | ||
4688 | variable, which is identical to the | ||
4689 | <filename>KERNEL_PATH</filename> variable. | ||
4690 | Both variables are common variables used by external | ||
4691 | Makefiles to point to the kernel source directory. | ||
4692 | </para> | ||
4693 | </glossdef> | ||
4694 | </glossentry> | ||
4695 | |||
4696 | <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm> | ||
4697 | <glossdef> | ||
4698 | <para> | ||
4699 | The location of the kernel sources. | ||
4700 | This variable is set to the value of the | ||
4701 | <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link> | ||
4702 | within the | ||
4703 | <link linkend='ref-classes-module'><filename>module</filename></link> | ||
4704 | class. | ||
4705 | For information on how this variable is used, see the | ||
4706 | "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>" | ||
4707 | section. | ||
4708 | </para> | ||
4709 | |||
4710 | <para> | ||
4711 | To help maximize compatibility with out-of-tree drivers | ||
4712 | used to build modules, the OpenEmbedded build system also | ||
4713 | recognizes and uses the | ||
4714 | <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link> | ||
4715 | variable, which is identical to the | ||
4716 | <filename>KERNEL_SRC</filename> variable. | ||
4717 | Both variables are common variables used by external | ||
4718 | Makefiles to point to the kernel source directory. | ||
4719 | </para> | ||
4720 | </glossdef> | ||
4721 | </glossentry> | ||
4722 | |||
4723 | <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm> | ||
4724 | <glossdef> | ||
4725 | <para> | ||
4726 | Provides a short description of a configuration fragment. | ||
4727 | You use this variable in the <filename>.scc</filename> | ||
4728 | file that describes a configuration fragment file. | ||
4729 | Here is the variable used in a file named | ||
4730 | <filename>smp.scc</filename> to describe SMP being | ||
4731 | enabled: | ||
4732 | <literallayout class='monospaced'> | ||
4733 | define KFEATURE_DESCRIPTION "Enable SMP" | ||
4734 | </literallayout> | ||
4735 | </para> | ||
4736 | </glossdef> | ||
4737 | </glossentry> | ||
4738 | |||
4739 | <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm> | ||
4740 | <glossdef> | ||
4741 | <para> | ||
4742 | The machine as known by the kernel. | ||
4743 | Sometimes the machine name used by the kernel does not match the machine name | ||
4744 | used by the OpenEmbedded build system. | ||
4745 | For example, the machine name that the OpenEmbedded build system understands as | ||
4746 | <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel. | ||
4747 | The kernel understands that machine as <filename>arm_versatile926ejs</filename>. | ||
4748 | For cases like these, the <filename>KMACHINE</filename> variable maps the | ||
4749 | kernel machine name to the OpenEmbedded build system machine name. | ||
4750 | </para> | ||
4751 | |||
4752 | <para> | ||
4753 | Kernel machine names are initially defined in the | ||
4754 | Yocto Linux Kernel's <filename>meta</filename> branch. | ||
4755 | From the <filename>meta</filename> branch, look in | ||
4756 | the <filename>meta/cfg/kernel-cache/bsp/<bsp_name>/<bsp-name>-<kernel-type>.scc</filename> file. | ||
4757 | For example, from the <filename>meta</filename> branch in the | ||
4758 | <filename>linux-yocto-3.0</filename> kernel, the | ||
4759 | <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file | ||
4760 | has the following: | ||
4761 | <literallayout class='monospaced'> | ||
4762 | define KMACHINE cedartrail | ||
4763 | define KTYPE standard | ||
4764 | define KARCH i386 | ||
4765 | |||
4766 | include ktypes/standard | ||
4767 | branch cedartrail | ||
4768 | |||
4769 | include cedartrail.scc | ||
4770 | </literallayout> | ||
4771 | You can see that the kernel understands the machine name for | ||
4772 | the Cedar Trail Board Support Package (BSP) as | ||
4773 | <filename>cedartrail</filename>. | ||
4774 | </para> | ||
4775 | |||
4776 | <para> | ||
4777 | If you look in the Cedar Trail BSP layer in the | ||
4778 | <filename>meta-intel</filename> | ||
4779 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink> | ||
4780 | at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>, | ||
4781 | you will find the following statements among others: | ||
4782 | <literallayout class='monospaced'> | ||
4783 | COMPATIBLE_MACHINE_cedartrail = "cedartrail" | ||
4784 | KMACHINE_cedartrail = "cedartrail" | ||
4785 | KBRANCH_cedartrail = "yocto/standard/cedartrail" | ||
4786 | KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc" | ||
4787 | KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc" | ||
4788 | |||
4789 | COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail" | ||
4790 | KMACHINE_cedartrail-nopvr = "cedartrail" | ||
4791 | KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail" | ||
4792 | KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc" | ||
4793 | </literallayout> | ||
4794 | The <filename>KMACHINE</filename> statements in the kernel's append file make sure that | ||
4795 | the OpenEmbedded build system and the Yocto Linux kernel understand the same machine | ||
4796 | names. | ||
4797 | </para> | ||
4798 | |||
4799 | <para> | ||
4800 | This append file uses two <filename>KMACHINE</filename> statements. | ||
4801 | The first is not really necessary but does ensure that the machine known to the | ||
4802 | OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine | ||
4803 | in the kernel also known as <filename>cedartrail</filename>: | ||
4804 | <literallayout class='monospaced'> | ||
4805 | KMACHINE_cedartrail = "cedartrail" | ||
4806 | </literallayout> | ||
4807 | </para> | ||
4808 | |||
4809 | <para> | ||
4810 | The second statement is a good example of why the <filename>KMACHINE</filename> variable | ||
4811 | is needed. | ||
4812 | In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename> | ||
4813 | machine name to refer to the Cedar Trail BSP that does not support the proprietary | ||
4814 | PowerVR driver. | ||
4815 | The kernel, however, uses the machine name <filename>cedartrail</filename>. | ||
4816 | Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to | ||
4817 | the kernel's <filename>cedartrail</filename> name: | ||
4818 | <literallayout class='monospaced'> | ||
4819 | KMACHINE_cedartrail-nopvr = "cedartrail" | ||
4820 | </literallayout> | ||
4821 | </para> | ||
4822 | |||
4823 | <para> | ||
4824 | BSPs that ship with the Yocto Project release provide all mappings between the Yocto | ||
4825 | Project kernel machine names and the OpenEmbedded machine names. | ||
4826 | Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine | ||
4827 | name you use is different than that used in the kernel. | ||
4828 | </para> | ||
4829 | </glossdef> | ||
4830 | </glossentry> | ||
4831 | |||
4832 | <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm> | ||
4833 | <glossdef> | ||
4834 | <para> | ||
4835 | Defines the kernel type to be used in assembling the | ||
4836 | configuration. | ||
4837 | The linux-yocto recipes define "standard", "tiny", | ||
4838 | and "preempt-rt" kernel types. | ||
4839 | See the | ||
4840 | "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>" | ||
4841 | section in the Yocto Project Linux Kernel Development | ||
4842 | Manual for more information on kernel types. | ||
4843 | </para> | ||
4844 | |||
4845 | <para> | ||
4846 | You define the <filename>KTYPE</filename> variable in the | ||
4847 | <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>. | ||
4848 | The value you use must match the value used for the | ||
4849 | <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link> | ||
4850 | value used by the kernel recipe. | ||
4851 | </para> | ||
4852 | </glossdef> | ||
4853 | </glossentry> | ||
4854 | </glossdiv> | ||
4855 | |||
4856 | <glossdiv id='var-glossary-l'><title>L</title> | ||
4857 | |||
4858 | <glossentry id='var-LABELS'><glossterm>LABELS</glossterm> | ||
4859 | <glossdef> | ||
4860 | <para> | ||
4861 | Provides a list of targets for automatic configuration. | ||
4862 | </para> | ||
4863 | |||
4864 | <para> | ||
4865 | See the | ||
4866 | <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link> | ||
4867 | class for more information on how this variable is used. | ||
4868 | </para> | ||
4869 | </glossdef> | ||
4870 | </glossentry> | ||
4871 | |||
4872 | <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm> | ||
4873 | <glossdef> | ||
4874 | <para>Lists the layers that this recipe depends upon, separated by spaces. | ||
4875 | Optionally, you can specify a specific layer version for a dependency | ||
4876 | by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3" | ||
4877 | to be compared against | ||
4878 | <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename> | ||
4879 | in this case). | ||
4880 | An error will be produced if any dependency is missing or | ||
4881 | the version numbers do not match exactly (if specified). | ||
4882 | This variable is used in the <filename>conf/layer.conf</filename> file | ||
4883 | and must be suffixed with the name of the specific layer (e.g. | ||
4884 | <filename>LAYERDEPENDS_mylayer</filename>).</para> | ||
4885 | </glossdef> | ||
4886 | </glossentry> | ||
4887 | |||
4888 | <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm> | ||
4889 | <glossdef> | ||
4890 | <para>When used inside the <filename>layer.conf</filename> configuration | ||
4891 | file, this variable provides the path of the current layer. | ||
4892 | This variable is not available outside of <filename>layer.conf</filename> | ||
4893 | and references are expanded immediately when parsing of the file completes.</para> | ||
4894 | </glossdef> | ||
4895 | </glossentry> | ||
4896 | |||
4897 | <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm> | ||
4898 | <glossdef> | ||
4899 | <para>Optionally specifies the version of a layer as a single number. | ||
4900 | You can use this within | ||
4901 | <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link> | ||
4902 | for another layer in order to depend on a specific version | ||
4903 | of the layer. | ||
4904 | This variable is used in the <filename>conf/layer.conf</filename> file | ||
4905 | and must be suffixed with the name of the specific layer (e.g. | ||
4906 | <filename>LAYERVERSION_mylayer</filename>).</para> | ||
4907 | </glossdef> | ||
4908 | </glossentry> | ||
4909 | |||
4910 | <glossentry id='var-LDFLAGS'><glossterm>LDFLAGS</glossterm> | ||
4911 | <glossdef> | ||
4912 | <para> | ||
4913 | Specifies the flags to pass to the linker. | ||
4914 | This variable is exported to an environment | ||
4915 | variable and thus made visible to the software being | ||
4916 | built during the compilation step. | ||
4917 | </para> | ||
4918 | |||
4919 | <para> | ||
4920 | Default initialization for <filename>LDFLAGS</filename> | ||
4921 | varies depending on what is being built: | ||
4922 | <itemizedlist> | ||
4923 | <listitem><para> | ||
4924 | <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link> | ||
4925 | when building for the target | ||
4926 | </para></listitem> | ||
4927 | <listitem><para> | ||
4928 | <link linkend='var-BUILD_LDFLAGS'><filename>BUILD_LDFLAGS</filename></link> | ||
4929 | when building for the build host (i.e. | ||
4930 | <filename>-native</filename>) | ||
4931 | </para></listitem> | ||
4932 | <listitem><para> | ||
4933 | <link linkend='var-BUILDSDK_LDFLAGS'><filename>BUILDSDK_LDFLAGS</filename></link> | ||
4934 | when building for an SDK (i.e. | ||
4935 | <filename>nativesdk-</filename>) | ||
4936 | </para></listitem> | ||
4937 | </itemizedlist> | ||
4938 | </para> | ||
4939 | </glossdef> | ||
4940 | </glossentry> | ||
4941 | |||
4942 | <glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm> | ||
4943 | <glossdef> | ||
4944 | <para> | ||
4945 | Specifies the lead (or primary) compiled library file | ||
4946 | (<filename>.so</filename>) that the | ||
4947 | <link linkend='ref-classes-debian'><filename>debian</filename></link> | ||
4948 | class applies its naming policy to given a recipe that | ||
4949 | packages multiple libraries. | ||
4950 | </para> | ||
4951 | |||
4952 | <para> | ||
4953 | This variable works in conjunction with the | ||
4954 | <filename>debian</filename> class. | ||
4955 | </para> | ||
4956 | </glossdef> | ||
4957 | </glossentry> | ||
4958 | |||
4959 | <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm> | ||
4960 | <glossdef> | ||
4961 | <para>Checksums of the license text in the recipe source code.</para> | ||
4962 | <para>This variable tracks changes in license text of the source | ||
4963 | code files. | ||
4964 | If the license text is changed, it will trigger a build | ||
4965 | failure, which gives the developer an opportunity to review any | ||
4966 | license change.</para> | ||
4967 | <para> | ||
4968 | This variable must be defined for all recipes (unless | ||
4969 | <link linkend='var-LICENSE'><filename>LICENSE</filename></link> | ||
4970 | is set to "CLOSED").</para> | ||
4971 | <para>For more information, see the | ||
4972 | "<link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'> | ||
4973 | Tracking License Changes</link>" section.</para> | ||
4974 | </glossdef> | ||
4975 | </glossentry> | ||
4976 | |||
4977 | <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm> | ||
4978 | <glossdef> | ||
4979 | <para> | ||
4980 | The list of source licenses for the recipe. | ||
4981 | Follow these rules: | ||
4982 | <itemizedlist> | ||
4983 | <listitem><para>Do not use spaces within individual | ||
4984 | license names.</para></listitem> | ||
4985 | <listitem><para>Separate license names using | ||
4986 | | (pipe) when there is a choice between licenses. | ||
4987 | </para></listitem> | ||
4988 | <listitem><para>Separate license names using | ||
4989 | & (ampersand) when multiple licenses exist | ||
4990 | that cover different parts of the source. | ||
4991 | </para></listitem> | ||
4992 | <listitem><para>You can use spaces between license | ||
4993 | names.</para></listitem> | ||
4994 | <listitem><para>For standard licenses, use the names | ||
4995 | of the files in | ||
4996 | <filename>meta/files/common-licenses/</filename> | ||
4997 | or the | ||
4998 | <link linkend='var-SPDXLICENSEMAP'><filename>SPDXLICENSEMAP</filename></link> | ||
4999 | flag names defined in | ||
5000 | <filename>meta/conf/licenses.conf</filename>. | ||
5001 | </para></listitem> | ||
5002 | </itemizedlist> | ||
5003 | </para> | ||
5004 | |||
5005 | <para> | ||
5006 | Here are some examples: | ||
5007 | <literallayout class='monospaced'> | ||
5008 | LICENSE = "LGPLv2.1 | GPLv3" | ||
5009 | LICENSE = "MPL-1 & LGPLv2.1" | ||
5010 | LICENSE = "GPLv2+" | ||
5011 | </literallayout> | ||
5012 | The first example is from the recipes for Qt, which the user | ||
5013 | may choose to distribute under either the LGPL version | ||
5014 | 2.1 or GPL version 3. | ||
5015 | The second example is from Cairo where two licenses cover | ||
5016 | different parts of the source code. | ||
5017 | The final example is from <filename>sysstat</filename>, | ||
5018 | which presents a single license. | ||
5019 | </para> | ||
5020 | |||
5021 | <para> | ||
5022 | You can also specify licenses on a per-package basis to | ||
5023 | handle situations where components of the output have | ||
5024 | different licenses. | ||
5025 | For example, a piece of software whose code is | ||
5026 | licensed under GPLv2 but has accompanying documentation | ||
5027 | licensed under the GNU Free Documentation License 1.2 could | ||
5028 | be specified as follows: | ||
5029 | <literallayout class='monospaced'> | ||
5030 | LICENSE = "GFDL-1.2 & GPLv2" | ||
5031 | LICENSE_${PN} = "GPLv2" | ||
5032 | LICENSE_${PN}-doc = "GFDL-1.2" | ||
5033 | </literallayout> | ||
5034 | </para> | ||
5035 | </glossdef> | ||
5036 | </glossentry> | ||
5037 | |||
5038 | <glossentry id='var-LICENSE_FLAGS'><glossterm>LICENSE_FLAGS</glossterm> | ||
5039 | <glossdef> | ||
5040 | <para> | ||
5041 | Specifies additional flags for a recipe you must | ||
5042 | whitelist through | ||
5043 | <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link> | ||
5044 | in order to allow the recipe to be built. | ||
5045 | When providing multiple flags, separate them with | ||
5046 | spaces. | ||
5047 | </para> | ||
5048 | |||
5049 | <para> | ||
5050 | This value is independent of | ||
5051 | <link linkend='var-LICENSE'><filename>LICENSE</filename></link> | ||
5052 | and is typically used to mark recipes that might | ||
5053 | require additional licenses in order to be used in a | ||
5054 | commercial product. | ||
5055 | For more information, see the | ||
5056 | "<link linkend='enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</link>" | ||
5057 | section. | ||
5058 | </para> | ||
5059 | </glossdef> | ||
5060 | </glossentry> | ||
5061 | |||
5062 | <glossentry id='var-LICENSE_FLAGS_WHITELIST'><glossterm>LICENSE_FLAGS_WHITELIST</glossterm> | ||
5063 | <glossdef> | ||
5064 | <para> | ||
5065 | Lists license flags that when specified in | ||
5066 | <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link> | ||
5067 | within a recipe should not prevent that recipe from being | ||
5068 | built. | ||
5069 | This practice is otherwise known as "whitelisting" | ||
5070 | license flags. | ||
5071 | For more information, see the | ||
5072 | <link linkend='enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</link>" | ||
5073 | section. | ||
5074 | </para> | ||
5075 | </glossdef> | ||
5076 | </glossentry> | ||
5077 | |||
5078 | <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm> | ||
5079 | <glossdef> | ||
5080 | <para>Path to additional licenses used during the build. | ||
5081 | By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename> | ||
5082 | to define the directory that holds common license text used during the build. | ||
5083 | The <filename>LICENSE_PATH</filename> variable allows you to extend that | ||
5084 | location to other areas that have additional licenses: | ||
5085 | <literallayout class='monospaced'> | ||
5086 | LICENSE_PATH += "<replaceable>path-to-additional-common-licenses</replaceable>" | ||
5087 | </literallayout></para> | ||
5088 | </glossdef> | ||
5089 | </glossentry> | ||
5090 | |||
5091 | <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm> | ||
5092 | <glossdef> | ||
5093 | <para> | ||
5094 | Defines the kernel type to be used in assembling the | ||
5095 | configuration. | ||
5096 | The linux-yocto recipes define "standard", "tiny", and | ||
5097 | "preempt-rt" kernel types. | ||
5098 | See the | ||
5099 | "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>" | ||
5100 | section in the Yocto Project Linux Kernel Development | ||
5101 | Manual for more information on kernel types. | ||
5102 | </para> | ||
5103 | |||
5104 | <para> | ||
5105 | If you do not specify a | ||
5106 | <filename>LINUX_KERNEL_TYPE</filename>, it defaults to | ||
5107 | "standard". | ||
5108 | Together with | ||
5109 | <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>, | ||
5110 | the <filename>LINUX_KERNEL_TYPE</filename> variable | ||
5111 | defines the search | ||
5112 | arguments used by the kernel tools to find the appropriate | ||
5113 | description within the kernel | ||
5114 | <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> | ||
5115 | with which to build out the sources and configuration. | ||
5116 | </para> | ||
5117 | </glossdef> | ||
5118 | </glossentry> | ||
5119 | |||
5120 | <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm> | ||
5121 | <glossdef> | ||
5122 | <para>The Linux version from <filename>kernel.org</filename> | ||
5123 | on which the Linux kernel image being built using the | ||
5124 | OpenEmbedded build system is based. | ||
5125 | You define this variable in the kernel recipe. | ||
5126 | For example, the <filename>linux-yocto-3.4.bb</filename> | ||
5127 | kernel recipe found in | ||
5128 | <filename>meta/recipes-kernel/linux</filename> | ||
5129 | defines the variables as follows: | ||
5130 | <literallayout class='monospaced'> | ||
5131 | LINUX_VERSION ?= "3.4.24" | ||
5132 | </literallayout> | ||
5133 | The <filename>LINUX_VERSION</filename> variable is used to | ||
5134 | define <link linkend='var-PV'><filename>PV</filename></link> | ||
5135 | for the recipe: | ||
5136 | <literallayout class='monospaced'> | ||
5137 | PV = "${LINUX_VERSION}+git${SRCPV}" | ||
5138 | </literallayout></para> | ||
5139 | </glossdef> | ||
5140 | </glossentry> | ||
5141 | |||
5142 | <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm> | ||
5143 | <glossdef> | ||
5144 | <para>A string extension compiled into the version | ||
5145 | string of the Linux kernel built with the OpenEmbedded | ||
5146 | build system. | ||
5147 | You define this variable in the kernel recipe. | ||
5148 | For example, the linux-yocto kernel recipes all define | ||
5149 | the variable as follows: | ||
5150 | <literallayout class='monospaced'> | ||
5151 | LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}" | ||
5152 | </literallayout> | ||
5153 | Defining this variable essentially sets the | ||
5154 | Linux kernel configuration item | ||
5155 | <filename>CONFIG_LOCALVERSION</filename>, which is visible | ||
5156 | through the <filename>uname</filename> command. | ||
5157 | Here is an example that shows the extension assuming it | ||
5158 | was set as previously shown: | ||
5159 | <literallayout class='monospaced'> | ||
5160 | $ uname -r | ||
5161 | 3.7.0-rc8-custom | ||
5162 | </literallayout> | ||
5163 | </para> | ||
5164 | </glossdef> | ||
5165 | </glossentry> | ||
5166 | |||
5167 | <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm> | ||
5168 | <glossdef> | ||
5169 | <para> | ||
5170 | Specifies the directory to which the OpenEmbedded build | ||
5171 | system writes overall log files. | ||
5172 | The default directory is <filename>${TMPDIR}/log</filename>. | ||
5173 | </para> | ||
5174 | <para> | ||
5175 | For the directory containing logs specific to each task, | ||
5176 | see the <link linkend='var-T'><filename>T</filename></link> | ||
5177 | variable. | ||
5178 | </para> | ||
5179 | </glossdef> | ||
5180 | </glossentry> | ||
5181 | |||
5182 | </glossdiv> | ||
5183 | |||
5184 | <glossdiv id='var-glossary-m'><title>M</title> | ||
5185 | |||
5186 | <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm> | ||
5187 | <glossdef> | ||
5188 | <para> | ||
5189 | Specifies the target device for which the image is built. | ||
5190 | You define <filename>MACHINE</filename> in the | ||
5191 | <filename>local.conf</filename> file found in the | ||
5192 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
5193 | By default, <filename>MACHINE</filename> is set to | ||
5194 | "qemux86", which is an x86-based architecture machine to | ||
5195 | be emulated using QEMU: | ||
5196 | <literallayout class='monospaced'> | ||
5197 | MACHINE ?= "qemux86" | ||
5198 | </literallayout> | ||
5199 | The variable corresponds to a machine configuration file of the | ||
5200 | same name, through which machine-specific configurations are set. | ||
5201 | Thus, when <filename>MACHINE</filename> is set to "qemux86" there | ||
5202 | exists the corresponding <filename>qemux86.conf</filename> machine | ||
5203 | configuration file, which can be found in the | ||
5204 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> | ||
5205 | in <filename>meta/conf/machine</filename>. | ||
5206 | </para> | ||
5207 | |||
5208 | <para> | ||
5209 | The list of machines supported by the Yocto Project as | ||
5210 | shipped include the following: | ||
5211 | <literallayout class='monospaced'> | ||
5212 | MACHINE ?= "qemuarm" | ||
5213 | MACHINE ?= "qemumips" | ||
5214 | MACHINE ?= "qemuppc" | ||
5215 | MACHINE ?= "qemux86" | ||
5216 | MACHINE ?= "qemux86-64" | ||
5217 | MACHINE ?= "genericx86" | ||
5218 | MACHINE ?= "genericx86-64" | ||
5219 | MACHINE ?= "beaglebone" | ||
5220 | MACHINE ?= "mpc8315e-rdb" | ||
5221 | MACHINE ?= "edgerouter" | ||
5222 | </literallayout> | ||
5223 | The last five are Yocto Project reference hardware boards, which | ||
5224 | are provided in the <filename>meta-yocto-bsp</filename> layer. | ||
5225 | <note>Adding additional Board Support Package (BSP) layers | ||
5226 | to your configuration adds new possible settings for | ||
5227 | <filename>MACHINE</filename>. | ||
5228 | </note> | ||
5229 | </para> | ||
5230 | </glossdef> | ||
5231 | </glossentry> | ||
5232 | |||
5233 | <glossentry id='var-MACHINE_ARCH'><glossterm>MACHINE_ARCH</glossterm> | ||
5234 | <glossdef> | ||
5235 | <para> | ||
5236 | Specifies the name of the machine-specific architecture. | ||
5237 | This variable is set automatically from | ||
5238 | <link linkend='var-MACHINE'><filename>MACHINE</filename></link> | ||
5239 | or | ||
5240 | <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>. | ||
5241 | You should not hand-edit the | ||
5242 | <filename>MACHINE_ARCH</filename> variable. | ||
5243 | </para> | ||
5244 | </glossdef> | ||
5245 | </glossentry> | ||
5246 | |||
5247 | <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm> | ||
5248 | <glossdef> | ||
5249 | <para> | ||
5250 | A list of required machine-specific packages to install as part of | ||
5251 | the image being built. | ||
5252 | The build process depends on these packages being present. | ||
5253 | Furthermore, because this is a "machine essential" variable, the list of | ||
5254 | packages are essential for the machine to boot. | ||
5255 | The impact of this variable affects images based on | ||
5256 | <filename>packagegroup-core-boot</filename>, | ||
5257 | including the <filename>core-image-minimal</filename> image. | ||
5258 | </para> | ||
5259 | <para> | ||
5260 | This variable is similar to the | ||
5261 | <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename> | ||
5262 | variable with the exception that the image being built has a build | ||
5263 | dependency on the variable's list of packages. | ||
5264 | In other words, the image will not build if a file in this list is not found. | ||
5265 | </para> | ||
5266 | <para> | ||
5267 | As an example, suppose the machine for which you are building requires | ||
5268 | <filename>example-init</filename> to be run during boot to initialize the hardware. | ||
5269 | In this case, you would use the following in the machine's | ||
5270 | <filename>.conf</filename> configuration file: | ||
5271 | <literallayout class='monospaced'> | ||
5272 | MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" | ||
5273 | </literallayout> | ||
5274 | </para> | ||
5275 | </glossdef> | ||
5276 | </glossentry> | ||
5277 | |||
5278 | <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm> | ||
5279 | <glossdef> | ||
5280 | <para> | ||
5281 | A list of recommended machine-specific packages to install as part of | ||
5282 | the image being built. | ||
5283 | The build process does not depend on these packages being present. | ||
5284 | However, because this is a "machine essential" variable, the list of | ||
5285 | packages are essential for the machine to boot. | ||
5286 | The impact of this variable affects images based on | ||
5287 | <filename>packagegroup-core-boot</filename>, | ||
5288 | including the <filename>core-image-minimal</filename> image. | ||
5289 | </para> | ||
5290 | <para> | ||
5291 | This variable is similar to the | ||
5292 | <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename> | ||
5293 | variable with the exception that the image being built does not have a build | ||
5294 | dependency on the variable's list of packages. | ||
5295 | In other words, the image will still build if a package in this list is not found. | ||
5296 | Typically, this variable is used to handle essential kernel modules, whose | ||
5297 | functionality may be selected to be built into the kernel rather than as a module, | ||
5298 | in which case a package will not be produced. | ||
5299 | </para> | ||
5300 | <para> | ||
5301 | Consider an example where you have a custom kernel where a specific touchscreen | ||
5302 | driver is required for the machine to be usable. | ||
5303 | However, the driver can be built as a module or | ||
5304 | into the kernel depending on the kernel configuration. | ||
5305 | If the driver is built as a module, you want it to be installed. | ||
5306 | But, when the driver is built into the kernel, you still want the | ||
5307 | build to succeed. | ||
5308 | This variable sets up a "recommends" relationship so that in the latter case, | ||
5309 | the build will not fail due to the missing package. | ||
5310 | To accomplish this, assuming the package for the module was called | ||
5311 | <filename>kernel-module-ab123</filename>, you would use the | ||
5312 | following in the machine's <filename>.conf</filename> configuration | ||
5313 | file: | ||
5314 | <literallayout class='monospaced'> | ||
5315 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" | ||
5316 | </literallayout> | ||
5317 | </para> | ||
5318 | <para> | ||
5319 | Some examples of these machine essentials are flash, screen, keyboard, mouse, | ||
5320 | or touchscreen drivers (depending on the machine). | ||
5321 | </para> | ||
5322 | </glossdef> | ||
5323 | </glossentry> | ||
5324 | |||
5325 | <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm> | ||
5326 | <glossdef> | ||
5327 | <para> | ||
5328 | A list of machine-specific packages to install as part of the | ||
5329 | image being built that are not essential for the machine to boot. | ||
5330 | However, the build process for more fully-featured images | ||
5331 | depends on the packages being present. | ||
5332 | </para> | ||
5333 | <para> | ||
5334 | This variable affects all images based on | ||
5335 | <filename>packagegroup-base</filename>, which does not include the | ||
5336 | <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename> | ||
5337 | images. | ||
5338 | </para> | ||
5339 | <para> | ||
5340 | The variable is similar to the | ||
5341 | <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename> | ||
5342 | variable with the exception that the image being built has a build | ||
5343 | dependency on the variable's list of packages. | ||
5344 | In other words, the image will not build if a file in this list is not found. | ||
5345 | </para> | ||
5346 | <para> | ||
5347 | An example is a machine that has WiFi capability but is not | ||
5348 | essential for the machine to boot the image. | ||
5349 | However, if you are building a more fully-featured image, you want to enable | ||
5350 | the WiFi. | ||
5351 | The package containing the firmware for the WiFi hardware is always | ||
5352 | expected to exist, so it is acceptable for the build process to depend upon | ||
5353 | finding the package. | ||
5354 | In this case, assuming the package for the firmware was called | ||
5355 | <filename>wifidriver-firmware</filename>, you would use the following in the | ||
5356 | <filename>.conf</filename> file for the machine: | ||
5357 | <literallayout class='monospaced'> | ||
5358 | MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" | ||
5359 | </literallayout> | ||
5360 | </para> | ||
5361 | </glossdef> | ||
5362 | </glossentry> | ||
5363 | |||
5364 | <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm> | ||
5365 | <glossdef> | ||
5366 | <para> | ||
5367 | A list of machine-specific packages to install as part of the | ||
5368 | image being built that are not essential for booting the machine. | ||
5369 | The image being built has no build dependency on this list of packages. | ||
5370 | </para> | ||
5371 | <para> | ||
5372 | This variable affects only images based on | ||
5373 | <filename>packagegroup-base</filename>, which does not include the | ||
5374 | <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename> | ||
5375 | images. | ||
5376 | </para> | ||
5377 | <para> | ||
5378 | This variable is similar to the | ||
5379 | <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename> | ||
5380 | variable with the exception that the image being built does not have a build | ||
5381 | dependency on the variable's list of packages. | ||
5382 | In other words, the image will build if a file in this list is not found. | ||
5383 | </para> | ||
5384 | <para> | ||
5385 | An example is a machine that has WiFi capability but is not essential | ||
5386 | For the machine to boot the image. | ||
5387 | However, if you are building a more fully-featured image, you want to enable | ||
5388 | WiFi. | ||
5389 | In this case, the package containing the WiFi kernel module will not be produced | ||
5390 | if the WiFi driver is built into the kernel, in which case you still want the | ||
5391 | build to succeed instead of failing as a result of the package not being found. | ||
5392 | To accomplish this, assuming the package for the module was called | ||
5393 | <filename>kernel-module-examplewifi</filename>, you would use the | ||
5394 | following in the <filename>.conf</filename> file for the machine: | ||
5395 | <literallayout class='monospaced'> | ||
5396 | MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" | ||
5397 | </literallayout> | ||
5398 | </para> | ||
5399 | </glossdef> | ||
5400 | </glossentry> | ||
5401 | |||
5402 | <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm> | ||
5403 | <glossdef> | ||
5404 | <para> | ||
5405 | Specifies the list of hardware features the | ||
5406 | <link linkend='var-MACHINE'><filename>MACHINE</filename></link> is capable | ||
5407 | of supporting. | ||
5408 | For related information on enabling features, see the | ||
5409 | <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>, | ||
5410 | <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>, | ||
5411 | and | ||
5412 | <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> | ||
5413 | variables. | ||
5414 | </para> | ||
5415 | |||
5416 | <para> | ||
5417 | For a list of hardware features supported by the Yocto | ||
5418 | Project as shipped, see the | ||
5419 | "<link linkend='ref-features-machine'>Machine Features</link>" | ||
5420 | section. | ||
5421 | </para> | ||
5422 | </glossdef> | ||
5423 | </glossentry> | ||
5424 | |||
5425 | <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm> | ||
5426 | <glossdef> | ||
5427 | <para>Features to be added to | ||
5428 | <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename> | ||
5429 | if not also present in | ||
5430 | <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>. | ||
5431 | </para> | ||
5432 | |||
5433 | <para> | ||
5434 | This variable is set in the <filename>meta/conf/bitbake.conf</filename> file. | ||
5435 | It is not intended to be user-configurable. | ||
5436 | It is best to just reference the variable to see which machine features are | ||
5437 | being backfilled for all machine configurations. | ||
5438 | See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for | ||
5439 | more information. | ||
5440 | </para> | ||
5441 | </glossdef> | ||
5442 | </glossentry> | ||
5443 | |||
5444 | <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm> | ||
5445 | <glossdef> | ||
5446 | <para>Features from | ||
5447 | <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename> | ||
5448 | that should not be backfilled (i.e. added to | ||
5449 | <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>) | ||
5450 | during the build. | ||
5451 | See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for | ||
5452 | more information. | ||
5453 | </para> | ||
5454 | </glossdef> | ||
5455 | </glossentry> | ||
5456 | |||
5457 | <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm> | ||
5458 | <glossdef> | ||
5459 | <para> | ||
5460 | Lists overrides specific to the current machine. | ||
5461 | By default, this list includes the value | ||
5462 | of <filename><link linkend='var-MACHINE'>MACHINE</link></filename>. | ||
5463 | You can extend the list to apply variable overrides for | ||
5464 | classes of machines. | ||
5465 | For example, all QEMU emulated machines (e.g. qemuarm, | ||
5466 | qemux86, and so forth) include a common file named | ||
5467 | <filename>meta/conf/machine/include/qemu.inc</filename> | ||
5468 | that prepends <filename>MACHINEOVERRIDES</filename> with | ||
5469 | the following variable override: | ||
5470 | <literallayout class='monospaced'> | ||
5471 | MACHINEOVERRIDES =. "qemuall:" | ||
5472 | </literallayout> | ||
5473 | Applying an override like <filename>qemuall</filename> | ||
5474 | affects all QEMU emulated machines elsewhere. | ||
5475 | Here is an example from the | ||
5476 | <filename>connman-conf</filename> recipe: | ||
5477 | <literallayout class='monospaced'> | ||
5478 | SRC_URI_append_qemuall = "file://wired.config \ | ||
5479 | file://wired-setup \ | ||
5480 | " | ||
5481 | </literallayout> | ||
5482 | </para> | ||
5483 | </glossdef> | ||
5484 | </glossentry> | ||
5485 | |||
5486 | <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm> | ||
5487 | <glossdef> | ||
5488 | <para>The email address of the distribution maintainer.</para> | ||
5489 | </glossdef> | ||
5490 | </glossentry> | ||
5491 | |||
5492 | <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm> | ||
5493 | <glossdef> | ||
5494 | <para> | ||
5495 | Specifies additional paths from which the OpenEmbedded | ||
5496 | build system gets source code. | ||
5497 | When the build system searches for source code, it first | ||
5498 | tries the local download directory. | ||
5499 | If that location fails, the build system tries locations | ||
5500 | defined by | ||
5501 | <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>, | ||
5502 | the upstream source, and then locations specified by | ||
5503 | <filename>MIRRORS</filename> in that order. | ||
5504 | </para> | ||
5505 | |||
5506 | <para> | ||
5507 | Assuming your distribution | ||
5508 | (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>) | ||
5509 | is "poky", the default value for | ||
5510 | <filename>MIRRORS</filename> is defined in the | ||
5511 | <filename>conf/distro/poky.conf</filename> file in the | ||
5512 | <filename>meta-yocto</filename> Git repository. | ||
5513 | </para> | ||
5514 | </glossdef> | ||
5515 | </glossentry> | ||
5516 | |||
5517 | <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm> | ||
5518 | <glossdef> | ||
5519 | <para> | ||
5520 | Specifies a prefix has been added to | ||
5521 | <link linkend='var-PN'><filename>PN</filename></link> to create a special version | ||
5522 | of a recipe or package, such as a Multilib version. | ||
5523 | The variable is used in places where the prefix needs to be | ||
5524 | added to or removed from a the name (e.g. the | ||
5525 | <link linkend='var-BPN'><filename>BPN</filename></link> variable). | ||
5526 | <filename>MLPREFIX</filename> gets set when a prefix has been | ||
5527 | added to <filename>PN</filename>. | ||
5528 | </para> | ||
5529 | </glossdef> | ||
5530 | </glossentry> | ||
5531 | |||
5532 | <glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm> | ||
5533 | <glossdef> | ||
5534 | <para> | ||
5535 | This variable has been replaced by the | ||
5536 | <filename>KERNEL_MODULE_AUTOLOAD</filename> variable. | ||
5537 | You should replace all occurrences of | ||
5538 | <filename>module_autoload</filename> with additions to | ||
5539 | <filename>KERNEL_MODULE_AUTOLOAD</filename>, for example: | ||
5540 | <literallayout class='monospaced'> | ||
5541 | module_autoload_rfcomm = "rfcomm" | ||
5542 | </literallayout> | ||
5543 | should now be replaced with: | ||
5544 | <literallayout class='monospaced'> | ||
5545 | KERNEL_MODULE_AUTOLOAD += "rfcomm" | ||
5546 | </literallayout> | ||
5547 | See the | ||
5548 | <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link> | ||
5549 | variable for more information. | ||
5550 | </para> | ||
5551 | </glossdef> | ||
5552 | </glossentry> | ||
5553 | |||
5554 | <glossentry id='var-module_conf'><glossterm>module_conf</glossterm> | ||
5555 | <glossdef> | ||
5556 | <para> | ||
5557 | Specifies | ||
5558 | <ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink> | ||
5559 | syntax lines for inclusion in the | ||
5560 | <filename>/etc/modprobe.d/modname.conf</filename> file. | ||
5561 | </para> | ||
5562 | |||
5563 | <para> | ||
5564 | You can use this variable anywhere that it can be | ||
5565 | recognized by the kernel recipe or out-of-tree kernel | ||
5566 | module recipe (e.g. a machine configuration file, a | ||
5567 | distribution configuration file, an append file for the | ||
5568 | recipe, or the recipe itself). | ||
5569 | If you use this variable, you must also be sure to list | ||
5570 | the module name in the | ||
5571 | <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link> | ||
5572 | variable. | ||
5573 | </para> | ||
5574 | |||
5575 | <para> | ||
5576 | Here is the general syntax: | ||
5577 | <literallayout class='monospaced'> | ||
5578 | module_conf_<replaceable>module_name</replaceable> = "<replaceable>modprobe.d-syntax</replaceable>" | ||
5579 | </literallayout> | ||
5580 | You must use the kernel module name override. | ||
5581 | </para> | ||
5582 | |||
5583 | <para> | ||
5584 | Run <filename>man modprobe.d</filename> in the shell to | ||
5585 | find out more information on the exact syntax | ||
5586 | you want to provide with <filename>module_conf</filename>. | ||
5587 | </para> | ||
5588 | |||
5589 | <para> | ||
5590 | Including <filename>module_conf</filename> causes the | ||
5591 | OpenEmbedded build system to populate the | ||
5592 | <filename>/etc/modprobe.d/modname.conf</filename> | ||
5593 | file with <filename>modprobe.d</filename> syntax lines. | ||
5594 | Here is an example that adds the options | ||
5595 | <filename>arg1</filename> and <filename>arg2</filename> | ||
5596 | to a module named <filename>mymodule</filename>: | ||
5597 | <literallayout class='monospaced'> | ||
5598 | module_conf_mymodule = "options mymodule arg1=val1 arg2=val2" | ||
5599 | </literallayout> | ||
5600 | </para> | ||
5601 | |||
5602 | <para> | ||
5603 | For information on how to specify kernel modules to | ||
5604 | auto-load on boot, see the | ||
5605 | <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link> | ||
5606 | variable. | ||
5607 | </para> | ||
5608 | </glossdef> | ||
5609 | </glossentry> | ||
5610 | |||
5611 | <glossentry id='var-MODULE_IMAGE_BASE_NAME'><glossterm>MODULE_IMAGE_BASE_NAME</glossterm> | ||
5612 | <glossdef> | ||
5613 | <para> | ||
5614 | The base name of the kernel modules tarball. | ||
5615 | This variable is set in the | ||
5616 | <link linkend='ref-classes-kernel'>kernel</link> class | ||
5617 | as follows: | ||
5618 | <literallayout class='monospaced'> | ||
5619 | MODULE_IMAGE_BASE_NAME ?= "modules-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}" | ||
5620 | </literallayout> | ||
5621 | See the | ||
5622 | <link linkend='var-PKGE'><filename>PKGE</filename></link>, | ||
5623 | <link linkend='var-PKGV'><filename>PKGV</filename></link>, | ||
5624 | <link linkend='var-PKGR'><filename>PKGR</filename></link>, | ||
5625 | <link linkend='var-MACHINE'><filename>MACHINE</filename></link>, | ||
5626 | and | ||
5627 | <link linkend='var-DATETIME'><filename>DATETIME</filename></link> | ||
5628 | variables for additional information. | ||
5629 | </para> | ||
5630 | </glossdef> | ||
5631 | </glossentry> | ||
5632 | |||
5633 | <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm> | ||
5634 | <glossdef> | ||
5635 | <para> | ||
5636 | Controls creation of the <filename>modules-*.tgz</filename> | ||
5637 | file. | ||
5638 | Set this variable to "0" to disable creation of this | ||
5639 | file, which contains all of the kernel modules resulting | ||
5640 | from a kernel build. | ||
5641 | </para> | ||
5642 | </glossdef> | ||
5643 | </glossentry> | ||
5644 | |||
5645 | <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm> | ||
5646 | <glossdef> | ||
5647 | <para> | ||
5648 | Separates files for different machines such that you can build | ||
5649 | for multiple target machines using the same output directories. | ||
5650 | See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable | ||
5651 | for an example. | ||
5652 | </para> | ||
5653 | </glossdef> | ||
5654 | </glossentry> | ||
5655 | |||
5656 | </glossdiv> | ||
5657 | |||
5658 | <glossdiv id='var-glossary-n'><title>N</title> | ||
5659 | |||
5660 | <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm> | ||
5661 | <glossdef> | ||
5662 | <para> | ||
5663 | A string identifying the host distribution. | ||
5664 | Strings consist of the host distributor ID | ||
5665 | followed by the release, as reported by the | ||
5666 | <filename>lsb_release</filename> tool | ||
5667 | or as read from <filename>/etc/lsb-release</filename>. | ||
5668 | For example, when running a build on Ubuntu 12.10, the value | ||
5669 | is "Ubuntu-12.10". | ||
5670 | If this information is unable to be determined, the value | ||
5671 | resolves to "Unknown". | ||
5672 | </para> | ||
5673 | <para> | ||
5674 | This variable is used by default to isolate native shared | ||
5675 | state packages for different distributions (e.g. to avoid | ||
5676 | problems with <filename>glibc</filename> version | ||
5677 | incompatibilities). | ||
5678 | Additionally, the variable is checked against | ||
5679 | <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link> | ||
5680 | if that variable is set. | ||
5681 | </para> | ||
5682 | </glossdef> | ||
5683 | </glossentry> | ||
5684 | |||
5685 | <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm> | ||
5686 | <glossdef> | ||
5687 | <para> | ||
5688 | Prevents installation of all "recommended-only" packages. | ||
5689 | Recommended-only packages are packages installed only | ||
5690 | through the | ||
5691 | <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> | ||
5692 | variable). | ||
5693 | Setting the <filename>NO_RECOMMENDATIONS</filename> variable | ||
5694 | to "1" turns this feature on: | ||
5695 | <literallayout class='monospaced'> | ||
5696 | NO_RECOMMENDATIONS = "1" | ||
5697 | </literallayout> | ||
5698 | You can set this variable globally in your | ||
5699 | <filename>local.conf</filename> file or you can attach it to | ||
5700 | a specific image recipe by using the recipe name override: | ||
5701 | <literallayout class='monospaced'> | ||
5702 | NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>" | ||
5703 | </literallayout> | ||
5704 | </para> | ||
5705 | |||
5706 | <para> | ||
5707 | It is important to realize that if you choose to not install | ||
5708 | packages using this variable and some other packages are | ||
5709 | dependent on them (i.e. listed in a recipe's | ||
5710 | <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> | ||
5711 | variable), the OpenEmbedded build system ignores your | ||
5712 | request and will install the packages to avoid dependency | ||
5713 | errors. | ||
5714 | <note> | ||
5715 | Some recommended packages might be required for certain | ||
5716 | system functionality, such as kernel modules. | ||
5717 | It is up to you to add packages with the | ||
5718 | <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link> | ||
5719 | variable. | ||
5720 | </note> | ||
5721 | </para> | ||
5722 | |||
5723 | <para> | ||
5724 | Support for this variable exists only when using the | ||
5725 | IPK and RPM packaging backend. | ||
5726 | Support does not exist for DEB. | ||
5727 | </para> | ||
5728 | |||
5729 | <para> | ||
5730 | See the | ||
5731 | <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link> | ||
5732 | and the | ||
5733 | <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link> | ||
5734 | variables for related information. | ||
5735 | </para> | ||
5736 | </glossdef> | ||
5737 | </glossentry> | ||
5738 | |||
5739 | <glossentry id='var-NOHDD'><glossterm>NOHDD</glossterm> | ||
5740 | <glossdef> | ||
5741 | <para> | ||
5742 | Causes the OpenEmbedded build system to skip building the | ||
5743 | <filename>.hddimg</filename> image. | ||
5744 | The <filename>NOHDD</filename> variable is used with the | ||
5745 | <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link> | ||
5746 | class. | ||
5747 | Set the variable to "1" to prevent the | ||
5748 | <filename>.hddimg</filename> image from being built. | ||
5749 | </para> | ||
5750 | </glossdef> | ||
5751 | </glossentry> | ||
5752 | |||
5753 | <glossentry id='var-NOISO'><glossterm>NOISO</glossterm> | ||
5754 | <glossdef> | ||
5755 | <para> | ||
5756 | Causes the OpenEmbedded build system to skip building the | ||
5757 | ISO image. | ||
5758 | The <filename>NOISO</filename> variable is used with the | ||
5759 | <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link> | ||
5760 | class. | ||
5761 | Set the variable to "1" to prevent the ISO image from | ||
5762 | being built. | ||
5763 | To enable building an ISO image, set the variable to "0". | ||
5764 | </para> | ||
5765 | </glossdef> | ||
5766 | </glossentry> | ||
5767 | |||
5768 | </glossdiv> | ||
5769 | |||
5770 | <glossdiv id='var-glossary-o'><title>O</title> | ||
5771 | |||
5772 | <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm> | ||
5773 | <glossdef> | ||
5774 | <para> | ||
5775 | When inheriting the | ||
5776 | <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link> | ||
5777 | class, this variable | ||
5778 | specifies additional arguments passed to the "sed" command. | ||
5779 | The sed command alters any paths in configuration scripts | ||
5780 | that have been set up during compilation. | ||
5781 | Inheriting this class results in all paths in these scripts | ||
5782 | being changed to point into the | ||
5783 | <filename>sysroots/</filename> directory so that all builds | ||
5784 | that use the script will use the correct directories | ||
5785 | for the cross compiling layout. | ||
5786 | </para> | ||
5787 | |||
5788 | <para> | ||
5789 | See the <filename>meta/classes/binconfig.bbclass</filename> | ||
5790 | in the | ||
5791 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> | ||
5792 | for details on how this class applies these additional | ||
5793 | sed command arguments. | ||
5794 | For general information on the | ||
5795 | <filename>binconfig.bbclass</filename> class, see the | ||
5796 | "<link linkend='ref-classes-binconfig'>Binary Configuration Scripts - <filename>binconfig.bbclass</filename></link>" | ||
5797 | section. | ||
5798 | </para> | ||
5799 | </glossdef> | ||
5800 | </glossentry> | ||
5801 | |||
5802 | <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm> | ||
5803 | <glossdef> | ||
5804 | <para> | ||
5805 | An internal variable used to tell the OpenEmbedded build | ||
5806 | system what Python modules to import for every Python | ||
5807 | function run by the system. | ||
5808 | </para> | ||
5809 | |||
5810 | <note> | ||
5811 | Do not set this variable. | ||
5812 | It is for internal use only. | ||
5813 | </note> | ||
5814 | </glossdef> | ||
5815 | </glossentry> | ||
5816 | |||
5817 | <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm> | ||
5818 | <glossdef> | ||
5819 | <para> | ||
5820 | Controls how the OpenEmbedded build system spawns | ||
5821 | interactive terminals on the host development system | ||
5822 | (e.g. using the BitBake command with the | ||
5823 | <filename>-c devshell</filename> command-line option). | ||
5824 | For more information, see the | ||
5825 | "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section | ||
5826 | in the Yocto Project Development Manual. | ||
5827 | </para> | ||
5828 | |||
5829 | <para> | ||
5830 | You can use the following values for the | ||
5831 | <filename>OE_TERMINAL</filename> variable: | ||
5832 | <literallayout class='monospaced'> | ||
5833 | auto | ||
5834 | gnome | ||
5835 | xfce | ||
5836 | rxvt | ||
5837 | screen | ||
5838 | konsole | ||
5839 | none | ||
5840 | </literallayout> | ||
5841 | <note>Konsole support only works for KDE 3.x. | ||
5842 | Also, "auto" is the default behavior for | ||
5843 | <filename>OE_TERMINAL</filename></note> | ||
5844 | </para> | ||
5845 | </glossdef> | ||
5846 | </glossentry> | ||
5847 | |||
5848 | <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm> | ||
5849 | <glossdef> | ||
5850 | <para> | ||
5851 | The directory from which the top-level build environment | ||
5852 | setup script is sourced. | ||
5853 | The Yocto Project makes two top-level build environment | ||
5854 | setup scripts available: | ||
5855 | <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link> | ||
5856 | and | ||
5857 | <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>. | ||
5858 | When you run one of these scripts, the | ||
5859 | <filename>OEROOT</filename> variable resolves to the | ||
5860 | directory that contains the script. | ||
5861 | </para> | ||
5862 | |||
5863 | <para> | ||
5864 | For additional information on how this variable is used, | ||
5865 | see the initialization scripts. | ||
5866 | </para> | ||
5867 | </glossdef> | ||
5868 | </glossentry> | ||
5869 | |||
5870 | <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm> | ||
5871 | <glossdef> | ||
5872 | <para> | ||
5873 | Declares the oldest version of the Linux kernel that the | ||
5874 | produced binaries must support. | ||
5875 | This variable is passed into the build of the Embedded | ||
5876 | GNU C Library (<filename>glibc</filename>). | ||
5877 | </para> | ||
5878 | |||
5879 | <para> | ||
5880 | The default for this variable comes from the | ||
5881 | <filename>meta/conf/bitbake.conf</filename> configuration | ||
5882 | file. | ||
5883 | You can override this default by setting the variable | ||
5884 | in a custom distribution configuration file. | ||
5885 | </para> | ||
5886 | </glossdef> | ||
5887 | </glossentry> | ||
5888 | |||
5889 | <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm> | ||
5890 | <glossdef> | ||
5891 | <para> | ||
5892 | BitBake uses <filename>OVERRIDES</filename> to control | ||
5893 | what variables are overridden after BitBake parses | ||
5894 | recipes and configuration files. | ||
5895 | You can find more information on how overrides are handled | ||
5896 | in the | ||
5897 | "<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>" | ||
5898 | section of the BitBake User Manual. | ||
5899 | </para> | ||
5900 | </glossdef> | ||
5901 | </glossentry> | ||
5902 | </glossdiv> | ||
5903 | |||
5904 | <glossdiv id='var-glossary-p'><title>P</title> | ||
5905 | |||
5906 | <glossentry id='var-P'><glossterm>P</glossterm> | ||
5907 | <glossdef> | ||
5908 | <para>The recipe name and version. | ||
5909 | <filename>P</filename> is comprised of the following: | ||
5910 | <literallayout class='monospaced'> | ||
5911 | ${PN}-${PV} | ||
5912 | </literallayout></para> | ||
5913 | </glossdef> | ||
5914 | </glossentry> | ||
5915 | |||
5916 | <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm> | ||
5917 | <glossdef> | ||
5918 | <para> | ||
5919 | The architecture of the resulting package or packages. | ||
5920 | </para> | ||
5921 | |||
5922 | <para> | ||
5923 | By default, the value of this variable is set to | ||
5924 | <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link> | ||
5925 | when building for the target, | ||
5926 | <filename>BUILD_ARCH</filename> when building for the | ||
5927 | build host and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building | ||
5928 | for the SDK. | ||
5929 | However, if your recipe's output packages are built | ||
5930 | specific to the target machine rather than general for | ||
5931 | the architecture of the machine, you should set | ||
5932 | <filename>PACKAGE_ARCH</filename> to the value of | ||
5933 | <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link> | ||
5934 | in the recipe as follows: | ||
5935 | <literallayout class='monospaced'> | ||
5936 | PACKAGE_ARCH = "${MACHINE_ARCH}" | ||
5937 | </literallayout> | ||
5938 | </para> | ||
5939 | </glossdef> | ||
5940 | </glossentry> | ||
5941 | |||
5942 | <glossentry id='var-PACKAGE_ARCHS'><glossterm>PACKAGE_ARCHS</glossterm> | ||
5943 | <glossdef> | ||
5944 | <para> | ||
5945 | Specifies a list of architectures compatible with | ||
5946 | the target machine. | ||
5947 | This variable is set automatically and should not | ||
5948 | normally be hand-edited. | ||
5949 | Entries are separated using spaces and listed in order | ||
5950 | of priority. | ||
5951 | The default value for | ||
5952 | <filename>PACKAGE_ARCHS</filename> is "all any noarch | ||
5953 | ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}". | ||
5954 | </para> | ||
5955 | </glossdef> | ||
5956 | </glossentry> | ||
5957 | |||
5958 | |||
5959 | |||
5960 | <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm> | ||
5961 | <glossdef> | ||
5962 | <para>Enables easily adding packages to | ||
5963 | <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> | ||
5964 | before <filename>${<link linkend='var-PN'>PN</link>}</filename> | ||
5965 | so that those added packages can pick up files that would normally be | ||
5966 | included in the default package.</para> | ||
5967 | </glossdef> | ||
5968 | </glossentry> | ||
5969 | |||
5970 | <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm> | ||
5971 | <glossdef> | ||
5972 | <para> | ||
5973 | This variable, which is set in the | ||
5974 | <filename>local.conf</filename> configuration file found in | ||
5975 | the <filename>conf</filename> folder of the | ||
5976 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, | ||
5977 | specifies the package manager the OpenEmbedded build system | ||
5978 | uses when packaging data. | ||
5979 | </para> | ||
5980 | |||
5981 | <para> | ||
5982 | You can provide one or more of the following arguments for | ||
5983 | the variable: | ||
5984 | <literallayout class='monospaced'> | ||
5985 | PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar" | ||
5986 | </literallayout> | ||
5987 | The build system uses only the first argument in the list | ||
5988 | as the package manager when creating your image or SDK. | ||
5989 | However, packages will be created using any additional | ||
5990 | packaging classes you specify. | ||
5991 | For example, if you use the following in your | ||
5992 | <filename>local.conf</filename> file: | ||
5993 | <literallayout class='monospaced'> | ||
5994 | PACKAGE_CLASSES ?= "package_ipk package_tar" | ||
5995 | </literallayout> | ||
5996 | The OpenEmbedded build system uses the IPK package manager | ||
5997 | to create your image or SDK as well as generating | ||
5998 | TAR packages. | ||
5999 | </para> | ||
6000 | |||
6001 | <para> | ||
6002 | You cannot specify the | ||
6003 | <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link> | ||
6004 | class first in the list. | ||
6005 | Files using the <filename>.tar</filename> format cannot | ||
6006 | be used as a substitute packaging format | ||
6007 | for DEB, RPM, and IPK formatted files for your image or SDK. | ||
6008 | </para> | ||
6009 | |||
6010 | <para> | ||
6011 | For information on packaging and build performance effects | ||
6012 | as a result of the package manager in use, see the | ||
6013 | "<link linkend='ref-classes-package'><filename>package.bbclass</filename></link>" | ||
6014 | section. | ||
6015 | </para> | ||
6016 | </glossdef> | ||
6017 | </glossentry> | ||
6018 | |||
6019 | <glossentry id='var-PACKAGE_DEBUG_SPLIT_STYLE'><glossterm>PACKAGE_DEBUG_SPLIT_STYLE</glossterm> | ||
6020 | <glossdef> | ||
6021 | |||
6022 | <para> | ||
6023 | Determines how to split up the binary and debug information | ||
6024 | when creating <filename>*-dbg</filename> packages to be | ||
6025 | used with the GNU Project Debugger (GDB). | ||
6026 | </para> | ||
6027 | |||
6028 | <para> | ||
6029 | With the | ||
6030 | <filename>PACKAGE_DEBUG_SPLIT_STYLE</filename> variable, | ||
6031 | you can control where debug information, which can include | ||
6032 | or exclude source files, is stored: | ||
6033 | <itemizedlist> | ||
6034 | <listitem><para> | ||
6035 | ".debug": Debug symbol files are placed next | ||
6036 | to the binary in a <filename>.debug</filename> | ||
6037 | directory on the target. | ||
6038 | For example, if a binary is installed into | ||
6039 | <filename>/bin</filename>, the corresponding debug | ||
6040 | symbol files are installed in | ||
6041 | <filename>/bin/.debug</filename>. | ||
6042 | Source files are placed in | ||
6043 | <filename>/usr/src/debug</filename>. | ||
6044 | This is the default behavior. | ||
6045 | </para></listitem> | ||
6046 | <listitem><para> | ||
6047 | "debug-file-directory": Debug symbol files are | ||
6048 | placed under <filename>/usr/lib/debug</filename> | ||
6049 | on the target, and separated by the path from where | ||
6050 | the binary is installed. | ||
6051 | For example, if a binary is installed in | ||
6052 | <filename>/bin</filename>, the corresponding debug | ||
6053 | symbols are installed in | ||
6054 | <filename>/usr/lib/debug/bin</filename>. | ||
6055 | Source files are placed in | ||
6056 | <filename>/usr/src/debug</filename>. | ||
6057 | </para></listitem> | ||
6058 | <listitem><para> | ||
6059 | "debug-without-src": The same behavior as | ||
6060 | ".debug" previously described with the exception | ||
6061 | that no source files are installed. | ||
6062 | </para></listitem>. | ||
6063 | </itemizedlist> | ||
6064 | </para> | ||
6065 | |||
6066 | <para> | ||
6067 | You can find out more about debugging using GDB by reading | ||
6068 | the | ||
6069 | "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>" | ||
6070 | section in the Yocto Project Development Manual. | ||
6071 | </para> | ||
6072 | </glossdef> | ||
6073 | </glossentry> | ||
6074 | |||
6075 | <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm> | ||
6076 | <glossdef> | ||
6077 | <para> | ||
6078 | Lists packages that should not be installed into an image. | ||
6079 | For example: | ||
6080 | <literallayout class='monospaced'> | ||
6081 | PACKAGE_EXCLUDE = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..." | ||
6082 | </literallayout> | ||
6083 | You can set this variable globally in your | ||
6084 | <filename>local.conf</filename> file or you can attach it to | ||
6085 | a specific image recipe by using the recipe name override: | ||
6086 | <literallayout class='monospaced'> | ||
6087 | PACKAGE_EXCLUDE_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>" | ||
6088 | </literallayout> | ||
6089 | </para> | ||
6090 | |||
6091 | <para> | ||
6092 | If you choose to not install | ||
6093 | a package using this variable and some other package is | ||
6094 | dependent on it (i.e. listed in a recipe's | ||
6095 | <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> | ||
6096 | variable), the OpenEmbedded build system generates a fatal | ||
6097 | installation error. | ||
6098 | Because the build system halts the process with a fatal | ||
6099 | error, you can use the variable with an iterative | ||
6100 | development process to remove specific components from a | ||
6101 | system. | ||
6102 | </para> | ||
6103 | |||
6104 | <para> | ||
6105 | Support for this variable exists only when using the | ||
6106 | IPK and RPM packaging backend. | ||
6107 | Support does not exist for DEB. | ||
6108 | </para> | ||
6109 | |||
6110 | <para> | ||
6111 | See the | ||
6112 | <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link> | ||
6113 | and the | ||
6114 | <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link> | ||
6115 | variables for related information. | ||
6116 | </para> | ||
6117 | </glossdef> | ||
6118 | </glossentry> | ||
6119 | |||
6120 | <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm> | ||
6121 | <glossdef> | ||
6122 | <para>Specifies the list of architectures compatible with the device CPU. | ||
6123 | This variable is useful when you build for several different devices that use | ||
6124 | miscellaneous processors such as XScale and ARM926-EJS).</para> | ||
6125 | </glossdef> | ||
6126 | </glossentry> | ||
6127 | |||
6128 | <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm> | ||
6129 | <glossdef> | ||
6130 | |||
6131 | <para> | ||
6132 | The <filename>PACKAGE_GROUP</filename> variable has been | ||
6133 | renamed to | ||
6134 | <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>. | ||
6135 | See the variable description for | ||
6136 | <filename>FEATURE_PACKAGES</filename> for information. | ||
6137 | </para> | ||
6138 | |||
6139 | <para> | ||
6140 | If if you use the <filename>PACKAGE_GROUP</filename> | ||
6141 | variable, the OpenEmbedded build system issues a warning | ||
6142 | message. | ||
6143 | </para> | ||
6144 | </glossdef> | ||
6145 | </glossentry> | ||
6146 | |||
6147 | <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm> | ||
6148 | <glossdef> | ||
6149 | <para> | ||
6150 | The final list of packages passed to the package manager | ||
6151 | for installation into the image. | ||
6152 | </para> | ||
6153 | |||
6154 | <para> | ||
6155 | Because the package manager controls actual installation | ||
6156 | of all packages, the list of packages passed using | ||
6157 | <filename>PACKAGE_INSTALL</filename> is not the final list | ||
6158 | of packages that are actually installed. | ||
6159 | This variable is internal to the image construction | ||
6160 | code. | ||
6161 | Consequently, in general, you should use the | ||
6162 | <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link> | ||
6163 | variable to specify packages for installation. | ||
6164 | The exception to this is when working with | ||
6165 | the | ||
6166 | <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link> | ||
6167 | image. | ||
6168 | When working with an initial RAM disk (initramfs) | ||
6169 | image, use the <filename>PACKAGE_INSTALL</filename> | ||
6170 | variable. | ||
6171 | </para> | ||
6172 | </glossdef> | ||
6173 | </glossentry> | ||
6174 | |||
6175 | <glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm>PACKAGE_PREPROCESS_FUNCS</glossterm> | ||
6176 | <glossdef> | ||
6177 | <para> | ||
6178 | Specifies a list of functions run to pre-process the | ||
6179 | <link linkend='var-PKGD'><filename>PKGD</filename></link> | ||
6180 | directory prior to splitting the files out to individual | ||
6181 | packages. | ||
6182 | </para> | ||
6183 | </glossdef> | ||
6184 | </glossentry> | ||
6185 | |||
6186 | <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm> | ||
6187 | <glossdef> | ||
6188 | <para> | ||
6189 | This variable provides a means of enabling or disabling | ||
6190 | features of a recipe on a per-recipe basis. | ||
6191 | <filename>PACKAGECONFIG</filename> blocks are defined | ||
6192 | in recipes when you specify features and then arguments | ||
6193 | that define feature behaviors. | ||
6194 | Here is the basic block structure: | ||
6195 | <literallayout class='monospaced'> | ||
6196 | PACKAGECONFIG ??= "f1 f2 f3 ..." | ||
6197 | PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1" | ||
6198 | PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2" | ||
6199 | PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3" | ||
6200 | </literallayout> | ||
6201 | The <filename>PACKAGECONFIG</filename> | ||
6202 | variable itself specifies a space-separated list of the | ||
6203 | features to enable. | ||
6204 | Following the features, you can determine the behavior of | ||
6205 | each feature by providing up to four order-dependent | ||
6206 | arguments, which are separated by commas. | ||
6207 | You can omit any argument you like but must retain the | ||
6208 | separating commas. | ||
6209 | The order is important and specifies the following: | ||
6210 | <orderedlist> | ||
6211 | <listitem><para>Extra arguments | ||
6212 | that should be added to the configure script | ||
6213 | argument list | ||
6214 | (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>) | ||
6215 | if the feature is enabled.</para></listitem> | ||
6216 | <listitem><para>Extra arguments | ||
6217 | that should be added to <filename>EXTRA_OECONF</filename> | ||
6218 | if the feature is disabled. | ||
6219 | </para></listitem> | ||
6220 | <listitem><para>Additional build dependencies | ||
6221 | (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>) | ||
6222 | that should be added if the feature is enabled. | ||
6223 | </para></listitem> | ||
6224 | <listitem><para>Additional runtime dependencies | ||
6225 | (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>) | ||
6226 | that should be added if the feature is enabled. | ||
6227 | </para></listitem> | ||
6228 | </orderedlist> | ||
6229 | </para> | ||
6230 | |||
6231 | <para> | ||
6232 | Consider the following | ||
6233 | <filename>PACKAGECONFIG</filename> block taken from the | ||
6234 | <filename>librsvg</filename> recipe. | ||
6235 | In this example the feature is <filename>croco</filename>, | ||
6236 | which has three arguments that determine the feature's | ||
6237 | behavior. | ||
6238 | <literallayout class='monospaced'> | ||
6239 | PACKAGECONFIG ??= "croco" | ||
6240 | PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco" | ||
6241 | </literallayout> | ||
6242 | The <filename>--with-croco</filename> and | ||
6243 | <filename>libcroco</filename> arguments apply only if | ||
6244 | the feature is enabled. | ||
6245 | In this case, <filename>--with-croco</filename> is | ||
6246 | added to the configure script argument list and | ||
6247 | <filename>libcroco</filename> is added to | ||
6248 | <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>. | ||
6249 | On the other hand, if the feature is disabled say through | ||
6250 | a <filename>.bbappend</filename> file in another layer, then | ||
6251 | the second argument <filename>--without-croco</filename> is | ||
6252 | added to the configure script rather than | ||
6253 | <filename>--with-croco</filename>. | ||
6254 | </para> | ||
6255 | |||
6256 | <para> | ||
6257 | The basic <filename>PACKAGECONFIG</filename> structure | ||
6258 | previously described holds true regardless of whether you | ||
6259 | are creating a block or changing a block. | ||
6260 | When creating a block, use the structure inside your | ||
6261 | recipe. | ||
6262 | </para> | ||
6263 | |||
6264 | <para> | ||
6265 | If you want to change an existing | ||
6266 | <filename>PACKAGECONFIG</filename> block, you can do so | ||
6267 | one of two ways: | ||
6268 | <itemizedlist> | ||
6269 | <listitem><para><emphasis>Append file:</emphasis> | ||
6270 | Create an append file named | ||
6271 | <replaceable>recipename</replaceable><filename>.bbappend</filename> | ||
6272 | in your layer and override the value of | ||
6273 | <filename>PACKAGECONFIG</filename>. | ||
6274 | You can either completely override the variable: | ||
6275 | <literallayout class='monospaced'> | ||
6276 | PACKAGECONFIG="f4 f5" | ||
6277 | </literallayout> | ||
6278 | Or, you can just append the variable: | ||
6279 | <literallayout class='monospaced'> | ||
6280 | PACKAGECONFIG_append = " f4" | ||
6281 | </literallayout></para></listitem> | ||
6282 | <listitem><para><emphasis>Configuration file:</emphasis> | ||
6283 | This method is identical to changing the block | ||
6284 | through an append file except you edit your | ||
6285 | <filename>local.conf</filename> or | ||
6286 | <filename><replaceable>mydistro</replaceable>.conf</filename> file. | ||
6287 | As with append files previously described, | ||
6288 | you can either completely override the variable: | ||
6289 | <literallayout class='monospaced'> | ||
6290 | PACKAGECONFIG_pn-<replaceable>recipename</replaceable>="f4 f5" | ||
6291 | </literallayout> | ||
6292 | Or, you can just amend the variable: | ||
6293 | <literallayout class='monospaced'> | ||
6294 | PACKAGECONFIG_append_pn-<replaceable>recipename</replaceable> = " f4" | ||
6295 | </literallayout></para></listitem> | ||
6296 | </itemizedlist> | ||
6297 | </para> | ||
6298 | </glossdef> | ||
6299 | </glossentry> | ||
6300 | |||
6301 | <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm> | ||
6302 | <glossdef> | ||
6303 | <para>The list of packages to be created from the recipe. | ||
6304 | The default value is the following: | ||
6305 | <literallayout class='monospaced'> | ||
6306 | ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} | ||
6307 | </literallayout></para> | ||
6308 | </glossdef> | ||
6309 | </glossentry> | ||
6310 | |||
6311 | <glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm> | ||
6312 | <glossdef> | ||
6313 | <para> | ||
6314 | Specifies a list of functions run to perform additional | ||
6315 | splitting of files into individual packages. | ||
6316 | Recipes can either prepend to this variable or prepend | ||
6317 | to the <filename>populate_packages</filename> function | ||
6318 | in order to perform additional package splitting. | ||
6319 | In either case, the function should set | ||
6320 | <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>, | ||
6321 | <link linkend='var-FILES'><filename>FILES</filename></link>, | ||
6322 | <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> | ||
6323 | and other packaging variables appropriately in order to | ||
6324 | perform the desired splitting. | ||
6325 | </para> | ||
6326 | </glossdef> | ||
6327 | </glossentry> | ||
6328 | |||
6329 | <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm> | ||
6330 | <glossdef> | ||
6331 | <para> | ||
6332 | A promise that your recipe satisfies runtime dependencies | ||
6333 | for optional modules that are found in other recipes. | ||
6334 | <filename>PACKAGES_DYNAMIC</filename> | ||
6335 | does not actually satisfy the dependencies, it only states that | ||
6336 | they should be satisfied. | ||
6337 | For example, if a hard, runtime dependency | ||
6338 | (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>) | ||
6339 | of another package is satisfied | ||
6340 | at build time through the <filename>PACKAGES_DYNAMIC</filename> | ||
6341 | variable, but a package with the module name is never actually | ||
6342 | produced, then the other package will be broken. | ||
6343 | Thus, if you attempt to include that package in an image, | ||
6344 | you will get a dependency failure from the packaging system | ||
6345 | during the | ||
6346 | <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> | ||
6347 | task. | ||
6348 | </para> | ||
6349 | <para> | ||
6350 | Typically, if there is a chance that such a situation can | ||
6351 | occur and the package that is not created is valid | ||
6352 | without the dependency being satisfied, then you should use | ||
6353 | <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> | ||
6354 | (a soft runtime dependency) instead of | ||
6355 | <filename>RDEPENDS</filename>. | ||
6356 | </para> | ||
6357 | |||
6358 | <para> | ||
6359 | For an example of how to use the <filename>PACKAGES_DYNAMIC</filename> | ||
6360 | variable when you are splitting packages, see the | ||
6361 | "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section | ||
6362 | in the Yocto Project Development Manual. | ||
6363 | </para> | ||
6364 | </glossdef> | ||
6365 | </glossentry> | ||
6366 | |||
6367 | <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm> | ||
6368 | <glossdef> | ||
6369 | <para> | ||
6370 | Extra options passed to the <filename>make</filename> | ||
6371 | command during the | ||
6372 | <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> | ||
6373 | task in order to specify parallel compilation on the local | ||
6374 | build host. | ||
6375 | This variable is usually in the form "-j <x>", | ||
6376 | where x represents the maximum number of parallel threads | ||
6377 | <filename>make</filename> can run. | ||
6378 | </para> | ||
6379 | |||
6380 | <para> | ||
6381 | If your development host supports multiple cores, a good | ||
6382 | rule of thumb is to set this variable to twice the number | ||
6383 | of cores on the host. | ||
6384 | If you do not set <filename>PARALLEL_MAKE</filename>, it | ||
6385 | defaults to the number of cores your build system has. | ||
6386 | <note> | ||
6387 | Individual recipes might clear out this variable if | ||
6388 | the software being built has problems running its | ||
6389 | <filename>make</filename> process in parallel. | ||
6390 | </note> | ||
6391 | </para> | ||
6392 | </glossdef> | ||
6393 | </glossentry> | ||
6394 | |||
6395 | <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm> | ||
6396 | <glossdef> | ||
6397 | <para> | ||
6398 | Extra options passed to the | ||
6399 | <filename>make install</filename> command during the | ||
6400 | <link linkend='ref-tasks-install'><filename>do_install</filename></link> | ||
6401 | task in order to specify parallel installation. | ||
6402 | This variable defaults to the value of | ||
6403 | <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>. | ||
6404 | <note> | ||
6405 | Individual recipes might clear out this variable if | ||
6406 | the software being built has problems running its | ||
6407 | <filename>make install</filename> process in parallel. | ||
6408 | </note> | ||
6409 | </para> | ||
6410 | </glossdef> | ||
6411 | </glossentry> | ||
6412 | |||
6413 | <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm> | ||
6414 | <glossdef> | ||
6415 | <para> | ||
6416 | Determines the action to take when a patch fails. | ||
6417 | You can set this variable to one of two values: "noop" and | ||
6418 | "user". | ||
6419 | </para> | ||
6420 | |||
6421 | <para> | ||
6422 | The default value of "noop" causes the build to simply fail | ||
6423 | when the OpenEmbedded build system cannot successfully | ||
6424 | apply a patch. | ||
6425 | Setting the value to "user" causes the build system to | ||
6426 | launch a shell and places you in the right location so that | ||
6427 | you can manually resolve the conflicts. | ||
6428 | </para> | ||
6429 | |||
6430 | <para> | ||
6431 | Set this variable in your | ||
6432 | <filename>local.conf</filename> file. | ||
6433 | </para> | ||
6434 | </glossdef> | ||
6435 | </glossentry> | ||
6436 | |||
6437 | <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm> | ||
6438 | <glossdef> | ||
6439 | <para> | ||
6440 | Specifies the utility used to apply patches for a recipe | ||
6441 | during the | ||
6442 | <link linkend='ref-tasks-patch'><filename>do_patch</filename></link> | ||
6443 | task. | ||
6444 | You can specify one of three utilities: "patch", "quilt", or | ||
6445 | "git". | ||
6446 | The default utility used is "quilt" except for the | ||
6447 | quilt-native recipe itself. | ||
6448 | Because the quilt tool is not available at the | ||
6449 | time quilt-native is being patched, it uses "patch". | ||
6450 | </para> | ||
6451 | |||
6452 | <para> | ||
6453 | If you wish to use an alternative patching tool, set the | ||
6454 | variable in the recipe using one of the following: | ||
6455 | <literallayout class='monospaced'> | ||
6456 | PATCHTOOL = "patch" | ||
6457 | PATCHTOOL = "quilt" | ||
6458 | PATCHTOOL = "git" | ||
6459 | </literallayout> | ||
6460 | </para> | ||
6461 | </glossdef> | ||
6462 | </glossentry> | ||
6463 | |||
6464 | <glossentry id='var-PE'><glossterm>PE</glossterm> | ||
6465 | <glossdef> | ||
6466 | <para> | ||
6467 | The epoch of the recipe. | ||
6468 | By default, this variable is unset. | ||
6469 | The variable is used to make upgrades possible when the | ||
6470 | versioning scheme changes in some backwards incompatible | ||
6471 | way. | ||
6472 | </para> | ||
6473 | </glossdef> | ||
6474 | </glossentry> | ||
6475 | |||
6476 | <glossentry id='var-PF'><glossterm>PF</glossterm> | ||
6477 | <glossdef> | ||
6478 | <para>Specifies the recipe or package name and includes all version and revision | ||
6479 | numbers (i.e. <filename>glibc-2.13-r20+svnr15508/</filename> and | ||
6480 | <filename>bash-4.2-r1/</filename>). | ||
6481 | This variable is comprised of the following: | ||
6482 | <literallayout class='monospaced'> | ||
6483 | ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>} | ||
6484 | </literallayout></para> | ||
6485 | </glossdef> | ||
6486 | </glossentry> | ||
6487 | |||
6488 | <glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm> | ||
6489 | <glossdef> | ||
6490 | <para> | ||
6491 | When inheriting the | ||
6492 | <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link> | ||
6493 | class, this variable identifies packages that contain | ||
6494 | the pixbuf loaders used with | ||
6495 | <filename>gdk-pixbuf</filename>. | ||
6496 | By default, the <filename>pixbufcache</filename> class | ||
6497 | assumes that the loaders are in the recipe's main package | ||
6498 | (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>). | ||
6499 | Use this variable if the loaders you need are in a package | ||
6500 | other than that main package. | ||
6501 | </para> | ||
6502 | </glossdef> | ||
6503 | </glossentry> | ||
6504 | |||
6505 | <glossentry id='var-PKG'><glossterm>PKG</glossterm> | ||
6506 | <glossdef> | ||
6507 | <para> | ||
6508 | The name of the resulting package created by the | ||
6509 | OpenEmbedded build system. | ||
6510 | <note> | ||
6511 | When using the <filename>PKG</filename> variable, you | ||
6512 | must use a package name override. | ||
6513 | </note> | ||
6514 | For example, when the | ||
6515 | <link linkend='ref-classes-debian'><filename>debian</filename></link> | ||
6516 | class renames the output package, it does so by setting | ||
6517 | <filename>PKG_<replaceable>packagename</replaceable></filename>. | ||
6518 | </para> | ||
6519 | </glossdef> | ||
6520 | </glossentry> | ||
6521 | |||
6522 | <glossentry id='var-PKGD'><glossterm>PKGD</glossterm> | ||
6523 | <glossdef> | ||
6524 | <para> | ||
6525 | Points to the destination directory for files to be | ||
6526 | packaged before they are split into individual packages. | ||
6527 | This directory defaults to the following: | ||
6528 | <literallayout class='monospaced'> | ||
6529 | ${WORKDIR}/package | ||
6530 | </literallayout> | ||
6531 | Do not change this default. | ||
6532 | </para> | ||
6533 | </glossdef> | ||
6534 | </glossentry> | ||
6535 | |||
6536 | <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm> | ||
6537 | <glossdef> | ||
6538 | <para> | ||
6539 | Points to a shared, global-state directory that holds data | ||
6540 | generated during the packaging process. | ||
6541 | During the packaging process, the | ||
6542 | <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> | ||
6543 | task packages data for each recipe and installs it into | ||
6544 | this temporary, shared area. | ||
6545 | This directory defaults to the following: | ||
6546 | <literallayout class='monospaced'> | ||
6547 | ${STAGING_DIR_HOST}/pkgdata | ||
6548 | </literallayout> | ||
6549 | Do not change this default. | ||
6550 | </para> | ||
6551 | </glossdef> | ||
6552 | </glossentry> | ||
6553 | |||
6554 | <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm> | ||
6555 | <glossdef> | ||
6556 | <para> | ||
6557 | Points to the parent directory for files to be packaged | ||
6558 | after they have been split into individual packages. | ||
6559 | This directory defaults to the following: | ||
6560 | <literallayout class='monospaced'> | ||
6561 | ${WORKDIR}/packages-split | ||
6562 | </literallayout> | ||
6563 | Under this directory, the build system creates | ||
6564 | directories for each package specified in | ||
6565 | <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>. | ||
6566 | Do not change this default. | ||
6567 | </para> | ||
6568 | </glossdef> | ||
6569 | </glossentry> | ||
6570 | |||
6571 | <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm> | ||
6572 | <glossdef> | ||
6573 | <para> | ||
6574 | Points to a temporary work area used by the | ||
6575 | <link linkend='ref-tasks-package'><filename>do_package</filename></link> | ||
6576 | task to write output from the | ||
6577 | <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> | ||
6578 | task. | ||
6579 | The <filename>PKGDESTWORK</filename> location defaults to | ||
6580 | the following: | ||
6581 | <literallayout class='monospaced'> | ||
6582 | ${WORKDIR}/pkgdata | ||
6583 | </literallayout> | ||
6584 | The <filename>do_packagedata</filename> task then packages | ||
6585 | the data in the temporary work area and installs it into a | ||
6586 | shared directory pointed to by | ||
6587 | <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>. | ||
6588 | </para> | ||
6589 | |||
6590 | <para> | ||
6591 | Do not change this default. | ||
6592 | </para> | ||
6593 | </glossdef> | ||
6594 | </glossentry> | ||
6595 | |||
6596 | <glossentry id='var-PKGE'><glossterm>PKGE</glossterm> | ||
6597 | <glossdef> | ||
6598 | <para> | ||
6599 | The epoch of the output package built by the | ||
6600 | OpenEmbedded build system. | ||
6601 | By default, <filename>PKGE</filename> is set to | ||
6602 | <link linkend='var-PE'><filename>PE</filename></link>. | ||
6603 | </para> | ||
6604 | </glossdef> | ||
6605 | </glossentry> | ||
6606 | |||
6607 | <glossentry id='var-PKGR'><glossterm>PKGR</glossterm> | ||
6608 | <glossdef> | ||
6609 | <para> | ||
6610 | The revision of the output package built by the | ||
6611 | OpenEmbedded build system. | ||
6612 | By default, <filename>PKGR</filename> is set to | ||
6613 | <link linkend='var-PR'><filename>PR</filename></link>. | ||
6614 | </para> | ||
6615 | </glossdef> | ||
6616 | </glossentry> | ||
6617 | |||
6618 | <glossentry id='var-PKGV'><glossterm>PKGV</glossterm> | ||
6619 | <glossdef> | ||
6620 | <para> | ||
6621 | The version of the output package built by the | ||
6622 | OpenEmbedded build system. | ||
6623 | By default, <filename>PKGV</filename> is set to | ||
6624 | <link linkend='var-PV'><filename>PV</filename></link>. | ||
6625 | </para> | ||
6626 | </glossdef> | ||
6627 | </glossentry> | ||
6628 | |||
6629 | <glossentry id='var-PN'><glossterm>PN</glossterm> | ||
6630 | <glossdef> | ||
6631 | <para>This variable can have two separate functions depending on the context: a recipe | ||
6632 | name or a resulting package name.</para> | ||
6633 | <para><filename>PN</filename> refers to a recipe name in the context of a file used | ||
6634 | by the OpenEmbedded build system as input to create a package. | ||
6635 | The name is normally extracted from the recipe file name. | ||
6636 | For example, if the recipe is named | ||
6637 | <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename> | ||
6638 | will be "expat".</para> | ||
6639 | <para> | ||
6640 | The variable refers to a package name in the context of a file created or produced by the | ||
6641 | OpenEmbedded build system.</para> | ||
6642 | <para>If applicable, the <filename>PN</filename> variable also contains any special | ||
6643 | suffix or prefix. | ||
6644 | For example, using <filename>bash</filename> to build packages for the native | ||
6645 | machine, <filename>PN</filename> is <filename>bash-native</filename>. | ||
6646 | Using <filename>bash</filename> to build packages for the target and for Multilib, | ||
6647 | <filename>PN</filename> would be <filename>bash</filename> and | ||
6648 | <filename>lib64-bash</filename>, respectively. | ||
6649 | </para> | ||
6650 | </glossdef> | ||
6651 | </glossentry> | ||
6652 | |||
6653 | <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm> | ||
6654 | <glossdef> | ||
6655 | <para> | ||
6656 | Lists recipes you do not want the OpenEmbedded build system | ||
6657 | to build. | ||
6658 | This variable works in conjunction with the | ||
6659 | <link linkend='ref-classes-blacklist'><filename>blacklist</filename></link> | ||
6660 | class, which the recipe must inherit globally. | ||
6661 | </para> | ||
6662 | |||
6663 | <para> | ||
6664 | To prevent a recipe from being built, inherit the class | ||
6665 | globally and use the variable in your | ||
6666 | <filename>local.conf</filename> file. | ||
6667 | Here is an example that prevents | ||
6668 | <filename>myrecipe</filename> from being built: | ||
6669 | <literallayout class='monospaced'> | ||
6670 | INHERIT += "blacklist" | ||
6671 | PNBLACKLIST[myrecipe] = "Not supported by our organization." | ||
6672 | </literallayout> | ||
6673 | </para> | ||
6674 | </glossdef> | ||
6675 | </glossentry> | ||
6676 | |||
6677 | <glossentry id='var-PR'><glossterm>PR</glossterm> | ||
6678 | <glossdef> | ||
6679 | <para> | ||
6680 | The revision of the recipe. | ||
6681 | The default value for this variable is "r0". | ||
6682 | </para> | ||
6683 | </glossdef> | ||
6684 | </glossentry> | ||
6685 | |||
6686 | <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm> | ||
6687 | <glossdef> | ||
6688 | <para> | ||
6689 | If multiple recipes provide an item, this variable | ||
6690 | determines which recipe should be given preference. | ||
6691 | You should always suffix the variable with the name of the | ||
6692 | provided item, and you should set it to the | ||
6693 | <link linkend='var-PN'><filename>PN</filename></link> | ||
6694 | of the recipe to which you want to give precedence. | ||
6695 | Some examples: | ||
6696 | <literallayout class='monospaced'> | ||
6697 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" | ||
6698 | PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" | ||
6699 | PREFERRED_PROVIDER_virtual/libgl ?= "mesa" | ||
6700 | </literallayout> | ||
6701 | </para> | ||
6702 | </glossdef> | ||
6703 | </glossentry> | ||
6704 | |||
6705 | <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm> | ||
6706 | <glossdef> | ||
6707 | <para> | ||
6708 | If there are multiple versions of recipes available, this | ||
6709 | variable determines which recipe should be given preference. | ||
6710 | You must always suffix the variable with the | ||
6711 | <link linkend='var-PN'><filename>PN</filename></link> | ||
6712 | you want to select, and you should set the | ||
6713 | <link linkend='var-PV'><filename>PV</filename></link> | ||
6714 | accordingly for precedence. | ||
6715 | You can use the "<filename>%</filename>" character as a | ||
6716 | wildcard to match any number of characters, which can be | ||
6717 | useful when specifying versions that contain long revision | ||
6718 | numbers that could potentially change. | ||
6719 | Here are two examples: | ||
6720 | <literallayout class='monospaced'> | ||
6721 | PREFERRED_VERSION_python = "2.7.3" | ||
6722 | PREFERRED_VERSION_linux-yocto = "3.10%" | ||
6723 | </literallayout> | ||
6724 | </para> | ||
6725 | </glossdef> | ||
6726 | </glossentry> | ||
6727 | |||
6728 | <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm> | ||
6729 | <glossdef> | ||
6730 | <para> | ||
6731 | Specifies additional paths from which the OpenEmbedded | ||
6732 | build system gets source code. | ||
6733 | When the build system searches for source code, it first | ||
6734 | tries the local download directory. | ||
6735 | If that location fails, the build system tries locations | ||
6736 | defined by <filename>PREMIRRORS</filename>, the upstream | ||
6737 | source, and then locations specified by | ||
6738 | <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link> | ||
6739 | in that order. | ||
6740 | </para> | ||
6741 | |||
6742 | <para> | ||
6743 | Assuming your distribution | ||
6744 | (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>) | ||
6745 | is "poky", the default value for | ||
6746 | <filename>PREMIRRORS</filename> is defined in the | ||
6747 | <filename>conf/distro/poky.conf</filename> file in the | ||
6748 | <filename>meta-yocto</filename> Git repository. | ||
6749 | </para> | ||
6750 | |||
6751 | <para> | ||
6752 | Typically, you could add a specific server for the | ||
6753 | build system to attempt before any others by adding | ||
6754 | something like the following to the | ||
6755 | <filename>local.conf</filename> configuration file in the | ||
6756 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: | ||
6757 | <literallayout class='monospaced'> | ||
6758 | PREMIRRORS_prepend = "\ | ||
6759 | git://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
6760 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
6761 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
6762 | https://.*/.* http://www.yoctoproject.org/sources/ \n" | ||
6763 | </literallayout> | ||
6764 | These changes cause the build system to intercept | ||
6765 | Git, FTP, HTTP, and HTTPS requests and direct them to | ||
6766 | the <filename>http://</filename> sources mirror. | ||
6767 | You can use <filename>file://</filename> URLs to point | ||
6768 | to local directories or network shares as well. | ||
6769 | </para> | ||
6770 | </glossdef> | ||
6771 | </glossentry> | ||
6772 | |||
6773 | <glossentry id='var-PRINC'><glossterm>PRINC</glossterm> | ||
6774 | <glossdef> | ||
6775 | |||
6776 | <para> | ||
6777 | The <filename>PRINC</filename> variable has been deprecated | ||
6778 | and triggers a warning if detected during a build. | ||
6779 | For | ||
6780 | <link linkend='var-PR'><filename>PR</filename></link> | ||
6781 | increments on changes, use the PR service instead. | ||
6782 | You can find out more about this service in the | ||
6783 | "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>" | ||
6784 | section in the Yocto Project Development Manual. | ||
6785 | </para> | ||
6786 | <!-- | ||
6787 | |||
6788 | <para> | ||
6789 | Causes the | ||
6790 | <link linkend='var-PR'><filename>PR</filename></link> | ||
6791 | variable of <filename>.bbappend</filename> files to | ||
6792 | dynamically increment. | ||
6793 | This increment minimizes the impact of layer ordering. | ||
6794 | </para> | ||
6795 | |||
6796 | <para> | ||
6797 | In order to ensure multiple <filename>.bbappend</filename> | ||
6798 | files can co-exist, | ||
6799 | <filename>PRINC</filename> should be self-referencing. | ||
6800 | This variable defaults to 0. | ||
6801 | </para> | ||
6802 | |||
6803 | <para> | ||
6804 | Following is an example that increments | ||
6805 | <filename>PR</filename> by two: | ||
6806 | <literallayout class='monospaced'> | ||
6807 | PRINC := "${@int(PRINC) + 2}" | ||
6808 | </literallayout> | ||
6809 | It is advisable not to use strings such as ".= '.1'" with the variable because | ||
6810 | this usage is very sensitive to layer ordering. | ||
6811 | You should avoid explicit assignments as they cannot | ||
6812 | adequately represent multiple | ||
6813 | <filename>.bbappend</filename> files. | ||
6814 | </para> | ||
6815 | --> | ||
6816 | </glossdef> | ||
6817 | </glossentry> | ||
6818 | |||
6819 | <glossentry id='var-PRIVATE_LIBS'><glossterm>PRIVATE_LIBS</glossterm> | ||
6820 | <glossdef> | ||
6821 | <para> | ||
6822 | Specifies libraries installed within a recipe that | ||
6823 | should be ignored by the OpenEmbedded build system's | ||
6824 | shared library resolver. | ||
6825 | This variable is typically used when software being | ||
6826 | built by a recipe has its own private versions of a | ||
6827 | library normally provided by another recipe. | ||
6828 | In this case, you would not want the package containing | ||
6829 | the private libraries to be set as a dependency on other | ||
6830 | unrelated packages that should instead depend on the | ||
6831 | package providing the standard version of the library. | ||
6832 | </para> | ||
6833 | |||
6834 | <para> | ||
6835 | Libraries specified in this variable should be specified | ||
6836 | by their file name. | ||
6837 | For example, from the Firefox recipe in meta-browser: | ||
6838 | <literallayout class='monospaced'> | ||
6839 | PRIVATE_LIBS = "libmozjs.so \ | ||
6840 | libxpcom.so \ | ||
6841 | libnspr4.so \ | ||
6842 | libxul.so \ | ||
6843 | libmozalloc.so \ | ||
6844 | libplc4.so \ | ||
6845 | libplds4.so" | ||
6846 | </literallayout> | ||
6847 | </para> | ||
6848 | </glossdef> | ||
6849 | </glossentry> | ||
6850 | |||
6851 | <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm> | ||
6852 | <glossdef> | ||
6853 | <para> | ||
6854 | A list of aliases by which a particular recipe can be | ||
6855 | known. | ||
6856 | By default, a recipe's own | ||
6857 | <filename><link linkend='var-PN'>PN</link></filename> | ||
6858 | is implicitly already in its <filename>PROVIDES</filename> | ||
6859 | list. | ||
6860 | If a recipe uses <filename>PROVIDES</filename>, the | ||
6861 | additional aliases are synonyms for the recipe and can | ||
6862 | be useful satisfying dependencies of other recipes during | ||
6863 | the build as specified by | ||
6864 | <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>. | ||
6865 | </para> | ||
6866 | |||
6867 | <para> | ||
6868 | Consider the following example | ||
6869 | <filename>PROVIDES</filename> statement from a recipe | ||
6870 | file <filename>libav_0.8.11.bb</filename>: | ||
6871 | <literallayout class='monospaced'> | ||
6872 | PROVIDES += "libpostproc" | ||
6873 | </literallayout> | ||
6874 | The <filename>PROVIDES</filename> statement results in | ||
6875 | the "libav" recipe also being known as "libpostproc". | ||
6876 | </para> | ||
6877 | </glossdef> | ||
6878 | </glossentry> | ||
6879 | |||
6880 | <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm> | ||
6881 | <glossdef> | ||
6882 | <para> | ||
6883 | The network based | ||
6884 | <link linkend='var-PR'><filename>PR</filename></link> | ||
6885 | service host and port. | ||
6886 | </para> | ||
6887 | |||
6888 | <para> | ||
6889 | The <filename>conf/local.conf.sample.extended</filename> | ||
6890 | configuration file in the | ||
6891 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> | ||
6892 | shows how the <filename>PRSERV_HOST</filename> variable is | ||
6893 | set: | ||
6894 | <literallayout class='monospaced'> | ||
6895 | PRSERV_HOST = "localhost:0" | ||
6896 | </literallayout> | ||
6897 | You must set the variable if you want to automatically | ||
6898 | start a local | ||
6899 | <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>. | ||
6900 | You can set <filename>PRSERV_HOST</filename> to other | ||
6901 | values to use a remote PR service. | ||
6902 | </para> | ||
6903 | </glossdef> | ||
6904 | </glossentry> | ||
6905 | |||
6906 | <glossentry id='var-PTEST_ENABLED'><glossterm>PTEST_ENABLED</glossterm> | ||
6907 | <glossdef> | ||
6908 | <para> | ||
6909 | Specifies whether or not | ||
6910 | <ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Package Test</ulink> | ||
6911 | (ptest) functionality is enabled when building a recipe. | ||
6912 | You should not set this variable directly. | ||
6913 | Enabling and disabling building Package Tests | ||
6914 | at build time should be done by adding "ptest" to (or | ||
6915 | removing it from) | ||
6916 | <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. | ||
6917 | </para> | ||
6918 | </glossdef> | ||
6919 | </glossentry> | ||
6920 | |||
6921 | <glossentry id='var-PV'><glossterm>PV</glossterm> | ||
6922 | <glossdef> | ||
6923 | <para> | ||
6924 | The version of the recipe. | ||
6925 | The version is normally extracted from the recipe filename. | ||
6926 | For example, if the recipe is named | ||
6927 | <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename> | ||
6928 | will be "2.0.1". | ||
6929 | <filename>PV</filename> is generally not overridden within | ||
6930 | a recipe unless it is building an unstable (i.e. development) version from a source code repository | ||
6931 | (e.g. Git or Subversion). | ||
6932 | </para> | ||
6933 | </glossdef> | ||
6934 | </glossentry> | ||
6935 | |||
6936 | <glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm> | ||
6937 | <glossdef> | ||
6938 | <para> | ||
6939 | When used by recipes that inherit the | ||
6940 | <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>, | ||
6941 | <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>, | ||
6942 | <link linkend='ref-classes-distutils'><filename>distutils</filename></link>, | ||
6943 | or | ||
6944 | <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link> | ||
6945 | classes, denotes the Application Binary Interface (ABI) | ||
6946 | currently in use for Python. | ||
6947 | By default, the ABI is "m". | ||
6948 | You do not have to set this variable as the OpenEmbedded | ||
6949 | build system sets it for you. | ||
6950 | </para> | ||
6951 | |||
6952 | <para> | ||
6953 | The OpenEmbedded build system uses the ABI to construct | ||
6954 | directory names used when installing the Python headers | ||
6955 | and libraries in sysroot | ||
6956 | (e.g. <filename>.../python3.3m/...</filename>). | ||
6957 | </para> | ||
6958 | |||
6959 | <para> | ||
6960 | Recipes that inherit the | ||
6961 | <link linkend='ref-classes-distutils'><filename>distutils</filename></link> | ||
6962 | class during cross-builds also use this variable to | ||
6963 | locate the headers and libraries of the appropriate Python | ||
6964 | that the extension is targeting. | ||
6965 | </para> | ||
6966 | </glossdef> | ||
6967 | </glossentry> | ||
6968 | |||
6969 | <glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm> | ||
6970 | <glossdef> | ||
6971 | <para> | ||
6972 | When used by recipes that inherit the | ||
6973 | <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>, | ||
6974 | <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>, | ||
6975 | <link linkend='ref-classes-distutils'><filename>distutils</filename></link>, | ||
6976 | or | ||
6977 | <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link> | ||
6978 | classes, specifies the major Python version being built. | ||
6979 | For Python 2.x, <filename>PYTHON_PN</filename> would | ||
6980 | be "python2". For Python 3.x, the variable would be | ||
6981 | "python3". | ||
6982 | You do not have to set this variable as the | ||
6983 | OpenEmbedded build system automatically sets it for you. | ||
6984 | </para> | ||
6985 | |||
6986 | <para> | ||
6987 | The variable allows recipes to use common infrastructure | ||
6988 | such as the following: | ||
6989 | <literallayout class='monospaced'> | ||
6990 | DEPENDS += "${PYTHON_PN}-native" | ||
6991 | </literallayout> | ||
6992 | In the previous example, the version of the dependency | ||
6993 | is <filename>PYTHON_PN</filename>. | ||
6994 | </para> | ||
6995 | </glossdef> | ||
6996 | </glossentry> | ||
6997 | |||
6998 | </glossdiv> | ||
6999 | |||
7000 | <glossdiv id='var-glossary-q'><title>Q</title> | ||
7001 | |||
7002 | <glossentry id='var-QMAKE_PROFILES'><glossterm>QMAKE_PROFILES</glossterm> | ||
7003 | <glossdef> | ||
7004 | <para> | ||
7005 | Specifies your own subset of <filename>.pro</filename> | ||
7006 | files to be built for use with | ||
7007 | <filename>qmake</filename>. | ||
7008 | If you do not set this variable, all | ||
7009 | <filename>.pro</filename> files in the directory pointed to | ||
7010 | by <link linkend='var-S'><filename>S</filename></link> | ||
7011 | will be built by default. | ||
7012 | </para> | ||
7013 | |||
7014 | <para> | ||
7015 | This variable is used with recipes that inherit the | ||
7016 | <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link> | ||
7017 | class or other classes that inherit | ||
7018 | <filename>qmake_base</filename>. | ||
7019 | </para> | ||
7020 | </glossdef> | ||
7021 | </glossentry> | ||
7022 | |||
7023 | </glossdiv> | ||
7024 | |||
7025 | <glossdiv id='var-glossary-r'><title>R</title> | ||
7026 | |||
7027 | <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm> | ||
7028 | <glossdef> | ||
7029 | <para> | ||
7030 | The list of packages that conflict with packages. | ||
7031 | Note that packages will not be installed if conflicting | ||
7032 | packages are not first removed. | ||
7033 | </para> | ||
7034 | |||
7035 | <para> | ||
7036 | Like all package-controlling variables, you must always use | ||
7037 | them in conjunction with a package name override. | ||
7038 | Here is an example: | ||
7039 | <literallayout class='monospaced'> | ||
7040 | RCONFLICTS_${PN} = "<replaceable>another-conflicting-package-name</replaceable>" | ||
7041 | </literallayout> | ||
7042 | </para> | ||
7043 | |||
7044 | <para> | ||
7045 | BitBake, which the OpenEmbedded build system uses, supports | ||
7046 | specifying versioned dependencies. | ||
7047 | Although the syntax varies depending on the packaging | ||
7048 | format, BitBake hides these differences from you. | ||
7049 | Here is the general syntax to specify versions with | ||
7050 | the <filename>RCONFLICTS</filename> variable: | ||
7051 | <literallayout class='monospaced'> | ||
7052 | RCONFLICTS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)" | ||
7053 | </literallayout> | ||
7054 | For <filename>operator</filename>, you can specify the | ||
7055 | following: | ||
7056 | <literallayout class='monospaced'> | ||
7057 | = | ||
7058 | < | ||
7059 | > | ||
7060 | <= | ||
7061 | >= | ||
7062 | </literallayout> | ||
7063 | For example, the following sets up a dependency on version | ||
7064 | 1.2 or greater of the package <filename>foo</filename>: | ||
7065 | <literallayout class='monospaced'> | ||
7066 | RCONFLICTS_${PN} = "foo (>= 1.2)" | ||
7067 | </literallayout> | ||
7068 | </para> | ||
7069 | </glossdef> | ||
7070 | </glossentry> | ||
7071 | |||
7072 | <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm> | ||
7073 | <glossdef> | ||
7074 | <para> | ||
7075 | Lists a package's runtime dependencies (i.e. other packages) | ||
7076 | that must be installed in order for the built package to run | ||
7077 | correctly. | ||
7078 | If a package in this list cannot be found during the build, | ||
7079 | you will get a build error. | ||
7080 | </para> | ||
7081 | |||
7082 | <para> | ||
7083 | When you use the <filename>RDEPENDS</filename> variable | ||
7084 | in a recipe, you are essentially stating that the recipe's | ||
7085 | <link linkend='ref-tasks-build'><filename>do_build</filename></link> | ||
7086 | task depends on the existence of a specific package. | ||
7087 | Consider this simple example for two recipes named "a" and | ||
7088 | "b" that produce similarly named IPK packages. | ||
7089 | In this example, the <filename>RDEPENDS</filename> | ||
7090 | statement appears in the "a" recipe: | ||
7091 | <literallayout class='monospaced'> | ||
7092 | RDEPENDS_${PN} = "b" | ||
7093 | </literallayout> | ||
7094 | Here, the dependency is such that the | ||
7095 | <filename>do_build</filename> task for recipe "a" depends | ||
7096 | on the | ||
7097 | <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link> | ||
7098 | task of recipe "b". | ||
7099 | This means the package file for "b" must be available when | ||
7100 | the output for recipe "a" has been completely built. | ||
7101 | More importantly, package "a" will be marked as depending | ||
7102 | on package "b" in a manner that is understood by the | ||
7103 | package manager. | ||
7104 | </para> | ||
7105 | |||
7106 | <para> | ||
7107 | The names of the packages you list within | ||
7108 | <filename>RDEPENDS</filename> must be the names of other | ||
7109 | packages - they cannot be recipe names. | ||
7110 | Although package names and recipe names usually match, | ||
7111 | the important point here is that you are | ||
7112 | providing package names within the | ||
7113 | <filename>RDEPENDS</filename> variable. | ||
7114 | For an example of the default list of packages created from | ||
7115 | a recipe, see the | ||
7116 | <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link> | ||
7117 | variable. | ||
7118 | </para> | ||
7119 | |||
7120 | <para> | ||
7121 | Because the <filename>RDEPENDS</filename> variable applies | ||
7122 | to packages being built, you should always use the variable | ||
7123 | in a form with an attached package name. | ||
7124 | For example, suppose you are building a development package | ||
7125 | that depends on the <filename>perl</filename> package. | ||
7126 | In this case, you would use the following | ||
7127 | <filename>RDEPENDS</filename> statement: | ||
7128 | <literallayout class='monospaced'> | ||
7129 | RDEPENDS_${PN}-dev += "perl" | ||
7130 | </literallayout> | ||
7131 | In the example, the development package depends on | ||
7132 | the <filename>perl</filename> package. | ||
7133 | Thus, the <filename>RDEPENDS</filename> variable has the | ||
7134 | <filename>${PN}-dev</filename> package name as part of the | ||
7135 | variable. | ||
7136 | </para> | ||
7137 | |||
7138 | <para> | ||
7139 | The package name you attach to the | ||
7140 | <filename>RDEPENDS</filename> variable must appear | ||
7141 | as it would in the <filename>PACKAGES</filename> | ||
7142 | namespace before any renaming of the output package by | ||
7143 | classes like | ||
7144 | <link linkend='ref-classes-debian'><filename>debian</filename></link>. | ||
7145 | </para> | ||
7146 | |||
7147 | <para> | ||
7148 | In many cases you do not need to explicitly add | ||
7149 | runtime dependencies using | ||
7150 | <filename>RDEPENDS</filename> since some automatic | ||
7151 | handling occurs: | ||
7152 | <itemizedlist> | ||
7153 | <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If | ||
7154 | a runtime package contains a shared library | ||
7155 | (<filename>.so</filename>), the build | ||
7156 | processes the library in order to determine other | ||
7157 | libraries to which it is dynamically linked. | ||
7158 | The build process adds these libraries to | ||
7159 | <filename>RDEPENDS</filename> when creating the runtime | ||
7160 | package.</para></listitem> | ||
7161 | <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If | ||
7162 | the package ships a <filename>pkg-config</filename> | ||
7163 | information file, the build process uses this file | ||
7164 | to add items to the <filename>RDEPENDS</filename> | ||
7165 | variable to create the runtime packages. | ||
7166 | </para></listitem> | ||
7167 | </itemizedlist> | ||
7168 | </para> | ||
7169 | |||
7170 | <para> | ||
7171 | BitBake, which the OpenEmbedded build system uses, supports | ||
7172 | specifying versioned dependencies. | ||
7173 | Although the syntax varies depending on the packaging | ||
7174 | format, BitBake hides these differences from you. | ||
7175 | Here is the general syntax to specify versions with | ||
7176 | the <filename>RDEPENDS</filename> variable: | ||
7177 | <literallayout class='monospaced'> | ||
7178 | RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)" | ||
7179 | </literallayout> | ||
7180 | For <filename>operator</filename>, you can specify the | ||
7181 | following: | ||
7182 | <literallayout class='monospaced'> | ||
7183 | = | ||
7184 | < | ||
7185 | > | ||
7186 | <= | ||
7187 | >= | ||
7188 | </literallayout> | ||
7189 | For example, the following sets up a dependency on version | ||
7190 | 1.2 or greater of the package <filename>foo</filename>: | ||
7191 | <literallayout class='monospaced'> | ||
7192 | RDEPENDS_${PN} = "foo (>= 1.2)" | ||
7193 | </literallayout> | ||
7194 | </para> | ||
7195 | |||
7196 | <para> | ||
7197 | For information on build-time dependencies, see the | ||
7198 | <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> | ||
7199 | variable. | ||
7200 | </para> | ||
7201 | </glossdef> | ||
7202 | </glossentry> | ||
7203 | |||
7204 | <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm> | ||
7205 | <glossdef> | ||
7206 | <para> | ||
7207 | When inheriting the | ||
7208 | <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link> | ||
7209 | class, this | ||
7210 | variable identifies distribution features that must | ||
7211 | exist in the current configuration in order for the | ||
7212 | OpenEmbedded build system to build the recipe. | ||
7213 | In other words, if the | ||
7214 | <filename>REQUIRED_DISTRO_FEATURES</filename> variable | ||
7215 | lists a feature that does not appear in | ||
7216 | <filename>DISTRO_FEATURES</filename> within the | ||
7217 | current configuration, an error occurs and the | ||
7218 | build stops. | ||
7219 | </para> | ||
7220 | </glossdef> | ||
7221 | </glossentry> | ||
7222 | |||
7223 | <glossentry id='var-RM_OLD_IMAGE'><glossterm>RM_OLD_IMAGE</glossterm> | ||
7224 | <glossdef> | ||
7225 | <para> | ||
7226 | Reclaims disk space by removing previously built | ||
7227 | versions of the same image from the | ||
7228 | <filename>images</filename> directory pointed to by the | ||
7229 | <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link> | ||
7230 | variable. | ||
7231 | </para> | ||
7232 | |||
7233 | <para> | ||
7234 | Set this variable to "1" in your | ||
7235 | <filename>local.conf</filename> file to remove these | ||
7236 | images. | ||
7237 | </para> | ||
7238 | </glossdef> | ||
7239 | </glossentry> | ||
7240 | |||
7241 | <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm> | ||
7242 | <glossdef> | ||
7243 | <para> | ||
7244 | With <filename>rm_work</filename> enabled, this | ||
7245 | variable specifies a list of recipes whose work directories | ||
7246 | should not be removed. | ||
7247 | See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>" | ||
7248 | section for more details. | ||
7249 | </para> | ||
7250 | </glossdef> | ||
7251 | </glossentry> | ||
7252 | |||
7253 | <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm> | ||
7254 | <glossdef> | ||
7255 | <para> | ||
7256 | Defines the root home directory. | ||
7257 | By default, this directory is set as follows in the | ||
7258 | BitBake configuration file: | ||
7259 | <literallayout class='monospaced'> | ||
7260 | ROOT_HOME ??= "/home/root" | ||
7261 | </literallayout> | ||
7262 | <note> | ||
7263 | This default value is likely used because some | ||
7264 | embedded solutions prefer to have a read-only root | ||
7265 | filesystem and prefer to keep writeable data in one | ||
7266 | place. | ||
7267 | </note> | ||
7268 | </para> | ||
7269 | |||
7270 | <para> | ||
7271 | You can override the default by setting the variable | ||
7272 | in any layer or in the <filename>local.conf</filename> file. | ||
7273 | Because the default is set using a "weak" assignment | ||
7274 | (i.e. "??="), you can use either of the following forms | ||
7275 | to define your override: | ||
7276 | <literallayout class='monospaced'> | ||
7277 | ROOT_HOME = "/root" | ||
7278 | ROOT_HOME ?= "/root" | ||
7279 | </literallayout> | ||
7280 | These override examples use <filename>/root</filename>, | ||
7281 | which is probably the most commonly used override. | ||
7282 | </para> | ||
7283 | </glossdef> | ||
7284 | </glossentry> | ||
7285 | |||
7286 | <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm> | ||
7287 | <glossdef> | ||
7288 | <para> | ||
7289 | Indicates a filesystem image to include as the root | ||
7290 | filesystem. | ||
7291 | </para> | ||
7292 | |||
7293 | <para> | ||
7294 | The <filename>ROOTFS</filename> variable is an optional | ||
7295 | variable used with the | ||
7296 | <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link> | ||
7297 | class. | ||
7298 | </para> | ||
7299 | </glossdef> | ||
7300 | </glossentry> | ||
7301 | |||
7302 | <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm> | ||
7303 | <glossdef> | ||
7304 | <para> | ||
7305 | Added by classes to run post processing commands once the | ||
7306 | OpenEmbedded build system has created the root filesystem. | ||
7307 | You can specify shell commands separated by semicolons: | ||
7308 | <literallayout class='monospaced'> | ||
7309 | ROOTFS_POSTPROCESS_COMMAND += "<replaceable>shell_command</replaceable>; ... " | ||
7310 | </literallayout> | ||
7311 | If you need to pass the path to the root filesystem within | ||
7312 | the command, you can use | ||
7313 | <filename>${IMAGE_ROOTFS}</filename>, which points to | ||
7314 | the root filesystem image. | ||
7315 | See the | ||
7316 | <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link> | ||
7317 | variable for more information. | ||
7318 | </para> | ||
7319 | </glossdef> | ||
7320 | </glossentry> | ||
7321 | |||
7322 | <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm> | ||
7323 | <glossdef> | ||
7324 | <para> | ||
7325 | A list of package name aliases that a package also provides. | ||
7326 | These aliases are useful for satisfying runtime dependencies | ||
7327 | of other packages both during the build and on the target | ||
7328 | (as specified by | ||
7329 | <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>). | ||
7330 | <note> | ||
7331 | A package's own name is implicitly already in its | ||
7332 | <filename>RPROVIDES</filename> list. | ||
7333 | </note> | ||
7334 | </para> | ||
7335 | <para> | ||
7336 | As with all package-controlling variables, you must always | ||
7337 | use the variable in conjunction with a package name override. | ||
7338 | Here is an example: | ||
7339 | <literallayout class='monospaced'> | ||
7340 | RPROVIDES_${PN} = "widget-abi-2" | ||
7341 | </literallayout> | ||
7342 | </para> | ||
7343 | </glossdef> | ||
7344 | </glossentry> | ||
7345 | |||
7346 | <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm> | ||
7347 | <glossdef> | ||
7348 | <para> | ||
7349 | A list of packages that extends the usability of a package | ||
7350 | being built. | ||
7351 | The package being built does not depend on this list of | ||
7352 | packages in order to successfully build, but rather | ||
7353 | uses them for extended usability. | ||
7354 | To specify runtime dependencies for packages, see the | ||
7355 | <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> | ||
7356 | variable. | ||
7357 | </para> | ||
7358 | |||
7359 | <para> | ||
7360 | The package manager will automatically install the | ||
7361 | <filename>RRECOMMENDS</filename> list of packages when | ||
7362 | installing the built package. | ||
7363 | However, you can prevent listed packages from being | ||
7364 | installed by using the | ||
7365 | <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>, | ||
7366 | <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>, | ||
7367 | and | ||
7368 | <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link> | ||
7369 | variables. | ||
7370 | </para> | ||
7371 | |||
7372 | <para> | ||
7373 | Packages specified in | ||
7374 | <filename>RRECOMMENDS</filename> need not actually be | ||
7375 | produced. | ||
7376 | However, a recipe must exist that provides each package, | ||
7377 | either through the | ||
7378 | <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link> | ||
7379 | or | ||
7380 | <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link> | ||
7381 | variables or the | ||
7382 | <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link> | ||
7383 | variable, or an error will occur during the build. | ||
7384 | If such a recipe does exist and the package is not produced, | ||
7385 | the build continues without error. | ||
7386 | </para> | ||
7387 | |||
7388 | <para> | ||
7389 | Because the <filename>RRECOMMENDS</filename> variable | ||
7390 | applies to packages being built, you should always attach | ||
7391 | an override to the variable to specify the particular | ||
7392 | package whose usability is being extended. | ||
7393 | For example, suppose you are building a development package | ||
7394 | that is extended to support wireless functionality. | ||
7395 | In this case, you would use the following: | ||
7396 | <literallayout class='monospaced'> | ||
7397 | RRECOMMENDS_${PN}-dev += "<replaceable>wireless_package_name</replaceable>" | ||
7398 | </literallayout> | ||
7399 | In the example, the package name | ||
7400 | (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>) | ||
7401 | must appear as it would in the | ||
7402 | <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> | ||
7403 | namespace before any renaming of the output package by | ||
7404 | classes such as <filename>debian.bbclass</filename>. | ||
7405 | </para> | ||
7406 | |||
7407 | <para> | ||
7408 | BitBake, which the OpenEmbedded build system uses, supports | ||
7409 | specifying versioned recommends. | ||
7410 | Although the syntax varies depending on the packaging | ||
7411 | format, BitBake hides these differences from you. | ||
7412 | Here is the general syntax to specify versions with | ||
7413 | the <filename>RRECOMMENDS</filename> variable: | ||
7414 | <literallayout class='monospaced'> | ||
7415 | RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)" | ||
7416 | </literallayout> | ||
7417 | For <filename>operator</filename>, you can specify the | ||
7418 | following: | ||
7419 | <literallayout class='monospaced'> | ||
7420 | = | ||
7421 | < | ||
7422 | > | ||
7423 | <= | ||
7424 | >= | ||
7425 | </literallayout> | ||
7426 | For example, the following sets up a recommend on version | ||
7427 | 1.2 or greater of the package <filename>foo</filename>: | ||
7428 | <literallayout class='monospaced'> | ||
7429 | RRECOMMENDS_${PN} = "foo (>= 1.2)" | ||
7430 | </literallayout> | ||
7431 | </para> | ||
7432 | </glossdef> | ||
7433 | </glossentry> | ||
7434 | |||
7435 | <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm> | ||
7436 | <glossdef> | ||
7437 | <para> | ||
7438 | A list of packages replaced by a package. | ||
7439 | The package manager uses this variable to determine which | ||
7440 | package should be installed to replace other package(s) | ||
7441 | during an upgrade. | ||
7442 | In order to also have the other package(s) removed at the | ||
7443 | same time, you must add the name of the other | ||
7444 | package to the | ||
7445 | <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable. | ||
7446 | </para> | ||
7447 | <para> | ||
7448 | As with all package-controlling variables, you must use | ||
7449 | this variable in conjunction with a package name | ||
7450 | override. | ||
7451 | Here is an example: | ||
7452 | <literallayout class='monospaced'> | ||
7453 | RREPLACES_${PN} = "<replaceable>other-package-being-replaced</replaceable>" | ||
7454 | </literallayout> | ||
7455 | </para> | ||
7456 | |||
7457 | <para> | ||
7458 | BitBake, which the OpenEmbedded build system uses, supports | ||
7459 | specifying versioned replacements. | ||
7460 | Although the syntax varies depending on the packaging | ||
7461 | format, BitBake hides these differences from you. | ||
7462 | Here is the general syntax to specify versions with | ||
7463 | the <filename>RREPLACES</filename> variable: | ||
7464 | <literallayout class='monospaced'> | ||
7465 | RREPLACES_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)" | ||
7466 | </literallayout> | ||
7467 | For <filename>operator</filename>, you can specify the | ||
7468 | following: | ||
7469 | <literallayout class='monospaced'> | ||
7470 | = | ||
7471 | < | ||
7472 | > | ||
7473 | <= | ||
7474 | >= | ||
7475 | </literallayout> | ||
7476 | For example, the following sets up a replacement using | ||
7477 | version 1.2 or greater of the package | ||
7478 | <filename>foo</filename>: | ||
7479 | <literallayout class='monospaced'> | ||
7480 | RREPLACES_${PN} = "foo (>= 1.2)" | ||
7481 | </literallayout> | ||
7482 | </para> | ||
7483 | </glossdef> | ||
7484 | </glossentry> | ||
7485 | |||
7486 | <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm> | ||
7487 | <glossdef> | ||
7488 | <para> | ||
7489 | A list of additional packages that you can suggest for | ||
7490 | installation by the package manager at the time a package | ||
7491 | is installed. | ||
7492 | Not all package managers support this functionality. | ||
7493 | </para> | ||
7494 | <para> | ||
7495 | As with all package-controlling variables, you must always | ||
7496 | use this variable in conjunction with a package name | ||
7497 | override. | ||
7498 | Here is an example: | ||
7499 | <literallayout class='monospaced'> | ||
7500 | RSUGGESTS_${PN} = "<replaceable>useful-package</replaceable> <replaceable>another-package</replaceable>" | ||
7501 | </literallayout> | ||
7502 | </para> | ||
7503 | </glossdef> | ||
7504 | </glossentry> | ||
7505 | |||
7506 | </glossdiv> | ||
7507 | |||
7508 | <glossdiv id='var-glossary-s'><title>S</title> | ||
7509 | |||
7510 | <glossentry id='var-S'><glossterm>S</glossterm> | ||
7511 | <glossdef> | ||
7512 | <para> | ||
7513 | The location in the | ||
7514 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> | ||
7515 | where unpacked recipe source code resides. | ||
7516 | This location is within the work directory | ||
7517 | (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>), | ||
7518 | which is not static. | ||
7519 | The unpacked source location depends on the recipe name | ||
7520 | (<filename><link linkend='var-PN'>PN</link></filename>) and | ||
7521 | recipe version | ||
7522 | (<filename><link linkend='var-PV'>PV</link></filename>) as | ||
7523 | follows: | ||
7524 | <literallayout class='monospaced'> | ||
7525 | ${WORKDIR}/${PN}-${PV} | ||
7526 | </literallayout> | ||
7527 | As an example, assume a | ||
7528 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> | ||
7529 | top-level folder named <filename>poky</filename> and a | ||
7530 | default Build Directory at <filename>poky/build</filename>. | ||
7531 | In this case, the work directory the build system uses | ||
7532 | to keep the unpacked recipe for <filename>db</filename> | ||
7533 | is the following: | ||
7534 | <literallayout class='monospaced'> | ||
7535 | poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 | ||
7536 | </literallayout> | ||
7537 | </para> | ||
7538 | </glossdef> | ||
7539 | </glossentry> | ||
7540 | |||
7541 | <glossentry id='var-SANITY_REQUIRED_UTILITIES'><glossterm>SANITY_REQUIRED_UTILITIES</glossterm> | ||
7542 | <glossdef> | ||
7543 | <para> | ||
7544 | Specifies a list of command-line utilities that should be | ||
7545 | checked for during the initial sanity checking process when | ||
7546 | running BitBake. | ||
7547 | If any of the utilities are not installed on the build host, | ||
7548 | then BitBake immediately exits with an error. | ||
7549 | </para> | ||
7550 | </glossdef> | ||
7551 | </glossentry> | ||
7552 | |||
7553 | <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm> | ||
7554 | <glossdef> | ||
7555 | <para> | ||
7556 | A list of the host distribution identifiers that the | ||
7557 | build system has been tested against. | ||
7558 | Identifiers consist of the host distributor ID | ||
7559 | followed by the release, | ||
7560 | as reported by the <filename>lsb_release</filename> tool | ||
7561 | or as read from <filename>/etc/lsb-release</filename>. | ||
7562 | Separate the list items with explicit newline | ||
7563 | characters (<filename>\n</filename>). | ||
7564 | If <filename>SANITY_TESTED_DISTROS</filename> is not empty | ||
7565 | and the current value of | ||
7566 | <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link> | ||
7567 | does not appear in the list, then the build system reports | ||
7568 | a warning that indicates the current host distribution has | ||
7569 | not been tested as a build host. | ||
7570 | </para> | ||
7571 | </glossdef> | ||
7572 | </glossentry> | ||
7573 | |||
7574 | <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm> | ||
7575 | <glossdef> | ||
7576 | <para> | ||
7577 | The target architecture for the SDK. | ||
7578 | Typically, you do not directly set this variable. | ||
7579 | Instead, use | ||
7580 | <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>. | ||
7581 | </para> | ||
7582 | </glossdef> | ||
7583 | </glossentry> | ||
7584 | |||
7585 | <glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm> | ||
7586 | <glossdef> | ||
7587 | <para> | ||
7588 | The directory set up and used by the | ||
7589 | <link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link> | ||
7590 | to which the SDK is deployed. | ||
7591 | The <filename>populate_sdk_base</filename> class defines | ||
7592 | <filename>SDK_DEPLOY</filename> as follows: | ||
7593 | <literallayout class='monospaced'> | ||
7594 | SDK_DEPLOY = "${<link linkend='var-TMPDIR'>TMPDIR</link>}/deploy/sdk" | ||
7595 | </literallayout> | ||
7596 | </para> | ||
7597 | </glossdef> | ||
7598 | </glossentry> | ||
7599 | |||
7600 | <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm> | ||
7601 | <glossdef> | ||
7602 | <para> | ||
7603 | The parent directory used by the OpenEmbedded build system | ||
7604 | when creating SDK output. | ||
7605 | The | ||
7606 | <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link> | ||
7607 | class defines the variable as follows: | ||
7608 | <literallayout class='monospaced'> | ||
7609 | SDK_DIR = "${<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>}/sdk" | ||
7610 | </literallayout> | ||
7611 | <note> | ||
7612 | The <filename>SDK_DIR</filename> directory is a | ||
7613 | temporary directory as it is part of | ||
7614 | <filename>WORKDIR</filename>. | ||
7615 | The final output directory is | ||
7616 | <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>. | ||
7617 | </note> | ||
7618 | </para> | ||
7619 | </glossdef> | ||
7620 | </glossentry> | ||
7621 | |||
7622 | <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm> | ||
7623 | <glossdef> | ||
7624 | <para> | ||
7625 | The base name for SDK output files. | ||
7626 | The name is derived from the | ||
7627 | <link linkend='var-DISTRO'><filename>DISTRO</filename></link>, | ||
7628 | <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, | ||
7629 | <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>, | ||
7630 | <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>, | ||
7631 | and | ||
7632 | <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link> | ||
7633 | variables: | ||
7634 | <literallayout class='monospaced'> | ||
7635 | SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}" | ||
7636 | </literallayout> | ||
7637 | </para> | ||
7638 | </glossdef> | ||
7639 | </glossentry> | ||
7640 | |||
7641 | <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm> | ||
7642 | <glossdef> | ||
7643 | <para> | ||
7644 | The location used by the OpenEmbedded build system when | ||
7645 | creating SDK output. | ||
7646 | The | ||
7647 | <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link> | ||
7648 | class defines the variable as follows: | ||
7649 | <literallayout class='monospaced'> | ||
7650 | SDK_OUTPUT = "${<link linkend='var-SDK_DIR'>SDK_DIR</link>}/image" | ||
7651 | </literallayout> | ||
7652 | <note> | ||
7653 | The <filename>SDK_OUTPUT</filename> directory is a | ||
7654 | temporary directory as it is part of | ||
7655 | <filename>WORKDIR</filename> by way of | ||
7656 | <filename>SDK_DIR</filename>. | ||
7657 | The final output directory is | ||
7658 | <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>. | ||
7659 | </note> | ||
7660 | |||
7661 | </para> | ||
7662 | </glossdef> | ||
7663 | </glossentry> | ||
7664 | |||
7665 | <glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm> | ||
7666 | <glossdef> | ||
7667 | <para> | ||
7668 | Specifies a list of architectures compatible with | ||
7669 | the SDK machine. | ||
7670 | This variable is set automatically and should not | ||
7671 | normally be hand-edited. | ||
7672 | Entries are separated using spaces and listed in order | ||
7673 | of priority. | ||
7674 | The default value for | ||
7675 | <filename>SDK_PACKAGE_ARCHS</filename> is "all any noarch | ||
7676 | ${SDK_ARCH}-${SDKPKGSUFFIX}". | ||
7677 | </para> | ||
7678 | </glossdef> | ||
7679 | </glossentry> | ||
7680 | |||
7681 | <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm> | ||
7682 | <glossdef> | ||
7683 | <para>Equivalent to | ||
7684 | <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>. | ||
7685 | However, this variable applies to the SDK generated from an | ||
7686 | image using the following command: | ||
7687 | <literallayout class='monospaced'> | ||
7688 | $ bitbake -c populate_sdk <replaceable>imagename</replaceable> | ||
7689 | </literallayout> | ||
7690 | </para> | ||
7691 | </glossdef> | ||
7692 | </glossentry> | ||
7693 | |||
7694 | <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm> | ||
7695 | <glossdef> | ||
7696 | <para> | ||
7697 | The machine for which the Application Development Toolkit | ||
7698 | (ADT) or SDK is built. | ||
7699 | In other words, the SDK or ADT is built such that it | ||
7700 | runs on the target you specify with the | ||
7701 | <filename>SDKMACHINE</filename> value. | ||
7702 | The value points to a corresponding | ||
7703 | <filename>.conf</filename> file under | ||
7704 | <filename>conf/machine-sdk/</filename>. | ||
7705 | </para> | ||
7706 | |||
7707 | <para> | ||
7708 | You can use "i686" and "x86_64" as possible values | ||
7709 | for this variable. The variable defaults to "i686" | ||
7710 | and is set in the local.conf file in the Build Directory. | ||
7711 | <literallayout class='monospaced'> | ||
7712 | SDKMACHINE ?= "i686" | ||
7713 | </literallayout> | ||
7714 | <note> | ||
7715 | You cannot set the <filename>SDKMACHINE</filename> | ||
7716 | variable in your distribution configuration file. | ||
7717 | If you do, the configuration will not take affect. | ||
7718 | </note> | ||
7719 | </para> | ||
7720 | </glossdef> | ||
7721 | </glossentry> | ||
7722 | |||
7723 | <glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm> | ||
7724 | <glossdef> | ||
7725 | <para> | ||
7726 | Defines the path offered to the user for installation | ||
7727 | of the SDK that is generated by the OpenEmbedded build | ||
7728 | system. | ||
7729 | The path appears as the default location for installing | ||
7730 | the SDK when you run the SDK's installation script. | ||
7731 | You can override the offered path when you run the | ||
7732 | script. | ||
7733 | </para> | ||
7734 | </glossdef> | ||
7735 | </glossentry> | ||
7736 | |||
7737 | <glossentry id='var-SECTION'><glossterm>SECTION</glossterm> | ||
7738 | <glossdef> | ||
7739 | <para>The section in which packages should be categorized. | ||
7740 | Package management utilities can make use of this variable.</para> | ||
7741 | </glossdef> | ||
7742 | </glossentry> | ||
7743 | |||
7744 | <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm> | ||
7745 | <glossdef> | ||
7746 | <para> | ||
7747 | Specifies the optimization flags passed to the C compiler | ||
7748 | when building for the target. | ||
7749 | The flags are passed through the default value of the | ||
7750 | <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link> | ||
7751 | variable. | ||
7752 | </para> | ||
7753 | |||
7754 | <para> | ||
7755 | The <filename>SELECTED_OPTIMIZATION</filename> variable | ||
7756 | takes the value of | ||
7757 | <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename> | ||
7758 | unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1". | ||
7759 | If that is the case, the value of | ||
7760 | <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used. | ||
7761 | </para> | ||
7762 | </glossdef> | ||
7763 | </glossentry> | ||
7764 | |||
7765 | <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm> | ||
7766 | <glossdef> | ||
7767 | <para> | ||
7768 | Defines a serial console (TTY) to enable using getty. | ||
7769 | Provide a value that specifies the baud rate followed by | ||
7770 | the TTY device name separated by a space. | ||
7771 | You cannot specify more than one TTY device: | ||
7772 | <literallayout class='monospaced'> | ||
7773 | SERIAL_CONSOLE = "115200 ttyS0" | ||
7774 | </literallayout> | ||
7775 | <note> | ||
7776 | The <filename>SERIAL_CONSOLE</filename> variable | ||
7777 | is deprecated. | ||
7778 | Please use the | ||
7779 | <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link> | ||
7780 | variable. | ||
7781 | </note> | ||
7782 | </para> | ||
7783 | </glossdef> | ||
7784 | </glossentry> | ||
7785 | |||
7786 | <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm> | ||
7787 | <glossdef> | ||
7788 | <para> | ||
7789 | Defines the serial consoles (TTYs) to enable using getty. | ||
7790 | Provide a value that specifies the baud rate followed by | ||
7791 | the TTY device name separated by a semicolon. | ||
7792 | Use spaces to separate multiple devices: | ||
7793 | <literallayout class='monospaced'> | ||
7794 | SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" | ||
7795 | </literallayout> | ||
7796 | </para> | ||
7797 | </glossdef> | ||
7798 | </glossentry> | ||
7799 | |||
7800 | <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm> | ||
7801 | <glossdef> | ||
7802 | <para> | ||
7803 | Similar to | ||
7804 | <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link> | ||
7805 | except the device is checked for existence before attempting | ||
7806 | to enable it. | ||
7807 | This variable is currently only supported with SysVinit | ||
7808 | (i.e. not with systemd). | ||
7809 | </para> | ||
7810 | </glossdef> | ||
7811 | </glossentry> | ||
7812 | |||
7813 | <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm> | ||
7814 | <glossdef> | ||
7815 | <para> | ||
7816 | A list of recipe dependencies that should not be used to | ||
7817 | determine signatures of tasks from one recipe when they | ||
7818 | depend on tasks from another recipe. | ||
7819 | For example: | ||
7820 | <literallayout class='monospaced'> | ||
7821 | SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" | ||
7822 | </literallayout> | ||
7823 | In this example, <filename>intone</filename> depends on | ||
7824 | <filename>mplayer2</filename>. | ||
7825 | </para> | ||
7826 | |||
7827 | <para> | ||
7828 | Use of this variable is one mechanism to remove dependencies | ||
7829 | that affect task signatures and thus force rebuilds when a | ||
7830 | recipe changes. | ||
7831 | <note><title>Caution</title> | ||
7832 | If you add an inappropriate dependency for a recipe | ||
7833 | relationship, the software might break during | ||
7834 | runtime if the interface of the second recipe was | ||
7835 | changed after the first recipe had been built. | ||
7836 | </note> | ||
7837 | </para> | ||
7838 | </glossdef> | ||
7839 | </glossentry> | ||
7840 | |||
7841 | <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm> | ||
7842 | <glossdef> | ||
7843 | <para> | ||
7844 | A list of recipes that are completely stable and will | ||
7845 | never change. | ||
7846 | The ABI for the recipes in the list are presented by | ||
7847 | output from the tasks run to build the recipe. | ||
7848 | Use of this variable is one way to remove dependencies from | ||
7849 | one recipe on another that affect task signatures and | ||
7850 | thus force rebuilds when the recipe changes. | ||
7851 | <note><title>Caution</title> | ||
7852 | If you add an inappropriate variable to this list, | ||
7853 | the software might break at runtime if the | ||
7854 | interface of the recipe was changed after the other | ||
7855 | had been built. | ||
7856 | </note> | ||
7857 | </para> | ||
7858 | </glossdef> | ||
7859 | </glossentry> | ||
7860 | |||
7861 | <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm> | ||
7862 | <glossdef> | ||
7863 | <para> | ||
7864 | Specifies the number of bits for the target system CPU. | ||
7865 | The value should be either "32" or "64". | ||
7866 | </para> | ||
7867 | </glossdef> | ||
7868 | </glossentry> | ||
7869 | |||
7870 | <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm> | ||
7871 | <glossdef> | ||
7872 | <para> | ||
7873 | Specifies the endian byte order of the target system. | ||
7874 | The value should be either "le" for little-endian or "be" for big-endian. | ||
7875 | </para> | ||
7876 | </glossdef> | ||
7877 | </glossentry> | ||
7878 | |||
7879 | <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm> | ||
7880 | <glossdef> | ||
7881 | <para> | ||
7882 | Groups together machines based upon the same family | ||
7883 | of SOC (System On Chip). | ||
7884 | You typically set this variable in a common | ||
7885 | <filename>.inc</filename> file that you include in the | ||
7886 | configuration files of all the machines. | ||
7887 | <note> | ||
7888 | You must include | ||
7889 | <filename>conf/machine/include/soc-family.inc</filename> | ||
7890 | for this variable to appear in | ||
7891 | <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>. | ||
7892 | </note> | ||
7893 | </para> | ||
7894 | </glossdef> | ||
7895 | </glossentry> | ||
7896 | |||
7897 | <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm> | ||
7898 | <glossdef> | ||
7899 | <para> | ||
7900 | Defines the suffix for shared libraries used on the | ||
7901 | target platform. | ||
7902 | By default, this suffix is ".so.*" for all Linux-based | ||
7903 | systems and is defined in the | ||
7904 | <filename>meta/conf/bitbake.conf</filename> configuration | ||
7905 | file. | ||
7906 | </para> | ||
7907 | |||
7908 | <para> | ||
7909 | You will see this variable referenced in the default values | ||
7910 | of <filename>FILES_${PN}</filename>. | ||
7911 | </para> | ||
7912 | </glossdef> | ||
7913 | </glossentry> | ||
7914 | |||
7915 | <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm> | ||
7916 | <glossdef> | ||
7917 | <para> | ||
7918 | Defines the suffix for the development symbolic link | ||
7919 | (symlink) for shared libraries on the target platform. | ||
7920 | By default, this suffix is ".so" for Linux-based | ||
7921 | systems and is defined in the | ||
7922 | <filename>meta/conf/bitbake.conf</filename> configuration | ||
7923 | file. | ||
7924 | </para> | ||
7925 | |||
7926 | <para> | ||
7927 | You will see this variable referenced in the default values | ||
7928 | of <filename>FILES_${PN}-dev</filename>. | ||
7929 | </para> | ||
7930 | </glossdef> | ||
7931 | </glossentry> | ||
7932 | |||
7933 | <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm> | ||
7934 | <glossdef> | ||
7935 | <para> | ||
7936 | Defines your own | ||
7937 | <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link> | ||
7938 | from which to first fetch source before attempting to fetch | ||
7939 | from the upstream specified in | ||
7940 | <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>. | ||
7941 | </para> | ||
7942 | |||
7943 | <para> | ||
7944 | To use this variable, you must globally inherit the | ||
7945 | <link linkend='ref-classes-own-mirrors'><filename>own-mirrors</filename></link> | ||
7946 | class and then provide the URL to your mirrors. | ||
7947 | Here is an example: | ||
7948 | <literallayout class='monospaced'> | ||
7949 | INHERIT += "own-mirrors" | ||
7950 | SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" | ||
7951 | </literallayout> | ||
7952 | <note> | ||
7953 | You can specify only a single URL in | ||
7954 | <filename>SOURCE_MIRROR_URL</filename>. | ||
7955 | </note> | ||
7956 | </para> | ||
7957 | </glossdef> | ||
7958 | </glossentry> | ||
7959 | |||
7960 | <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm> | ||
7961 | <glossdef> | ||
7962 | <para> | ||
7963 | Maps commonly used license names to their SPDX counterparts | ||
7964 | found in <filename>meta/files/common-licenses/</filename>. | ||
7965 | For the default <filename>SPDXLICENSEMAP</filename> | ||
7966 | mappings, see the | ||
7967 | <filename>meta/conf/licenses.conf</filename> file. | ||
7968 | </para> | ||
7969 | |||
7970 | <para> | ||
7971 | For additional information, see the | ||
7972 | <link linkend='var-LICENSE'><filename>LICENSE</filename></link> | ||
7973 | variable. | ||
7974 | </para> | ||
7975 | </glossdef> | ||
7976 | </glossentry> | ||
7977 | |||
7978 | <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm> | ||
7979 | <glossdef> | ||
7980 | <para> | ||
7981 | A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the | ||
7982 | OpenEmbedded build system to create variants of recipes or packages. | ||
7983 | The list specifies the prefixes to strip off during certain circumstances | ||
7984 | such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable. | ||
7985 | </para> | ||
7986 | </glossdef> | ||
7987 | </glossentry> | ||
7988 | |||
7989 | <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm> | ||
7990 | <glossdef> | ||
7991 | <para>The list of source files - local or remote. | ||
7992 | This variable tells the OpenEmbedded build system which bits | ||
7993 | to pull in for the build and how to pull them in. | ||
7994 | For example, if the recipe or append file only needs to | ||
7995 | fetch a tarball from the Internet, the recipe or | ||
7996 | append file uses a single <filename>SRC_URI</filename> | ||
7997 | entry. | ||
7998 | On the other hand, if the recipe or append file needs to | ||
7999 | fetch a tarball, apply two patches, and include a custom | ||
8000 | file, the recipe or append file would include four | ||
8001 | instances of the variable.</para> | ||
8002 | <para>The following list explains the available URI protocols: | ||
8003 | <itemizedlist> | ||
8004 | <listitem><para><emphasis><filename>file://</filename> -</emphasis> | ||
8005 | Fetches files, which are usually files shipped with | ||
8006 | the | ||
8007 | <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>, | ||
8008 | from the local machine. | ||
8009 | The path is relative to the | ||
8010 | <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> | ||
8011 | variable. | ||
8012 | Thus, the build system searches, in order, from the | ||
8013 | following directories, which are assumed to be a | ||
8014 | subdirectories of the directory in which the | ||
8015 | recipe file (<filename>.bb</filename>) or | ||
8016 | append file (<filename>.bbappend</filename>) | ||
8017 | resides: | ||
8018 | <itemizedlist> | ||
8019 | <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis> | ||
8020 | The base recipe name without any special | ||
8021 | suffix or version numbers. | ||
8022 | </para></listitem> | ||
8023 | <listitem><para><emphasis><filename>${BP}</filename> -</emphasis> | ||
8024 | <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>. | ||
8025 | The base recipe name and version but without | ||
8026 | any special package name suffix. | ||
8027 | </para></listitem> | ||
8028 | <listitem><para><emphasis>files -</emphasis> | ||
8029 | Files within a directory, which is named | ||
8030 | <filename>files</filename> and is also | ||
8031 | alongside the recipe or append file. | ||
8032 | </para></listitem> | ||
8033 | </itemizedlist> | ||
8034 | <note> | ||
8035 | If you want the build system to pick up files | ||
8036 | specified through a | ||
8037 | <filename>SRC_URI</filename> | ||
8038 | statement from your append file, you need to be | ||
8039 | sure to extend the | ||
8040 | <filename>FILESPATH</filename> | ||
8041 | variable by also using the | ||
8042 | <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link> | ||
8043 | variable from within your append file. | ||
8044 | </note> | ||
8045 | </para></listitem> | ||
8046 | <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a | ||
8047 | Bazaar revision control repository.</para></listitem> | ||
8048 | <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a | ||
8049 | Git revision control repository.</para></listitem> | ||
8050 | <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from | ||
8051 | an OSC (OpenSUSE Build service) revision control repository.</para></listitem> | ||
8052 | <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from | ||
8053 | a repo (Git) repository.</para></listitem> | ||
8054 | <listitem><para><emphasis><filename>ccrc://</filename> -</emphasis> | ||
8055 | Fetches files from a ClearCase repository. | ||
8056 | </para></listitem> | ||
8057 | <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from | ||
8058 | the Internet using <filename>http</filename>.</para></listitem> | ||
8059 | <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files | ||
8060 | from the Internet using <filename>https</filename>.</para></listitem> | ||
8061 | <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files | ||
8062 | from the Internet using <filename>ftp</filename>.</para></listitem> | ||
8063 | <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from | ||
8064 | a CVS revision control repository.</para></listitem> | ||
8065 | <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from | ||
8066 | a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem> | ||
8067 | <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from | ||
8068 | a Perforce (<filename>p4</filename>) revision control repository.</para></listitem> | ||
8069 | <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from | ||
8070 | a secure shell.</para></listitem> | ||
8071 | <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from | ||
8072 | a Subversion (<filename>svn</filename>) revision control repository.</para></listitem> | ||
8073 | </itemizedlist> | ||
8074 | </para> | ||
8075 | <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist. | ||
8076 | Here are standard options: | ||
8077 | <itemizedlist> | ||
8078 | <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply | ||
8079 | the patch or not. | ||
8080 | The default action is to apply the patch.</para></listitem> | ||
8081 | <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which | ||
8082 | striplevel to use when applying the patch. | ||
8083 | The default level is 1.</para></listitem> | ||
8084 | <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies | ||
8085 | the directory in which the patch should be applied. | ||
8086 | The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>. | ||
8087 | </para></listitem> | ||
8088 | </itemizedlist> | ||
8089 | </para> | ||
8090 | <para>Here are options specific to recipes building code from a revision control system: | ||
8091 | <itemizedlist> | ||
8092 | <listitem><para><emphasis><filename>mindate</filename> -</emphasis> | ||
8093 | Apply the patch only if | ||
8094 | <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link> | ||
8095 | is equal to or greater than <filename>mindate</filename>. | ||
8096 | </para></listitem> | ||
8097 | <listitem><para><emphasis><filename>maxdate</filename> -</emphasis> | ||
8098 | Apply the patch only if <filename>SRCDATE</filename> | ||
8099 | is not later than <filename>mindate</filename>. | ||
8100 | </para></listitem> | ||
8101 | <listitem><para><emphasis><filename>minrev</filename> -</emphasis> | ||
8102 | Apply the patch only if <filename>SRCREV</filename> | ||
8103 | is equal to or greater than <filename>minrev</filename>. | ||
8104 | </para></listitem> | ||
8105 | <listitem><para><emphasis><filename>maxrev</filename> -</emphasis> | ||
8106 | Apply the patch only if <filename>SRCREV</filename> | ||
8107 | is not later than <filename>maxrev</filename>. | ||
8108 | </para></listitem> | ||
8109 | <listitem><para><emphasis><filename>rev</filename> -</emphasis> | ||
8110 | Apply the patch only if <filename>SRCREV</filename> | ||
8111 | is equal to <filename>rev</filename>. | ||
8112 | </para></listitem> | ||
8113 | <listitem><para><emphasis><filename>notrev</filename> -</emphasis> | ||
8114 | Apply the patch only if <filename>SRCREV</filename> | ||
8115 | is not equal to <filename>rev</filename>. | ||
8116 | </para></listitem> | ||
8117 | </itemizedlist> | ||
8118 | </para> | ||
8119 | <para>Here are some additional options worth mentioning: | ||
8120 | <itemizedlist> | ||
8121 | <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls | ||
8122 | whether or not to unpack the file if it is an archive. | ||
8123 | The default action is to unpack the file.</para></listitem> | ||
8124 | <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file | ||
8125 | (or extracts its contents) into the specified | ||
8126 | subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>. | ||
8127 | This option is useful for unusual tarballs or other archives that | ||
8128 | do not have their files already in a subdirectory within the archive. | ||
8129 | </para></listitem> | ||
8130 | <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a | ||
8131 | name to be used for association with <filename>SRC_URI</filename> checksums | ||
8132 | when you have more than one file specified in <filename>SRC_URI</filename>. | ||
8133 | </para></listitem> | ||
8134 | <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies | ||
8135 | the filename used when storing the downloaded file.</para></listitem> | ||
8136 | </itemizedlist> | ||
8137 | </para> | ||
8138 | </glossdef> | ||
8139 | </glossentry> | ||
8140 | |||
8141 | <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm> | ||
8142 | <glossdef> | ||
8143 | <para> | ||
8144 | By default, the OpenEmbedded build system automatically detects whether | ||
8145 | <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> | ||
8146 | contains files that are machine-specific. | ||
8147 | If so, the build system automatically changes | ||
8148 | <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>. | ||
8149 | Setting this variable to "0" disables this behavior. | ||
8150 | </para> | ||
8151 | </glossdef> | ||
8152 | </glossentry> | ||
8153 | |||
8154 | <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm> | ||
8155 | <glossdef> | ||
8156 | <para> | ||
8157 | The date of the source code used to build the package. | ||
8158 | This variable applies only if the source was fetched from a Source Code Manager (SCM). | ||
8159 | </para> | ||
8160 | </glossdef> | ||
8161 | </glossentry> | ||
8162 | |||
8163 | <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm> | ||
8164 | <glossdef> | ||
8165 | <para> | ||
8166 | Returns the version string of the current package. | ||
8167 | This string is used to help define the value of | ||
8168 | <link linkend='var-PV'><filename>PV</filename></link>. | ||
8169 | </para> | ||
8170 | |||
8171 | <para> | ||
8172 | The <filename>SRCPV</filename> variable is defined in the | ||
8173 | <filename>meta/conf/bitbake.conf</filename> configuration | ||
8174 | file in the | ||
8175 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> | ||
8176 | as follows: | ||
8177 | <literallayout class='monospaced'> | ||
8178 | SRCPV = "${@bb.fetch2.get_srcrev(d)}" | ||
8179 | </literallayout> | ||
8180 | </para> | ||
8181 | |||
8182 | <para> | ||
8183 | Recipes that need to define <filename>PV</filename> do so | ||
8184 | with the help of the <filename>SRCPV</filename>. | ||
8185 | For example, the <filename>ofono</filename> recipe | ||
8186 | (<filename>ofono_git.bb</filename>) located in | ||
8187 | <filename>meta/recipes-connectivity</filename> in the | ||
8188 | Source Directory defines <filename>PV</filename> as | ||
8189 | follows: | ||
8190 | <literallayout class='monospaced'> | ||
8191 | PV = "0.12-git${SRCPV}" | ||
8192 | </literallayout> | ||
8193 | </para> | ||
8194 | </glossdef> | ||
8195 | </glossentry> | ||
8196 | |||
8197 | <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm> | ||
8198 | <glossdef> | ||
8199 | <para> | ||
8200 | The revision of the source code used to build the package. | ||
8201 | This variable applies to Subversion, Git, Mercurial and Bazaar | ||
8202 | only. | ||
8203 | Note that if you wish to build a fixed revision and you wish | ||
8204 | to avoid performing a query on the remote repository every time | ||
8205 | BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a | ||
8206 | full revision identifier and not just a tag. | ||
8207 | </para> | ||
8208 | </glossdef> | ||
8209 | </glossentry> | ||
8210 | |||
8211 | <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm> | ||
8212 | <glossdef> | ||
8213 | <para>The directory for the shared state cache.</para> | ||
8214 | </glossdef> | ||
8215 | </glossentry> | ||
8216 | |||
8217 | <glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm> | ||
8218 | <glossdef> | ||
8219 | <para> | ||
8220 | If set to "1", allows fetches from | ||
8221 | mirrors that are specified in | ||
8222 | <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> | ||
8223 | to work even when fetching from the network has been | ||
8224 | disabled by setting <filename>BB_NO_NETWORK</filename> | ||
8225 | to "1". | ||
8226 | Using the | ||
8227 | <filename>SSTATE_MIRROR_ALLOW_NETWORK</filename> | ||
8228 | variable is useful if you have set | ||
8229 | <filename>SSTATE_MIRRORS</filename> to point to an | ||
8230 | internal server for your shared state cache, but | ||
8231 | you want to disable any other fetching from the network. | ||
8232 | </para> | ||
8233 | </glossdef> | ||
8234 | </glossentry> | ||
8235 | |||
8236 | <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm> | ||
8237 | <glossdef> | ||
8238 | <para> | ||
8239 | Configures the OpenEmbedded build system to search other | ||
8240 | mirror locations for prebuilt cache data objects before | ||
8241 | building out the data. | ||
8242 | This variable works like fetcher | ||
8243 | <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link> | ||
8244 | and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link> | ||
8245 | and points to the cache locations to check for the shared | ||
8246 | objects. | ||
8247 | </para> | ||
8248 | |||
8249 | <para> | ||
8250 | You can specify a filesystem directory or a remote URL such | ||
8251 | as HTTP or FTP. | ||
8252 | The locations you specify need to contain the shared state | ||
8253 | cache (sstate-cache) results from previous builds. | ||
8254 | The sstate-cache you point to can also be from builds on | ||
8255 | other machines. | ||
8256 | </para> | ||
8257 | |||
8258 | <para> | ||
8259 | If a mirror uses the same structure as | ||
8260 | <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, | ||
8261 | you need to add | ||
8262 | "PATH" at the end as shown in the examples below. | ||
8263 | The build system substitutes the correct path within the | ||
8264 | directory structure. | ||
8265 | <literallayout class='monospaced'> | ||
8266 | SSTATE_MIRRORS ?= "\ | ||
8267 | file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH \n \ | ||
8268 | file://.* file:///<replaceable>some-local-dir</replaceable>/sstate/PATH" | ||
8269 | </literallayout> | ||
8270 | </para> | ||
8271 | </glossdef> | ||
8272 | </glossentry> | ||
8273 | |||
8274 | <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm> | ||
8275 | <glossdef> | ||
8276 | <para> | ||
8277 | Specifies the path to the <filename>/lib</filename> | ||
8278 | subdirectory of the sysroot directory for the | ||
8279 | build host. | ||
8280 | </para> | ||
8281 | </glossdef> | ||
8282 | </glossentry> | ||
8283 | |||
8284 | <glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm> | ||
8285 | <glossdef> | ||
8286 | <para> | ||
8287 | Specifies the path to the <filename>/lib</filename> | ||
8288 | subdirectory of the sysroot directory for the target | ||
8289 | for which the current recipe is being built | ||
8290 | (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>). | ||
8291 | </para> | ||
8292 | </glossdef> | ||
8293 | </glossentry> | ||
8294 | |||
8295 | <glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm> | ||
8296 | <glossdef> | ||
8297 | <para> | ||
8298 | Specifies the path to the | ||
8299 | <filename>/usr/bin</filename> subdirectory of the | ||
8300 | sysroot directory for the target for which the current | ||
8301 | recipe is being built | ||
8302 | (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>). | ||
8303 | </para> | ||
8304 | </glossdef> | ||
8305 | </glossentry> | ||
8306 | |||
8307 | <glossentry id='var-STAGING_BINDIR_CROSS'><glossterm>STAGING_BINDIR_CROSS</glossterm> | ||
8308 | <glossdef> | ||
8309 | <para> | ||
8310 | Specifies the path to the directory containing binary | ||
8311 | configuration scripts. | ||
8312 | These scripts provide configuration information for | ||
8313 | other software that wants to make use of libraries or | ||
8314 | include files provided by the software associated with | ||
8315 | the script. | ||
8316 | <note> | ||
8317 | This style of build configuration has been largely | ||
8318 | replaced by <filename>pkg-config</filename>. | ||
8319 | Consequently, if <filename>pkg-config</filename> | ||
8320 | is supported by the library to which you are linking, | ||
8321 | it is recommended you use | ||
8322 | <filename>pkg-config</filename> instead of a | ||
8323 | provided configuration script. | ||
8324 | </note> | ||
8325 | </para> | ||
8326 | </glossdef> | ||
8327 | </glossentry> | ||
8328 | |||
8329 | <glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm> | ||
8330 | <glossdef> | ||
8331 | <para> | ||
8332 | Specifies the path to the | ||
8333 | <filename>/usr/bin</filename> subdirectory of the | ||
8334 | sysroot directory for the build host. | ||
8335 | </para> | ||
8336 | </glossdef> | ||
8337 | </glossentry> | ||
8338 | |||
8339 | <glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm> | ||
8340 | <glossdef> | ||
8341 | <para> | ||
8342 | Specifies the path to the <filename>/usr/share</filename> | ||
8343 | subdirectory of the sysroot directory for the target | ||
8344 | for which the current recipe is being built | ||
8345 | (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>). | ||
8346 | </para> | ||
8347 | </glossdef> | ||
8348 | </glossentry> | ||
8349 | |||
8350 | <glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm> | ||
8351 | <glossdef> | ||
8352 | <para> | ||
8353 | Specifies the path to the top-level sysroots directory | ||
8354 | (i.e. | ||
8355 | <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots</filename>). | ||
8356 | <note> | ||
8357 | Recipes should never write files directly under | ||
8358 | this directory because the OpenEmbedded build system | ||
8359 | manages the directory automatically. | ||
8360 | Instead, files should be installed to | ||
8361 | <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename> | ||
8362 | within your recipe's | ||
8363 | <link linkend='ref-tasks-install'><filename>do_install</filename></link> | ||
8364 | task and then the OpenEmbedded build system will | ||
8365 | stage a subset of those files into the sysroot. | ||
8366 | </note> | ||
8367 | </para> | ||
8368 | </glossdef> | ||
8369 | </glossentry> | ||
8370 | |||
8371 | <glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm> | ||
8372 | <glossdef> | ||
8373 | <para> | ||
8374 | Specifies the path to the primary sysroot directory for | ||
8375 | which the target is being built. | ||
8376 | Depending on the type of recipe and the build target, the | ||
8377 | recipe's value is as follows: | ||
8378 | <itemizedlist> | ||
8379 | <listitem><para>For recipes building for the target | ||
8380 | machine, the value is "${STAGING_DIR}/${MACHINE}". | ||
8381 | </para></listitem> | ||
8382 | <listitem><para>For <filename>native</filename> | ||
8383 | recipes building | ||
8384 | for the build host, the value is empty given the | ||
8385 | assumption that when building for the build host, | ||
8386 | the build host's own directories should be used. | ||
8387 | </para></listitem> | ||
8388 | <listitem><para>For <filename>nativesdk</filename> | ||
8389 | recipes that Build for the SDK, the value is | ||
8390 | "${STAGING_DIR}/${MULTIMACH_HOST_SYS}". | ||
8391 | </para></listitem> | ||
8392 | </itemizedlist> | ||
8393 | </para> | ||
8394 | </glossdef> | ||
8395 | </glossentry> | ||
8396 | |||
8397 | <glossentry id='var-STAGING_DATADIR_NATIVE'><glossterm>STAGING_DATADIR_NATIVE</glossterm> | ||
8398 | <glossdef> | ||
8399 | <para> | ||
8400 | Specifies the path to the <filename>/usr/share</filename> | ||
8401 | subdirectory of the sysroot directory for the build host. | ||
8402 | </para> | ||
8403 | </glossdef> | ||
8404 | </glossentry> | ||
8405 | |||
8406 | |||
8407 | |||
8408 | <glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm> | ||
8409 | <glossdef> | ||
8410 | <para> | ||
8411 | Specifies the path to the sysroot directory for the | ||
8412 | build host. | ||
8413 | </para> | ||
8414 | </glossdef> | ||
8415 | </glossentry> | ||
8416 | |||
8417 | <glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm> | ||
8418 | <glossdef> | ||
8419 | <para> | ||
8420 | Specifies the path to the sysroot directory for the | ||
8421 | target for which the current recipe is being built. | ||
8422 | In most cases, this path is the | ||
8423 | <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>. | ||
8424 | </para> | ||
8425 | |||
8426 | <para> | ||
8427 | Some recipes build binaries that can run on the target | ||
8428 | system but those binaries in turn generate code for | ||
8429 | another different system (e.g. cross-canadian recipes). | ||
8430 | Using terminology from GNU, the primary system is referred | ||
8431 | to as the "HOST" and the secondary, or different, system is | ||
8432 | referred to as the "TARGET". | ||
8433 | Thus, the binaries run on the "HOST" system and | ||
8434 | and generate binaries for the "TARGET" system. | ||
8435 | <filename>STAGING_DIR_TARGET</filename> points to the | ||
8436 | sysroot used for the "TARGET" system. | ||
8437 | </para> | ||
8438 | </glossdef> | ||
8439 | </glossentry> | ||
8440 | |||
8441 | <glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm>STAGING_ETCDIR_NATIVE</glossterm> | ||
8442 | <glossdef> | ||
8443 | <para> | ||
8444 | Specifies the path to the <filename>/etc</filename> | ||
8445 | subdirectory of the sysroot directory for the | ||
8446 | build host. | ||
8447 | </para> | ||
8448 | </glossdef> | ||
8449 | </glossentry> | ||
8450 | |||
8451 | <glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm> | ||
8452 | <glossdef> | ||
8453 | <para> | ||
8454 | Specifies the path to the <filename>/usr</filename> | ||
8455 | subdirectory of the sysroot directory for the target | ||
8456 | for which the current recipe is being built | ||
8457 | (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>). | ||
8458 | </para> | ||
8459 | </glossdef> | ||
8460 | </glossentry> | ||
8461 | |||
8462 | <glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm> | ||
8463 | <glossdef> | ||
8464 | <para> | ||
8465 | Specifies the path to the | ||
8466 | <filename>/usr/include</filename> subdirectory of the | ||
8467 | sysroot directory for the target for which the current | ||
8468 | recipe being built | ||
8469 | (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>). | ||
8470 | </para> | ||
8471 | </glossdef> | ||
8472 | </glossentry> | ||
8473 | |||
8474 | <glossentry id='var-STAGING_INCDIR_NATIVE'><glossterm>STAGING_INCDIR_NATIVE</glossterm> | ||
8475 | <glossdef> | ||
8476 | <para> | ||
8477 | Specifies the path to the <filename>/usr/include</filename> | ||
8478 | subdirectory of the sysroot directory for the build host. | ||
8479 | </para> | ||
8480 | </glossdef> | ||
8481 | </glossentry> | ||
8482 | |||
8483 | <glossentry id='var-STAGING_LIBDIR'><glossterm>STAGING_LIBDIR</glossterm> | ||
8484 | <glossdef> | ||
8485 | <para> | ||
8486 | Specifies the path to the <filename>/usr/lib</filename> | ||
8487 | subdirectory of the sysroot directory for the target for | ||
8488 | which the current recipe is being built | ||
8489 | (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>). | ||
8490 | </para> | ||
8491 | </glossdef> | ||
8492 | </glossentry> | ||
8493 | |||
8494 | <glossentry id='var-STAGING_LIBDIR_NATIVE'><glossterm>STAGING_LIBDIR_NATIVE</glossterm> | ||
8495 | <glossdef> | ||
8496 | <para> | ||
8497 | Specifies the path to the <filename>/usr/lib</filename> | ||
8498 | subdirectory of the sysroot directory for the build host. | ||
8499 | </para> | ||
8500 | </glossdef> | ||
8501 | </glossentry> | ||
8502 | |||
8503 | <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm> | ||
8504 | <glossdef> | ||
8505 | <para> | ||
8506 | The directory with kernel headers that are required to build out-of-tree | ||
8507 | modules. | ||
8508 | </para> | ||
8509 | </glossdef> | ||
8510 | </glossentry> | ||
8511 | |||
8512 | <glossentry id='var-STAMP'><glossterm>STAMP</glossterm> | ||
8513 | <glossdef> | ||
8514 | <para> | ||
8515 | Specifies the base path used to create recipe stamp files. | ||
8516 | The path to an actual stamp file is constructed by evaluating this | ||
8517 | string and then appending additional information. | ||
8518 | Currently, the default assignment for <filename>STAMP</filename> | ||
8519 | as set in the <filename>meta/conf/bitbake.conf</filename> file | ||
8520 | is: | ||
8521 | <literallayout class='monospaced'> | ||
8522 | STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" | ||
8523 | </literallayout> | ||
8524 | See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>, | ||
8525 | <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>, | ||
8526 | <link linkend='var-PN'><filename>PN</filename></link>, | ||
8527 | <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>, | ||
8528 | <link linkend='var-PV'><filename>PV</filename></link>, and | ||
8529 | <link linkend='var-PR'><filename>PR</filename></link> for related variable | ||
8530 | information. | ||
8531 | </para> | ||
8532 | </glossdef> | ||
8533 | </glossentry> | ||
8534 | |||
8535 | <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm> | ||
8536 | <glossdef> | ||
8537 | <para> | ||
8538 | Specifies the base directory in which the OpenEmbedded | ||
8539 | build system places stamps. | ||
8540 | The default directory is | ||
8541 | <filename>${TMPDIR}/stamps</filename>. | ||
8542 | </para> | ||
8543 | </glossdef> | ||
8544 | </glossentry> | ||
8545 | |||
8546 | <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm> | ||
8547 | <glossdef> | ||
8548 | <para>The short (72 characters or less) summary of the binary package for packaging | ||
8549 | systems such as <filename>opkg</filename>, <filename>rpm</filename> or | ||
8550 | <filename>dpkg</filename>. | ||
8551 | By default, <filename>SUMMARY</filename> is used to define | ||
8552 | the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link> | ||
8553 | variable if <filename>DESCRIPTION</filename> is not set | ||
8554 | in the recipe. | ||
8555 | </para> | ||
8556 | </glossdef> | ||
8557 | </glossentry> | ||
8558 | |||
8559 | <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm> | ||
8560 | <glossdef> | ||
8561 | <para> | ||
8562 | Specifies the kernel boot default console. | ||
8563 | If you want to use a console other than the default, | ||
8564 | set this variable in your recipe as follows where "X" is | ||
8565 | the console number you want to use: | ||
8566 | <literallayout class='monospaced'> | ||
8567 | SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" | ||
8568 | </literallayout> | ||
8569 | </para> | ||
8570 | |||
8571 | <para> | ||
8572 | The | ||
8573 | <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link> | ||
8574 | class initially sets this variable to null but then checks | ||
8575 | for a value later. | ||
8576 | </para> | ||
8577 | </glossdef> | ||
8578 | </glossentry> | ||
8579 | |||
8580 | <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm> | ||
8581 | <glossdef> | ||
8582 | <para> | ||
8583 | Lists additional options to add to the syslinux file. | ||
8584 | You need to set this variable in your recipe. | ||
8585 | If you want to list multiple options, separate the options | ||
8586 | with a semicolon character (<filename>;</filename>). | ||
8587 | </para> | ||
8588 | |||
8589 | <para> | ||
8590 | The | ||
8591 | <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link> | ||
8592 | class uses this variable to create a set of options. | ||
8593 | </para> | ||
8594 | </glossdef> | ||
8595 | </glossentry> | ||
8596 | |||
8597 | <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm> | ||
8598 | <glossdef> | ||
8599 | <para> | ||
8600 | Specifies the alternate serial port or turns it off. | ||
8601 | To turn off serial, set this variable to an empty string | ||
8602 | in your recipe. | ||
8603 | The variable's default value is set in the | ||
8604 | <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link> | ||
8605 | as follows: | ||
8606 | <literallayout class='monospaced'> | ||
8607 | SYSLINUX_SERIAL ?= "0 115200" | ||
8608 | </literallayout> | ||
8609 | The class checks for and uses the variable as needed. </para> | ||
8610 | </glossdef> | ||
8611 | </glossentry> | ||
8612 | |||
8613 | <glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm> | ||
8614 | <glossdef> | ||
8615 | <para> | ||
8616 | An <filename>.LSS</filename> file used as the background | ||
8617 | for the VGA boot menu when you are using the boot menu. | ||
8618 | You need to set this variable in your recipe. | ||
8619 | </para> | ||
8620 | |||
8621 | <para> | ||
8622 | The | ||
8623 | <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link> | ||
8624 | class checks for this variable and if found, the | ||
8625 | OpenEmbedded build system installs the splash screen. | ||
8626 | </para> | ||
8627 | </glossdef> | ||
8628 | </glossentry> | ||
8629 | |||
8630 | <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm> | ||
8631 | <glossdef> | ||
8632 | <para> | ||
8633 | Specifies the alternate console=tty... kernel boot argument. | ||
8634 | The variable's default value is set in the | ||
8635 | <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link> | ||
8636 | as follows: | ||
8637 | <literallayout class='monospaced'> | ||
8638 | SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" | ||
8639 | </literallayout> | ||
8640 | The class checks for and uses the variable as needed. | ||
8641 | </para> | ||
8642 | </glossdef> | ||
8643 | </glossentry> | ||
8644 | |||
8645 | <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm> | ||
8646 | <glossdef> | ||
8647 | <para> | ||
8648 | A list of functions to execute after files are staged into | ||
8649 | the sysroot. | ||
8650 | These functions are usually used to apply additional | ||
8651 | processing on the staged files, or to stage additional | ||
8652 | files. | ||
8653 | </para> | ||
8654 | </glossdef> | ||
8655 | </glossentry> | ||
8656 | |||
8657 | <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm> | ||
8658 | <glossdef> | ||
8659 | <para> | ||
8660 | When inheriting the | ||
8661 | <link linkend='ref-classes-systemd'><filename>systemd</filename></link> | ||
8662 | class, this variable specifies whether the service you have | ||
8663 | specified in | ||
8664 | <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link> | ||
8665 | should be started automatically or not. | ||
8666 | By default, the service is enabled to automatically start | ||
8667 | at boot time. | ||
8668 | The default setting is in the | ||
8669 | <link linkend='ref-classes-systemd'><filename>systemd</filename></link> | ||
8670 | class as follows: | ||
8671 | <literallayout class='monospaced'> | ||
8672 | SYSTEMD_AUTO_ENABLE ??= "enable" | ||
8673 | </literallayout> | ||
8674 | You can disable the service by setting the variable to | ||
8675 | "disable". | ||
8676 | </para> | ||
8677 | </glossdef> | ||
8678 | </glossentry> | ||
8679 | |||
8680 | <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm> | ||
8681 | <glossdef> | ||
8682 | <para> | ||
8683 | When inheriting the | ||
8684 | <link linkend='ref-classes-systemd'><filename>systemd</filename></link> | ||
8685 | class, this variable locates the systemd unit files when | ||
8686 | they are not found in the main recipe's package. | ||
8687 | By default, the | ||
8688 | <filename>SYSTEMD_PACKAGES</filename> variable is set | ||
8689 | such that the systemd unit files are assumed to reside in | ||
8690 | the recipes main package: | ||
8691 | <literallayout class='monospaced'> | ||
8692 | SYSTEMD_PACKAGES ?= "${PN}" | ||
8693 | </literallayout> | ||
8694 | If these unit files are not in this recipe's main | ||
8695 | package, you need to use | ||
8696 | <filename>SYSTEMD_PACKAGES</filename> to list the package | ||
8697 | or packages in which the build system can find the systemd | ||
8698 | unit files. | ||
8699 | </para> | ||
8700 | </glossdef> | ||
8701 | </glossentry> | ||
8702 | |||
8703 | <glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm> | ||
8704 | <glossdef> | ||
8705 | <para> | ||
8706 | When inheriting the | ||
8707 | <link linkend='ref-classes-systemd'><filename>systemd</filename></link> | ||
8708 | class, this variable specifies the systemd service name for | ||
8709 | a package. | ||
8710 | </para> | ||
8711 | |||
8712 | <para> | ||
8713 | When you specify this file in your recipe, use a package | ||
8714 | name override to indicate the package to which the value | ||
8715 | applies. | ||
8716 | Here is an example from the connman recipe: | ||
8717 | <literallayout class='monospaced'> | ||
8718 | SYSTEMD_SERVICE_${PN} = "connman.service" | ||
8719 | </literallayout> | ||
8720 | </para> | ||
8721 | </glossdef> | ||
8722 | </glossentry> | ||
8723 | |||
8724 | <glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>SYSVINIT_ENABLED_GETTYS</glossterm> | ||
8725 | <glossdef> | ||
8726 | <para> | ||
8727 | When using | ||
8728 | <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>, | ||
8729 | specifies a space-separated list of the virtual terminals | ||
8730 | that should be running a | ||
8731 | <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink> | ||
8732 | (allowing login), assuming | ||
8733 | <link linkend='var-USE_VT'><filename>USE_VT</filename></link> | ||
8734 | is not set to "0". | ||
8735 | </para> | ||
8736 | |||
8737 | <para> | ||
8738 | The default value for | ||
8739 | <filename>SYSVINIT_ENABLED_GETTYS</filename> is "1" | ||
8740 | (i.e. only run a getty on the first virtual terminal). | ||
8741 | </para> | ||
8742 | </glossdef> | ||
8743 | </glossentry> | ||
8744 | |||
8745 | </glossdiv> | ||
8746 | |||
8747 | <glossdiv id='var-glossary-t'><title>T</title> | ||
8748 | |||
8749 | <glossentry id='var-T'><glossterm>T</glossterm> | ||
8750 | <glossdef> | ||
8751 | <para>This variable points to a directory were BitBake places | ||
8752 | temporary files, which consist mostly of task logs and | ||
8753 | scripts, when building a particular recipe. | ||
8754 | The variable is typically set as follows: | ||
8755 | <literallayout class='monospaced'> | ||
8756 | T = "${WORKDIR}/temp" | ||
8757 | </literallayout> | ||
8758 | The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> | ||
8759 | is the directory into which BitBake unpacks and builds the | ||
8760 | recipe. | ||
8761 | The default <filename>bitbake.conf</filename> file sets this variable.</para> | ||
8762 | <para>The <filename>T</filename> variable is not to be confused with | ||
8763 | the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable, | ||
8764 | which points to the root of the directory tree where BitBake | ||
8765 | places the output of an entire build. | ||
8766 | </para> | ||
8767 | </glossdef> | ||
8768 | </glossentry> | ||
8769 | |||
8770 | <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm> | ||
8771 | <glossdef> | ||
8772 | <para> | ||
8773 | The target machine's architecture. | ||
8774 | The OpenEmbedded build system supports many | ||
8775 | architectures. | ||
8776 | Here is an example list of architectures supported. | ||
8777 | This list is by no means complete as the architecture | ||
8778 | is configurable: | ||
8779 | <literallayout class='monospaced'> | ||
8780 | arm | ||
8781 | i586 | ||
8782 | x86_64 | ||
8783 | powerpc | ||
8784 | powerpc64 | ||
8785 | mips | ||
8786 | mipsel | ||
8787 | </literallayout> | ||
8788 | For additional information on machine architectures, see | ||
8789 | the | ||
8790 | <link linkend='var-TUNE_ARCH'><filename>TUNE_ARCH</filename></link> | ||
8791 | variable. | ||
8792 | </para> | ||
8793 | </glossdef> | ||
8794 | </glossentry> | ||
8795 | |||
8796 | <glossentry id='var-TARGET_AS_ARCH'><glossterm>TARGET_AS_ARCH</glossterm> | ||
8797 | <glossdef> | ||
8798 | <para> | ||
8799 | Specifies architecture-specific assembler flags for the | ||
8800 | target system. | ||
8801 | <filename>TARGET_AS_ARCH</filename> is initialized from | ||
8802 | <link linkend='var-TUNE_ASARGS'><filename>TUNE_ASARGS</filename></link> | ||
8803 | by default in the BitBake configuration file | ||
8804 | (<filename>meta/conf/bitbake.conf</filename>): | ||
8805 | <literallayout class='monospaced'> | ||
8806 | TARGET_AS_ARCH = "${TUNE_ASARGS}" | ||
8807 | </literallayout> | ||
8808 | </para> | ||
8809 | </glossdef> | ||
8810 | </glossentry> | ||
8811 | |||
8812 | <glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm> | ||
8813 | <glossdef> | ||
8814 | <para> | ||
8815 | Specifies architecture-specific C compiler flags for the | ||
8816 | target system. | ||
8817 | <filename>TARGET_CC_ARCH</filename> is initialized from | ||
8818 | <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link> | ||
8819 | by default. | ||
8820 | <note> | ||
8821 | It is a common workaround to append | ||
8822 | <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link> | ||
8823 | to <filename>TARGET_CC_ARCH</filename> | ||
8824 | in recipes that build software for the target that | ||
8825 | would not otherwise respect the exported | ||
8826 | <filename>LDFLAGS</filename> variable. | ||
8827 | </note> | ||
8828 | </para> | ||
8829 | </glossdef> | ||
8830 | </glossentry> | ||
8831 | |||
8832 | <glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm> | ||
8833 | <glossdef> | ||
8834 | <para> | ||
8835 | This is a specific kernel compiler flag for a CPU or | ||
8836 | Application Binary Interface (ABI) tune. | ||
8837 | The flag is used rarely and only for cases where a | ||
8838 | userspace | ||
8839 | <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link> | ||
8840 | is not compatible with the kernel compilation. | ||
8841 | The <filename>TARGET_CC_KERNEL_ARCH</filename> variable | ||
8842 | allows the kernel (and associated modules) to use a | ||
8843 | different configuration. | ||
8844 | See the | ||
8845 | <filename>meta/conf/machine/include/arm/feature-arm-thumb.inc</filename> | ||
8846 | file in the | ||
8847 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> | ||
8848 | for an example. | ||
8849 | </para> | ||
8850 | </glossdef> | ||
8851 | </glossentry> | ||
8852 | |||
8853 | <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm> | ||
8854 | <glossdef> | ||
8855 | <para> | ||
8856 | Specifies the flags to pass to the C compiler when building | ||
8857 | for the target. | ||
8858 | When building in the target context, | ||
8859 | <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link> | ||
8860 | is set to the value of this variable by default. | ||
8861 | </para> | ||
8862 | |||
8863 | <para> | ||
8864 | Additionally, the SDK's environment setup script sets | ||
8865 | the | ||
8866 | <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link> | ||
8867 | variable in the environment to the | ||
8868 | <filename>TARGET_CFLAGS</filename> value so that | ||
8869 | executables built using the SDK also have the flags | ||
8870 | applied. | ||
8871 | </para> | ||
8872 | </glossdef> | ||
8873 | </glossentry> | ||
8874 | |||
8875 | <glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm> | ||
8876 | <glossdef> | ||
8877 | <para> | ||
8878 | Specifies the flags to pass to the C pre-processor | ||
8879 | (i.e. to both the C and the C++ compilers) when building | ||
8880 | for the target. | ||
8881 | When building in the target context, | ||
8882 | <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link> | ||
8883 | is set to the value of this variable by default. | ||
8884 | </para> | ||
8885 | |||
8886 | <para> | ||
8887 | Additionally, the SDK's environment setup script sets | ||
8888 | the | ||
8889 | <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link> | ||
8890 | variable in the environment to the | ||
8891 | <filename>TARGET_CPPFLAGS</filename> value so that | ||
8892 | executables built using the SDK also have the flags | ||
8893 | applied. | ||
8894 | </para> | ||
8895 | </glossdef> | ||
8896 | </glossentry> | ||
8897 | |||
8898 | <glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm> | ||
8899 | <glossdef> | ||
8900 | <para> | ||
8901 | Specifies the flags to pass to the C++ compiler when | ||
8902 | building for the target. | ||
8903 | When building in the target context, | ||
8904 | <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link> | ||
8905 | is set to the value of this variable by default. | ||
8906 | </para> | ||
8907 | |||
8908 | <para> | ||
8909 | Additionally, the SDK's environment setup script sets | ||
8910 | the | ||
8911 | <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link> | ||
8912 | variable in the environment to the | ||
8913 | <filename>TARGET_CXXFLAGS</filename> value so that | ||
8914 | executables built using the SDK also have the flags | ||
8915 | applied. | ||
8916 | </para> | ||
8917 | </glossdef> | ||
8918 | </glossentry> | ||
8919 | |||
8920 | <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm> | ||
8921 | <glossdef> | ||
8922 | <para>Specifies the method for handling FPU code. | ||
8923 | For FPU-less targets, which include most ARM CPUs, the variable must be | ||
8924 | set to "soft". | ||
8925 | If not, the kernel emulation gets used, which results in a performance penalty.</para> | ||
8926 | </glossdef> | ||
8927 | </glossentry> | ||
8928 | |||
8929 | <glossentry id='var-TARGET_LD_ARCH'><glossterm>TARGET_LD_ARCH</glossterm> | ||
8930 | <glossdef> | ||
8931 | <para> | ||
8932 | Specifies architecture-specific linker flags for the | ||
8933 | target system. | ||
8934 | <filename>TARGET_LD_ARCH</filename> is initialized from | ||
8935 | <link linkend='var-TUNE_LDARGS'><filename>TUNE_LDARGS</filename></link> | ||
8936 | by default in the BitBake configuration file | ||
8937 | (<filename>meta/conf/bitbake.conf</filename>): | ||
8938 | <literallayout class='monospaced'> | ||
8939 | TARGET_LD_ARCH = "${TUNE_LDARGS}" | ||
8940 | </literallayout> | ||
8941 | </para> | ||
8942 | </glossdef> | ||
8943 | </glossentry> | ||
8944 | |||
8945 | <glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm> | ||
8946 | <glossdef> | ||
8947 | <para> | ||
8948 | Specifies the flags to pass to the linker when building | ||
8949 | for the target. | ||
8950 | When building in the target context, | ||
8951 | <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link> | ||
8952 | is set to the value of this variable by default. | ||
8953 | </para> | ||
8954 | |||
8955 | <para> | ||
8956 | Additionally, the SDK's environment setup script sets | ||
8957 | the | ||
8958 | <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link> | ||
8959 | variable in the environment to the | ||
8960 | <filename>TARGET_LDFLAGS</filename> value so that | ||
8961 | executables built using the SDK also have the flags | ||
8962 | applied. | ||
8963 | </para> | ||
8964 | </glossdef> | ||
8965 | </glossentry> | ||
8966 | |||
8967 | <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm> | ||
8968 | <glossdef> | ||
8969 | <para>Specifies the target's operating system. | ||
8970 | The variable can be set to "linux" for <filename>glibc</filename>-based systems and | ||
8971 | to "linux-uclibc" for <filename>uclibc</filename>. | ||
8972 | For ARM/EABI targets, there are also "linux-gnueabi" and | ||
8973 | "linux-uclibc-gnueabi" values possible.</para> | ||
8974 | </glossdef> | ||
8975 | </glossentry> | ||
8976 | |||
8977 | <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm> | ||
8978 | <glossdef> | ||
8979 | <para> | ||
8980 | Specifies the GNU standard C library (<filename>libc</filename>) | ||
8981 | variant to use during the build process. | ||
8982 | This variable replaces <filename>POKYLIBC</filename>, which is no longer | ||
8983 | supported. | ||
8984 | </para> | ||
8985 | <para> | ||
8986 | You can select "glibc" or "uclibc". | ||
8987 | </para> | ||
8988 | </glossdef> | ||
8989 | </glossentry> | ||
8990 | |||
8991 | <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm> | ||
8992 | <glossdef> | ||
8993 | <para> | ||
8994 | Specifies the toolchain selector. | ||
8995 | <filename>TCMODE</filename> controls the characteristics | ||
8996 | of the generated packages and images by telling the | ||
8997 | OpenEmbedded build system which toolchain profile to use. | ||
8998 | By default, the OpenEmbedded build system builds its own | ||
8999 | internal toolchain. | ||
9000 | The variable's default value is "default", which uses | ||
9001 | that internal toolchain. | ||
9002 | <note> | ||
9003 | If <filename>TCMODE</filename> is set to a value | ||
9004 | other than "default", then it is your responsibility | ||
9005 | to ensure that the toolchain is compatible with the | ||
9006 | default toolchain. | ||
9007 | Using older or newer versions of these components | ||
9008 | might cause build problems. | ||
9009 | See the | ||
9010 | <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink> | ||
9011 | for the specific components with which the toolchain | ||
9012 | must be compatible. | ||
9013 | </note> | ||
9014 | </para> | ||
9015 | |||
9016 | <para> | ||
9017 | With additional layers, it is possible to use a pre-compiled | ||
9018 | external toolchain. | ||
9019 | One example is the Sourcery G++ Toolchain. | ||
9020 | The support for this toolchain resides in the separate | ||
9021 | <filename>meta-sourcery</filename> layer at | ||
9022 | <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>. | ||
9023 | You can use <filename>meta-sourcery</filename> as a | ||
9024 | template for adding support for other external toolchains. | ||
9025 | </para> | ||
9026 | |||
9027 | <para> | ||
9028 | The <filename>TCMODE</filename> variable points the build | ||
9029 | system to a file in | ||
9030 | <filename>conf/distro/include/tcmode-${TCMODE}.inc</filename>. | ||
9031 | Thus, for <filename>meta-sourcery</filename>, | ||
9032 | which has <filename>conf/distro/include/tcmode-external-sourcery.inc</filename>, | ||
9033 | you would set the variable as follows: | ||
9034 | <literallayout class='monospaced'> | ||
9035 | TCMODE ?= "external-sourcery" | ||
9036 | </literallayout> | ||
9037 | </para> | ||
9038 | |||
9039 | <para> | ||
9040 | The variable is similar to | ||
9041 | <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, | ||
9042 | which controls the variant of the GNU standard C library | ||
9043 | (<filename>libc</filename>) used during the build process: | ||
9044 | <filename>glibc</filename> or <filename>uclibc</filename>. | ||
9045 | </para> | ||
9046 | </glossdef> | ||
9047 | </glossentry> | ||
9048 | |||
9049 | <glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm> | ||
9050 | <glossdef> | ||
9051 | <para> | ||
9052 | The location the OpenEmbedded build system uses to export | ||
9053 | tests when the | ||
9054 | <link linkend='var-TEST_EXPORT_ONLY'><filename>TEST_EXPORT_ONLY</filename></link> | ||
9055 | variable is set to "1". | ||
9056 | </para> | ||
9057 | |||
9058 | <para> | ||
9059 | The <filename>TEST_EXPORT_DIR</filename> variable defaults | ||
9060 | to <filename>"${TMPDIR}/testimage/${PN}"</filename>. | ||
9061 | </para> | ||
9062 | </glossdef> | ||
9063 | </glossentry> | ||
9064 | |||
9065 | <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm> | ||
9066 | <glossdef> | ||
9067 | <para> | ||
9068 | Specifies to export the tests only. | ||
9069 | Set this variable to "1" if you do not want to run the | ||
9070 | tests but you want them to be exported in a manner that | ||
9071 | you to run them outside of the build system. | ||
9072 | </para> | ||
9073 | </glossdef> | ||
9074 | </glossentry> | ||
9075 | |||
9076 | <glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm> | ||
9077 | <glossdef> | ||
9078 | <para> | ||
9079 | Automatically runs the series of automated tests for | ||
9080 | images when an image is successfully built. | ||
9081 | </para> | ||
9082 | |||
9083 | <para> | ||
9084 | These tests are written in Python making use of the | ||
9085 | <filename>unittest</filename> module, and the majority of | ||
9086 | them run commands on the target system over | ||
9087 | <filename>ssh</filename>. | ||
9088 | You can set this variable to "1" in your | ||
9089 | <filename>local.conf</filename> file in the | ||
9090 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> | ||
9091 | to have the OpenEmbedded build system automatically run | ||
9092 | these tests after an image successfully builds: | ||
9093 | <literallayout class='monospaced'> | ||
9094 | TEST_IMAGE = "1" | ||
9095 | </literallayout> | ||
9096 | For more information on enabling, running, and writing | ||
9097 | these tests, see the | ||
9098 | "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>" | ||
9099 | section in the Yocto Project Development Manual and the | ||
9100 | "<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>" | ||
9101 | section. | ||
9102 | </para> | ||
9103 | </glossdef> | ||
9104 | </glossentry> | ||
9105 | |||
9106 | <glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm> | ||
9107 | <glossdef> | ||
9108 | <para> | ||
9109 | Holds the SSH log and the boot log for QEMU machines. | ||
9110 | The <filename>TEST_LOG_DIR</filename> variable defaults | ||
9111 | to <filename>"${WORKDIR}/testimage"</filename>. | ||
9112 | <note> | ||
9113 | Actual test results reside in the task log | ||
9114 | (<filename>log.do_testimage</filename>), which is in | ||
9115 | the <filename>${WORKDIR}/temp/</filename> directory. | ||
9116 | </note> | ||
9117 | </para> | ||
9118 | </glossdef> | ||
9119 | </glossentry> | ||
9120 | |||
9121 | <glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm>TEST_POWERCONTROL_CMD</glossterm> | ||
9122 | <glossdef> | ||
9123 | <para> | ||
9124 | For automated hardware testing, specifies the command to | ||
9125 | use to control the power of the target machine under test. | ||
9126 | Typically, this command would point to a script that | ||
9127 | performs the appropriate action (e.g. interacting | ||
9128 | with a web-enabled power strip). | ||
9129 | The specified command should expect to receive as the last | ||
9130 | argument "off", "on" or "cycle" specifying to power off, | ||
9131 | on, or cycle (power off and then power on) the device, | ||
9132 | respectively. | ||
9133 | </para> | ||
9134 | </glossdef> | ||
9135 | </glossentry> | ||
9136 | |||
9137 | <glossentry id='var-TEST_POWERCONTROL_EXTRA_ARGS'><glossterm>TEST_POWERCONTROL_EXTRA_ARGS</glossterm> | ||
9138 | <glossdef> | ||
9139 | <para> | ||
9140 | For automated hardware testing, specifies additional | ||
9141 | arguments to pass through to the command specified in | ||
9142 | <link linkend='var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></link>. | ||
9143 | Setting <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename> | ||
9144 | is optional. | ||
9145 | You can use it if you wish, for example, to separate the | ||
9146 | machine-specific and non-machine-specific parts of the | ||
9147 | arguments. | ||
9148 | </para> | ||
9149 | </glossdef> | ||
9150 | </glossentry> | ||
9151 | |||
9152 | <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm> | ||
9153 | <glossdef> | ||
9154 | <para> | ||
9155 | The time in seconds allowed for an image to boot before | ||
9156 | automated runtime tests begin to run against an | ||
9157 | image. | ||
9158 | The default timeout period to allow the boot process to | ||
9159 | reach the login prompt is 500 seconds. | ||
9160 | You can specify a different value in the | ||
9161 | <filename>local.conf</filename> file. | ||
9162 | </para> | ||
9163 | |||
9164 | <para> | ||
9165 | For more information on testing images, see the | ||
9166 | "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>" | ||
9167 | section in the Yocto Project Development Manual. | ||
9168 | </para> | ||
9169 | </glossdef> | ||
9170 | </glossentry> | ||
9171 | |||
9172 | <glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm>TEST_SERIALCONTROL_CMD</glossterm> | ||
9173 | <glossdef> | ||
9174 | <para> | ||
9175 | For automated hardware testing, specifies the command | ||
9176 | to use to connect to the serial console of the target | ||
9177 | machine under test. | ||
9178 | This command simply needs to connect to the serial console | ||
9179 | and forward that connection to standard input and output | ||
9180 | as any normal terminal program does. | ||
9181 | </para> | ||
9182 | |||
9183 | <para> | ||
9184 | For example, to use the Picocom terminal program on | ||
9185 | serial device <filename>/dev/ttyUSB0</filename> at | ||
9186 | 115200bps, you would set the variable as follows: | ||
9187 | <literallayout class='monospaced'> | ||
9188 | TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" | ||
9189 | </literallayout> | ||
9190 | </para> | ||
9191 | </glossdef> | ||
9192 | </glossentry> | ||
9193 | |||
9194 | <glossentry id='var-TEST_SERIALCONTROL_EXTRA_ARGS'><glossterm>TEST_SERIALCONTROL_EXTRA_ARGS</glossterm> | ||
9195 | <glossdef> | ||
9196 | <para> | ||
9197 | For automated hardware testing, specifies additional | ||
9198 | arguments to pass through to the command specified in | ||
9199 | <link linkend='var-TEST_SERIALCONTROL_CMD'><filename>TEST_SERIALCONTROL_CMD</filename></link>. | ||
9200 | Setting <filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename> | ||
9201 | is optional. | ||
9202 | You can use it if you wish, for example, to separate the | ||
9203 | machine-specific and non-machine-specific parts of the | ||
9204 | command. | ||
9205 | </para> | ||
9206 | </glossdef> | ||
9207 | </glossentry> | ||
9208 | |||
9209 | <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm> | ||
9210 | <glossdef> | ||
9211 | <para> | ||
9212 | The IP address of the build machine (host machine). | ||
9213 | This IP address is usually automatically detected. | ||
9214 | However, if detection fails, this variable needs to be set | ||
9215 | to the IP address of the build machine (i.e. where | ||
9216 | the build is taking place). | ||
9217 | <note> | ||
9218 | The <filename>TEST_SERVER_IP</filename> variable | ||
9219 | is only used for a small number of tests such as | ||
9220 | the "smart" test suite, which needs to download | ||
9221 | packages from <filename>DEPLOY_DIR/rpm</filename>. | ||
9222 | </note> | ||
9223 | </para> | ||
9224 | </glossdef> | ||
9225 | </glossentry> | ||
9226 | |||
9227 | <glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm> | ||
9228 | <glossdef> | ||
9229 | <para> | ||
9230 | Specifies the target controller to use when running tests | ||
9231 | against a test image. | ||
9232 | The default controller to use is "qemu": | ||
9233 | <literallayout class='monospaced'> | ||
9234 | TEST_TARGET = "qemu" | ||
9235 | </literallayout> | ||
9236 | A target controller is a class that defines how an | ||
9237 | image gets deployed on a target and how a target is started. | ||
9238 | A layer can extend the controllers by adding a module | ||
9239 | in the layer's <filename>/lib/oeqa/controllers</filename> | ||
9240 | directory and by inheriting the | ||
9241 | <filename>BaseTarget</filename> class, which is an abstract | ||
9242 | class that cannot be used as a value of | ||
9243 | <filename>TEST_TARGET</filename>. | ||
9244 | </para> | ||
9245 | |||
9246 | <para> | ||
9247 | You can provide the following arguments with | ||
9248 | <filename>TEST_TARGET</filename>: | ||
9249 | <itemizedlist> | ||
9250 | <listitem><para><emphasis>"qemu" and "QemuTarget":</emphasis> | ||
9251 | Boots a QEMU image and runs the tests. | ||
9252 | See the | ||
9253 | "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>" | ||
9254 | section in the Yocto Project Development Manual for | ||
9255 | more information. | ||
9256 | </para></listitem> | ||
9257 | <listitem><para><emphasis>"simpleremote" and "SimpleRemoteTarget":</emphasis> | ||
9258 | Runs the tests on target hardware that is already | ||
9259 | up and running. | ||
9260 | The hardware can be on the network or it can be | ||
9261 | a device running an image on QEMU. | ||
9262 | You must also set | ||
9263 | <link linkend='var-TEST_TARGET_IP'><filename>TEST_TARGET_IP</filename></link> | ||
9264 | when you use "simpleremote" or "SimpleRemoteTarget". | ||
9265 | <note> | ||
9266 | This argument is defined in | ||
9267 | <filename>meta/lib/oeqa/targetcontrol.py</filename>. | ||
9268 | The small caps names are kept for compatibility | ||
9269 | reasons. | ||
9270 | </note> | ||
9271 | </para></listitem> | ||
9272 | <listitem><para><emphasis>"GummibootTarget":</emphasis> | ||
9273 | Automatically deploys and runs tests on an | ||
9274 | EFI-enabled machine that has a master image | ||
9275 | installed. | ||
9276 | <note> | ||
9277 | This argument is defined in | ||
9278 | <filename>meta/lib/oeqa/controllers/masterimage.py</filename>. | ||
9279 | </note> | ||
9280 | </para></listitem> | ||
9281 | </itemizedlist> | ||
9282 | </para> | ||
9283 | |||
9284 | <para> | ||
9285 | For information on running tests on hardware, see the | ||
9286 | "<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>" | ||
9287 | section in the Yocto Project Development Manual. | ||
9288 | </para> | ||
9289 | </glossdef> | ||
9290 | </glossentry> | ||
9291 | |||
9292 | <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm> | ||
9293 | <glossdef> | ||
9294 | <para> | ||
9295 | The IP address of your hardware under test. | ||
9296 | The <filename>TEST_TARGET_IP</filename> variable has no | ||
9297 | effect when | ||
9298 | <link linkend='var-TEST_TARGET'><filename>TEST_TARGET</filename></link> | ||
9299 | is set to "qemu". | ||
9300 | </para> | ||
9301 | |||
9302 | <para> | ||
9303 | When you specify the IP address, you can also include a | ||
9304 | port. | ||
9305 | Here is an example: | ||
9306 | <literallayout class='monospaced'> | ||
9307 | TEST_TARGET_IP = "192.168.1.4:2201" | ||
9308 | </literallayout> | ||
9309 | Specifying a port is useful when SSH is started on a | ||
9310 | non-standard port or in cases when your hardware under test | ||
9311 | is behind a firewall or network that is not directly | ||
9312 | accessible from your host and you need to do port address | ||
9313 | translation. | ||
9314 | </para> | ||
9315 | </glossdef> | ||
9316 | </glossentry> | ||
9317 | |||
9318 | <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm> | ||
9319 | <glossdef> | ||
9320 | <para> | ||
9321 | An ordered list of tests (modules) to run against | ||
9322 | an image when performing automated runtime testing. | ||
9323 | </para> | ||
9324 | |||
9325 | <para> | ||
9326 | The OpenEmbedded build system provides a core set of tests | ||
9327 | that can be used against images. | ||
9328 | <note> | ||
9329 | Currently, there is only support for running these tests | ||
9330 | under QEMU. | ||
9331 | </note> | ||
9332 | Tests include <filename>ping</filename>, | ||
9333 | <filename>ssh</filename>, <filename>df</filename> among | ||
9334 | others. | ||
9335 | You can add your own tests to the list of tests by | ||
9336 | appending <filename>TEST_SUITES</filename> as follows: | ||
9337 | <literallayout class='monospaced'> | ||
9338 | TEST_SUITES_append = " <replaceable>mytest</replaceable>" | ||
9339 | </literallayout> | ||
9340 | Alternatively, you can provide the "auto" option to | ||
9341 | have all applicable tests run against the image. | ||
9342 | <literallayout class='monospaced'> | ||
9343 | TEST_SUITES_append = " auto" | ||
9344 | </literallayout> | ||
9345 | Using this option causes the build system to automatically | ||
9346 | run tests that are applicable to the image. | ||
9347 | Tests that are not applicable are skipped. | ||
9348 | </para> | ||
9349 | |||
9350 | <para> | ||
9351 | The order in which tests are run is important. | ||
9352 | Tests that depend on another test must appear later in the | ||
9353 | list than the test on which they depend. | ||
9354 | For example, if you append the list of tests with two | ||
9355 | tests (<filename>test_A</filename> and | ||
9356 | <filename>test_B</filename>) where | ||
9357 | <filename>test_B</filename> is dependent on | ||
9358 | <filename>test_A</filename>, then you must order the tests | ||
9359 | as follows: | ||
9360 | <literallayout class='monospaced'> | ||
9361 | TEST_SUITES = " test_A test_B" | ||
9362 | </literallayout> | ||
9363 | </para> | ||
9364 | |||
9365 | <para> | ||
9366 | For more information on testing images, see the | ||
9367 | "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>" | ||
9368 | section in the Yocto Project Development Manual. | ||
9369 | </para> | ||
9370 | </glossdef> | ||
9371 | </glossentry> | ||
9372 | |||
9373 | <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm> | ||
9374 | <glossdef> | ||
9375 | <para> | ||
9376 | The directory in which the file BitBake is currently | ||
9377 | parsing is located. | ||
9378 | Do not manually set this variable. | ||
9379 | </para> | ||
9380 | </glossdef> | ||
9381 | </glossentry> | ||
9382 | |||
9383 | <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm> | ||
9384 | <glossdef> | ||
9385 | <para> | ||
9386 | This variable is the base directory the OpenEmbedded | ||
9387 | build system uses for all build output and intermediate | ||
9388 | files (other than the shared state cache). | ||
9389 | By default, the <filename>TMPDIR</filename> variable points | ||
9390 | to <filename>tmp</filename> within the | ||
9391 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
9392 | </para> | ||
9393 | |||
9394 | <para> | ||
9395 | If you want to establish this directory in a location other | ||
9396 | than the default, you can uncomment and edit the following | ||
9397 | statement in the | ||
9398 | <filename>conf/local.conf</filename> file in the | ||
9399 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: | ||
9400 | <literallayout class='monospaced'> | ||
9401 | #TMPDIR = "${TOPDIR}/tmp" | ||
9402 | </literallayout> | ||
9403 | An example use for this scenario is to set | ||
9404 | <filename>TMPDIR</filename> to a local disk, which does | ||
9405 | not use NFS, while having the Build Directory use NFS. | ||
9406 | </para> | ||
9407 | |||
9408 | <para> | ||
9409 | The filesystem used by <filename>TMPDIR</filename> must | ||
9410 | have standard filesystem semantics (i.e. mixed-case files | ||
9411 | are unique, POSIX file locking, and persistent inodes). | ||
9412 | Due to various issues with NFS and bugs in some | ||
9413 | implementations, NFS does not meet this minimum | ||
9414 | requirement. | ||
9415 | Consequently, <filename>TMPDIR</filename> cannot be on | ||
9416 | NFS. | ||
9417 | </para> | ||
9418 | </glossdef> | ||
9419 | </glossentry> | ||
9420 | |||
9421 | <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm> | ||
9422 | <glossdef> | ||
9423 | <para> | ||
9424 | This variable lists packages the OpenEmbedded build system | ||
9425 | uses when building an SDK, which contains a | ||
9426 | cross-development environment. | ||
9427 | The packages specified by this variable are part of the | ||
9428 | toolchain set that runs on the | ||
9429 | <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>, | ||
9430 | and each package should usually have the prefix | ||
9431 | "nativesdk-". | ||
9432 | When building an SDK using | ||
9433 | <filename>bitbake -c populate_sdk <imagename></filename>, | ||
9434 | a default list of packages is set in this variable, but | ||
9435 | you can add additional packages to the list. | ||
9436 | </para> | ||
9437 | |||
9438 | <para> | ||
9439 | For background information on cross-development toolchains | ||
9440 | in the Yocto Project development environment, see the | ||
9441 | "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" | ||
9442 | section. | ||
9443 | For information on setting up a cross-development | ||
9444 | environment, see the | ||
9445 | "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>" | ||
9446 | section in the Yocto Project Application Developer's Guide. | ||
9447 | </para> | ||
9448 | </glossdef> | ||
9449 | </glossentry> | ||
9450 | |||
9451 | <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm> | ||
9452 | <glossdef> | ||
9453 | <para> | ||
9454 | This variable lists packages the OpenEmbedded build system | ||
9455 | uses when it creates the target part of an SDK | ||
9456 | (i.e. the part built for the target hardware), which | ||
9457 | includes libraries and headers. | ||
9458 | </para> | ||
9459 | |||
9460 | <para> | ||
9461 | For background information on cross-development toolchains | ||
9462 | in the Yocto Project development environment, see the | ||
9463 | "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" | ||
9464 | section. | ||
9465 | For information on setting up a cross-development | ||
9466 | environment, see the | ||
9467 | "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>" | ||
9468 | section in the Yocto Project Application Developer's Guide. | ||
9469 | </para> | ||
9470 | </glossdef> | ||
9471 | </glossentry> | ||
9472 | |||
9473 | <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm> | ||
9474 | <glossdef> | ||
9475 | <para> | ||
9476 | The top-level | ||
9477 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | ||
9478 | BitBake automatically sets this variable when you | ||
9479 | initialize your build environment using either | ||
9480 | <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link> | ||
9481 | or | ||
9482 | <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>. | ||
9483 | </para> | ||
9484 | </glossdef> | ||
9485 | </glossentry> | ||
9486 | |||
9487 | <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm> | ||
9488 | <glossdef> | ||
9489 | <para> | ||
9490 | A sanitized version of | ||
9491 | <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>. | ||
9492 | This variable is used where the architecture is needed in | ||
9493 | a value where underscores are not allowed, for example | ||
9494 | within package filenames. | ||
9495 | In this case, dash characters replace any underscore | ||
9496 | characters used in TARGET_ARCH. | ||
9497 | </para> | ||
9498 | |||
9499 | <para> | ||
9500 | Do not edit this variable. | ||
9501 | </para> | ||
9502 | </glossdef> | ||
9503 | </glossentry> | ||
9504 | |||
9505 | <glossentry id='var-TUNE_ARCH'><glossterm>TUNE_ARCH</glossterm> | ||
9506 | <glossdef> | ||
9507 | <para> | ||
9508 | The GNU canonical architecture for a specific architecture | ||
9509 | (i.e. <filename>arm</filename>, | ||
9510 | <filename>armeb</filename>, | ||
9511 | <filename>mips</filename>, | ||
9512 | <filename>mips64</filename>, and so forth). | ||
9513 | BitBake uses this value to setup configuration. | ||
9514 | </para> | ||
9515 | |||
9516 | <para> | ||
9517 | <filename>TUNE_ARCH</filename> definitions are specific to | ||
9518 | a given architecture. | ||
9519 | The definitions can be a single static definition, or | ||
9520 | can be dynamically adjusted. | ||
9521 | You can see details for a given CPU family by looking at | ||
9522 | the architecture's <filename>README</filename> file. | ||
9523 | For example, the | ||
9524 | <filename>meta/conf/machine/include/mips/README</filename> | ||
9525 | file in the | ||
9526 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> | ||
9527 | provides information for <filename>TUNE_ARCH</filename> | ||
9528 | specific to the <filename>mips</filename> architecture. | ||
9529 | </para> | ||
9530 | |||
9531 | <para> | ||
9532 | <filename>TUNE_ARCH</filename> is tied closely to | ||
9533 | <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>, | ||
9534 | which defines the target machine's architecture. | ||
9535 | The BitBake configuration file | ||
9536 | (<filename>meta/conf/bitbake.conf</filename>) sets | ||
9537 | <filename>TARGET_ARCH</filename> as follows: | ||
9538 | <literallayout class='monospaced'> | ||
9539 | TARGET_ARCH = "${TUNE_ARCH}" | ||
9540 | </literallayout> | ||
9541 | </para> | ||
9542 | |||
9543 | <para> | ||
9544 | The following list, which is by no means complete since | ||
9545 | architectures are configurable, shows supported machine | ||
9546 | architectures: | ||
9547 | <literallayout class='monospaced'> | ||
9548 | arm | ||
9549 | i586 | ||
9550 | x86_64 | ||
9551 | powerpc | ||
9552 | powerpc64 | ||
9553 | mips | ||
9554 | mipsel | ||
9555 | </literallayout> | ||
9556 | </para> | ||
9557 | </glossdef> | ||
9558 | </glossentry> | ||
9559 | |||
9560 | <glossentry id='var-TUNE_ASARGS'><glossterm>TUNE_ASARGS</glossterm> | ||
9561 | <glossdef> | ||
9562 | <para> | ||
9563 | Specifies architecture-specific assembler flags for | ||
9564 | the target system. | ||
9565 | The set of flags is based on the selected tune features. | ||
9566 | <filename>TUNE_ASARGS</filename> is set using | ||
9567 | the tune include files, which are typically under | ||
9568 | <filename>meta/conf/machine/include/</filename> and are | ||
9569 | influenced through <filename>TUNE_FEATURES</filename>. | ||
9570 | For example, the | ||
9571 | <filename>meta/conf/machine/include/x86/arch-x86.inc</filename> | ||
9572 | file defines the flags for the x86 architecture as follows: | ||
9573 | <literallayout class='monospaced'> | ||
9574 | TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" | ||
9575 | </literallayout> | ||
9576 | <note> | ||
9577 | Board Support Packages (BSPs) can supply their own | ||
9578 | set of flags. | ||
9579 | </note> | ||
9580 | </para> | ||
9581 | </glossdef> | ||
9582 | </glossentry> | ||
9583 | |||
9584 | <glossentry id='var-TUNE_CCARGS'><glossterm>TUNE_CCARGS</glossterm> | ||
9585 | <glossdef> | ||
9586 | <para> | ||
9587 | Specifies architecture-specific C compiler flags for | ||
9588 | the target system. | ||
9589 | The set of flags is based on the selected tune features. | ||
9590 | <filename>TUNE_CCARGS</filename> is set using | ||
9591 | the tune include files, which are typically under | ||
9592 | <filename>meta/conf/machine/include/</filename> and are | ||
9593 | influenced through <filename>TUNE_FEATURES</filename>. | ||
9594 | <note> | ||
9595 | Board Support Packages (BSPs) can supply their own | ||
9596 | set of flags. | ||
9597 | </note> | ||
9598 | </para> | ||
9599 | </glossdef> | ||
9600 | </glossentry> | ||
9601 | |||
9602 | <glossentry id='var-TUNE_LDARGS'><glossterm>TUNE_LDARGS</glossterm> | ||
9603 | <glossdef> | ||
9604 | <para> | ||
9605 | Specifies architecture-specific linker flags for | ||
9606 | the target system. | ||
9607 | The set of flags is based on the selected tune features. | ||
9608 | <filename>TUNE_LDARGS</filename> is set using | ||
9609 | the tune include files, which are typically under | ||
9610 | <filename>meta/conf/machine/include/</filename> and are | ||
9611 | influenced through <filename>TUNE_FEATURES</filename>. | ||
9612 | For example, the | ||
9613 | <filename>meta/conf/machine/include/x86/arch-x86.inc</filename> | ||
9614 | file defines the flags for the x86 architecture as follows: | ||
9615 | <literallayout class='monospaced'> | ||
9616 | TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}" | ||
9617 | </literallayout> | ||
9618 | <note> | ||
9619 | Board Support Packages (BSPs) can supply their own | ||
9620 | set of flags. | ||
9621 | </note> | ||
9622 | </para> | ||
9623 | </glossdef> | ||
9624 | </glossentry> | ||
9625 | |||
9626 | <glossentry id='var-TUNE_FEATURES'><glossterm>TUNE_FEATURES</glossterm> | ||
9627 | <glossdef> | ||
9628 | <para> | ||
9629 | Features used to "tune" a compiler for optimal use | ||
9630 | given a specific processor. | ||
9631 | The features are defined within the tune files and allow | ||
9632 | arguments (i.e. <filename>TUNE_*ARGS</filename>) to be | ||
9633 | dynamically generated based on the features. | ||
9634 | </para> | ||
9635 | |||
9636 | <para> | ||
9637 | The OpenEmbedded build system verifies the features | ||
9638 | to be sure they are not conflicting and that they are | ||
9639 | supported. | ||
9640 | </para> | ||
9641 | |||
9642 | <para> | ||
9643 | The BitBake configuration file | ||
9644 | (<filename>meta/conf/bitbake.conf</filename>) defines | ||
9645 | <filename>TUNE_FEATURES</filename> as follows: | ||
9646 | <literallayout class='monospaced'> | ||
9647 | TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}" | ||
9648 | </literallayout> | ||
9649 | See the | ||
9650 | <link linkend='var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></link> | ||
9651 | variable for more information. | ||
9652 | </para> | ||
9653 | </glossdef> | ||
9654 | </glossentry> | ||
9655 | |||
9656 | <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm> | ||
9657 | <glossdef> | ||
9658 | <para> | ||
9659 | The package architecture understood by the packaging | ||
9660 | system to define the architecture, ABI, and tuning of | ||
9661 | output packages. | ||
9662 | </para> | ||
9663 | </glossdef> | ||
9664 | </glossentry> | ||
9665 | |||
9666 | <glossentry id='var-TUNE_PKGARCH_tune'><glossterm>TUNE_PKGARCH_tune</glossterm> | ||
9667 | <glossdef> | ||
9668 | <para> | ||
9669 | The CPU or Application Binary Interface (ABI) specific | ||
9670 | tuning of the | ||
9671 | <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>. | ||
9672 | </para> | ||
9673 | |||
9674 | <para> | ||
9675 | These tune-specific package architectures are defined in | ||
9676 | the machine include files. | ||
9677 | Here is an example of the "core2-32" tuning as used | ||
9678 | in the | ||
9679 | <filename>meta/conf/machine/include/tune-core2.inc</filename> | ||
9680 | file: | ||
9681 | <literallayout class='monospaced'> | ||
9682 | TUNE_PKGARCH_tune-core2-32 = "core2-32" | ||
9683 | </literallayout> | ||
9684 | </para> | ||
9685 | </glossdef> | ||
9686 | </glossentry> | ||
9687 | |||
9688 | <glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm> | ||
9689 | <glossdef> | ||
9690 | <para> | ||
9691 | An underlying Application Binary Interface (ABI) used by | ||
9692 | a particular tuning in a given toolchain layer. | ||
9693 | Providers that use prebuilt libraries can use the | ||
9694 | <filename>TUNEABI</filename>, | ||
9695 | <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>, | ||
9696 | and | ||
9697 | <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link> | ||
9698 | variables to check compatibility of tunings against their | ||
9699 | selection of libraries. | ||
9700 | </para> | ||
9701 | |||
9702 | <para> | ||
9703 | If <filename>TUNEABI</filename> is undefined, then every | ||
9704 | tuning is allowed. | ||
9705 | See the | ||
9706 | <link linkend='ref-classes-sanity'><filename>sanity</filename></link> | ||
9707 | class to see how the variable is used. | ||
9708 | </para> | ||
9709 | </glossdef> | ||
9710 | </glossentry> | ||
9711 | |||
9712 | <glossentry id='var-TUNEABI_OVERRIDE'><glossterm>TUNEABI_OVERRIDE</glossterm> | ||
9713 | <glossdef> | ||
9714 | <para> | ||
9715 | If set, the OpenEmbedded system ignores the | ||
9716 | <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link> | ||
9717 | variable. | ||
9718 | Providers that use prebuilt libraries can use the | ||
9719 | <filename>TUNEABI_OVERRIDE</filename>, | ||
9720 | <filename>TUNEABI_WHITELIST</filename>, | ||
9721 | and | ||
9722 | <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link> | ||
9723 | variables to check compatibility of a tuning against their | ||
9724 | selection of libraries. | ||
9725 | </para> | ||
9726 | |||
9727 | <para> | ||
9728 | See the | ||
9729 | <link linkend='ref-classes-sanity'><filename>sanity</filename></link> | ||
9730 | class to see how the variable is used. | ||
9731 | </para> | ||
9732 | </glossdef> | ||
9733 | </glossentry> | ||
9734 | |||
9735 | <glossentry id='var-TUNEABI_WHITELIST'><glossterm>TUNEABI_WHITELIST</glossterm> | ||
9736 | <glossdef> | ||
9737 | <para> | ||
9738 | A whitelist of permissible | ||
9739 | <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link> | ||
9740 | values. | ||
9741 | If <filename>TUNEABI_WHITELIST</filename> is not set, | ||
9742 | all tunes are allowed. | ||
9743 | Providers that use prebuilt libraries can use the | ||
9744 | <filename>TUNEABI_WHITELIST</filename>, | ||
9745 | <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>, | ||
9746 | and <filename>TUNEABI</filename> variables to check | ||
9747 | compatibility of a tuning against their selection of | ||
9748 | libraries. | ||
9749 | </para> | ||
9750 | |||
9751 | <para> | ||
9752 | See the | ||
9753 | <link linkend='ref-classes-sanity'><filename>sanity</filename></link> | ||
9754 | class to see how the variable is used. | ||
9755 | </para> | ||
9756 | </glossdef> | ||
9757 | </glossentry> | ||
9758 | |||
9759 | <glossentry id='var-TUNECONFLICT'><glossterm>TUNECONFLICT[<replaceable>feature</replaceable>]</glossterm> | ||
9760 | <glossdef> | ||
9761 | <para> | ||
9762 | Specifies CPU or Application Binary Interface (ABI) | ||
9763 | tuning features that conflict with <replaceable>feature</replaceable>. | ||
9764 | </para> | ||
9765 | |||
9766 | <para> | ||
9767 | Known tuning conflicts are specified in the machine include | ||
9768 | files in the | ||
9769 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | ||
9770 | Here is an example from the | ||
9771 | <filename>meta/conf/machine/include/mips/arch-mips.inc</filename> | ||
9772 | include file that lists the "o32" and "n64" features as | ||
9773 | conflicting with the "n32" feature: | ||
9774 | <literallayout class='monospaced'> | ||
9775 | TUNECONFLICTS[n32] = "o32 n64" | ||
9776 | </literallayout> | ||
9777 | </para> | ||
9778 | </glossdef> | ||
9779 | </glossentry> | ||
9780 | |||
9781 | <glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[<replaceable>feature</replaceable>]</glossterm> | ||
9782 | <glossdef> | ||
9783 | <para> | ||
9784 | Specifies a valid CPU or Application Binary Interface (ABI) | ||
9785 | tuning feature. | ||
9786 | The specified feature is stored as a flag. | ||
9787 | Valid features are specified in the machine include files | ||
9788 | (e.g. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>). | ||
9789 | Here is an example from that file: | ||
9790 | <literallayout class='monospaced'> | ||
9791 | TUNEVALID[bigendian] = "Enable big-endian mode." | ||
9792 | </literallayout> | ||
9793 | See the machine include files in the | ||
9794 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> | ||
9795 | for these features. | ||
9796 | </para> | ||
9797 | </glossdef> | ||
9798 | </glossentry> | ||
9799 | |||
9800 | </glossdiv> | ||
9801 | |||
9802 | <glossdiv id='var-glossary-u'><title>U</title> | ||
9803 | |||
9804 | <glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm> | ||
9805 | <glossdef> | ||
9806 | <para> | ||
9807 | Configures the | ||
9808 | <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link> | ||
9809 | and can also define | ||
9810 | <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> | ||
9811 | for individual cases. | ||
9812 | </para> | ||
9813 | |||
9814 | <para> | ||
9815 | Following is an example from the | ||
9816 | <filename>meta-fsl-arm</filename> layer. | ||
9817 | <literallayout class='monospaced'> | ||
9818 | UBOOT_CONFIG ??= "sd" | ||
9819 | UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard" | ||
9820 | UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config" | ||
9821 | UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs" | ||
9822 | UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config" | ||
9823 | </literallayout> | ||
9824 | In this example, "sd" is selected as the configuration | ||
9825 | of the possible four for the | ||
9826 | <filename>UBOOT_MACHINE</filename>. | ||
9827 | The "sd" configuration defines "mx6qsabreauto_config" | ||
9828 | as the value for <filename>UBOOT_MACHINE</filename>, while | ||
9829 | the "sdcard" specifies the | ||
9830 | <filename>IMAGE_FSTYPES</filename> to use for the U-boot | ||
9831 | image. | ||
9832 | </para> | ||
9833 | |||
9834 | <para> | ||
9835 | For more information on how the | ||
9836 | <filename>UBOOT_CONFIG</filename> is handled, see the | ||
9837 | <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass'><filename>uboot-config</filename></ulink> | ||
9838 | class. | ||
9839 | </para> | ||
9840 | </glossdef> | ||
9841 | </glossentry> | ||
9842 | |||
9843 | <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm> | ||
9844 | <glossdef> | ||
9845 | <para> | ||
9846 | Specifies the entry point for the U-Boot image. | ||
9847 | During U-Boot image creation, the | ||
9848 | <filename>UBOOT_ENTRYPOINT</filename> variable is passed | ||
9849 | as a command-line parameter to the | ||
9850 | <filename>uboot-mkimage</filename> utility. | ||
9851 | </para> | ||
9852 | </glossdef> | ||
9853 | </glossentry> | ||
9854 | |||
9855 | <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm> | ||
9856 | <glossdef> | ||
9857 | <para> | ||
9858 | Specifies the load address for the U-Boot image. | ||
9859 | During U-Boot image creation, the | ||
9860 | <filename>UBOOT_LOADADDRESS</filename> variable is passed | ||
9861 | as a command-line parameter to the | ||
9862 | <filename>uboot-mkimage</filename> utility. | ||
9863 | </para> | ||
9864 | </glossdef> | ||
9865 | </glossentry> | ||
9866 | |||
9867 | <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm> | ||
9868 | <glossdef> | ||
9869 | <para> | ||
9870 | Appends a string to the name of the local version of the | ||
9871 | U-Boot image. | ||
9872 | For example, assuming the version of the U-Boot image | ||
9873 | built was "2013.10, the full version string reported by | ||
9874 | U-Boot would be "2013.10-yocto" given the following | ||
9875 | statement: | ||
9876 | <literallayout class='monospaced'> | ||
9877 | UBOOT_LOCALVERSION = "-yocto" | ||
9878 | </literallayout> | ||
9879 | </para> | ||
9880 | </glossdef> | ||
9881 | </glossentry> | ||
9882 | |||
9883 | <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm> | ||
9884 | <glossdef> | ||
9885 | <para> | ||
9886 | Specifies the value passed on the | ||
9887 | <filename>make</filename> command line when building | ||
9888 | a U-Boot image. | ||
9889 | The value indicates the target platform configuration. | ||
9890 | You typically set this variable from the machine | ||
9891 | configuration file (i.e. | ||
9892 | <filename>conf/machine/<replaceable>machine_name</replaceable>.conf</filename>). | ||
9893 | </para> | ||
9894 | |||
9895 | <para> | ||
9896 | Please see the "Selection of Processor Architecture and | ||
9897 | Board Type" section in the U-Boot README for valid values | ||
9898 | for this variable. | ||
9899 | </para> | ||
9900 | </glossdef> | ||
9901 | </glossentry> | ||
9902 | |||
9903 | <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm> | ||
9904 | <glossdef> | ||
9905 | <para> | ||
9906 | Specifies the target called in the | ||
9907 | <filename>Makefile</filename>. | ||
9908 | The default target is "all". | ||
9909 | </para> | ||
9910 | </glossdef> | ||
9911 | </glossentry> | ||
9912 | |||
9913 | <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm> | ||
9914 | <glossdef> | ||
9915 | <para> | ||
9916 | Points to the generated U-Boot extension. | ||
9917 | For example, <filename>u-boot.sb</filename> has a | ||
9918 | <filename>.sb</filename> extension. | ||
9919 | </para> | ||
9920 | |||
9921 | <para> | ||
9922 | The default U-Boot extension is | ||
9923 | <filename>.bin</filename> | ||
9924 | </para> | ||
9925 | </glossdef> | ||
9926 | </glossentry> | ||
9927 | |||
9928 | <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm> | ||
9929 | <glossdef> | ||
9930 | <para> | ||
9931 | Specifies the target used for building U-Boot. | ||
9932 | The target is passed directly as part of the "make" command | ||
9933 | (e.g. SPL and AIS). | ||
9934 | If you do not specifically set this variable, the | ||
9935 | OpenEmbedded build process passes and uses "all" for the | ||
9936 | target during the U-Boot building process. | ||
9937 | </para> | ||
9938 | </glossdef> | ||
9939 | </glossentry> | ||
9940 | |||
9941 | <glossentry id='var-USE_VT'><glossterm>USE_VT</glossterm> | ||
9942 | <glossdef> | ||
9943 | <para> | ||
9944 | When using | ||
9945 | <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>, | ||
9946 | determines whether or not to run a | ||
9947 | <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink> | ||
9948 | on any virtual terminals in order to enable logging in | ||
9949 | through those terminals. | ||
9950 | </para> | ||
9951 | |||
9952 | <para> | ||
9953 | The default value used for <filename>USE_VT</filename> | ||
9954 | is "1" when no default value is specifically set. | ||
9955 | Typically, you would set <filename>USE_VT</filename> | ||
9956 | to "0" in the machine configuration file for machines | ||
9957 | that do not have a graphical display attached and | ||
9958 | therefore do not need virtual terminal functionality. | ||
9959 | </para> | ||
9960 | </glossdef> | ||
9961 | </glossentry> | ||
9962 | |||
9963 | <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm> | ||
9964 | <glossdef> | ||
9965 | <para> | ||
9966 | A list of classes to globally inherit. | ||
9967 | These classes are used by the OpenEmbedded build system | ||
9968 | to enable extra features (e.g. | ||
9969 | <filename>buildstats</filename>, | ||
9970 | <filename>image-mklibs</filename>, and so forth). | ||
9971 | </para> | ||
9972 | |||
9973 | <para> | ||
9974 | The default list is set in your | ||
9975 | <filename>local.conf</filename> file: | ||
9976 | <literallayout class='monospaced'> | ||
9977 | USER_CLASSES ?= "buildstats image-mklibs image-prelink" | ||
9978 | </literallayout> | ||
9979 | For more information, see | ||
9980 | <filename>meta-yocto/conf/local.conf.sample</filename> in | ||
9981 | the | ||
9982 | <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. | ||
9983 | </para> | ||
9984 | </glossdef> | ||
9985 | </glossentry> | ||
9986 | |||
9987 | <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm> | ||
9988 | <glossdef> | ||
9989 | <para> | ||
9990 | Forces the OpenEmbedded build system to produce an error | ||
9991 | if the user identification (<filename>uid</filename>) and | ||
9992 | group identification (<filename>gid</filename>) values | ||
9993 | are not defined in <filename>files/passwd</filename> | ||
9994 | and <filename>files/group</filename> files. | ||
9995 | </para> | ||
9996 | |||
9997 | <para> | ||
9998 | The default behavior for the build system is to dynamically | ||
9999 | apply <filename>uid</filename> and | ||
10000 | <filename>gid</filename> values. | ||
10001 | Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename> | ||
10002 | variable is by default not set. | ||
10003 | If you plan on using statically assigned | ||
10004 | <filename>gid</filename> and <filename>uid</filename> | ||
10005 | values, you should set | ||
10006 | the <filename>USERADD_ERROR_DYNAMIC</filename> variable in | ||
10007 | your <filename>local.conf</filename> file as | ||
10008 | follows: | ||
10009 | <literallayout class='monospaced'> | ||
10010 | USERADD_ERROR_DYNAMIC = "1" | ||
10011 | </literallayout> | ||
10012 | Overriding the default behavior implies you are going to | ||
10013 | also take steps to set static <filename>uid</filename> and | ||
10014 | <filename>gid</filename> values through use of the | ||
10015 | <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>, | ||
10016 | <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>, | ||
10017 | and | ||
10018 | <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link> | ||
10019 | variables. | ||
10020 | </para> | ||
10021 | </glossdef> | ||
10022 | </glossentry> | ||
10023 | |||
10024 | <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm> | ||
10025 | <glossdef> | ||
10026 | <para> | ||
10027 | Specifies a password file to use for obtaining static | ||
10028 | group identification (<filename>gid</filename>) values | ||
10029 | when the OpenEmbedded build system adds a group to the | ||
10030 | system during package installation. | ||
10031 | </para> | ||
10032 | |||
10033 | <para> | ||
10034 | When applying static group identification | ||
10035 | (<filename>gid</filename>) values, the OpenEmbedded build | ||
10036 | system looks in | ||
10037 | <link linkend='var-BBPATH'><filename>BBPATH</filename></link> | ||
10038 | for a <filename>files/group</filename> file and then applies | ||
10039 | those <filename>uid</filename> values. | ||
10040 | Set the variable as follows in your | ||
10041 | <filename>local.conf</filename> file: | ||
10042 | <literallayout class='monospaced'> | ||
10043 | USERADD_GID_TABLES = "files/group" | ||
10044 | </literallayout> | ||
10045 | </para> | ||
10046 | |||
10047 | <note> | ||
10048 | Setting the | ||
10049 | <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link> | ||
10050 | variable to "useradd-staticids" causes the build system | ||
10051 | to use static <filename>gid</filename> values. | ||
10052 | </note> | ||
10053 | </glossdef> | ||
10054 | </glossentry> | ||
10055 | |||
10056 | <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm> | ||
10057 | <glossdef> | ||
10058 | <para> | ||
10059 | Specifies a password file to use for obtaining static | ||
10060 | user identification (<filename>uid</filename>) values | ||
10061 | when the OpenEmbedded build system adds a user to the | ||
10062 | system during package installation. | ||
10063 | </para> | ||
10064 | |||
10065 | <para> | ||
10066 | When applying static user identification | ||
10067 | (<filename>uid</filename>) values, the OpenEmbedded build | ||
10068 | system looks in | ||
10069 | <link linkend='var-BBPATH'><filename>BBPATH</filename></link> | ||
10070 | for a <filename>files/passwd</filename> file and then applies | ||
10071 | those <filename>uid</filename> values. | ||
10072 | Set the variable as follows in your | ||
10073 | <filename>local.conf</filename> file: | ||
10074 | <literallayout class='monospaced'> | ||
10075 | USERADD_UID_TABLES = "files/passwd" | ||
10076 | </literallayout> | ||
10077 | </para> | ||
10078 | |||
10079 | <note> | ||
10080 | Setting the | ||
10081 | <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link> | ||
10082 | variable to "useradd-staticids" causes the build system | ||
10083 | to use static <filename>uid</filename> values. | ||
10084 | </note> | ||
10085 | </glossdef> | ||
10086 | </glossentry> | ||
10087 | |||
10088 | <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm> | ||
10089 | <glossdef> | ||
10090 | <para> | ||
10091 | When inheriting the | ||
10092 | <link linkend='ref-classes-useradd'><filename>useradd</filename></link> | ||
10093 | class, this variable | ||
10094 | specifies the individual packages within the recipe that | ||
10095 | require users and/or groups to be added. | ||
10096 | </para> | ||
10097 | |||
10098 | <para> | ||
10099 | You must set this variable if the recipe inherits the | ||
10100 | class. | ||
10101 | For example, the following enables adding a user for the | ||
10102 | main package in a recipe: | ||
10103 | <literallayout class='monospaced'> | ||
10104 | USERADD_PACKAGES = "${PN}" | ||
10105 | </literallayout> | ||
10106 | <note> | ||
10107 | If follows that if you are going to use the | ||
10108 | <filename>USERADD_PACKAGES</filename> variable, | ||
10109 | you need to set one or more of the | ||
10110 | <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>, | ||
10111 | <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>, | ||
10112 | or | ||
10113 | <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link> | ||
10114 | variables. | ||
10115 | </note> | ||
10116 | </para> | ||
10117 | |||
10118 | </glossdef> | ||
10119 | </glossentry> | ||
10120 | |||
10121 | <glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm> | ||
10122 | <glossdef> | ||
10123 | <para> | ||
10124 | When inheriting the | ||
10125 | <link linkend='ref-classes-useradd'><filename>useradd</filename></link> | ||
10126 | class, this variable | ||
10127 | specifies for a package what parameters should be passed | ||
10128 | to the <filename>useradd</filename> command | ||
10129 | if you wish to add a user to the system when the package | ||
10130 | is installed. | ||
10131 | </para> | ||
10132 | |||
10133 | <para> | ||
10134 | Here is an example from the <filename>dbus</filename> | ||
10135 | recipe: | ||
10136 | <literallayout class='monospaced'> | ||
10137 | USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \ | ||
10138 | --no-create-home --shell /bin/false \ | ||
10139 | --user-group messagebus" | ||
10140 | </literallayout> | ||
10141 | For information on the standard Linux shell command | ||
10142 | <filename>useradd</filename>, see | ||
10143 | <ulink url='http://linux.die.net/man/8/useradd'></ulink>. | ||
10144 | </para> | ||
10145 | </glossdef> | ||
10146 | </glossentry> | ||
10147 | |||
10148 | <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm> | ||
10149 | <glossdef> | ||
10150 | <para> | ||
10151 | When set to "useradd-staticids", causes the | ||
10152 | OpenEmbedded build system to base all user and group | ||
10153 | additions on a static | ||
10154 | <filename>passwd</filename> and | ||
10155 | <filename>group</filename> files found in | ||
10156 | <link linkend='var-BBPATH'><filename>BBPATH</filename></link>. | ||
10157 | </para> | ||
10158 | |||
10159 | <para> | ||
10160 | To use static user identification (<filename>uid</filename>) | ||
10161 | and group identification (<filename>gid</filename>) | ||
10162 | values, set the variable | ||
10163 | as follows in your <filename>local.conf</filename> file: | ||
10164 | <literallayout class='monospaced'> | ||
10165 | USERADDEXTENSION = "useradd-staticids" | ||
10166 | </literallayout> | ||
10167 | <note> | ||
10168 | Setting this variable to use static | ||
10169 | <filename>uid</filename> and <filename>gid</filename> | ||
10170 | values causes the OpenEmbedded build system to employ | ||
10171 | the | ||
10172 | <link linkend='ref-classes-useradd-staticids'><filename>useradd-staticids</filename></link> | ||
10173 | class. | ||
10174 | </note> | ||
10175 | </para> | ||
10176 | |||
10177 | <para> | ||
10178 | If you use static <filename>uid</filename> and | ||
10179 | <filename>gid</filename> information, you must also | ||
10180 | specify the <filename>files/passwd</filename> and | ||
10181 | <filename>files/group</filename> files by setting the | ||
10182 | <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link> | ||
10183 | and | ||
10184 | <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link> | ||
10185 | variables. | ||
10186 | Additionally, you should also set the | ||
10187 | <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link> | ||
10188 | variable. | ||
10189 | </para> | ||
10190 | </glossdef> | ||
10191 | </glossentry> | ||
10192 | |||
10193 | </glossdiv> | ||
10194 | |||
10195 | <!-- <glossdiv id='var-glossary-v'><title>V</title>--> | ||
10196 | <!-- </glossdiv>--> | ||
10197 | |||
10198 | <glossdiv id='var-glossary-w'><title>W</title> | ||
10199 | |||
10200 | <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm> | ||
10201 | <glossdef> | ||
10202 | <para> | ||
10203 | Specifies the quality assurance checks whose failures are | ||
10204 | reported as warnings by the OpenEmbedded build system. | ||
10205 | You set this variable in your distribution configuration | ||
10206 | file. | ||
10207 | For a list of the checks you can control with this variable, | ||
10208 | see the | ||
10209 | "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>" | ||
10210 | section. | ||
10211 | </para> | ||
10212 | </glossdef> | ||
10213 | </glossentry> | ||
10214 | |||
10215 | <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm> | ||
10216 | <glossdef> | ||
10217 | <para> | ||
10218 | The pathname of the work directory in which the OpenEmbedded | ||
10219 | build system builds a recipe. | ||
10220 | This directory is located within the | ||
10221 | <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> | ||
10222 | directory structure and is specific to the recipe being | ||
10223 | built and the system for which it is being built. | ||
10224 | </para> | ||
10225 | |||
10226 | <para> | ||
10227 | The <filename>WORKDIR</filename> directory is defined as | ||
10228 | follows: | ||
10229 | <literallayout class='monospaced'> | ||
10230 | ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} | ||
10231 | </literallayout> | ||
10232 | The actual directory depends on several things: | ||
10233 | <itemizedlist> | ||
10234 | <listitem><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>: | ||
10235 | The top-level build output directory</listitem> | ||
10236 | <listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>: | ||
10237 | The target system identifier</listitem> | ||
10238 | <listitem><link linkend='var-PN'><filename>PN</filename></link>: | ||
10239 | The recipe name</listitem> | ||
10240 | <listitem><link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>: | ||
10241 | The epoch - (if | ||
10242 | <link linkend='var-PE'><filename>PE</filename></link> | ||
10243 | is not specified, which is usually the case for most | ||
10244 | recipes, then <filename>EXTENDPE</filename> is blank)</listitem> | ||
10245 | <listitem><link linkend='var-PV'><filename>PV</filename></link>: | ||
10246 | The recipe version</listitem> | ||
10247 | <listitem><link linkend='var-PR'><filename>PR</filename></link>: | ||
10248 | The recipe revision</listitem> | ||
10249 | </itemizedlist> | ||
10250 | </para> | ||
10251 | |||
10252 | <para> | ||
10253 | As an example, assume a Source Directory top-level folder | ||
10254 | name <filename>poky</filename>, a default Build Directory at | ||
10255 | <filename>poky/build</filename>, and a | ||
10256 | <filename>qemux86-poky-linux</filename> machine target | ||
10257 | system. | ||
10258 | Furthermore, suppose your recipe is named | ||
10259 | <filename>foo_1.3.0-r0.bb</filename>. | ||
10260 | In this case, the work directory the build system uses to | ||
10261 | build the package would be as follows: | ||
10262 | <literallayout class='monospaced'> | ||
10263 | poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 | ||
10264 | </literallayout> | ||
10265 | </para> | ||
10266 | </glossdef> | ||
10267 | </glossentry> | ||
10268 | |||
10269 | </glossdiv> | ||
10270 | |||
10271 | <!-- <glossdiv id='var-glossary-x'><title>X</title>--> | ||
10272 | <!-- </glossdiv>--> | ||
10273 | |||
10274 | <!-- <glossdiv id='var-glossary-y'><title>Y</title>--> | ||
10275 | <!-- </glossdiv>--> | ||
10276 | |||
10277 | <!-- <glossdiv id='var-glossary-z'><title>Z</title>--> | ||
10278 | <!-- </glossdiv>--> | ||
10279 | |||
10280 | </glossary> | ||
10281 | </chapter> | ||
10282 | <!-- | ||
10283 | vim: expandtab tw=80 ts=4 | ||
10284 | --> | ||