diff options
Diffstat (limited to 'bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml')
-rw-r--r-- | bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml | 2537 |
1 files changed, 0 insertions, 2537 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml deleted file mode 100644 index 4c29b2464f..0000000000 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml +++ /dev/null | |||
@@ -1,2537 +0,0 @@ | |||
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-bb-variables-glos'> | ||
7 | |||
8 | <title>Variables Glossary</title> | ||
9 | |||
10 | <para> | ||
11 | This chapter lists common variables used by BitBake and gives an overview | ||
12 | of their function and contents. | ||
13 | </para> | ||
14 | |||
15 | <note> | ||
16 | Following are some points regarding the variables listed in this glossary: | ||
17 | <itemizedlist> | ||
18 | <listitem><para>The variables listed in this glossary | ||
19 | are specific to BitBake. | ||
20 | Consequently, the descriptions are limited to that context. | ||
21 | </para></listitem> | ||
22 | <listitem><para>Also, variables exist in other systems that use BitBake | ||
23 | (e.g. The Yocto Project and OpenEmbedded) that have names identical | ||
24 | to those found in this glossary. | ||
25 | For such cases, the variables in those systems extend the | ||
26 | functionality of the variable as it is described here in | ||
27 | this glossary. | ||
28 | </para></listitem> | ||
29 | <listitem><para>Finally, there are variables mentioned in this | ||
30 | glossary that do not appear in the BitBake glossary. | ||
31 | These other variables are variables used in systems that use | ||
32 | BitBake. | ||
33 | </para></listitem> | ||
34 | </itemizedlist> | ||
35 | </note> | ||
36 | |||
37 | <glossary id='ref-bb-variables-glossary'> | ||
38 | |||
39 | <para> | ||
40 | <link linkend='var-bb-ASSUME_PROVIDED'>A</link> | ||
41 | <link linkend='var-bb-B'>B</link> | ||
42 | <link linkend='var-bb-CACHE'>C</link> | ||
43 | <link linkend='var-bb-DEFAULT_PREFERENCE'>D</link> | ||
44 | <link linkend='var-bb-EXCLUDE_FROM_WORLD'>E</link> | ||
45 | <link linkend='var-bb-FAKEROOT'>F</link> | ||
46 | <link linkend='var-bb-GITDIR'>G</link> | ||
47 | <link linkend='var-bb-HGDIR'>H</link> | ||
48 | <link linkend='var-bb-INHERIT'>I</link> | ||
49 | <!-- <link linkend='var-glossary-j'>J</link> --> | ||
50 | <!-- <link linkend='var-KARCH'>K</link> --> | ||
51 | <link linkend='var-bb-LAYERDEPENDS'>L</link> | ||
52 | <link linkend='var-bb-MIRRORS'>M</link> | ||
53 | <!-- <link linkend='var-glossary-n'>N</link> --> | ||
54 | <link linkend='var-bb-OVERRIDES'>O</link> | ||
55 | <link linkend='var-bb-P4DIR'>P</link> | ||
56 | <!-- <link linkend='var-QMAKE_PROFILES'>Q</link> --> | ||
57 | <link linkend='var-bb-RDEPENDS'>R</link> | ||
58 | <link linkend='var-bb-SECTION'>S</link> | ||
59 | <link linkend='var-bb-T'>T</link> | ||
60 | <!-- <link linkend='var-UBOOT_CONFIG'>U</link> --> | ||
61 | <!-- <link linkend='var-glossary-v'>V</link> --> | ||
62 | <!-- <link linkend='var-WARN_QA'>W</link> --> | ||
63 | <!-- <link linkend='var-glossary-x'>X</link> --> | ||
64 | <!-- <link linkend='var-glossary-y'>Y</link> --> | ||
65 | <!-- <link linkend='var-glossary-z'>Z</link>--> | ||
66 | </para> | ||
67 | |||
68 | <glossdiv id='var-bb-glossary-a'><title>A</title> | ||
69 | |||
70 | <glossentry id='var-bb-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm> | ||
71 | <glossdef> | ||
72 | <para> | ||
73 | Lists recipe names | ||
74 | (<link linkend='var-bb-PN'><filename>PN</filename></link> | ||
75 | values) BitBake does not attempt to build. | ||
76 | Instead, BitBake assumes these recipes have already been | ||
77 | built. | ||
78 | </para> | ||
79 | |||
80 | <para> | ||
81 | In OpenEmbedded-Core, <filename>ASSUME_PROVIDED</filename> | ||
82 | mostly specifies native tools that should not be built. | ||
83 | An example is <filename>git-native</filename>, which | ||
84 | when specified allows for the Git binary from the host to | ||
85 | be used rather than building | ||
86 | <filename>git-native</filename>. | ||
87 | </para> | ||
88 | </glossdef> | ||
89 | </glossentry> | ||
90 | |||
91 | </glossdiv> | ||
92 | |||
93 | |||
94 | <glossdiv id='var-bb-glossary-b'><title>B</title> | ||
95 | |||
96 | <glossentry id='var-bb-B'><glossterm>B</glossterm> | ||
97 | <glossdef> | ||
98 | <para> | ||
99 | The directory in which BitBake executes functions | ||
100 | during a recipe's build process. | ||
101 | </para> | ||
102 | </glossdef> | ||
103 | </glossentry> | ||
104 | |||
105 | <glossentry id='var-bb-BB_ALLOWED_NETWORKS'><glossterm>BB_ALLOWED_NETWORKS</glossterm> | ||
106 | <glossdef> | ||
107 | <para> | ||
108 | Specifies a space-delimited list of hosts that the fetcher | ||
109 | is allowed to use to obtain the required source code. | ||
110 | Following are considerations surrounding this variable: | ||
111 | <itemizedlist> | ||
112 | <listitem><para> | ||
113 | This host list is only used if | ||
114 | <link linkend='var-bb-BB_NO_NETWORK'><filename>BB_NO_NETWORK</filename></link> | ||
115 | is either not set or set to "0". | ||
116 | </para></listitem> | ||
117 | <listitem><para> | ||
118 | Limited support for the "<filename>*</filename>" | ||
119 | wildcard character for matching against the | ||
120 | beginning of host names exists. | ||
121 | For example, the following setting matches | ||
122 | <filename>git.gnu.org</filename>, | ||
123 | <filename>ftp.gnu.org</filename>, and | ||
124 | <filename>foo.git.gnu.org</filename>. | ||
125 | <literallayout class='monospaced'> | ||
126 | BB_ALLOWED_NETWORKS = "*.gnu.org" | ||
127 | </literallayout> | ||
128 | <note><title>Important</title> | ||
129 | <para>The use of the "<filename>*</filename>" | ||
130 | character only works at the beginning of | ||
131 | a host name and it must be isolated from | ||
132 | the remainder of the host name. | ||
133 | You cannot use the wildcard character in any | ||
134 | other location of the name or combined with | ||
135 | the front part of the name.</para> | ||
136 | |||
137 | <para>For example, | ||
138 | <filename>*.foo.bar</filename> is supported, | ||
139 | while <filename>*aa.foo.bar</filename> is not. | ||
140 | </para> | ||
141 | </note> | ||
142 | </para></listitem> | ||
143 | <listitem><para> | ||
144 | Mirrors not in the host list are skipped and | ||
145 | logged in debug. | ||
146 | </para></listitem> | ||
147 | <listitem><para> | ||
148 | Attempts to access networks not in the host list | ||
149 | cause a failure. | ||
150 | </para></listitem> | ||
151 | </itemizedlist> | ||
152 | Using <filename>BB_ALLOWED_NETWORKS</filename> in | ||
153 | conjunction with | ||
154 | <link linkend='var-bb-PREMIRRORS'><filename>PREMIRRORS</filename></link> | ||
155 | is very useful. | ||
156 | Adding the host you want to use to | ||
157 | <filename>PREMIRRORS</filename> results in the source code | ||
158 | being fetched from an allowed location and avoids raising | ||
159 | an error when a host that is not allowed is in a | ||
160 | <link linkend='var-bb-SRC_URI'><filename>SRC_URI</filename></link> | ||
161 | statement. | ||
162 | This is because the fetcher does not attempt to use the | ||
163 | host listed in <filename>SRC_URI</filename> after a | ||
164 | successful fetch from the | ||
165 | <filename>PREMIRRORS</filename> occurs. | ||
166 | </para> | ||
167 | </glossdef> | ||
168 | </glossentry> | ||
169 | |||
170 | <glossentry id='var-bb-BB_CONSOLELOG'><glossterm>BB_CONSOLELOG</glossterm> | ||
171 | <glossdef> | ||
172 | <para> | ||
173 | Specifies the path to a log file into which BitBake's user | ||
174 | interface writes output during the build. | ||
175 | </para> | ||
176 | </glossdef> | ||
177 | </glossentry> | ||
178 | |||
179 | <glossentry id='var-bb-BB_CURRENTTASK'><glossterm>BB_CURRENTTASK</glossterm> | ||
180 | <glossdef> | ||
181 | <para> | ||
182 | Contains the name of the currently running task. | ||
183 | The name does not include the | ||
184 | <filename>do_</filename> prefix. | ||
185 | </para> | ||
186 | </glossdef> | ||
187 | </glossentry> | ||
188 | |||
189 | <glossentry id='var-bb-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm> | ||
190 | <glossdef> | ||
191 | <para> | ||
192 | Defines how BitBake handles situations where an append | ||
193 | file (<filename>.bbappend</filename>) has no | ||
194 | corresponding recipe file (<filename>.bb</filename>). | ||
195 | This condition often occurs when layers get out of sync | ||
196 | (e.g. <filename>oe-core</filename> bumps a | ||
197 | recipe version and the old recipe no longer exists and the | ||
198 | other layer has not been updated to the new version | ||
199 | of the recipe yet). | ||
200 | </para> | ||
201 | |||
202 | <para> | ||
203 | The default fatal behavior is safest because it is | ||
204 | the sane reaction given something is out of sync. | ||
205 | It is important to realize when your changes are no longer | ||
206 | being applied. | ||
207 | </para> | ||
208 | </glossdef> | ||
209 | </glossentry> | ||
210 | |||
211 | <glossentry id='var-bb-BB_DEFAULT_TASK'><glossterm>BB_DEFAULT_TASK</glossterm> | ||
212 | <glossdef> | ||
213 | <para> | ||
214 | The default task to use when none is specified (e.g. | ||
215 | with the <filename>-c</filename> command line option). | ||
216 | The task name specified should not include the | ||
217 | <filename>do_</filename> prefix. | ||
218 | </para> | ||
219 | </glossdef> | ||
220 | </glossentry> | ||
221 | |||
222 | <glossentry id='var-bb-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm> | ||
223 | <glossdef> | ||
224 | <para> | ||
225 | Monitors disk space and available inodes during the build | ||
226 | and allows you to control the build based on these | ||
227 | parameters. | ||
228 | </para> | ||
229 | |||
230 | <para> | ||
231 | Disk space monitoring is disabled by default. | ||
232 | When setting this variable, use the following form: | ||
233 | <literallayout class='monospaced'> | ||
234 | BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]" | ||
235 | |||
236 | where: | ||
237 | |||
238 | <action> is: | ||
239 | ABORT: Immediately abort the build when | ||
240 | a threshold is broken. | ||
241 | STOPTASKS: Stop the build after the currently | ||
242 | executing tasks have finished when | ||
243 | a threshold is broken. | ||
244 | WARN: Issue a warning but continue the | ||
245 | build when a threshold is broken. | ||
246 | Subsequent warnings are issued as | ||
247 | defined by the | ||
248 | <link linkend='var-bb-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable, | ||
249 | which must be defined. | ||
250 | |||
251 | <dir> is: | ||
252 | Any directory you choose. You can specify one or | ||
253 | more directories to monitor by separating the | ||
254 | groupings with a space. If two directories are | ||
255 | on the same device, only the first directory | ||
256 | is monitored. | ||
257 | |||
258 | <threshold> is: | ||
259 | Either the minimum available disk space, | ||
260 | the minimum number of free inodes, or | ||
261 | both. You must specify at least one. To | ||
262 | omit one or the other, simply omit the value. | ||
263 | Specify the threshold using G, M, K for Gbytes, | ||
264 | Mbytes, and Kbytes, respectively. If you do | ||
265 | not specify G, M, or K, Kbytes is assumed by | ||
266 | default. Do not use GB, MB, or KB. | ||
267 | </literallayout> | ||
268 | </para> | ||
269 | |||
270 | <para> | ||
271 | Here are some examples: | ||
272 | <literallayout class='monospaced'> | ||
273 | BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" | ||
274 | BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" | ||
275 | BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" | ||
276 | </literallayout> | ||
277 | The first example works only if you also set | ||
278 | the <link linkend='var-bb-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable. | ||
279 | This example causes the build system to immediately | ||
280 | abort when either the disk space in <filename>${TMPDIR}</filename> drops | ||
281 | below 1 Gbyte or the available free inodes drops below | ||
282 | 100 Kbytes. | ||
283 | Because two directories are provided with the variable, the | ||
284 | build system also issues a | ||
285 | warning when the disk space in the | ||
286 | <filename>${SSTATE_DIR}</filename> directory drops | ||
287 | below 1 Gbyte or the number of free inodes drops | ||
288 | below 100 Kbytes. | ||
289 | Subsequent warnings are issued during intervals as | ||
290 | defined by the <filename>BB_DISKMON_WARNINTERVAL</filename> | ||
291 | variable. | ||
292 | </para> | ||
293 | |||
294 | <para> | ||
295 | The second example stops the build after all currently | ||
296 | executing tasks complete when the minimum disk space | ||
297 | in the <filename>${TMPDIR}</filename> | ||
298 | directory drops below 1 Gbyte. | ||
299 | No disk monitoring occurs for the free inodes in this case. | ||
300 | </para> | ||
301 | |||
302 | <para> | ||
303 | The final example immediately aborts the build when the | ||
304 | number of free inodes in the <filename>${TMPDIR}</filename> directory | ||
305 | drops below 100 Kbytes. | ||
306 | No disk space monitoring for the directory itself occurs | ||
307 | in this case. | ||
308 | </para> | ||
309 | </glossdef> | ||
310 | </glossentry> | ||
311 | |||
312 | <glossentry id='var-bb-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm> | ||
313 | <glossdef> | ||
314 | <para> | ||
315 | Defines the disk space and free inode warning intervals. | ||
316 | </para> | ||
317 | |||
318 | <para> | ||
319 | If you are going to use the | ||
320 | <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must | ||
321 | also use the | ||
322 | <link linkend='var-bb-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable | ||
323 | and define its action as "WARN". | ||
324 | During the build, subsequent warnings are issued each time | ||
325 | disk space or number of free inodes further reduces by | ||
326 | the respective interval. | ||
327 | </para> | ||
328 | |||
329 | <para> | ||
330 | If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename> | ||
331 | variable and you do use <filename>BB_DISKMON_DIRS</filename> with | ||
332 | the "WARN" action, the disk monitoring interval defaults to | ||
333 | the following: | ||
334 | <literallayout class='monospaced'> | ||
335 | BB_DISKMON_WARNINTERVAL = "50M,5K" | ||
336 | </literallayout> | ||
337 | </para> | ||
338 | |||
339 | <para> | ||
340 | When specifying the variable in your configuration file, | ||
341 | use the following form: | ||
342 | <literallayout class='monospaced'> | ||
343 | BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>" | ||
344 | |||
345 | where: | ||
346 | |||
347 | <disk_space_interval> is: | ||
348 | An interval of memory expressed in either | ||
349 | G, M, or K for Gbytes, Mbytes, or Kbytes, | ||
350 | respectively. You cannot use GB, MB, or KB. | ||
351 | |||
352 | <disk_inode_interval> is: | ||
353 | An interval of free inodes expressed in either | ||
354 | G, M, or K for Gbytes, Mbytes, or Kbytes, | ||
355 | respectively. You cannot use GB, MB, or KB. | ||
356 | </literallayout> | ||
357 | </para> | ||
358 | |||
359 | <para> | ||
360 | Here is an example: | ||
361 | <literallayout class='monospaced'> | ||
362 | BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" | ||
363 | BB_DISKMON_WARNINTERVAL = "50M,5K" | ||
364 | </literallayout> | ||
365 | These variables cause BitBake to | ||
366 | issue subsequent warnings each time the available | ||
367 | disk space further reduces by 50 Mbytes or the number | ||
368 | of free inodes further reduces by 5 Kbytes in the | ||
369 | <filename>${SSTATE_DIR}</filename> directory. | ||
370 | Subsequent warnings based on the interval occur each time | ||
371 | a respective interval is reached beyond the initial warning | ||
372 | (i.e. 1 Gbytes and 100 Kbytes). | ||
373 | </para> | ||
374 | </glossdef> | ||
375 | </glossentry> | ||
376 | |||
377 | <glossentry id='var-bb-BB_ENV_WHITELIST'><glossterm>BB_ENV_WHITELIST</glossterm> | ||
378 | <glossdef> | ||
379 | <para> | ||
380 | Specifies the internal whitelist of variables to allow | ||
381 | through from the external environment into BitBake's | ||
382 | datastore. | ||
383 | If the value of this variable is not specified | ||
384 | (which is the default), the following list is used: | ||
385 | <link linkend='var-bb-BBPATH'><filename>BBPATH</filename></link>, | ||
386 | <link linkend='var-bb-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link>, | ||
387 | <link linkend='var-bb-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>, | ||
388 | and | ||
389 | <link linkend='var-bb-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>. | ||
390 | <note> | ||
391 | You must set this variable in the external environment | ||
392 | in order for it to work. | ||
393 | </note> | ||
394 | </para> | ||
395 | </glossdef> | ||
396 | </glossentry> | ||
397 | |||
398 | <glossentry id='var-bb-BB_ENV_EXTRAWHITE'><glossterm>BB_ENV_EXTRAWHITE</glossterm> | ||
399 | <glossdef> | ||
400 | <para> | ||
401 | Specifies an additional set of variables to allow through | ||
402 | (whitelist) from the external environment into BitBake's | ||
403 | datastore. | ||
404 | This list of variables are on top of the internal list | ||
405 | set in | ||
406 | <link linkend='var-bb-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>. | ||
407 | <note> | ||
408 | You must set this variable in the external | ||
409 | environment in order for it to work. | ||
410 | </note> | ||
411 | </para> | ||
412 | </glossdef> | ||
413 | </glossentry> | ||
414 | |||
415 | <glossentry id='var-bb-BB_FETCH_PREMIRRORONLY'><glossterm>BB_FETCH_PREMIRRORONLY</glossterm> | ||
416 | <glossdef> | ||
417 | <para> | ||
418 | When set to "1", causes BitBake's fetcher module to only | ||
419 | search | ||
420 | <link linkend='var-bb-PREMIRRORS'><filename>PREMIRRORS</filename></link> | ||
421 | for files. | ||
422 | BitBake will not search the main | ||
423 | <link linkend='var-bb-SRC_URI'><filename>SRC_URI</filename></link> | ||
424 | or | ||
425 | <link linkend='var-bb-MIRRORS'><filename>MIRRORS</filename></link>. | ||
426 | </para> | ||
427 | </glossdef> | ||
428 | </glossentry> | ||
429 | |||
430 | <glossentry id='var-bb-BB_FILENAME'><glossterm>BB_FILENAME</glossterm> | ||
431 | <glossdef> | ||
432 | <para> | ||
433 | Contains the filename of the recipe that owns the currently | ||
434 | running task. | ||
435 | For example, if the <filename>do_fetch</filename> task that | ||
436 | resides in the <filename>my-recipe.bb</filename> is | ||
437 | executing, the <filename>BB_FILENAME</filename> variable | ||
438 | contains "/foo/path/my-recipe.bb". | ||
439 | </para> | ||
440 | </glossdef> | ||
441 | </glossentry> | ||
442 | |||
443 | <glossentry id='var-bb-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm> | ||
444 | <glossdef> | ||
445 | <para> | ||
446 | Causes tarballs of the Git repositories, including the | ||
447 | Git metadata, to be placed in the | ||
448 | <link linkend='var-bb-DL_DIR'><filename>DL_DIR</filename></link> | ||
449 | directory. | ||
450 | Anyone wishing to create a source mirror would want to | ||
451 | enable this variable. | ||
452 | </para> | ||
453 | |||
454 | <para> | ||
455 | For performance reasons, creating and placing tarballs of | ||
456 | the Git repositories is not the default action by BitBake. | ||
457 | <literallayout class='monospaced'> | ||
458 | BB_GENERATE_MIRROR_TARBALLS = "1" | ||
459 | </literallayout> | ||
460 | </para> | ||
461 | </glossdef> | ||
462 | </glossentry> | ||
463 | |||
464 | <glossentry id='var-bb-BB_HASHCONFIG_WHITELIST'><glossterm>BB_HASHCONFIG_WHITELIST</glossterm> | ||
465 | <glossdef> | ||
466 | <para> | ||
467 | Lists variables that are excluded from base configuration | ||
468 | checksum, which is used to determine if the cache can | ||
469 | be reused. | ||
470 | </para> | ||
471 | |||
472 | <para> | ||
473 | One of the ways BitBake determines whether to re-parse the | ||
474 | main metadata is through checksums of the variables in the | ||
475 | datastore of the base configuration data. | ||
476 | There are variables that you typically want to exclude when | ||
477 | checking whether or not to re-parse and thus rebuild the | ||
478 | cache. | ||
479 | As an example, you would usually exclude | ||
480 | <filename>TIME</filename> and <filename>DATE</filename> | ||
481 | because these variables are always changing. | ||
482 | If you did not exclude them, BitBake would never reuse the | ||
483 | cache. | ||
484 | </para> | ||
485 | </glossdef> | ||
486 | </glossentry> | ||
487 | |||
488 | <glossentry id='var-bb-BB_HASHBASE_WHITELIST'><glossterm>BB_HASHBASE_WHITELIST</glossterm> | ||
489 | <glossdef> | ||
490 | <para> | ||
491 | Lists variables that are excluded from checksum and | ||
492 | dependency data. | ||
493 | Variables that are excluded can therefore change without | ||
494 | affecting the checksum mechanism. | ||
495 | A common example would be the variable for the path of | ||
496 | the build. | ||
497 | BitBake's output should not (and usually does not) depend | ||
498 | on the directory in which it was built. | ||
499 | </para> | ||
500 | </glossdef> | ||
501 | </glossentry> | ||
502 | |||
503 | <glossentry id='var-bb-BB_HASHCHECK_FUNCTION'><glossterm>BB_HASHCHECK_FUNCTION</glossterm> | ||
504 | <glossdef> | ||
505 | <para> | ||
506 | Specifies the name of the function to call during the | ||
507 | "setscene" part of the task's execution in order to | ||
508 | validate the list of task hashes. | ||
509 | The function returns the list of setscene tasks that should | ||
510 | be executed. | ||
511 | </para> | ||
512 | |||
513 | <para> | ||
514 | At this point in the execution of the code, the objective | ||
515 | is to quickly verify if a given setscene function is likely | ||
516 | to work or not. | ||
517 | It's easier to check the list of setscene functions in | ||
518 | one pass than to call many individual tasks. | ||
519 | The returned list need not be completely accurate. | ||
520 | A given setscene task can still later fail. | ||
521 | However, the more accurate the data returned, the more | ||
522 | efficient the build will be. | ||
523 | </para> | ||
524 | </glossdef> | ||
525 | </glossentry> | ||
526 | |||
527 | <glossentry id='var-bb-BB_INVALIDCONF'><glossterm>BB_INVALIDCONF</glossterm> | ||
528 | <glossdef> | ||
529 | <para> | ||
530 | Used in combination with the | ||
531 | <filename>ConfigParsed</filename> event to trigger | ||
532 | re-parsing the base metadata (i.e. all the | ||
533 | recipes). | ||
534 | The <filename>ConfigParsed</filename> event can set the | ||
535 | variable to trigger the re-parse. | ||
536 | You must be careful to avoid recursive loops with this | ||
537 | functionality. | ||
538 | </para> | ||
539 | </glossdef> | ||
540 | </glossentry> | ||
541 | |||
542 | <glossentry id='var-bb-BB_LOGCONFIG'><glossterm>BB_LOGCONFIG</glossterm> | ||
543 | <glossdef> | ||
544 | <para> | ||
545 | Specifies the name of a config file that contains the user | ||
546 | logging configuration. See | ||
547 | <link linkend="logging">Logging</link> for additional | ||
548 | information | ||
549 | </para> | ||
550 | </glossdef> | ||
551 | </glossentry> | ||
552 | |||
553 | <glossentry id='var-bb-BB_LOGFMT'><glossterm>BB_LOGFMT</glossterm> | ||
554 | <glossdef> | ||
555 | <para> | ||
556 | Specifies the name of the log files saved into | ||
557 | <filename>${</filename><link linkend='var-bb-T'><filename>T</filename></link><filename>}</filename>. | ||
558 | By default, the <filename>BB_LOGFMT</filename> variable | ||
559 | is undefined and the log file names get created using the | ||
560 | following form: | ||
561 | <literallayout class='monospaced'> | ||
562 | log.{task}.{pid} | ||
563 | </literallayout> | ||
564 | If you want to force log files to take a specific name, | ||
565 | you can set this variable in a configuration file. | ||
566 | </para> | ||
567 | </glossdef> | ||
568 | </glossentry> | ||
569 | |||
570 | <glossentry id='var-bb-BB_NICE_LEVEL'><glossterm>BB_NICE_LEVEL</glossterm> | ||
571 | <glossdef> | ||
572 | <para> | ||
573 | Allows BitBake to run at a specific priority | ||
574 | (i.e. nice level). | ||
575 | System permissions usually mean that BitBake can reduce its | ||
576 | priority but not raise it again. | ||
577 | See | ||
578 | <link linkend='var-bb-BB_TASK_NICE_LEVEL'><filename>BB_TASK_NICE_LEVEL</filename></link> | ||
579 | for additional information. | ||
580 | </para> | ||
581 | </glossdef> | ||
582 | </glossentry> | ||
583 | |||
584 | <glossentry id='var-bb-BB_NO_NETWORK'><glossterm>BB_NO_NETWORK</glossterm> | ||
585 | <glossdef> | ||
586 | <para> | ||
587 | Disables network access in the BitBake fetcher modules. | ||
588 | With this access disabled, any command that attempts to | ||
589 | access the network becomes an error. | ||
590 | </para> | ||
591 | |||
592 | <para> | ||
593 | Disabling network access is useful for testing source | ||
594 | mirrors, running builds when not connected to the Internet, | ||
595 | and when operating in certain kinds of firewall | ||
596 | environments. | ||
597 | </para> | ||
598 | </glossdef> | ||
599 | </glossentry> | ||
600 | |||
601 | <glossentry id='var-bb-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm> | ||
602 | <glossdef> | ||
603 | <para> | ||
604 | The maximum number of tasks BitBake should run in parallel | ||
605 | at any one time. | ||
606 | If your host development system supports multiple cores, | ||
607 | a good rule of thumb is to set this variable to twice the | ||
608 | number of cores. | ||
609 | </para> | ||
610 | </glossdef> | ||
611 | </glossentry> | ||
612 | |||
613 | <glossentry id='var-bb-BB_NUMBER_PARSE_THREADS'><glossterm>BB_NUMBER_PARSE_THREADS</glossterm> | ||
614 | <glossdef> | ||
615 | <para> | ||
616 | Sets the number of threads BitBake uses when parsing. | ||
617 | By default, the number of threads is equal to the number | ||
618 | of cores on the system. | ||
619 | </para> | ||
620 | </glossdef> | ||
621 | </glossentry> | ||
622 | |||
623 | <glossentry id='var-bb-BB_ORIGENV'><glossterm>BB_ORIGENV</glossterm> | ||
624 | <glossdef> | ||
625 | <para> | ||
626 | Contains a copy of the original external environment in | ||
627 | which BitBake was run. | ||
628 | The copy is taken before any whitelisted variable values | ||
629 | are filtered into BitBake's datastore. | ||
630 | <note> | ||
631 | The contents of this variable is a datastore object | ||
632 | that can be queried using the normal datastore | ||
633 | operations. | ||
634 | </note> | ||
635 | </para> | ||
636 | </glossdef> | ||
637 | </glossentry> | ||
638 | |||
639 | <glossentry id='var-bb-BB_PRESERVE_ENV'><glossterm>BB_PRESERVE_ENV</glossterm> | ||
640 | <glossdef> | ||
641 | <para> | ||
642 | Disables whitelisting and instead allows all variables | ||
643 | through from the external environment into BitBake's | ||
644 | datastore. | ||
645 | <note> | ||
646 | You must set this variable in the external | ||
647 | environment in order for it to work. | ||
648 | </note> | ||
649 | </para> | ||
650 | </glossdef> | ||
651 | </glossentry> | ||
652 | |||
653 | <glossentry id='var-bb-BB_RUNFMT'><glossterm>BB_RUNFMT</glossterm> | ||
654 | <glossdef> | ||
655 | <para> | ||
656 | Specifies the name of the executable script files | ||
657 | (i.e. run files) saved into | ||
658 | <filename>${</filename><link linkend='var-bb-T'><filename>T</filename></link><filename>}</filename>. | ||
659 | By default, the <filename>BB_RUNFMT</filename> variable | ||
660 | is undefined and the run file names get created using the | ||
661 | following form: | ||
662 | <literallayout class='monospaced'> | ||
663 | run.{task}.{pid} | ||
664 | </literallayout> | ||
665 | If you want to force run files to take a specific name, | ||
666 | you can set this variable in a configuration file. | ||
667 | </para> | ||
668 | </glossdef> | ||
669 | </glossentry> | ||
670 | |||
671 | <glossentry id='var-bb-BB_RUNTASK'><glossterm>BB_RUNTASK</glossterm> | ||
672 | <glossdef> | ||
673 | <para> | ||
674 | Contains the name of the currently executing task. | ||
675 | The value includes the "do_" prefix. | ||
676 | For example, if the currently executing task is | ||
677 | <filename>do_config</filename>, the value is | ||
678 | "do_config". | ||
679 | </para> | ||
680 | </glossdef> | ||
681 | </glossentry> | ||
682 | |||
683 | <glossentry id='var-bb-BB_SCHEDULER'><glossterm>BB_SCHEDULER</glossterm> | ||
684 | <glossdef> | ||
685 | <para> | ||
686 | Selects the name of the scheduler to use for the | ||
687 | scheduling of BitBake tasks. | ||
688 | Three options exist: | ||
689 | <itemizedlist> | ||
690 | <listitem><para><emphasis>basic</emphasis> - | ||
691 | The basic framework from which everything derives. | ||
692 | Using this option causes tasks to be ordered | ||
693 | numerically as they are parsed. | ||
694 | </para></listitem> | ||
695 | <listitem><para><emphasis>speed</emphasis> - | ||
696 | Executes tasks first that have more tasks | ||
697 | depending on them. | ||
698 | The "speed" option is the default. | ||
699 | </para></listitem> | ||
700 | <listitem><para><emphasis>completion</emphasis> - | ||
701 | Causes the scheduler to try to complete a given | ||
702 | recipe once its build has started. | ||
703 | </para></listitem> | ||
704 | </itemizedlist> | ||
705 | </para> | ||
706 | </glossdef> | ||
707 | </glossentry> | ||
708 | |||
709 | <glossentry id='var-bb-BB_SCHEDULERS'><glossterm>BB_SCHEDULERS</glossterm> | ||
710 | <glossdef> | ||
711 | <para> | ||
712 | Defines custom schedulers to import. | ||
713 | Custom schedulers need to be derived from the | ||
714 | <filename>RunQueueScheduler</filename> class. | ||
715 | </para> | ||
716 | |||
717 | <para> | ||
718 | For information how to select a scheduler, see the | ||
719 | <link linkend='var-bb-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link> | ||
720 | variable. | ||
721 | </para> | ||
722 | </glossdef> | ||
723 | </glossentry> | ||
724 | |||
725 | <glossentry id='var-bb-BB_SETSCENE_DEPVALID'><glossterm>BB_SETSCENE_DEPVALID</glossterm> | ||
726 | <glossdef> | ||
727 | <para> | ||
728 | Specifies a function BitBake calls that determines | ||
729 | whether BitBake requires a setscene dependency to be met. | ||
730 | </para> | ||
731 | |||
732 | <para> | ||
733 | When running a setscene task, BitBake needs to | ||
734 | know which dependencies of that setscene task also need | ||
735 | to be run. | ||
736 | Whether dependencies also need to be run is highly | ||
737 | dependent on the metadata. | ||
738 | The function specified by this variable returns a | ||
739 | "True" or "False" depending on whether the dependency needs | ||
740 | to be met. | ||
741 | </para> | ||
742 | </glossdef> | ||
743 | </glossentry> | ||
744 | |||
745 | <glossentry id='var-bb-BB_SETSCENE_VERIFY_FUNCTION2'><glossterm>BB_SETSCENE_VERIFY_FUNCTION2</glossterm> | ||
746 | <glossdef> | ||
747 | <para> | ||
748 | Specifies a function to call that verifies the list of | ||
749 | planned task execution before the main task execution | ||
750 | happens. | ||
751 | The function is called once BitBake has a list of setscene | ||
752 | tasks that have run and either succeeded or failed. | ||
753 | </para> | ||
754 | |||
755 | <para> | ||
756 | The function allows for a task list check to see if they | ||
757 | make sense. | ||
758 | Even if BitBake was planning to skip a task, the | ||
759 | returned value of the function can force BitBake to run | ||
760 | the task, which is necessary under certain metadata | ||
761 | defined circumstances. | ||
762 | </para> | ||
763 | </glossdef> | ||
764 | </glossentry> | ||
765 | |||
766 | <glossentry id='var-bb-BB_SIGNATURE_EXCLUDE_FLAGS'><glossterm>BB_SIGNATURE_EXCLUDE_FLAGS</glossterm> | ||
767 | <glossdef> | ||
768 | <para> | ||
769 | Lists variable flags (varflags) | ||
770 | that can be safely excluded from checksum | ||
771 | and dependency data for keys in the datastore. | ||
772 | When generating checksum or dependency data for keys in the | ||
773 | datastore, the flags set against that key are normally | ||
774 | included in the checksum. | ||
775 | </para> | ||
776 | |||
777 | <para> | ||
778 | For more information on varflags, see the | ||
779 | "<link linkend='variable-flags'>Variable Flags</link>" | ||
780 | section. | ||
781 | </para> | ||
782 | </glossdef> | ||
783 | </glossentry> | ||
784 | |||
785 | <glossentry id='var-bb-BB_SIGNATURE_HANDLER'><glossterm>BB_SIGNATURE_HANDLER</glossterm> | ||
786 | <glossdef> | ||
787 | <para> | ||
788 | Defines the name of the signature handler BitBake uses. | ||
789 | The signature handler defines the way stamp files are | ||
790 | created and handled, if and how the signature is | ||
791 | incorporated into the stamps, and how the signature | ||
792 | itself is generated. | ||
793 | </para> | ||
794 | |||
795 | <para> | ||
796 | A new signature handler can be added by injecting a class | ||
797 | derived from the | ||
798 | <filename>SignatureGenerator</filename> class into the | ||
799 | global namespace. | ||
800 | </para> | ||
801 | </glossdef> | ||
802 | </glossentry> | ||
803 | |||
804 | <glossentry id='var-bb-BB_SRCREV_POLICY'><glossterm>BB_SRCREV_POLICY</glossterm> | ||
805 | <glossdef> | ||
806 | <para> | ||
807 | Defines the behavior of the fetcher when it interacts with | ||
808 | source control systems and dynamic source revisions. | ||
809 | The <filename>BB_SRCREV_POLICY</filename> variable is | ||
810 | useful when working without a network. | ||
811 | </para> | ||
812 | |||
813 | <para> | ||
814 | The variable can be set using one of two policies: | ||
815 | <itemizedlist> | ||
816 | <listitem><para><emphasis>cache</emphasis> - | ||
817 | Retains the value the system obtained previously | ||
818 | rather than querying the source control system | ||
819 | each time. | ||
820 | </para></listitem> | ||
821 | <listitem><para><emphasis>clear</emphasis> - | ||
822 | Queries the source controls system every time. | ||
823 | With this policy, there is no cache. | ||
824 | The "clear" policy is the default. | ||
825 | </para></listitem> | ||
826 | </itemizedlist> | ||
827 | </para> | ||
828 | </glossdef> | ||
829 | </glossentry> | ||
830 | |||
831 | <glossentry id='var-bb-BB_STAMP_POLICY'><glossterm>BB_STAMP_POLICY</glossterm> | ||
832 | <glossdef> | ||
833 | <para> | ||
834 | Defines the mode used for how timestamps of stamp files | ||
835 | are compared. | ||
836 | You can set the variable to one of the following modes: | ||
837 | <itemizedlist> | ||
838 | <listitem><para><emphasis>perfile</emphasis> - | ||
839 | Timestamp comparisons are only made | ||
840 | between timestamps of a specific recipe. | ||
841 | This is the default mode. | ||
842 | </para></listitem> | ||
843 | <listitem><para><emphasis>full</emphasis> - | ||
844 | Timestamp comparisons are made for all | ||
845 | dependencies. | ||
846 | </para></listitem> | ||
847 | <listitem><para><emphasis>whitelist</emphasis> - | ||
848 | Identical to "full" mode except timestamp | ||
849 | comparisons are made for recipes listed in the | ||
850 | <link linkend='var-bb-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link> | ||
851 | variable. | ||
852 | </para></listitem> | ||
853 | </itemizedlist> | ||
854 | <note> | ||
855 | Stamp policies are largely obsolete with the | ||
856 | introduction of setscene tasks. | ||
857 | </note> | ||
858 | </para> | ||
859 | </glossdef> | ||
860 | </glossentry> | ||
861 | |||
862 | <glossentry id='var-bb-BB_STAMP_WHITELIST'><glossterm>BB_STAMP_WHITELIST</glossterm> | ||
863 | <glossdef> | ||
864 | <para> | ||
865 | Lists files whose stamp file timestamps are compared when | ||
866 | the stamp policy mode is set to "whitelist". | ||
867 | For information on stamp policies, see the | ||
868 | <link linkend='var-bb-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link> | ||
869 | variable. | ||
870 | </para> | ||
871 | </glossdef> | ||
872 | </glossentry> | ||
873 | |||
874 | <glossentry id='var-bb-BB_STRICT_CHECKSUM'><glossterm>BB_STRICT_CHECKSUM</glossterm> | ||
875 | <glossdef> | ||
876 | <para> | ||
877 | Sets a more strict checksum mechanism for non-local URLs. | ||
878 | Setting this variable to a value causes BitBake | ||
879 | to report an error if it encounters a non-local URL | ||
880 | that does not have at least one checksum specified. | ||
881 | </para> | ||
882 | </glossdef> | ||
883 | </glossentry> | ||
884 | |||
885 | <glossentry id='var-bb-BB_TASK_IONICE_LEVEL'><glossterm>BB_TASK_IONICE_LEVEL</glossterm> | ||
886 | <glossdef> | ||
887 | <para> | ||
888 | Allows adjustment of a task's Input/Output priority. | ||
889 | During Autobuilder testing, random failures can occur | ||
890 | for tasks due to I/O starvation. | ||
891 | These failures occur during various QEMU runtime timeouts. | ||
892 | You can use the <filename>BB_TASK_IONICE_LEVEL</filename> | ||
893 | variable to adjust the I/O priority of these tasks. | ||
894 | <note> | ||
895 | This variable works similarly to the | ||
896 | <link linkend='var-bb-BB_TASK_NICE_LEVEL'><filename>BB_TASK_NICE_LEVEL</filename></link> | ||
897 | variable except with a task's I/O priorities. | ||
898 | </note> | ||
899 | </para> | ||
900 | |||
901 | <para> | ||
902 | Set the variable as follows: | ||
903 | <literallayout class='monospaced'> | ||
904 | BB_TASK_IONICE_LEVEL = "<replaceable>class</replaceable>.<replaceable>prio</replaceable>" | ||
905 | </literallayout> | ||
906 | For <replaceable>class</replaceable>, the default value is | ||
907 | "2", which is a best effort. | ||
908 | You can use "1" for realtime and "3" for idle. | ||
909 | If you want to use realtime, you must have superuser | ||
910 | privileges. | ||
911 | </para> | ||
912 | |||
913 | <para> | ||
914 | For <replaceable>prio</replaceable>, you can use any | ||
915 | value from "0", which is the highest priority, to "7", | ||
916 | which is the lowest. | ||
917 | The default value is "4". | ||
918 | You do not need any special privileges to use this range | ||
919 | of priority values. | ||
920 | <note> | ||
921 | In order for your I/O priority settings to take effect, | ||
922 | you need the Completely Fair Queuing (CFQ) Scheduler | ||
923 | selected for the backing block device. | ||
924 | To select the scheduler, use the following command form | ||
925 | where <replaceable>device</replaceable> is the device | ||
926 | (e.g. sda, sdb, and so forth): | ||
927 | <literallayout class='monospaced'> | ||
928 | $ sudo sh -c “echo cfq > /sys/block/<replaceable>device</replaceable>/queu/scheduler | ||
929 | </literallayout> | ||
930 | </note> | ||
931 | </para> | ||
932 | </glossdef> | ||
933 | </glossentry> | ||
934 | |||
935 | <glossentry id='var-bb-BB_TASK_NICE_LEVEL'><glossterm>BB_TASK_NICE_LEVEL</glossterm> | ||
936 | <glossdef> | ||
937 | <para> | ||
938 | Allows specific tasks to change their priority | ||
939 | (i.e. nice level). | ||
940 | </para> | ||
941 | |||
942 | <para> | ||
943 | You can use this variable in combination with task | ||
944 | overrides to raise or lower priorities of specific tasks. | ||
945 | For example, on the | ||
946 | <ulink url='http://www.yoctoproject.org'>Yocto Project</ulink> | ||
947 | autobuilder, QEMU emulation in images is given a higher | ||
948 | priority as compared to build tasks to ensure that images | ||
949 | do not suffer timeouts on loaded systems. | ||
950 | </para> | ||
951 | </glossdef> | ||
952 | </glossentry> | ||
953 | |||
954 | <glossentry id='var-bb-BB_TASKHASH'><glossterm>BB_TASKHASH</glossterm> | ||
955 | <glossdef> | ||
956 | <para> | ||
957 | Within an executing task, this variable holds the hash | ||
958 | of the task as returned by the currently enabled | ||
959 | signature generator. | ||
960 | </para> | ||
961 | </glossdef> | ||
962 | </glossentry> | ||
963 | |||
964 | <glossentry id='var-bb-BB_VERBOSE_LOGS'><glossterm>BB_VERBOSE_LOGS</glossterm> | ||
965 | <glossdef> | ||
966 | <para> | ||
967 | Controls how verbose BitBake is during builds. | ||
968 | If set, shell scripts echo commands and shell script output | ||
969 | appears on standard out (stdout). | ||
970 | </para> | ||
971 | </glossdef> | ||
972 | </glossentry> | ||
973 | |||
974 | <glossentry id='var-bb-BB_WORKERCONTEXT'><glossterm>BB_WORKERCONTEXT</glossterm> | ||
975 | <glossdef> | ||
976 | <para> | ||
977 | Specifies if the current context is executing a task. | ||
978 | BitBake sets this variable to "1" when a task is | ||
979 | being executed. | ||
980 | The value is not set when the task is in server context | ||
981 | during parsing or event handling. | ||
982 | </para> | ||
983 | </glossdef> | ||
984 | </glossentry> | ||
985 | |||
986 | |||
987 | <glossentry id='var-bb-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm> | ||
988 | <glossdef> | ||
989 | <para> | ||
990 | Allows you to extend a recipe so that it builds variants | ||
991 | of the software. | ||
992 | Some examples of these variants for recipes from the | ||
993 | OpenEmbedded-Core metadata are "natives" such as | ||
994 | <filename>quilt-native</filename>, which is a copy of | ||
995 | Quilt built to run on the build system; "crosses" such | ||
996 | as <filename>gcc-cross</filename>, which is a compiler | ||
997 | built to run on the build machine but produces binaries | ||
998 | that run on the target <filename>MACHINE</filename>; | ||
999 | "nativesdk", which targets the SDK machine instead of | ||
1000 | <filename>MACHINE</filename>; and "mulitlibs" in the form | ||
1001 | "<filename>multilib:</filename><replaceable>multilib_name</replaceable>". | ||
1002 | </para> | ||
1003 | |||
1004 | <para> | ||
1005 | To build a different variant of the recipe with a minimal | ||
1006 | amount of code, it usually is as simple as adding the | ||
1007 | variable to your recipe. | ||
1008 | Here are two examples. | ||
1009 | The "native" variants are from the OpenEmbedded-Core | ||
1010 | metadata: | ||
1011 | <literallayout class='monospaced'> | ||
1012 | BBCLASSEXTEND =+ "native nativesdk" | ||
1013 | BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>" | ||
1014 | </literallayout> | ||
1015 | <note> | ||
1016 | <para> | ||
1017 | Internally, the <filename>BBCLASSEXTEND</filename> | ||
1018 | mechanism generates recipe variants by rewriting | ||
1019 | variable values and applying overrides such as | ||
1020 | <filename>_class-native</filename>. | ||
1021 | For example, to generate a native version of a recipe, | ||
1022 | a | ||
1023 | <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> | ||
1024 | on "foo" is rewritten to a <filename>DEPENDS</filename> | ||
1025 | on "foo-native". | ||
1026 | </para> | ||
1027 | |||
1028 | <para> | ||
1029 | Even when using <filename>BBCLASSEXTEND</filename>, the | ||
1030 | recipe is only parsed once. | ||
1031 | Parsing once adds some limitations. | ||
1032 | For example, it is not possible to | ||
1033 | include a different file depending on the variant, | ||
1034 | since <filename>include</filename> statements are | ||
1035 | processed when the recipe is parsed. | ||
1036 | </para> | ||
1037 | </note> | ||
1038 | </para> | ||
1039 | </glossdef> | ||
1040 | </glossentry> | ||
1041 | |||
1042 | <glossentry id='var-bb-BBDEBUG'><glossterm>BBDEBUG</glossterm> | ||
1043 | <glossdef> | ||
1044 | <para> | ||
1045 | Sets the BitBake debug output level to a specific value | ||
1046 | as incremented by the <filename>-D</filename> command line | ||
1047 | option. | ||
1048 | <note> | ||
1049 | You must set this variable in the external environment | ||
1050 | in order for it to work. | ||
1051 | </note> | ||
1052 | </para> | ||
1053 | </glossdef> | ||
1054 | </glossentry> | ||
1055 | |||
1056 | <glossentry id='var-bb-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm> | ||
1057 | <glossdef> | ||
1058 | <para>Lists the names of configured layers. | ||
1059 | These names are used to find the other <filename>BBFILE_*</filename> | ||
1060 | variables. | ||
1061 | Typically, each layer appends its name to this variable in its | ||
1062 | <filename>conf/layer.conf</filename> file. | ||
1063 | </para> | ||
1064 | </glossdef> | ||
1065 | </glossentry> | ||
1066 | |||
1067 | <glossentry id='var-bb-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm> | ||
1068 | <glossdef> | ||
1069 | <para>Variable that expands to match files from | ||
1070 | <link linkend='var-bb-BBFILES'><filename>BBFILES</filename></link> | ||
1071 | in a particular layer. | ||
1072 | This variable is used in the <filename>conf/layer.conf</filename> file and must | ||
1073 | be suffixed with the name of the specific layer (e.g. | ||
1074 | <filename>BBFILE_PATTERN_emenlow</filename>).</para> | ||
1075 | </glossdef> | ||
1076 | </glossentry> | ||
1077 | |||
1078 | <glossentry id='var-bb-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm> | ||
1079 | <glossdef> | ||
1080 | <para>Assigns the priority for recipe files in each layer.</para> | ||
1081 | <para>This variable is useful in situations where the same recipe appears in | ||
1082 | more than one layer. | ||
1083 | Setting this variable allows you to prioritize a | ||
1084 | layer against other layers that contain the same recipe - effectively | ||
1085 | letting you control the precedence for the multiple layers. | ||
1086 | The precedence established through this variable stands regardless of a | ||
1087 | recipe's version | ||
1088 | (<link linkend='var-bb-PV'><filename>PV</filename></link> variable). | ||
1089 | For example, a layer that has a recipe with a higher <filename>PV</filename> value but for | ||
1090 | which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a | ||
1091 | lower precedence.</para> | ||
1092 | <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher | ||
1093 | precedence. | ||
1094 | For example, the value 6 has a higher precedence than the value 5. | ||
1095 | If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer | ||
1096 | dependencies (see the | ||
1097 | <filename><link linkend='var-bb-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for | ||
1098 | more information. | ||
1099 | The default priority, if unspecified | ||
1100 | for a layer with no dependencies, is the lowest defined priority + 1 | ||
1101 | (or 1 if no priorities are defined).</para> | ||
1102 | <tip> | ||
1103 | You can use the command <filename>bitbake-layers show-layers</filename> to list | ||
1104 | all configured layers along with their priorities. | ||
1105 | </tip> | ||
1106 | </glossdef> | ||
1107 | </glossentry> | ||
1108 | |||
1109 | <glossentry id='var-bb-BBFILES'><glossterm>BBFILES</glossterm> | ||
1110 | <glossdef> | ||
1111 | <para> | ||
1112 | A space-separated list of recipe files BitBake uses to | ||
1113 | build software. | ||
1114 | </para> | ||
1115 | |||
1116 | <para> | ||
1117 | When specifying recipe files, you can pattern match using | ||
1118 | Python's | ||
1119 | <ulink url='https://docs.python.org/3/library/glob.html'><filename>glob</filename></ulink> | ||
1120 | syntax. | ||
1121 | For details on the syntax, see the documentation by | ||
1122 | following the previous link. | ||
1123 | </para> | ||
1124 | </glossdef> | ||
1125 | </glossentry> | ||
1126 | |||
1127 | <glossentry id='var-BBFILES_DYNAMIC'><glossterm>BBFILES_DYNAMIC</glossterm> | ||
1128 | <info> | ||
1129 | BBFILES_DYNAMIC[doc] = "Activates content depending on presence of identified layers." | ||
1130 | </info> | ||
1131 | <glossdef> | ||
1132 | <para role="glossdeffirst"> | ||
1133 | Activates content depending on presence of identified layers. | ||
1134 | You identify the layers by the collections that the layers | ||
1135 | define. | ||
1136 | </para> | ||
1137 | |||
1138 | <para> | ||
1139 | Use the <filename>BBFILES_DYNAMIC</filename> variable to | ||
1140 | avoid <filename>.bbappend</filename> files whose | ||
1141 | corresponding <filename>.bb</filename> file is in a layer | ||
1142 | that attempts to modify other layers through | ||
1143 | <filename>.bbappend</filename> but does not want to | ||
1144 | introduce a hard dependency on those other layers. | ||
1145 | </para> | ||
1146 | |||
1147 | <para> | ||
1148 | Additionally you can prefix the rule with "!" to add | ||
1149 | <filename>.bbappend</filename> and <filename>.bb</filename> files | ||
1150 | in case a layer is not present. | ||
1151 | Use this avoid hard dependency on those other layers. | ||
1152 | </para> | ||
1153 | |||
1154 | <para> | ||
1155 | Use the following form for | ||
1156 | <filename>BBFILES_DYNAMIC</filename>: | ||
1157 | <literallayout class='monospaced'> | ||
1158 | <replaceable>collection_name</replaceable>:<replaceable>filename_pattern</replaceable> | ||
1159 | </literallayout> | ||
1160 | The following example identifies two collection names and | ||
1161 | two filename patterns: | ||
1162 | <literallayout class='monospaced'> | ||
1163 | BBFILES_DYNAMIC += "\ | ||
1164 | clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ | ||
1165 | core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \ | ||
1166 | " | ||
1167 | </literallayout> | ||
1168 | When the collection name is prefixed with "!" it will add the file pattern in case | ||
1169 | the layer is absent: | ||
1170 | <literallayout class='monospaced'> | ||
1171 | BBFILES_DYNAMIC += "\ | ||
1172 | !clang-layer:${LAYERDIR}/backfill/meta-clang/*/*/*.bb \ | ||
1173 | " | ||
1174 | </literallayout> | ||
1175 | |||
1176 | This next example shows an error message that occurs | ||
1177 | because invalid entries are found, which cause parsing to | ||
1178 | abort: | ||
1179 | <literallayout class='monospaced'> | ||
1180 | ERROR: BBFILES_DYNAMIC entries must be of the form {!}<collection name>:<filename pattern>, not: | ||
1181 | /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend | ||
1182 | /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend | ||
1183 | </literallayout> | ||
1184 | </para> | ||
1185 | </glossdef> | ||
1186 | </glossentry> | ||
1187 | |||
1188 | <glossentry id='var-bb-BBINCLUDED'><glossterm>BBINCLUDED</glossterm> | ||
1189 | <glossdef> | ||
1190 | <para> | ||
1191 | Contains a space-separated list of all of all files that | ||
1192 | BitBake's parser included during parsing of the current | ||
1193 | file. | ||
1194 | </para> | ||
1195 | </glossdef> | ||
1196 | </glossentry> | ||
1197 | |||
1198 | <glossentry id='var-bb-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm> | ||
1199 | <glossdef> | ||
1200 | <para> | ||
1201 | If set to a value, enables printing the task log when | ||
1202 | reporting a failed task. | ||
1203 | </para> | ||
1204 | </glossdef> | ||
1205 | </glossentry> | ||
1206 | |||
1207 | <glossentry id='var-bb-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm> | ||
1208 | <glossdef> | ||
1209 | <para> | ||
1210 | If | ||
1211 | <link linkend='var-bb-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link> | ||
1212 | is set, specifies the maximum number of lines from the | ||
1213 | task log file to print when reporting a failed task. | ||
1214 | If you do not set <filename>BBINCLUDELOGS_LINES</filename>, | ||
1215 | the entire log is printed. | ||
1216 | </para> | ||
1217 | </glossdef> | ||
1218 | </glossentry> | ||
1219 | |||
1220 | <glossentry id='var-bb-BBLAYERS'><glossterm>BBLAYERS</glossterm> | ||
1221 | <glossdef> | ||
1222 | <para>Lists the layers to enable during the build. | ||
1223 | This variable is defined in the <filename>bblayers.conf</filename> configuration | ||
1224 | file in the build directory. | ||
1225 | Here is an example: | ||
1226 | <literallayout class='monospaced'> | ||
1227 | BBLAYERS = " \ | ||
1228 | /home/scottrif/poky/meta \ | ||
1229 | /home/scottrif/poky/meta-yocto \ | ||
1230 | /home/scottrif/poky/meta-yocto-bsp \ | ||
1231 | /home/scottrif/poky/meta-mykernel \ | ||
1232 | " | ||
1233 | |||
1234 | </literallayout> | ||
1235 | This example enables four layers, one of which is a custom, user-defined layer | ||
1236 | named <filename>meta-mykernel</filename>. | ||
1237 | </para> | ||
1238 | </glossdef> | ||
1239 | </glossentry> | ||
1240 | |||
1241 | <glossentry id='var-bb-BBLAYERS_FETCH_DIR'><glossterm>BBLAYERS_FETCH_DIR</glossterm> | ||
1242 | <glossdef> | ||
1243 | <para> | ||
1244 | Sets the base location where layers are stored. | ||
1245 | This setting is used in conjunction with | ||
1246 | <filename>bitbake-layers layerindex-fetch</filename> and | ||
1247 | tells <filename>bitbake-layers</filename> where to place | ||
1248 | the fetched layers. | ||
1249 | </para> | ||
1250 | </glossdef> | ||
1251 | </glossentry> | ||
1252 | |||
1253 | <glossentry id='var-bb-BBMASK'><glossterm>BBMASK</glossterm> | ||
1254 | <glossdef> | ||
1255 | <para> | ||
1256 | Prevents BitBake from processing recipes and recipe | ||
1257 | append files. | ||
1258 | </para> | ||
1259 | |||
1260 | <para> | ||
1261 | You can use the <filename>BBMASK</filename> variable | ||
1262 | to "hide" these <filename>.bb</filename> and | ||
1263 | <filename>.bbappend</filename> files. | ||
1264 | BitBake ignores any recipe or recipe append files that | ||
1265 | match any of the expressions. | ||
1266 | It is as if BitBake does not see them at all. | ||
1267 | Consequently, matching files are not parsed or otherwise | ||
1268 | used by BitBake. | ||
1269 | </para> | ||
1270 | |||
1271 | <para> | ||
1272 | The values you provide are passed to Python's regular | ||
1273 | expression compiler. | ||
1274 | Consequently, the syntax follows Python's Regular | ||
1275 | Expression (re) syntax. | ||
1276 | The expressions are compared against the full paths to | ||
1277 | the files. | ||
1278 | For complete syntax information, see Python's | ||
1279 | documentation at | ||
1280 | <ulink url='http://docs.python.org/3/library/re.html#re'></ulink>. | ||
1281 | </para> | ||
1282 | |||
1283 | <para> | ||
1284 | The following example uses a complete regular expression | ||
1285 | to tell BitBake to ignore all recipe and recipe append | ||
1286 | files in the <filename>meta-ti/recipes-misc/</filename> | ||
1287 | directory: | ||
1288 | <literallayout class='monospaced'> | ||
1289 | BBMASK = "meta-ti/recipes-misc/" | ||
1290 | </literallayout> | ||
1291 | If you want to mask out multiple directories or recipes, | ||
1292 | you can specify multiple regular expression fragments. | ||
1293 | This next example masks out multiple directories and | ||
1294 | individual recipes: | ||
1295 | <literallayout class='monospaced'> | ||
1296 | BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" | ||
1297 | BBMASK += "/meta-oe/recipes-support/" | ||
1298 | BBMASK += "/meta-foo/.*/openldap" | ||
1299 | BBMASK += "opencv.*\.bbappend" | ||
1300 | BBMASK += "lzma" | ||
1301 | </literallayout> | ||
1302 | <note> | ||
1303 | When specifying a directory name, use the trailing | ||
1304 | slash character to ensure you match just that directory | ||
1305 | name. | ||
1306 | </note> | ||
1307 | </para> | ||
1308 | </glossdef> | ||
1309 | </glossentry> | ||
1310 | |||
1311 | <glossentry id='var-bb-BBMULTICONFIG'><glossterm>BBMULTICONFIG</glossterm> | ||
1312 | <info> | ||
1313 | BBMULTICONFIG[doc] = "Enables BitBake to perform multiple configuration builds and lists each separate configuration (multiconfig)." | ||
1314 | </info> | ||
1315 | <glossdef> | ||
1316 | <para role="glossdeffirst"> | ||
1317 | <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> | ||
1318 | Enables BitBake to perform multiple configuration builds | ||
1319 | and lists each separate configuration (multiconfig). | ||
1320 | You can use this variable to cause BitBake to build | ||
1321 | multiple targets where each target has a separate | ||
1322 | configuration. | ||
1323 | Define <filename>BBMULTICONFIG</filename> in your | ||
1324 | <filename>conf/local.conf</filename> configuration file. | ||
1325 | </para> | ||
1326 | |||
1327 | <para> | ||
1328 | As an example, the following line specifies three | ||
1329 | multiconfigs, each having a separate configuration file: | ||
1330 | <literallayout class='monospaced'> | ||
1331 | BBMULTIFONFIG = "configA configB configC" | ||
1332 | </literallayout> | ||
1333 | Each configuration file you use must reside in the | ||
1334 | build directory within a directory named | ||
1335 | <filename>conf/multiconfig</filename> (e.g. | ||
1336 | <replaceable>build_directory</replaceable><filename>/conf/multiconfig/configA.conf</filename>). | ||
1337 | </para> | ||
1338 | |||
1339 | <para> | ||
1340 | For information on how to use | ||
1341 | <filename>BBMULTICONFIG</filename> in an environment that | ||
1342 | supports building targets with multiple configurations, | ||
1343 | see the | ||
1344 | "<link linkend='executing-a-multiple-configuration-build'>Executing a Multiple Configuration Build</link>" | ||
1345 | section. | ||
1346 | </para> | ||
1347 | </glossdef> | ||
1348 | </glossentry> | ||
1349 | |||
1350 | <glossentry id='var-bb-BBPATH'><glossterm>BBPATH</glossterm> | ||
1351 | <glossdef> | ||
1352 | <para> | ||
1353 | Used by BitBake to locate class | ||
1354 | (<filename>.bbclass</filename>) and configuration | ||
1355 | (<filename>.conf</filename>) files. | ||
1356 | This variable is analogous to the | ||
1357 | <filename>PATH</filename> variable. | ||
1358 | </para> | ||
1359 | |||
1360 | <para> | ||
1361 | If you run BitBake from a directory outside of the | ||
1362 | build directory, | ||
1363 | you must be sure to set | ||
1364 | <filename>BBPATH</filename> to point to the | ||
1365 | build directory. | ||
1366 | Set the variable as you would any environment variable | ||
1367 | and then run BitBake: | ||
1368 | <literallayout class='monospaced'> | ||
1369 | $ BBPATH="<replaceable>build_directory</replaceable>" | ||
1370 | $ export BBPATH | ||
1371 | $ bitbake <replaceable>target</replaceable> | ||
1372 | </literallayout> | ||
1373 | </para> | ||
1374 | </glossdef> | ||
1375 | </glossentry> | ||
1376 | |||
1377 | <glossentry id='var-bb-BBSERVER'><glossterm>BBSERVER</glossterm> | ||
1378 | <glossdef> | ||
1379 | <para> | ||
1380 | Points to the server that runs memory-resident BitBake. | ||
1381 | The variable is only used when you employ memory-resident | ||
1382 | BitBake. | ||
1383 | </para> | ||
1384 | </glossdef> | ||
1385 | </glossentry> | ||
1386 | |||
1387 | <glossentry id='var-bb-BBTARGETS'><glossterm>BBTARGETS</glossterm> | ||
1388 | <glossdef> | ||
1389 | <para> | ||
1390 | Allows you to use a configuration file to add to the list | ||
1391 | of command-line target recipes you want to build. | ||
1392 | </para> | ||
1393 | </glossdef> | ||
1394 | </glossentry> | ||
1395 | |||
1396 | <glossentry id='var-bb-BBVERSIONS'><glossterm>BBVERSIONS</glossterm> | ||
1397 | <glossdef> | ||
1398 | <para> | ||
1399 | Allows a single recipe to build multiple versions of a | ||
1400 | project from a single recipe file. | ||
1401 | You also able to specify conditional metadata | ||
1402 | using the | ||
1403 | <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link> | ||
1404 | mechanism for a single version or for an optionally named | ||
1405 | range of versions. | ||
1406 | </para> | ||
1407 | |||
1408 | <para> | ||
1409 | For more information on <filename>BBVERSIONS</filename>, | ||
1410 | see the | ||
1411 | "<link linkend='variants-class-extension-mechanism'>Variants - Class Extension Mechanism</link>" | ||
1412 | section. | ||
1413 | </para> | ||
1414 | </glossdef> | ||
1415 | </glossentry> | ||
1416 | |||
1417 | <glossentry id='var-bb-BITBAKE_UI'><glossterm>BITBAKE_UI</glossterm> | ||
1418 | <glossdef> | ||
1419 | <para> | ||
1420 | Used to specify the UI module to use when running BitBake. | ||
1421 | Using this variable is equivalent to using the | ||
1422 | <filename>-u</filename> command-line option. | ||
1423 | <note> | ||
1424 | You must set this variable in the external environment | ||
1425 | in order for it to work. | ||
1426 | </note> | ||
1427 | </para> | ||
1428 | </glossdef> | ||
1429 | </glossentry> | ||
1430 | |||
1431 | <glossentry id='var-bb-BUILDNAME'><glossterm>BUILDNAME</glossterm> | ||
1432 | <glossdef> | ||
1433 | <para> | ||
1434 | A name assigned to the build. | ||
1435 | The name defaults to a datetime stamp of when the build was | ||
1436 | started but can be defined by the metadata. | ||
1437 | </para> | ||
1438 | </glossdef> | ||
1439 | </glossentry> | ||
1440 | |||
1441 | <glossentry id='var-bb-BZRDIR'><glossterm>BZRDIR</glossterm> | ||
1442 | <glossdef> | ||
1443 | <para> | ||
1444 | The directory in which files checked out of a Bazaar | ||
1445 | system are stored. | ||
1446 | </para> | ||
1447 | </glossdef> | ||
1448 | </glossentry> | ||
1449 | |||
1450 | </glossdiv> | ||
1451 | |||
1452 | <glossdiv id='var-bb-glossary-c'><title>C</title> | ||
1453 | |||
1454 | <glossentry id='var-bb-CACHE'><glossterm>CACHE</glossterm> | ||
1455 | <glossdef> | ||
1456 | <para> | ||
1457 | Specifies the directory BitBake uses to store a cache | ||
1458 | of the metadata so it does not need to be parsed every | ||
1459 | time BitBake is started. | ||
1460 | </para> | ||
1461 | </glossdef> | ||
1462 | </glossentry> | ||
1463 | |||
1464 | <glossentry id='var-bb-CVSDIR'><glossterm>CVSDIR</glossterm> | ||
1465 | <glossdef> | ||
1466 | <para> | ||
1467 | The directory in which files checked out under the | ||
1468 | CVS system are stored. | ||
1469 | </para> | ||
1470 | </glossdef> | ||
1471 | </glossentry> | ||
1472 | |||
1473 | </glossdiv> | ||
1474 | |||
1475 | <glossdiv id='var-bb-glossary-d'><title>D</title> | ||
1476 | |||
1477 | <glossentry id='var-bb-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm> | ||
1478 | <glossdef> | ||
1479 | <para> | ||
1480 | Specifies a weak bias for recipe selection priority. | ||
1481 | </para> | ||
1482 | <para> | ||
1483 | The most common usage of this is variable is to set | ||
1484 | it to "-1" within a recipe for a development version of a | ||
1485 | piece of software. | ||
1486 | Using the variable in this way causes the stable version | ||
1487 | of the recipe to build by default in the absence of | ||
1488 | <filename><link linkend='var-bb-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename> | ||
1489 | being used to build the development version. | ||
1490 | </para> | ||
1491 | <note> | ||
1492 | The bias provided by <filename>DEFAULT_PREFERENCE</filename> | ||
1493 | is weak and is overridden by | ||
1494 | <filename><link linkend='var-bb-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename> | ||
1495 | if that variable is different between two layers | ||
1496 | that contain different versions of the same recipe. | ||
1497 | </note> | ||
1498 | </glossdef> | ||
1499 | </glossentry> | ||
1500 | |||
1501 | <glossentry id='var-bb-DEPENDS'><glossterm>DEPENDS</glossterm> | ||
1502 | <glossdef> | ||
1503 | <para> | ||
1504 | Lists a recipe's build-time dependencies | ||
1505 | (i.e. other recipe files). | ||
1506 | </para> | ||
1507 | |||
1508 | <para> | ||
1509 | Consider this simple example for two recipes named "a" and | ||
1510 | "b" that produce similarly named packages. | ||
1511 | In this example, the <filename>DEPENDS</filename> | ||
1512 | statement appears in the "a" recipe: | ||
1513 | <literallayout class='monospaced'> | ||
1514 | DEPENDS = "b" | ||
1515 | </literallayout> | ||
1516 | Here, the dependency is such that the | ||
1517 | <filename>do_configure</filename> task for recipe "a" | ||
1518 | depends on the <filename>do_populate_sysroot</filename> | ||
1519 | task of recipe "b". | ||
1520 | This means anything that recipe "b" puts into sysroot | ||
1521 | is available when recipe "a" is configuring itself. | ||
1522 | </para> | ||
1523 | |||
1524 | <para> | ||
1525 | For information on runtime dependencies, see the | ||
1526 | <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link> | ||
1527 | variable. | ||
1528 | </para> | ||
1529 | </glossdef> | ||
1530 | </glossentry> | ||
1531 | |||
1532 | <glossentry id='var-bb-DESCRIPTION'><glossterm>DESCRIPTION</glossterm> | ||
1533 | <glossdef> | ||
1534 | <para> | ||
1535 | A long description for the recipe. | ||
1536 | </para> | ||
1537 | </glossdef> | ||
1538 | </glossentry> | ||
1539 | |||
1540 | <glossentry id='var-bb-DL_DIR'><glossterm>DL_DIR</glossterm> | ||
1541 | <glossdef> | ||
1542 | <para> | ||
1543 | The central download directory used by the build process to | ||
1544 | store downloads. | ||
1545 | By default, <filename>DL_DIR</filename> gets files | ||
1546 | suitable for mirroring for everything except Git | ||
1547 | repositories. | ||
1548 | If you want tarballs of Git repositories, use the | ||
1549 | <link linkend='var-bb-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link> | ||
1550 | variable. | ||
1551 | </para> | ||
1552 | </glossdef> | ||
1553 | |||
1554 | </glossentry> | ||
1555 | </glossdiv> | ||
1556 | |||
1557 | <glossdiv id='var-bb-glossary-e'><title>E</title> | ||
1558 | |||
1559 | <glossentry id='var-bb-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm> | ||
1560 | <glossdef> | ||
1561 | <para> | ||
1562 | Directs BitBake to exclude a recipe from world builds (i.e. | ||
1563 | <filename>bitbake world</filename>). | ||
1564 | During world builds, BitBake locates, parses and builds all | ||
1565 | recipes found in every layer exposed in the | ||
1566 | <filename>bblayers.conf</filename> configuration file. | ||
1567 | </para> | ||
1568 | |||
1569 | <para> | ||
1570 | To exclude a recipe from a world build using this variable, | ||
1571 | set the variable to "1" in the recipe. | ||
1572 | </para> | ||
1573 | |||
1574 | <note> | ||
1575 | Recipes added to <filename>EXCLUDE_FROM_WORLD</filename> | ||
1576 | may still be built during a world build in order to satisfy | ||
1577 | dependencies of other recipes. | ||
1578 | Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename> | ||
1579 | only ensures that the recipe is not explicitly added | ||
1580 | to the list of build targets in a world build. | ||
1581 | </note> | ||
1582 | </glossdef> | ||
1583 | </glossentry> | ||
1584 | |||
1585 | </glossdiv> | ||
1586 | |||
1587 | <glossdiv id='var-bb-glossary-f'><title>F</title> | ||
1588 | |||
1589 | <glossentry id='var-bb-FAKEROOT'><glossterm>FAKEROOT</glossterm> | ||
1590 | <glossdef> | ||
1591 | <para> | ||
1592 | Contains the command to use when running a shell script | ||
1593 | in a fakeroot environment. | ||
1594 | The <filename>FAKEROOT</filename> variable is obsolete | ||
1595 | and has been replaced by the other | ||
1596 | <filename>FAKEROOT*</filename> variables. | ||
1597 | See these entries in the glossary for more information. | ||
1598 | </para> | ||
1599 | </glossdef> | ||
1600 | </glossentry> | ||
1601 | |||
1602 | <glossentry id='var-bb-FAKEROOTBASEENV'><glossterm>FAKEROOTBASEENV</glossterm> | ||
1603 | <glossdef> | ||
1604 | <para> | ||
1605 | Lists environment variables to set when executing | ||
1606 | the command defined by | ||
1607 | <link linkend='var-bb-FAKEROOTCMD'><filename>FAKEROOTCMD</filename></link> | ||
1608 | that starts the bitbake-worker process | ||
1609 | in the fakeroot environment. | ||
1610 | </para> | ||
1611 | </glossdef> | ||
1612 | </glossentry> | ||
1613 | |||
1614 | <glossentry id='var-bb-FAKEROOTCMD'><glossterm>FAKEROOTCMD</glossterm> | ||
1615 | <glossdef> | ||
1616 | <para> | ||
1617 | Contains the command that starts the bitbake-worker | ||
1618 | process in the fakeroot environment. | ||
1619 | </para> | ||
1620 | </glossdef> | ||
1621 | </glossentry> | ||
1622 | |||
1623 | <glossentry id='var-bb-FAKEROOTDIRS'><glossterm>FAKEROOTDIRS</glossterm> | ||
1624 | <glossdef> | ||
1625 | <para> | ||
1626 | Lists directories to create before running a task in | ||
1627 | the fakeroot environment. | ||
1628 | </para> | ||
1629 | </glossdef> | ||
1630 | </glossentry> | ||
1631 | |||
1632 | <glossentry id='var-bb-FAKEROOTENV'><glossterm>FAKEROOTENV</glossterm> | ||
1633 | <glossdef> | ||
1634 | <para> | ||
1635 | Lists environment variables to set when running a task | ||
1636 | in the fakeroot environment. | ||
1637 | For additional information on environment variables and | ||
1638 | the fakeroot environment, see the | ||
1639 | <link linkend='var-bb-FAKEROOTBASEENV'><filename>FAKEROOTBASEENV</filename></link> | ||
1640 | variable. | ||
1641 | </para> | ||
1642 | </glossdef> | ||
1643 | </glossentry> | ||
1644 | |||
1645 | <glossentry id='var-bb-FAKEROOTNOENV'><glossterm>FAKEROOTNOENV</glossterm> | ||
1646 | <glossdef> | ||
1647 | <para> | ||
1648 | Lists environment variables to set when running a task | ||
1649 | that is not in the fakeroot environment. | ||
1650 | For additional information on environment variables and | ||
1651 | the fakeroot environment, see the | ||
1652 | <link linkend='var-bb-FAKEROOTENV'><filename>FAKEROOTENV</filename></link> | ||
1653 | variable. | ||
1654 | </para> | ||
1655 | </glossdef> | ||
1656 | </glossentry> | ||
1657 | |||
1658 | <glossentry id='var-bb-FETCHCMD'><glossterm>FETCHCMD</glossterm> | ||
1659 | <glossdef> | ||
1660 | <para> | ||
1661 | Defines the command the BitBake fetcher module | ||
1662 | executes when running fetch operations. | ||
1663 | You need to use an override suffix when you use the | ||
1664 | variable (e.g. <filename>FETCHCMD_git</filename> | ||
1665 | or <filename>FETCHCMD_svn</filename>). | ||
1666 | </para> | ||
1667 | </glossdef> | ||
1668 | </glossentry> | ||
1669 | |||
1670 | <glossentry id='var-bb-FILE'><glossterm>FILE</glossterm> | ||
1671 | <glossdef> | ||
1672 | <para> | ||
1673 | Points at the current file. | ||
1674 | BitBake sets this variable during the parsing process | ||
1675 | to identify the file being parsed. | ||
1676 | BitBake also sets this variable when a recipe is being | ||
1677 | executed to identify the recipe file. | ||
1678 | </para> | ||
1679 | </glossdef> | ||
1680 | </glossentry> | ||
1681 | |||
1682 | <glossentry id='var-bb-FILESPATH'><glossterm>FILESPATH</glossterm> | ||
1683 | <glossdef> | ||
1684 | <para> | ||
1685 | Specifies directories BitBake uses when searching for | ||
1686 | patches and files. | ||
1687 | The "local" fetcher module uses these directories when | ||
1688 | handling <filename>file://</filename> URLs. | ||
1689 | The variable behaves like a shell <filename>PATH</filename> | ||
1690 | environment variable. | ||
1691 | The value is a colon-separated list of directories that | ||
1692 | are searched left-to-right in order. | ||
1693 | </para> | ||
1694 | </glossdef> | ||
1695 | </glossentry> | ||
1696 | |||
1697 | </glossdiv> | ||
1698 | |||
1699 | |||
1700 | <glossdiv id='var-bb-glossary-g'><title>G</title> | ||
1701 | |||
1702 | <glossentry id='var-bb-GITDIR'><glossterm>GITDIR</glossterm> | ||
1703 | <glossdef> | ||
1704 | <para> | ||
1705 | The directory in which a local copy of a Git repository | ||
1706 | is stored when it is cloned. | ||
1707 | </para> | ||
1708 | </glossdef> | ||
1709 | </glossentry> | ||
1710 | |||
1711 | </glossdiv> | ||
1712 | |||
1713 | |||
1714 | <glossdiv id='var-bb-glossary-h'><title>H</title> | ||
1715 | |||
1716 | <glossentry id='var-bb-HGDIR'><glossterm>HGDIR</glossterm> | ||
1717 | <glossdef> | ||
1718 | <para> | ||
1719 | The directory in which files checked out of a Mercurial | ||
1720 | system are stored. | ||
1721 | </para> | ||
1722 | </glossdef> | ||
1723 | </glossentry> | ||
1724 | |||
1725 | <glossentry id='var-bb-HOMEPAGE'><glossterm>HOMEPAGE</glossterm> | ||
1726 | <glossdef> | ||
1727 | <para>Website where more information about the software the recipe is building | ||
1728 | can be found.</para> | ||
1729 | </glossdef> | ||
1730 | </glossentry> | ||
1731 | |||
1732 | </glossdiv> | ||
1733 | |||
1734 | <glossdiv id='var-bb-glossary-i'><title>I</title> | ||
1735 | |||
1736 | <glossentry id='var-bb-INHERIT'><glossterm>INHERIT</glossterm> | ||
1737 | <glossdef> | ||
1738 | <para> | ||
1739 | Causes the named class or classes to be inherited globally. | ||
1740 | Anonymous functions in the class or classes | ||
1741 | are not executed for the | ||
1742 | base configuration and in each individual recipe. | ||
1743 | The OpenEmbedded build system ignores changes to | ||
1744 | <filename>INHERIT</filename> in individual recipes. | ||
1745 | </para> | ||
1746 | |||
1747 | <para> | ||
1748 | For more information on <filename>INHERIT</filename>, see | ||
1749 | the | ||
1750 | "<link linkend="inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</link>" | ||
1751 | section. | ||
1752 | </para> | ||
1753 | </glossdef> | ||
1754 | </glossentry> | ||
1755 | |||
1756 | </glossdiv> | ||
1757 | |||
1758 | <!-- | ||
1759 | <glossdiv id='var-glossary-j'><title>J</title> | ||
1760 | </glossdiv> | ||
1761 | |||
1762 | <glossdiv id='var-glossary-k'><title>K</title> | ||
1763 | </glossdiv> | ||
1764 | --> | ||
1765 | |||
1766 | <glossdiv id='var-bb-glossary-l'><title>L</title> | ||
1767 | |||
1768 | <glossentry id='var-bb-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm> | ||
1769 | <glossdef> | ||
1770 | <para>Lists the layers, separated by spaces, upon which this recipe depends. | ||
1771 | Optionally, you can specify a specific layer version for a dependency | ||
1772 | by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3" | ||
1773 | to be compared against | ||
1774 | <link linkend='var-bb-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename> | ||
1775 | in this case). | ||
1776 | BitBake produces an error if any dependency is missing or | ||
1777 | the version numbers do not match exactly (if specified).</para> | ||
1778 | <para> | ||
1779 | You use this variable in the <filename>conf/layer.conf</filename> file. | ||
1780 | You must also use the specific layer name as a suffix | ||
1781 | to the variable (e.g. <filename>LAYERDEPENDS_mylayer</filename>).</para> | ||
1782 | </glossdef> | ||
1783 | </glossentry> | ||
1784 | |||
1785 | <glossentry id='var-bb-LAYERDIR'><glossterm>LAYERDIR</glossterm> | ||
1786 | <glossdef> | ||
1787 | <para>When used inside the <filename>layer.conf</filename> configuration | ||
1788 | file, this variable provides the path of the current layer. | ||
1789 | This variable is not available outside of <filename>layer.conf</filename> | ||
1790 | and references are expanded immediately when parsing of the file completes.</para> | ||
1791 | </glossdef> | ||
1792 | </glossentry> | ||
1793 | |||
1794 | <glossentry id='var-bb-LAYERDIR_RE'><glossterm>LAYERDIR_RE</glossterm> | ||
1795 | <glossdef> | ||
1796 | <para>When used inside the <filename>layer.conf</filename> configuration | ||
1797 | file, this variable provides the path of the current layer, | ||
1798 | escaped for use in a regular expression | ||
1799 | (<link linkend='var-bb-BBFILE_PATTERN'><filename>BBFILE_PATTERN</filename></link>). | ||
1800 | This variable is not available outside of <filename>layer.conf</filename> | ||
1801 | and references are expanded immediately when parsing of the file completes.</para> | ||
1802 | </glossdef> | ||
1803 | </glossentry> | ||
1804 | |||
1805 | <glossentry id='var-bb-LAYERVERSION'><glossterm>LAYERVERSION</glossterm> | ||
1806 | <glossdef> | ||
1807 | <para>Optionally specifies the version of a layer as a single number. | ||
1808 | You can use this variable within | ||
1809 | <link linkend='var-bb-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link> | ||
1810 | for another layer in order to depend on a specific version | ||
1811 | of the layer.</para> | ||
1812 | <para> | ||
1813 | You use this variable in the <filename>conf/layer.conf</filename> file. | ||
1814 | You must also use the specific layer name as a suffix | ||
1815 | to the variable (e.g. <filename>LAYERDEPENDS_mylayer</filename>).</para> | ||
1816 | </glossdef> | ||
1817 | </glossentry> | ||
1818 | |||
1819 | <glossentry id='var-bb-LICENSE'><glossterm>LICENSE</glossterm> | ||
1820 | <glossdef> | ||
1821 | <para> | ||
1822 | The list of source licenses for the recipe. | ||
1823 | </para> | ||
1824 | </glossdef> | ||
1825 | </glossentry> | ||
1826 | |||
1827 | </glossdiv> | ||
1828 | |||
1829 | <glossdiv id='var-bb-glossary-m'><title>M</title> | ||
1830 | |||
1831 | <glossentry id='var-bb-MIRRORS'><glossterm>MIRRORS</glossterm> | ||
1832 | <glossdef> | ||
1833 | <para> | ||
1834 | Specifies additional paths from which BitBake gets source code. | ||
1835 | When the build system searches for source code, it first | ||
1836 | tries the local download directory. | ||
1837 | If that location fails, the build system tries locations | ||
1838 | defined by | ||
1839 | <link linkend='var-bb-PREMIRRORS'><filename>PREMIRRORS</filename></link>, | ||
1840 | the upstream source, and then locations specified by | ||
1841 | <filename>MIRRORS</filename> in that order. | ||
1842 | </para> | ||
1843 | </glossdef> | ||
1844 | </glossentry> | ||
1845 | |||
1846 | <glossentry id='var-bb-MULTI_PROVIDER_WHITELIST'><glossterm>MULTI_PROVIDER_WHITELIST</glossterm> | ||
1847 | <glossdef> | ||
1848 | <para> | ||
1849 | Allows you to suppress BitBake warnings caused when | ||
1850 | building two separate recipes that provide the same | ||
1851 | output. | ||
1852 | </para> | ||
1853 | |||
1854 | <para> | ||
1855 | BitBake normally issues a warning when building two | ||
1856 | different recipes where each provides the same output. | ||
1857 | This scenario is usually something the user does not | ||
1858 | want. | ||
1859 | However, cases do exist where it makes sense, particularly | ||
1860 | in the <filename>virtual/*</filename> namespace. | ||
1861 | You can use this variable to suppress BitBake's warnings. | ||
1862 | </para> | ||
1863 | |||
1864 | <para> | ||
1865 | To use the variable, list provider names (e.g. | ||
1866 | recipe names, <filename>virtual/kernel</filename>, | ||
1867 | and so forth). | ||
1868 | </para> | ||
1869 | </glossdef> | ||
1870 | </glossentry> | ||
1871 | |||
1872 | </glossdiv> | ||
1873 | |||
1874 | <!-- | ||
1875 | <glossdiv id='var-glossary-n'><title>N</title> | ||
1876 | </glossdiv> | ||
1877 | --> | ||
1878 | |||
1879 | <glossdiv id='var-bb-glossary-o'><title>O</title> | ||
1880 | |||
1881 | <glossentry id='var-bb-OVERRIDES'><glossterm>OVERRIDES</glossterm> | ||
1882 | <glossdef> | ||
1883 | <para> | ||
1884 | BitBake uses <filename>OVERRIDES</filename> to control | ||
1885 | what variables are overridden after BitBake parses | ||
1886 | recipes and configuration files. | ||
1887 | </para> | ||
1888 | |||
1889 | <para> | ||
1890 | Following is a simple example that uses an overrides | ||
1891 | list based on machine architectures: | ||
1892 | <literallayout class='monospaced'> | ||
1893 | OVERRIDES = "arm:x86:mips:powerpc" | ||
1894 | </literallayout> | ||
1895 | You can find information on how to use | ||
1896 | <filename>OVERRIDES</filename> in the | ||
1897 | "<link linkend='conditional-syntax-overrides'>Conditional Syntax (Overrides)</link>" | ||
1898 | section. | ||
1899 | </para> | ||
1900 | </glossdef> | ||
1901 | </glossentry> | ||
1902 | </glossdiv> | ||
1903 | |||
1904 | <glossdiv id='var-bb-glossary-p'><title>P</title> | ||
1905 | |||
1906 | <glossentry id='var-bb-P4DIR'><glossterm>P4DIR</glossterm> | ||
1907 | <glossdef> | ||
1908 | <para> | ||
1909 | The directory in which a local copy of a Perforce depot | ||
1910 | is stored when it is fetched. | ||
1911 | </para> | ||
1912 | </glossdef> | ||
1913 | </glossentry> | ||
1914 | |||
1915 | <glossentry id='var-bb-PACKAGES'><glossterm>PACKAGES</glossterm> | ||
1916 | <glossdef> | ||
1917 | <para>The list of packages the recipe creates. | ||
1918 | </para> | ||
1919 | </glossdef> | ||
1920 | </glossentry> | ||
1921 | |||
1922 | <glossentry id='var-bb-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm> | ||
1923 | <glossdef> | ||
1924 | <para> | ||
1925 | A promise that your recipe satisfies runtime dependencies | ||
1926 | for optional modules that are found in other recipes. | ||
1927 | <filename>PACKAGES_DYNAMIC</filename> | ||
1928 | does not actually satisfy the dependencies, it only states that | ||
1929 | they should be satisfied. | ||
1930 | For example, if a hard, runtime dependency | ||
1931 | (<link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link>) | ||
1932 | of another package is satisfied during the build | ||
1933 | through the <filename>PACKAGES_DYNAMIC</filename> | ||
1934 | variable, but a package with the module name is never actually | ||
1935 | produced, then the other package will be broken. | ||
1936 | </para> | ||
1937 | </glossdef> | ||
1938 | </glossentry> | ||
1939 | |||
1940 | <glossentry id='var-bb-PE'><glossterm>PE</glossterm> | ||
1941 | <glossdef> | ||
1942 | <para> | ||
1943 | The epoch of the recipe. | ||
1944 | By default, this variable is unset. | ||
1945 | The variable is used to make upgrades possible when the | ||
1946 | versioning scheme changes in some backwards incompatible | ||
1947 | way. | ||
1948 | </para> | ||
1949 | </glossdef> | ||
1950 | </glossentry> | ||
1951 | |||
1952 | <glossentry id='var-bb-PERSISTENT_DIR'><glossterm>PERSISTENT_DIR</glossterm> | ||
1953 | <glossdef> | ||
1954 | <para> | ||
1955 | Specifies the directory BitBake uses to store data that | ||
1956 | should be preserved between builds. | ||
1957 | In particular, the data stored is the data that uses | ||
1958 | BitBake's persistent data API and the data used by the | ||
1959 | PR Server and PR Service. | ||
1960 | </para> | ||
1961 | </glossdef> | ||
1962 | </glossentry> | ||
1963 | |||
1964 | <glossentry id='var-bb-PF'><glossterm>PF</glossterm> | ||
1965 | <glossdef> | ||
1966 | <para> | ||
1967 | Specifies the recipe or package name and includes all version and revision | ||
1968 | numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and | ||
1969 | <filename>bash-4.2-r1/</filename>). | ||
1970 | </para> | ||
1971 | </glossdef> | ||
1972 | </glossentry> | ||
1973 | |||
1974 | <glossentry id='var-bb-PN'><glossterm>PN</glossterm> | ||
1975 | <glossdef> | ||
1976 | <para>The recipe name.</para> | ||
1977 | </glossdef> | ||
1978 | </glossentry> | ||
1979 | |||
1980 | <glossentry id='var-bb-PR'><glossterm>PR</glossterm> | ||
1981 | <glossdef> | ||
1982 | <para>The revision of the recipe. | ||
1983 | </para> | ||
1984 | </glossdef> | ||
1985 | </glossentry> | ||
1986 | |||
1987 | <glossentry id='var-bb-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm> | ||
1988 | <glossdef> | ||
1989 | <para> | ||
1990 | Determines which recipe should be given preference when | ||
1991 | multiple recipes provide the same item. | ||
1992 | You should always suffix the variable with the name of the | ||
1993 | provided item, and you should set it to the | ||
1994 | <link linkend='var-bb-PN'><filename>PN</filename></link> | ||
1995 | of the recipe to which you want to give precedence. | ||
1996 | Some examples: | ||
1997 | <literallayout class='monospaced'> | ||
1998 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" | ||
1999 | PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" | ||
2000 | PREFERRED_PROVIDER_virtual/libgl ?= "mesa" | ||
2001 | </literallayout> | ||
2002 | </para> | ||
2003 | </glossdef> | ||
2004 | </glossentry> | ||
2005 | |||
2006 | <glossentry id='var-bb-PREFERRED_PROVIDERS'><glossterm>PREFERRED_PROVIDERS</glossterm> | ||
2007 | <glossdef> | ||
2008 | <para> | ||
2009 | Determines which recipe should be given preference for | ||
2010 | cases where multiple recipes provide the same item. | ||
2011 | Functionally, | ||
2012 | <filename>PREFERRED_PROVIDERS</filename> is identical to | ||
2013 | <link linkend='var-bb-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>. | ||
2014 | However, the <filename>PREFERRED_PROVIDERS</filename> | ||
2015 | variable lets you define preferences for multiple | ||
2016 | situations using the following form: | ||
2017 | <literallayout class='monospaced'> | ||
2018 | PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..." | ||
2019 | </literallayout> | ||
2020 | This form is a convenient replacement for the following: | ||
2021 | <literallayout class='monospaced'> | ||
2022 | PREFERRED_PROVIDER_xxx = "yyy" | ||
2023 | PREFERRED_PROVIDER_aaa = "bbb" | ||
2024 | </literallayout> | ||
2025 | </para> | ||
2026 | </glossdef> | ||
2027 | </glossentry> | ||
2028 | |||
2029 | <glossentry id='var-bb-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm> | ||
2030 | <glossdef> | ||
2031 | <para> | ||
2032 | If there are multiple versions of recipes available, this | ||
2033 | variable determines which recipe should be given preference. | ||
2034 | You must always suffix the variable with the | ||
2035 | <link linkend='var-bb-PN'><filename>PN</filename></link> | ||
2036 | you want to select, and you should set | ||
2037 | <link linkend='var-bb-PV'><filename>PV</filename></link> | ||
2038 | accordingly for precedence. | ||
2039 | </para> | ||
2040 | |||
2041 | <para> | ||
2042 | The <filename>PREFERRED_VERSION</filename> variable | ||
2043 | supports limited wildcard use through the | ||
2044 | "<filename>%</filename>" character. | ||
2045 | You can use the character to match any number of | ||
2046 | characters, which can be useful when specifying versions | ||
2047 | that contain long revision numbers that potentially change. | ||
2048 | Here are two examples: | ||
2049 | <literallayout class='monospaced'> | ||
2050 | PREFERRED_VERSION_python = "2.7.3" | ||
2051 | PREFERRED_VERSION_linux-yocto = "4.12%" | ||
2052 | </literallayout> | ||
2053 | <note><title>Important</title> | ||
2054 | The use of the "<filename>%</filename>" character | ||
2055 | is limited in that it only works at the end of the | ||
2056 | string. | ||
2057 | You cannot use the wildcard character in any other | ||
2058 | location of the string. | ||
2059 | </note> | ||
2060 | </para> | ||
2061 | </glossdef> | ||
2062 | </glossentry> | ||
2063 | |||
2064 | <glossentry id='var-bb-PREMIRRORS'><glossterm>PREMIRRORS</glossterm> | ||
2065 | <glossdef> | ||
2066 | <para> | ||
2067 | Specifies additional paths from which BitBake gets source code. | ||
2068 | When the build system searches for source code, it first | ||
2069 | tries the local download directory. | ||
2070 | If that location fails, the build system tries locations | ||
2071 | defined by <filename>PREMIRRORS</filename>, the upstream | ||
2072 | source, and then locations specified by | ||
2073 | <link linkend='var-bb-MIRRORS'><filename>MIRRORS</filename></link> | ||
2074 | in that order. | ||
2075 | </para> | ||
2076 | |||
2077 | <para> | ||
2078 | Typically, you would add a specific server for the | ||
2079 | build system to attempt before any others by adding | ||
2080 | something like the following to your configuration: | ||
2081 | <literallayout class='monospaced'> | ||
2082 | PREMIRRORS_prepend = "\ | ||
2083 | git://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
2084 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
2085 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
2086 | https://.*/.* http://www.yoctoproject.org/sources/ \n" | ||
2087 | </literallayout> | ||
2088 | These changes cause the build system to intercept | ||
2089 | Git, FTP, HTTP, and HTTPS requests and direct them to | ||
2090 | the <filename>http://</filename> sources mirror. | ||
2091 | You can use <filename>file://</filename> URLs to point | ||
2092 | to local directories or network shares as well. | ||
2093 | </para> | ||
2094 | </glossdef> | ||
2095 | </glossentry> | ||
2096 | |||
2097 | <glossentry id='var-bb-PROVIDES'><glossterm>PROVIDES</glossterm> | ||
2098 | <glossdef> | ||
2099 | <para> | ||
2100 | A list of aliases by which a particular recipe can be | ||
2101 | known. | ||
2102 | By default, a recipe's own | ||
2103 | <filename><link linkend='var-bb-PN'>PN</link></filename> | ||
2104 | is implicitly already in its <filename>PROVIDES</filename> | ||
2105 | list. | ||
2106 | If a recipe uses <filename>PROVIDES</filename>, the | ||
2107 | additional aliases are synonyms for the recipe and can | ||
2108 | be useful satisfying dependencies of other recipes during | ||
2109 | the build as specified by | ||
2110 | <filename><link linkend='var-bb-DEPENDS'>DEPENDS</link></filename>. | ||
2111 | </para> | ||
2112 | |||
2113 | <para> | ||
2114 | Consider the following example | ||
2115 | <filename>PROVIDES</filename> statement from a recipe | ||
2116 | file <filename>libav_0.8.11.bb</filename>: | ||
2117 | <literallayout class='monospaced'> | ||
2118 | PROVIDES += "libpostproc" | ||
2119 | </literallayout> | ||
2120 | The <filename>PROVIDES</filename> statement results in | ||
2121 | the "libav" recipe also being known as "libpostproc". | ||
2122 | </para> | ||
2123 | |||
2124 | <para> | ||
2125 | In addition to providing recipes under alternate names, | ||
2126 | the <filename>PROVIDES</filename> mechanism is also used | ||
2127 | to implement virtual targets. | ||
2128 | A virtual target is a name that corresponds to some | ||
2129 | particular functionality (e.g. a Linux kernel). | ||
2130 | Recipes that provide the functionality in question list the | ||
2131 | virtual target in <filename>PROVIDES</filename>. | ||
2132 | Recipes that depend on the functionality in question can | ||
2133 | include the virtual target in | ||
2134 | <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> | ||
2135 | to leave the choice of provider open. | ||
2136 | </para> | ||
2137 | |||
2138 | <para> | ||
2139 | Conventionally, virtual targets have names on the form | ||
2140 | "virtual/function" (e.g. "virtual/kernel"). | ||
2141 | The slash is simply part of the name and has no | ||
2142 | syntactical significance. | ||
2143 | </para> | ||
2144 | </glossdef> | ||
2145 | </glossentry> | ||
2146 | |||
2147 | <glossentry id='var-bb-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm> | ||
2148 | <glossdef> | ||
2149 | <para> | ||
2150 | The network based | ||
2151 | <link linkend='var-bb-PR'><filename>PR</filename></link> | ||
2152 | service host and port. | ||
2153 | </para> | ||
2154 | |||
2155 | <para> | ||
2156 | Following is an example of how the <filename>PRSERV_HOST</filename> variable is | ||
2157 | set: | ||
2158 | <literallayout class='monospaced'> | ||
2159 | PRSERV_HOST = "localhost:0" | ||
2160 | </literallayout> | ||
2161 | You must set the variable if you want to automatically | ||
2162 | start a local PR service. | ||
2163 | You can set <filename>PRSERV_HOST</filename> to other | ||
2164 | values to use a remote PR service. | ||
2165 | </para> | ||
2166 | </glossdef> | ||
2167 | </glossentry> | ||
2168 | |||
2169 | <glossentry id='var-bb-PV'><glossterm>PV</glossterm> | ||
2170 | <glossdef> | ||
2171 | <para>The version of the recipe. | ||
2172 | </para> | ||
2173 | </glossdef> | ||
2174 | </glossentry> | ||
2175 | |||
2176 | </glossdiv> | ||
2177 | |||
2178 | <!-- | ||
2179 | <glossdiv id='var-glossary-q'><title>Q</title> | ||
2180 | </glossdiv> | ||
2181 | --> | ||
2182 | |||
2183 | <glossdiv id='var-bb-glossary-r'><title>R</title> | ||
2184 | |||
2185 | <glossentry id='var-bb-RDEPENDS'><glossterm>RDEPENDS</glossterm> | ||
2186 | <glossdef> | ||
2187 | <para> | ||
2188 | Lists a package's runtime dependencies (i.e. other packages) | ||
2189 | that must be installed in order for the built package to run | ||
2190 | correctly. | ||
2191 | If a package in this list cannot be found during the build, | ||
2192 | you will get a build error. | ||
2193 | </para> | ||
2194 | |||
2195 | <para> | ||
2196 | Because the <filename>RDEPENDS</filename> variable applies | ||
2197 | to packages being built, you should always use the variable | ||
2198 | in a form with an attached package name. | ||
2199 | For example, suppose you are building a development package | ||
2200 | that depends on the <filename>perl</filename> package. | ||
2201 | In this case, you would use the following | ||
2202 | <filename>RDEPENDS</filename> statement: | ||
2203 | <literallayout class='monospaced'> | ||
2204 | RDEPENDS_${PN}-dev += "perl" | ||
2205 | </literallayout> | ||
2206 | In the example, the development package depends on | ||
2207 | the <filename>perl</filename> package. | ||
2208 | Thus, the <filename>RDEPENDS</filename> variable has the | ||
2209 | <filename>${PN}-dev</filename> package name as part of the | ||
2210 | variable. | ||
2211 | </para> | ||
2212 | |||
2213 | <para> | ||
2214 | BitBake supports specifying versioned dependencies. | ||
2215 | Although the syntax varies depending on the packaging | ||
2216 | format, BitBake hides these differences from you. | ||
2217 | Here is the general syntax to specify versions with | ||
2218 | the <filename>RDEPENDS</filename> variable: | ||
2219 | <literallayout class='monospaced'> | ||
2220 | RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)" | ||
2221 | </literallayout> | ||
2222 | For <filename>operator</filename>, you can specify the | ||
2223 | following: | ||
2224 | <literallayout class='monospaced'> | ||
2225 | = | ||
2226 | < | ||
2227 | > | ||
2228 | <= | ||
2229 | >= | ||
2230 | </literallayout> | ||
2231 | For example, the following sets up a dependency on version | ||
2232 | 1.2 or greater of the package <filename>foo</filename>: | ||
2233 | <literallayout class='monospaced'> | ||
2234 | RDEPENDS_${PN} = "foo (>= 1.2)" | ||
2235 | </literallayout> | ||
2236 | </para> | ||
2237 | |||
2238 | <para> | ||
2239 | For information on build-time dependencies, see the | ||
2240 | <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> | ||
2241 | variable. | ||
2242 | </para> | ||
2243 | </glossdef> | ||
2244 | </glossentry> | ||
2245 | |||
2246 | <glossentry id='var-bb-REPODIR'><glossterm>REPODIR</glossterm> | ||
2247 | <glossdef> | ||
2248 | <para> | ||
2249 | The directory in which a local copy of a | ||
2250 | <filename>google-repo</filename> directory is stored | ||
2251 | when it is synced. | ||
2252 | </para> | ||
2253 | </glossdef> | ||
2254 | </glossentry> | ||
2255 | |||
2256 | <glossentry id='var-bb-RPROVIDES'><glossterm>RPROVIDES</glossterm> | ||
2257 | <glossdef> | ||
2258 | <para> | ||
2259 | A list of package name aliases that a package also provides. | ||
2260 | These aliases are useful for satisfying runtime dependencies | ||
2261 | of other packages both during the build and on the target | ||
2262 | (as specified by | ||
2263 | <filename><link linkend='var-bb-RDEPENDS'>RDEPENDS</link></filename>). | ||
2264 | </para> | ||
2265 | <para> | ||
2266 | As with all package-controlling variables, you must always | ||
2267 | use the variable in conjunction with a package name override. | ||
2268 | Here is an example: | ||
2269 | <literallayout class='monospaced'> | ||
2270 | RPROVIDES_${PN} = "widget-abi-2" | ||
2271 | </literallayout> | ||
2272 | </para> | ||
2273 | </glossdef> | ||
2274 | </glossentry> | ||
2275 | |||
2276 | <glossentry id='var-bb-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm> | ||
2277 | <glossdef> | ||
2278 | <para> | ||
2279 | A list of packages that extends the usability of a package | ||
2280 | being built. | ||
2281 | The package being built does not depend on this list of | ||
2282 | packages in order to successfully build, but needs them for | ||
2283 | the extended usability. | ||
2284 | To specify runtime dependencies for packages, see the | ||
2285 | <filename><link linkend='var-bb-RDEPENDS'>RDEPENDS</link></filename> | ||
2286 | variable. | ||
2287 | </para> | ||
2288 | |||
2289 | <para> | ||
2290 | BitBake supports specifying versioned recommends. | ||
2291 | Although the syntax varies depending on the packaging | ||
2292 | format, BitBake hides these differences from you. | ||
2293 | Here is the general syntax to specify versions with | ||
2294 | the <filename>RRECOMMENDS</filename> variable: | ||
2295 | <literallayout class='monospaced'> | ||
2296 | RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)" | ||
2297 | </literallayout> | ||
2298 | For <filename>operator</filename>, you can specify the | ||
2299 | following: | ||
2300 | <literallayout class='monospaced'> | ||
2301 | = | ||
2302 | < | ||
2303 | > | ||
2304 | <= | ||
2305 | >= | ||
2306 | </literallayout> | ||
2307 | For example, the following sets up a recommend on version | ||
2308 | 1.2 or greater of the package <filename>foo</filename>: | ||
2309 | <literallayout class='monospaced'> | ||
2310 | RRECOMMENDS_${PN} = "foo (>= 1.2)" | ||
2311 | </literallayout> | ||
2312 | </para> | ||
2313 | </glossdef> | ||
2314 | </glossentry> | ||
2315 | |||
2316 | </glossdiv> | ||
2317 | |||
2318 | <glossdiv id='var-bb-glossary-s'><title>S</title> | ||
2319 | |||
2320 | <glossentry id='var-bb-SECTION'><glossterm>SECTION</glossterm> | ||
2321 | <glossdef> | ||
2322 | <para>The section in which packages should be categorized.</para> | ||
2323 | </glossdef> | ||
2324 | </glossentry> | ||
2325 | |||
2326 | <glossentry id='var-bb-SRC_URI'><glossterm>SRC_URI</glossterm> | ||
2327 | <glossdef> | ||
2328 | <para> | ||
2329 | The list of source files - local or remote. | ||
2330 | This variable tells BitBake which bits | ||
2331 | to pull for the build and how to pull them. | ||
2332 | For example, if the recipe or append file needs to | ||
2333 | fetch a single tarball from the Internet, the recipe or | ||
2334 | append file uses a <filename>SRC_URI</filename> | ||
2335 | entry that specifies that tarball. | ||
2336 | On the other hand, if the recipe or append file needs to | ||
2337 | fetch a tarball and include a custom file, the recipe or | ||
2338 | append file needs an <filename>SRC_URI</filename> variable | ||
2339 | that specifies all those sources.</para> | ||
2340 | <para>The following list explains the available URI protocols: | ||
2341 | <itemizedlist> | ||
2342 | <listitem><para><emphasis><filename>file://</filename> -</emphasis> | ||
2343 | Fetches files, which are usually files shipped with | ||
2344 | the metadata, | ||
2345 | from the local machine. | ||
2346 | The path is relative to the | ||
2347 | <link linkend='var-bb-FILESPATH'><filename>FILESPATH</filename></link> | ||
2348 | variable.</para></listitem> | ||
2349 | <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a | ||
2350 | Bazaar revision control repository.</para></listitem> | ||
2351 | <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a | ||
2352 | Git revision control repository.</para></listitem> | ||
2353 | <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from | ||
2354 | an OSC (OpenSUSE Build service) revision control repository.</para></listitem> | ||
2355 | <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from | ||
2356 | a repo (Git) repository.</para></listitem> | ||
2357 | <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from | ||
2358 | the Internet using HTTP.</para></listitem> | ||
2359 | <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files | ||
2360 | from the Internet using HTTPS.</para></listitem> | ||
2361 | <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files | ||
2362 | from the Internet using FTP.</para></listitem> | ||
2363 | <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from | ||
2364 | a CVS revision control repository.</para></listitem> | ||
2365 | <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from | ||
2366 | a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem> | ||
2367 | <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from | ||
2368 | a Perforce (<filename>p4</filename>) revision control repository.</para></listitem> | ||
2369 | <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from | ||
2370 | a secure shell.</para></listitem> | ||
2371 | <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from | ||
2372 | a Subversion (<filename>svn</filename>) revision control repository.</para></listitem> | ||
2373 | </itemizedlist> | ||
2374 | </para> | ||
2375 | <para>Here are some additional options worth mentioning: | ||
2376 | <itemizedlist> | ||
2377 | <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls | ||
2378 | whether or not to unpack the file if it is an archive. | ||
2379 | The default action is to unpack the file.</para></listitem> | ||
2380 | <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file | ||
2381 | (or extracts its contents) into the specified | ||
2382 | subdirectory. | ||
2383 | This option is useful for unusual tarballs or other archives that | ||
2384 | do not have their files already in a subdirectory within the archive. | ||
2385 | </para></listitem> | ||
2386 | <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a | ||
2387 | name to be used for association with <filename>SRC_URI</filename> checksums | ||
2388 | when you have more than one file specified in <filename>SRC_URI</filename>. | ||
2389 | </para></listitem> | ||
2390 | <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies | ||
2391 | the filename used when storing the downloaded file.</para></listitem> | ||
2392 | </itemizedlist> | ||
2393 | </para> | ||
2394 | </glossdef> | ||
2395 | </glossentry> | ||
2396 | |||
2397 | <glossentry id='var-bb-SRCDATE'><glossterm>SRCDATE</glossterm> | ||
2398 | <glossdef> | ||
2399 | <para> | ||
2400 | The date of the source code used to build the package. | ||
2401 | This variable applies only if the source was fetched from a Source Code Manager (SCM). | ||
2402 | </para> | ||
2403 | </glossdef> | ||
2404 | </glossentry> | ||
2405 | |||
2406 | <glossentry id='var-bb-SRCREV'><glossterm>SRCREV</glossterm> | ||
2407 | <glossdef> | ||
2408 | <para> | ||
2409 | The revision of the source code used to build the package. | ||
2410 | This variable applies only when using Subversion, Git, Mercurial and Bazaar. | ||
2411 | If you want to build a fixed revision and you want | ||
2412 | to avoid performing a query on the remote repository every time | ||
2413 | BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a | ||
2414 | full revision identifier and not just a tag. | ||
2415 | </para> | ||
2416 | </glossdef> | ||
2417 | </glossentry> | ||
2418 | |||
2419 | <glossentry id='var-bb-SRCREV_FORMAT'><glossterm>SRCREV_FORMAT</glossterm> | ||
2420 | <glossdef> | ||
2421 | <para> | ||
2422 | Helps construct valid | ||
2423 | <link linkend='var-bb-SRCREV'><filename>SRCREV</filename></link> | ||
2424 | values when multiple source controlled URLs are used in | ||
2425 | <link linkend='var-bb-SRC_URI'><filename>SRC_URI</filename></link>. | ||
2426 | </para> | ||
2427 | |||
2428 | <para> | ||
2429 | The system needs help constructing these values under these | ||
2430 | circumstances. | ||
2431 | Each component in the <filename>SRC_URI</filename> | ||
2432 | is assigned a name and these are referenced | ||
2433 | in the <filename>SRCREV_FORMAT</filename> variable. | ||
2434 | Consider an example with URLs named "machine" and "meta". | ||
2435 | In this case, <filename>SRCREV_FORMAT</filename> could look | ||
2436 | like "machine_meta" and those names would have the SCM | ||
2437 | versions substituted into each position. | ||
2438 | Only one <filename>AUTOINC</filename> placeholder is added | ||
2439 | and if needed. | ||
2440 | And, this placeholder is placed at the start of the | ||
2441 | returned string. | ||
2442 | </para> | ||
2443 | </glossdef> | ||
2444 | </glossentry> | ||
2445 | |||
2446 | <glossentry id='var-bb-STAMP'><glossterm>STAMP</glossterm> | ||
2447 | <glossdef> | ||
2448 | <para> | ||
2449 | Specifies the base path used to create recipe stamp files. | ||
2450 | The path to an actual stamp file is constructed by evaluating this | ||
2451 | string and then appending additional information. | ||
2452 | </para> | ||
2453 | </glossdef> | ||
2454 | </glossentry> | ||
2455 | |||
2456 | <glossentry id='var-bb-STAMPCLEAN'><glossterm>STAMPCLEAN</glossterm> | ||
2457 | <glossdef> | ||
2458 | <para> | ||
2459 | Specifies the base path used to create recipe stamp files. | ||
2460 | Unlike the | ||
2461 | <link linkend='var-bb-STAMP'><filename>STAMP</filename></link> | ||
2462 | variable, <filename>STAMPCLEAN</filename> can contain | ||
2463 | wildcards to match the range of files a clean operation | ||
2464 | should remove. | ||
2465 | BitBake uses a clean operation to remove any other stamps | ||
2466 | it should be removing when creating a new stamp. | ||
2467 | </para> | ||
2468 | </glossdef> | ||
2469 | </glossentry> | ||
2470 | |||
2471 | <glossentry id='var-bb-SUMMARY'><glossterm>SUMMARY</glossterm> | ||
2472 | <glossdef> | ||
2473 | <para> | ||
2474 | A short summary for the recipe, which is 72 characters or less. | ||
2475 | </para> | ||
2476 | </glossdef> | ||
2477 | </glossentry> | ||
2478 | |||
2479 | <glossentry id='var-bb-SVNDIR'><glossterm>SVNDIR</glossterm> | ||
2480 | <glossdef> | ||
2481 | <para> | ||
2482 | The directory in which files checked out of a Subversion | ||
2483 | system are stored. | ||
2484 | </para> | ||
2485 | </glossdef> | ||
2486 | </glossentry> | ||
2487 | |||
2488 | </glossdiv> | ||
2489 | |||
2490 | <glossdiv id='var-bb-glossary-t'><title>T</title> | ||
2491 | |||
2492 | <glossentry id='var-bb-T'><glossterm>T</glossterm> | ||
2493 | <glossdef> | ||
2494 | <para>Points to a directory were BitBake places | ||
2495 | temporary files, which consist mostly of task logs and | ||
2496 | scripts, when building a particular recipe. | ||
2497 | </para> | ||
2498 | </glossdef> | ||
2499 | </glossentry> | ||
2500 | |||
2501 | <glossentry id='var-bb-TOPDIR'><glossterm>TOPDIR</glossterm> | ||
2502 | <glossdef> | ||
2503 | <para> | ||
2504 | Points to the build directory. | ||
2505 | BitBake automatically sets this variable. | ||
2506 | </para> | ||
2507 | </glossdef> | ||
2508 | </glossentry> | ||
2509 | |||
2510 | </glossdiv> | ||
2511 | |||
2512 | <!-- | ||
2513 | <glossdiv id='var-glossary-u'><title>U</title> | ||
2514 | </glossdiv> | ||
2515 | |||
2516 | <glossdiv id='var-glossary-v'><title>V</title> | ||
2517 | </glossdiv> | ||
2518 | |||
2519 | <glossdiv id='var-glossary-w'><title>W</title> | ||
2520 | </glossdiv> | ||
2521 | |||
2522 | <glossdiv id='var-glossary-x'><title>X</title> | ||
2523 | </glossdiv> | ||
2524 | |||
2525 | <glossdiv id='var-glossary-y'><title>Y</title> | ||
2526 | </glossdiv> | ||
2527 | |||
2528 | <glossdiv id='var-glossary-z'><title>Z</title> | ||
2529 | </glossdiv> | ||
2530 | --> | ||
2531 | |||
2532 | |||
2533 | </glossary> | ||
2534 | </chapter> | ||
2535 | <!-- | ||
2536 | vim: expandtab tw=80 ts=4 | ||
2537 | --> | ||