blob: a84b2bc994b5806926a82cf9ad45a26498ca52ac [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<!-- Dummy chapter -->
6<chapter id='ref-variables-glos'>
7
8<title>Variables Glossary</title>
9
10<para>
11 This chapter lists common variables used 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-variables-glossary'>
38
39 <para>
40 <link linkend='var-ASSUME_PROVIDED'>A</link>
41 <link linkend='var-B'>B</link>
42 <link linkend='var-CACHE'>C</link>
43 <link linkend='var-DEFAULT_PREFERENCE'>D</link>
44 <link linkend='var-EXCLUDE_FROM_WORLD'>E</link>
45 <link linkend='var-FAKEROOT'>F</link>
46 <link linkend='var-GITDIR'>G</link>
47 <link linkend='var-HGDIR'>H</link>
48<!-- <link linkend='var-ICECC_DISABLED'>I</link> -->
49<!-- <link linkend='var-glossary-j'>J</link> -->
50<!-- <link linkend='var-KARCH'>K</link> -->
51 <link linkend='var-LAYERDEPENDS'>L</link>
52 <link linkend='var-MIRRORS'>M</link>
53<!-- <link linkend='var-glossary-n'>N</link> -->
54 <link linkend='var-OVERRIDES'>O</link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060055 <link linkend='var-P4DIR'>P</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050056<!-- <link linkend='var-QMAKE_PROFILES'>Q</link> -->
57 <link linkend='var-RDEPENDS'>R</link>
58 <link linkend='var-SECTION'>S</link>
59 <link linkend='var-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-glossary-a'><title>A</title>
69
70 <glossentry id='var-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm>
71 <glossdef>
72 <para>
73 Lists recipe names
74 (<link linkend='var-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>
Brad Bishop316dfdd2018-06-25 12:45:53 -040081 In OpenEmbedded-Core, <filename>ASSUME_PROVIDED</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050082 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-glossary-b'><title>B</title>
95
96 <glossentry id='var-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_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_NO_NETWORK'><filename>BB_NO_NETWORK</filename></link>
115 is either not set or set to "0".
116 </para></listitem>
117 <listitem><para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800118 Limited support for the "<filename>*</filename>"
119 wildcard character for matching against the
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500120 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>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800128 <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>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500142 </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-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-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_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_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_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_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_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 = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
235
236 where:
237
238 &lt;action&gt; 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_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
249 which must be defined.
250
251 &lt;dir&gt; 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 &lt;threshold&gt; 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_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_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_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 = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
344
345 where:
346
347 &lt;disk_space_interval&gt; 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 &lt;disk_inode_interval&gt; 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_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-BBPATH'><filename>BBPATH</filename></link>,
386 <link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link>,
387 <link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>,
388 and
389 <link linkend='var-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_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_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_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-PREMIRRORS'><filename>PREMIRRORS</filename></link>
421 for files.
422 BitBake will not search the main
423 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
424 or
425 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>.
426 </para>
427 </glossdef>
428 </glossentry>
429
430 <glossentry id='var-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_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-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_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_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_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_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_LOGFMT'><glossterm>BB_LOGFMT</glossterm>
543 <glossdef>
544 <para>
545 Specifies the name of the log files saved into
546 <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}</filename>.
547 By default, the <filename>BB_LOGFMT</filename> variable
548 is undefined and the log file names get created using the
549 following form:
550 <literallayout class='monospaced'>
551 log.{task}.{pid}
552 </literallayout>
553 If you want to force log files to take a specific name,
554 you can set this variable in a configuration file.
555 </para>
556 </glossdef>
557 </glossentry>
558
559 <glossentry id='var-BB_NICE_LEVEL'><glossterm>BB_NICE_LEVEL</glossterm>
560 <glossdef>
561 <para>
562 Allows BitBake to run at a specific priority
563 (i.e. nice level).
564 System permissions usually mean that BitBake can reduce its
565 priority but not raise it again.
566 See
567 <link linkend='var-BB_TASK_NICE_LEVEL'><filename>BB_TASK_NICE_LEVEL</filename></link>
568 for additional information.
569 </para>
570 </glossdef>
571 </glossentry>
572
573 <glossentry id='var-BB_NO_NETWORK'><glossterm>BB_NO_NETWORK</glossterm>
574 <glossdef>
575 <para>
576 Disables network access in the BitBake fetcher modules.
577 With this access disabled, any command that attempts to
578 access the network becomes an error.
579 </para>
580
581 <para>
582 Disabling network access is useful for testing source
583 mirrors, running builds when not connected to the Internet,
584 and when operating in certain kinds of firewall
585 environments.
586 </para>
587 </glossdef>
588 </glossentry>
589
590 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
591 <glossdef>
592 <para>
593 The maximum number of tasks BitBake should run in parallel
594 at any one time.
595 If your host development system supports multiple cores,
596 a good rule of thumb is to set this variable to twice the
597 number of cores.
598 </para>
599 </glossdef>
600 </glossentry>
601
602 <glossentry id='var-BB_NUMBER_PARSE_THREADS'><glossterm>BB_NUMBER_PARSE_THREADS</glossterm>
603 <glossdef>
604 <para>
605 Sets the number of threads BitBake uses when parsing.
606 By default, the number of threads is equal to the number
607 of cores on the system.
608 </para>
609 </glossdef>
610 </glossentry>
611
612 <glossentry id='var-BB_ORIGENV'><glossterm>BB_ORIGENV</glossterm>
613 <glossdef>
614 <para>
615 Contains a copy of the original external environment in
616 which BitBake was run.
617 The copy is taken before any whitelisted variable values
618 are filtered into BitBake's datastore.
619 <note>
620 The contents of this variable is a datastore object
621 that can be queried using the normal datastore
622 operations.
623 </note>
624 </para>
625 </glossdef>
626 </glossentry>
627
628 <glossentry id='var-BB_PRESERVE_ENV'><glossterm>BB_PRESERVE_ENV</glossterm>
629 <glossdef>
630 <para>
631 Disables whitelisting and instead allows all variables
632 through from the external environment into BitBake's
633 datastore.
634 <note>
635 You must set this variable in the external
636 environment in order for it to work.
637 </note>
638 </para>
639 </glossdef>
640 </glossentry>
641
642 <glossentry id='var-BB_RUNFMT'><glossterm>BB_RUNFMT</glossterm>
643 <glossdef>
644 <para>
645 Specifies the name of the executable script files
646 (i.e. run files) saved into
647 <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}</filename>.
648 By default, the <filename>BB_RUNFMT</filename> variable
649 is undefined and the run file names get created using the
650 following form:
651 <literallayout class='monospaced'>
652 run.{task}.{pid}
653 </literallayout>
654 If you want to force run files to take a specific name,
655 you can set this variable in a configuration file.
656 </para>
657 </glossdef>
658 </glossentry>
659
660 <glossentry id='var-BB_RUNTASK'><glossterm>BB_RUNTASK</glossterm>
661 <glossdef>
662 <para>
663 Contains the name of the currently executing task.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800664 The value includes the "do_" prefix.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500665 For example, if the currently executing task is
666 <filename>do_config</filename>, the value is
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800667 "do_config".
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500668 </para>
669 </glossdef>
670 </glossentry>
671
672 <glossentry id='var-BB_SCHEDULER'><glossterm>BB_SCHEDULER</glossterm>
673 <glossdef>
674 <para>
675 Selects the name of the scheduler to use for the
676 scheduling of BitBake tasks.
677 Three options exist:
678 <itemizedlist>
679 <listitem><para><emphasis>basic</emphasis> -
680 The basic framework from which everything derives.
681 Using this option causes tasks to be ordered
682 numerically as they are parsed.
683 </para></listitem>
684 <listitem><para><emphasis>speed</emphasis> -
685 Executes tasks first that have more tasks
686 depending on them.
687 The "speed" option is the default.
688 </para></listitem>
689 <listitem><para><emphasis>completion</emphasis> -
690 Causes the scheduler to try to complete a given
691 recipe once its build has started.
692 </para></listitem>
693 </itemizedlist>
694 </para>
695 </glossdef>
696 </glossentry>
697
698 <glossentry id='var-BB_SCHEDULERS'><glossterm>BB_SCHEDULERS</glossterm>
699 <glossdef>
700 <para>
701 Defines custom schedulers to import.
702 Custom schedulers need to be derived from the
703 <filename>RunQueueScheduler</filename> class.
704 </para>
705
706 <para>
707 For information how to select a scheduler, see the
708 <link linkend='var-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link>
709 variable.
710 </para>
711 </glossdef>
712 </glossentry>
713
714 <glossentry id='var-BB_SETSCENE_DEPVALID'><glossterm>BB_SETSCENE_DEPVALID</glossterm>
715 <glossdef>
716 <para>
717 Specifies a function BitBake calls that determines
718 whether BitBake requires a setscene dependency to be met.
719 </para>
720
721 <para>
722 When running a setscene task, BitBake needs to
723 know which dependencies of that setscene task also need
724 to be run.
725 Whether dependencies also need to be run is highly
726 dependent on the metadata.
727 The function specified by this variable returns a
728 "True" or "False" depending on whether the dependency needs
729 to be met.
730 </para>
731 </glossdef>
732 </glossentry>
733
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600734 <glossentry id='var-BB_SETSCENE_VERIFY_FUNCTION2'><glossterm>BB_SETSCENE_VERIFY_FUNCTION2</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500735 <glossdef>
736 <para>
737 Specifies a function to call that verifies the list of
738 planned task execution before the main task execution
739 happens.
740 The function is called once BitBake has a list of setscene
741 tasks that have run and either succeeded or failed.
742 </para>
743
744 <para>
745 The function allows for a task list check to see if they
746 make sense.
747 Even if BitBake was planning to skip a task, the
748 returned value of the function can force BitBake to run
749 the task, which is necessary under certain metadata
750 defined circumstances.
751 </para>
752 </glossdef>
753 </glossentry>
754
755 <glossentry id='var-BB_SIGNATURE_EXCLUDE_FLAGS'><glossterm>BB_SIGNATURE_EXCLUDE_FLAGS</glossterm>
756 <glossdef>
757 <para>
758 Lists variable flags (varflags)
759 that can be safely excluded from checksum
760 and dependency data for keys in the datastore.
761 When generating checksum or dependency data for keys in the
762 datastore, the flags set against that key are normally
763 included in the checksum.
764 </para>
765
766 <para>
767 For more information on varflags, see the
768 "<link linkend='variable-flags'>Variable Flags</link>"
769 section.
770 </para>
771 </glossdef>
772 </glossentry>
773
774 <glossentry id='var-BB_SIGNATURE_HANDLER'><glossterm>BB_SIGNATURE_HANDLER</glossterm>
775 <glossdef>
776 <para>
777 Defines the name of the signature handler BitBake uses.
778 The signature handler defines the way stamp files are
779 created and handled, if and how the signature is
780 incorporated into the stamps, and how the signature
781 itself is generated.
782 </para>
783
784 <para>
785 A new signature handler can be added by injecting a class
786 derived from the
787 <filename>SignatureGenerator</filename> class into the
788 global namespace.
789 </para>
790 </glossdef>
791 </glossentry>
792
793 <glossentry id='var-BB_SRCREV_POLICY'><glossterm>BB_SRCREV_POLICY</glossterm>
794 <glossdef>
795 <para>
796 Defines the behavior of the fetcher when it interacts with
797 source control systems and dynamic source revisions.
798 The <filename>BB_SRCREV_POLICY</filename> variable is
799 useful when working without a network.
800 </para>
801
802 <para>
803 The variable can be set using one of two policies:
804 <itemizedlist>
805 <listitem><para><emphasis>cache</emphasis> -
806 Retains the value the system obtained previously
807 rather than querying the source control system
808 each time.
809 </para></listitem>
810 <listitem><para><emphasis>clear</emphasis> -
811 Queries the source controls system every time.
812 With this policy, there is no cache.
813 The "clear" policy is the default.
814 </para></listitem>
815 </itemizedlist>
816 </para>
817 </glossdef>
818 </glossentry>
819
820 <glossentry id='var-BB_STAMP_POLICY'><glossterm>BB_STAMP_POLICY</glossterm>
821 <glossdef>
822 <para>
823 Defines the mode used for how timestamps of stamp files
824 are compared.
825 You can set the variable to one of the following modes:
826 <itemizedlist>
827 <listitem><para><emphasis>perfile</emphasis> -
828 Timestamp comparisons are only made
829 between timestamps of a specific recipe.
830 This is the default mode.
831 </para></listitem>
832 <listitem><para><emphasis>full</emphasis> -
833 Timestamp comparisons are made for all
834 dependencies.
835 </para></listitem>
836 <listitem><para><emphasis>whitelist</emphasis> -
837 Identical to "full" mode except timestamp
838 comparisons are made for recipes listed in the
839 <link linkend='var-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link>
840 variable.
841 </para></listitem>
842 </itemizedlist>
843 <note>
844 Stamp policies are largely obsolete with the
845 introduction of setscene tasks.
846 </note>
847 </para>
848 </glossdef>
849 </glossentry>
850
851 <glossentry id='var-BB_STAMP_WHITELIST'><glossterm>BB_STAMP_WHITELIST</glossterm>
852 <glossdef>
853 <para>
854 Lists files whose stamp file timestamps are compared when
855 the stamp policy mode is set to "whitelist".
856 For information on stamp policies, see the
857 <link linkend='var-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link>
858 variable.
859 </para>
860 </glossdef>
861 </glossentry>
862
863 <glossentry id='var-BB_STRICT_CHECKSUM'><glossterm>BB_STRICT_CHECKSUM</glossterm>
864 <glossdef>
865 <para>
866 Sets a more strict checksum mechanism for non-local URLs.
867 Setting this variable to a value causes BitBake
868 to report an error if it encounters a non-local URL
869 that does not have at least one checksum specified.
870 </para>
871 </glossdef>
872 </glossentry>
873
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500874 <glossentry id='var-BB_TASK_IONICE_LEVEL'><glossterm>BB_TASK_IONICE_LEVEL</glossterm>
875 <glossdef>
876 <para>
877 Allows adjustment of a task's Input/Output priority.
878 During Autobuilder testing, random failures can occur
879 for tasks due to I/O starvation.
880 These failures occur during various QEMU runtime timeouts.
881 You can use the <filename>BB_TASK_IONICE_LEVEL</filename>
882 variable to adjust the I/O priority of these tasks.
883 <note>
884 This variable works similarly to the
885 <link linkend='var-BB_TASK_NICE_LEVEL'><filename>BB_TASK_NICE_LEVEL</filename></link>
886 variable except with a task's I/O priorities.
887 </note>
888 </para>
889
890 <para>
891 Set the variable as follows:
892 <literallayout class='monospaced'>
893 BB_TASK_IONICE_LEVEL = "<replaceable>class</replaceable>.<replaceable>prio</replaceable>"
894 </literallayout>
895 For <replaceable>class</replaceable>, the default value is
896 "2", which is a best effort.
897 You can use "1" for realtime and "3" for idle.
898 If you want to use realtime, you must have superuser
899 privileges.
900 </para>
901
902 <para>
903 For <replaceable>prio</replaceable>, you can use any
904 value from "0", which is the highest priority, to "7",
905 which is the lowest.
906 The default value is "4".
907 You do not need any special privileges to use this range
908 of priority values.
909 <note>
910 In order for your I/O priority settings to take effect,
911 you need the Completely Fair Queuing (CFQ) Scheduler
912 selected for the backing block device.
913 To select the scheduler, use the following command form
914 where <replaceable>device</replaceable> is the device
915 (e.g. sda, sdb, and so forth):
916 <literallayout class='monospaced'>
917 $ sudo sh -c “echo cfq > /sys/block/<replaceable>device</replaceable>/queu/scheduler
918 </literallayout>
919 </note>
920 </para>
921 </glossdef>
922 </glossentry>
923
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500924 <glossentry id='var-BB_TASK_NICE_LEVEL'><glossterm>BB_TASK_NICE_LEVEL</glossterm>
925 <glossdef>
926 <para>
927 Allows specific tasks to change their priority
928 (i.e. nice level).
929 </para>
930
931 <para>
932 You can use this variable in combination with task
933 overrides to raise or lower priorities of specific tasks.
934 For example, on the
935 <ulink url='http://www.yoctoproject.org'>Yocto Project</ulink>
936 autobuilder, QEMU emulation in images is given a higher
937 priority as compared to build tasks to ensure that images
938 do not suffer timeouts on loaded systems.
939 </para>
940 </glossdef>
941 </glossentry>
942
943 <glossentry id='var-BB_TASKHASH'><glossterm>BB_TASKHASH</glossterm>
944 <glossdef>
945 <para>
946 Within an executing task, this variable holds the hash
947 of the task as returned by the currently enabled
948 signature generator.
949 </para>
950 </glossdef>
951 </glossentry>
952
953 <glossentry id='var-BB_VERBOSE_LOGS'><glossterm>BB_VERBOSE_LOGS</glossterm>
954 <glossdef>
955 <para>
956 Controls how verbose BitBake is during builds.
957 If set, shell scripts echo commands and shell script output
958 appears on standard out (stdout).
959 </para>
960 </glossdef>
961 </glossentry>
962
963 <glossentry id='var-BB_WORKERCONTEXT'><glossterm>BB_WORKERCONTEXT</glossterm>
964 <glossdef>
965 <para>
966 Specifies if the current context is executing a task.
967 BitBake sets this variable to "1" when a task is
968 being executed.
969 The value is not set when the task is in server context
970 during parsing or event handling.
971 </para>
972 </glossdef>
973 </glossentry>
974
975
976 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
977 <glossdef>
978 <para>
979 Allows you to extend a recipe so that it builds variants
980 of the software.
981 Some examples of these variants for recipes from the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400982 OpenEmbedded-Core metadata are "natives" such as
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500983 <filename>quilt-native</filename>, which is a copy of
984 Quilt built to run on the build system; "crosses" such
985 as <filename>gcc-cross</filename>, which is a compiler
986 built to run on the build machine but produces binaries
987 that run on the target <filename>MACHINE</filename>;
988 "nativesdk", which targets the SDK machine instead of
989 <filename>MACHINE</filename>; and "mulitlibs" in the form
990 "<filename>multilib:</filename><replaceable>multilib_name</replaceable>".
991 </para>
992
993 <para>
994 To build a different variant of the recipe with a minimal
995 amount of code, it usually is as simple as adding the
996 variable to your recipe.
997 Here are two examples.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400998 The "native" variants are from the OpenEmbedded-Core
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500999 metadata:
1000 <literallayout class='monospaced'>
1001 BBCLASSEXTEND =+ "native nativesdk"
1002 BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>"
1003 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001004 <note>
1005 <para>
1006 Internally, the <filename>BBCLASSEXTEND</filename>
1007 mechanism generates recipe variants by rewriting
1008 variable values and applying overrides such as
1009 <filename>_class-native</filename>.
1010 For example, to generate a native version of a recipe,
1011 a
1012 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1013 on "foo" is rewritten to a <filename>DEPENDS</filename>
1014 on "foo-native".
1015 </para>
1016
1017 <para>
1018 Even when using <filename>BBCLASSEXTEND</filename>, the
1019 recipe is only parsed once.
1020 Parsing once adds some limitations.
1021 For example, it is not possible to
1022 include a different file depending on the variant,
1023 since <filename>include</filename> statements are
1024 processed when the recipe is parsed.
1025 </para>
1026 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001027 </para>
1028 </glossdef>
1029 </glossentry>
1030
1031 <glossentry id='var-BBDEBUG'><glossterm>BBDEBUG</glossterm>
1032 <glossdef>
1033 <para>
1034 Sets the BitBake debug output level to a specific value
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001035 as incremented by the <filename>-D</filename> command line
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001036 option.
1037 <note>
1038 You must set this variable in the external environment
1039 in order for it to work.
1040 </note>
1041 </para>
1042 </glossdef>
1043 </glossentry>
1044
1045 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
1046 <glossdef>
1047 <para>Lists the names of configured layers.
1048 These names are used to find the other <filename>BBFILE_*</filename>
1049 variables.
1050 Typically, each layer appends its name to this variable in its
1051 <filename>conf/layer.conf</filename> file.
1052 </para>
1053 </glossdef>
1054 </glossentry>
1055
1056 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
1057 <glossdef>
1058 <para>Variable that expands to match files from
1059 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
1060 in a particular layer.
1061 This variable is used in the <filename>conf/layer.conf</filename> file and must
1062 be suffixed with the name of the specific layer (e.g.
1063 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
1064 </glossdef>
1065 </glossentry>
1066
1067 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
1068 <glossdef>
1069 <para>Assigns the priority for recipe files in each layer.</para>
1070 <para>This variable is useful in situations where the same recipe appears in
1071 more than one layer.
1072 Setting this variable allows you to prioritize a
1073 layer against other layers that contain the same recipe - effectively
1074 letting you control the precedence for the multiple layers.
1075 The precedence established through this variable stands regardless of a
1076 recipe's version
1077 (<link linkend='var-PV'><filename>PV</filename></link> variable).
1078 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
1079 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
1080 lower precedence.</para>
1081 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
1082 precedence.
1083 For example, the value 6 has a higher precedence than the value 5.
1084 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
1085 dependencies (see the
1086 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
1087 more information.
1088 The default priority, if unspecified
1089 for a layer with no dependencies, is the lowest defined priority + 1
1090 (or 1 if no priorities are defined).</para>
1091 <tip>
1092 You can use the command <filename>bitbake-layers show-layers</filename> to list
1093 all configured layers along with their priorities.
1094 </tip>
1095 </glossdef>
1096 </glossentry>
1097
1098 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
1099 <glossdef>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001100 <para>
1101 A space-separated list of recipe files BitBake uses to
1102 build software.
1103 </para>
1104
1105 <para>
1106 When specifying recipe files, you can pattern match using
1107 Python's
1108 <ulink url='https://docs.python.org/3/library/glob.html'><filename>glob</filename></ulink>
1109 syntax.
1110 For details on the syntax, see the documentation by
1111 following the previous link.
1112 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001113 </glossdef>
1114 </glossentry>
1115
1116 <glossentry id='var-BBINCLUDED'><glossterm>BBINCLUDED</glossterm>
1117 <glossdef>
1118 <para>
1119 Contains a space-separated list of all of all files that
1120 BitBake's parser included during parsing of the current
1121 file.
1122 </para>
1123 </glossdef>
1124 </glossentry>
1125
1126 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
1127 <glossdef>
1128 <para>
1129 If set to a value, enables printing the task log when
1130 reporting a failed task.
1131 </para>
1132 </glossdef>
1133 </glossentry>
1134
1135 <glossentry id='var-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm>
1136 <glossdef>
1137 <para>
1138 If
1139 <link linkend='var-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link>
1140 is set, specifies the maximum number of lines from the
1141 task log file to print when reporting a failed task.
1142 If you do not set <filename>BBINCLUDELOGS_LINES</filename>,
1143 the entire log is printed.
1144 </para>
1145 </glossdef>
1146 </glossentry>
1147
1148 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
1149 <glossdef>
1150 <para>Lists the layers to enable during the build.
1151 This variable is defined in the <filename>bblayers.conf</filename> configuration
1152 file in the build directory.
1153 Here is an example:
1154 <literallayout class='monospaced'>
1155 BBLAYERS = " \
1156 /home/scottrif/poky/meta \
1157 /home/scottrif/poky/meta-yocto \
1158 /home/scottrif/poky/meta-yocto-bsp \
1159 /home/scottrif/poky/meta-mykernel \
1160 "
1161
1162 </literallayout>
1163 This example enables four layers, one of which is a custom, user-defined layer
1164 named <filename>meta-mykernel</filename>.
1165 </para>
1166 </glossdef>
1167 </glossentry>
1168
1169 <glossentry id='var-BBLAYERS_FETCH_DIR'><glossterm>BBLAYERS_FETCH_DIR</glossterm>
1170 <glossdef>
1171 <para>
1172 Sets the base location where layers are stored.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001173 This setting is used in conjunction with
1174 <filename>bitbake-layers layerindex-fetch</filename> and
1175 tells <filename>bitbake-layers</filename> where to place
1176 the fetched layers.
1177 </para>
1178 </glossdef>
1179 </glossentry>
1180
1181 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
1182 <glossdef>
1183 <para>
1184 Prevents BitBake from processing recipes and recipe
1185 append files.
1186 </para>
1187
1188 <para>
1189 You can use the <filename>BBMASK</filename> variable
1190 to "hide" these <filename>.bb</filename> and
1191 <filename>.bbappend</filename> files.
1192 BitBake ignores any recipe or recipe append files that
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001193 match any of the expressions.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001194 It is as if BitBake does not see them at all.
1195 Consequently, matching files are not parsed or otherwise
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001196 used by BitBake.
1197 </para>
1198
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001199 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001200 The values you provide are passed to Python's regular
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001201 expression compiler.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001202 Consequently, the syntax follows Python's Regular
1203 Expression (re) syntax.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001204 The expressions are compared against the full paths to
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001205 the files.
1206 For complete syntax information, see Python's
1207 documentation at
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001208 <ulink url='http://docs.python.org/3/library/re.html#re'></ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001209 </para>
1210
1211 <para>
1212 The following example uses a complete regular expression
1213 to tell BitBake to ignore all recipe and recipe append
1214 files in the <filename>meta-ti/recipes-misc/</filename>
1215 directory:
1216 <literallayout class='monospaced'>
1217 BBMASK = "meta-ti/recipes-misc/"
1218 </literallayout>
1219 If you want to mask out multiple directories or recipes,
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001220 you can specify multiple regular expression fragments.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001221 This next example masks out multiple directories and
1222 individual recipes:
1223 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001224 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
1225 BBMASK += "/meta-oe/recipes-support/"
1226 BBMASK += "/meta-foo/.*/openldap"
1227 BBMASK += "opencv.*\.bbappend"
1228 BBMASK += "lzma"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001229 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001230 <note>
1231 When specifying a directory name, use the trailing
1232 slash character to ensure you match just that directory
1233 name.
1234 </note>
1235 </para>
1236 </glossdef>
1237 </glossentry>
1238
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001239 <glossentry id='var-BBMULTICONFIG'><glossterm>BBMULTICONFIG</glossterm>
1240 <info>
1241 BBMULTICONFIG[doc] = "Enables BitBake to perform multiple configuration builds and lists each separate configuration (multiconfig)."
1242 </info>
1243 <glossdef>
1244 <para role="glossdeffirst">
1245<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1246 Enables BitBake to perform multiple configuration builds
1247 and lists each separate configuration (multiconfig).
1248 You can use this variable to cause BitBake to build
1249 multiple targets where each target has a separate
1250 configuration.
1251 Define <filename>BBMULTICONFIG</filename> in your
1252 <filename>conf/local.conf</filename> configuration file.
1253 </para>
1254
1255 <para>
1256 As an example, the following line specifies three
1257 multiconfigs, each having a separate configuration file:
1258 <literallayout class='monospaced'>
1259 BBMULTIFONFIG = "configA configB configC"
1260 </literallayout>
1261 Each configuration file you use must reside in the
1262 build directory within a directory named
1263 <filename>conf/multiconfig</filename> (e.g.
1264 <replaceable>build_directory</replaceable><filename>/conf/multiconfig/configA.conf</filename>).
1265 </para>
1266
1267 <para>
1268 For information on how to use
1269 <filename>BBMULTICONFIG</filename> in an environment that
1270 supports building targets with multiple configurations,
1271 see the
1272 "<link linkend='executing-a-multiple-configuration-build'>Executing a Multiple Configuration Build</link>"
1273 section.
1274 </para>
1275 </glossdef>
1276 </glossentry>
1277
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001278 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
1279 <glossdef>
1280 <para>
1281 Used by BitBake to locate class
1282 (<filename>.bbclass</filename>) and configuration
1283 (<filename>.conf</filename>) files.
1284 This variable is analogous to the
1285 <filename>PATH</filename> variable.
1286 </para>
1287
1288 <para>
1289 If you run BitBake from a directory outside of the
1290 build directory,
1291 you must be sure to set
1292 <filename>BBPATH</filename> to point to the
1293 build directory.
1294 Set the variable as you would any environment variable
1295 and then run BitBake:
1296 <literallayout class='monospaced'>
1297 $ BBPATH="<replaceable>build_directory</replaceable>"
1298 $ export BBPATH
1299 $ bitbake <replaceable>target</replaceable>
1300 </literallayout>
1301 </para>
1302 </glossdef>
1303 </glossentry>
1304
1305 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
1306 <glossdef>
1307 <para>
1308 Points to the server that runs memory-resident BitBake.
1309 The variable is only used when you employ memory-resident
1310 BitBake.
1311 </para>
1312 </glossdef>
1313 </glossentry>
1314
Patrick Williamsf1e5d692016-03-30 15:21:19 -05001315 <glossentry id='var-BBTARGETS'><glossterm>BBTARGETS</glossterm>
1316 <glossdef>
1317 <para>
1318 Allows you to use a configuration file to add to the list
1319 of command-line target recipes you want to build.
1320 </para>
1321 </glossdef>
1322 </glossentry>
1323
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001324 <glossentry id='var-BBVERSIONS'><glossterm>BBVERSIONS</glossterm>
1325 <glossdef>
1326 <para>
1327 Allows a single recipe to build multiple versions of a
1328 project from a single recipe file.
1329 You also able to specify conditional metadata
1330 using the
1331 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1332 mechanism for a single version or for an optionally named
1333 range of versions.
1334 </para>
1335
1336 <para>
1337 For more information on <filename>BBVERSIONS</filename>,
1338 see the
1339 "<link linkend='variants-class-extension-mechanism'>Variants - Class Extension Mechanism</link>"
1340 section.
1341 </para>
1342 </glossdef>
1343 </glossentry>
1344
1345 <glossentry id='var-BITBAKE_UI'><glossterm>BITBAKE_UI</glossterm>
1346 <glossdef>
1347 <para>
1348 Used to specify the UI module to use when running BitBake.
1349 Using this variable is equivalent to using the
1350 <filename>-u</filename> command-line option.
1351 <note>
1352 You must set this variable in the external environment
1353 in order for it to work.
1354 </note>
1355 </para>
1356 </glossdef>
1357 </glossentry>
1358
1359 <glossentry id='var-BUILDNAME'><glossterm>BUILDNAME</glossterm>
1360 <glossdef>
1361 <para>
1362 A name assigned to the build.
1363 The name defaults to a datetime stamp of when the build was
1364 started but can be defined by the metadata.
1365 </para>
1366 </glossdef>
1367 </glossentry>
1368
1369 <glossentry id='var-BZRDIR'><glossterm>BZRDIR</glossterm>
1370 <glossdef>
1371 <para>
1372 The directory in which files checked out of a Bazaar
1373 system are stored.
1374 </para>
1375 </glossdef>
1376 </glossentry>
1377
1378 </glossdiv>
1379
1380 <glossdiv id='var-glossary-c'><title>C</title>
1381
1382 <glossentry id='var-CACHE'><glossterm>CACHE</glossterm>
1383 <glossdef>
1384 <para>
1385 Specifies the directory BitBake uses to store a cache
1386 of the metadata so it does not need to be parsed every
1387 time BitBake is started.
1388 </para>
1389 </glossdef>
1390 </glossentry>
1391
1392 <glossentry id='var-CVSDIR'><glossterm>CVSDIR</glossterm>
1393 <glossdef>
1394 <para>
1395 The directory in which files checked out under the
1396 CVS system are stored.
1397 </para>
1398 </glossdef>
1399 </glossentry>
1400
1401 </glossdiv>
1402
1403 <glossdiv id='var-glossary-d'><title>D</title>
1404
1405 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
1406 <glossdef>
1407 <para>
1408 Specifies a weak bias for recipe selection priority.
1409 </para>
1410 <para>
1411 The most common usage of this is variable is to set
1412 it to "-1" within a recipe for a development version of a
1413 piece of software.
1414 Using the variable in this way causes the stable version
1415 of the recipe to build by default in the absence of
1416 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
1417 being used to build the development version.
1418 </para>
1419 <note>
1420 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
1421 is weak and is overridden by
1422 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
1423 if that variable is different between two layers
1424 that contain different versions of the same recipe.
1425 </note>
1426 </glossdef>
1427 </glossentry>
1428
1429 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
1430 <glossdef>
1431 <para>
1432 Lists a recipe's build-time dependencies
1433 (i.e. other recipe files).
1434 </para>
1435
1436 <para>
1437 Consider this simple example for two recipes named "a" and
1438 "b" that produce similarly named packages.
1439 In this example, the <filename>DEPENDS</filename>
1440 statement appears in the "a" recipe:
1441 <literallayout class='monospaced'>
1442 DEPENDS = "b"
1443 </literallayout>
1444 Here, the dependency is such that the
1445 <filename>do_configure</filename> task for recipe "a"
1446 depends on the <filename>do_populate_sysroot</filename>
1447 task of recipe "b".
1448 This means anything that recipe "b" puts into sysroot
1449 is available when recipe "a" is configuring itself.
1450 </para>
1451
1452 <para>
1453 For information on runtime dependencies, see the
1454 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1455 variable.
1456 </para>
1457 </glossdef>
1458 </glossentry>
1459
1460 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
1461 <glossdef>
1462 <para>
1463 A long description for the recipe.
1464 </para>
1465 </glossdef>
1466 </glossentry>
1467
1468 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
1469 <glossdef>
1470 <para>
1471 The central download directory used by the build process to
1472 store downloads.
1473 By default, <filename>DL_DIR</filename> gets files
1474 suitable for mirroring for everything except Git
1475 repositories.
1476 If you want tarballs of Git repositories, use the
1477 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
1478 variable.
1479 </para>
1480 </glossdef>
1481
1482 </glossentry>
1483 </glossdiv>
1484
1485 <glossdiv id='var-glossary-e'><title>E</title>
1486
1487 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
1488 <glossdef>
1489 <para>
1490 Directs BitBake to exclude a recipe from world builds (i.e.
1491 <filename>bitbake world</filename>).
1492 During world builds, BitBake locates, parses and builds all
1493 recipes found in every layer exposed in the
1494 <filename>bblayers.conf</filename> configuration file.
1495 </para>
1496
1497 <para>
1498 To exclude a recipe from a world build using this variable,
1499 set the variable to "1" in the recipe.
1500 </para>
1501
1502 <note>
1503 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
1504 may still be built during a world build in order to satisfy
1505 dependencies of other recipes.
1506 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
1507 only ensures that the recipe is not explicitly added
1508 to the list of build targets in a world build.
1509 </note>
1510 </glossdef>
1511 </glossentry>
1512
1513 </glossdiv>
1514
1515 <glossdiv id='var-glossary-f'><title>F</title>
1516
1517 <glossentry id='var-FAKEROOT'><glossterm>FAKEROOT</glossterm>
1518 <glossdef>
1519 <para>
1520 Contains the command to use when running a shell script
1521 in a fakeroot environment.
1522 The <filename>FAKEROOT</filename> variable is obsolete
1523 and has been replaced by the other
1524 <filename>FAKEROOT*</filename> variables.
1525 See these entries in the glossary for more information.
1526 </para>
1527 </glossdef>
1528 </glossentry>
1529
1530 <glossentry id='var-FAKEROOTBASEENV'><glossterm>FAKEROOTBASEENV</glossterm>
1531 <glossdef>
1532 <para>
1533 Lists environment variables to set when executing
1534 the command defined by
1535 <link linkend='var-FAKEROOTCMD'><filename>FAKEROOTCMD</filename></link>
1536 that starts the bitbake-worker process
1537 in the fakeroot environment.
1538 </para>
1539 </glossdef>
1540 </glossentry>
1541
1542 <glossentry id='var-FAKEROOTCMD'><glossterm>FAKEROOTCMD</glossterm>
1543 <glossdef>
1544 <para>
1545 Contains the command that starts the bitbake-worker
1546 process in the fakeroot environment.
1547 </para>
1548 </glossdef>
1549 </glossentry>
1550
1551 <glossentry id='var-FAKEROOTDIRS'><glossterm>FAKEROOTDIRS</glossterm>
1552 <glossdef>
1553 <para>
1554 Lists directories to create before running a task in
1555 the fakeroot environment.
1556 </para>
1557 </glossdef>
1558 </glossentry>
1559
1560 <glossentry id='var-FAKEROOTENV'><glossterm>FAKEROOTENV</glossterm>
1561 <glossdef>
1562 <para>
1563 Lists environment variables to set when running a task
1564 in the fakeroot environment.
1565 For additional information on environment variables and
1566 the fakeroot environment, see the
1567 <link linkend='var-FAKEROOTBASEENV'><filename>FAKEROOTBASEENV</filename></link>
1568 variable.
1569 </para>
1570 </glossdef>
1571 </glossentry>
1572
1573 <glossentry id='var-FAKEROOTNOENV'><glossterm>FAKEROOTNOENV</glossterm>
1574 <glossdef>
1575 <para>
1576 Lists environment variables to set when running a task
1577 that is not in the fakeroot environment.
1578 For additional information on environment variables and
1579 the fakeroot environment, see the
1580 <link linkend='var-FAKEROOTENV'><filename>FAKEROOTENV</filename></link>
1581 variable.
1582 </para>
1583 </glossdef>
1584 </glossentry>
1585
1586 <glossentry id='var-FETCHCMD'><glossterm>FETCHCMD</glossterm>
1587 <glossdef>
1588 <para>
1589 Defines the command the BitBake fetcher module
1590 executes when running fetch operations.
1591 You need to use an override suffix when you use the
1592 variable (e.g. <filename>FETCHCMD_git</filename>
1593 or <filename>FETCHCMD_svn</filename>).
1594 </para>
1595 </glossdef>
1596 </glossentry>
1597
1598 <glossentry id='var-FILE'><glossterm>FILE</glossterm>
1599 <glossdef>
1600 <para>
1601 Points at the current file.
1602 BitBake sets this variable during the parsing process
1603 to identify the file being parsed.
1604 BitBake also sets this variable when a recipe is being
1605 executed to identify the recipe file.
1606 </para>
1607 </glossdef>
1608 </glossentry>
1609
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001610 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
1611 <glossdef>
1612 <para>
1613 Specifies directories BitBake uses when searching for
1614 patches and files.
1615 The "local" fetcher module uses these directories when
1616 handling <filename>file://</filename> URLs.
1617 The variable behaves like a shell <filename>PATH</filename>
1618 environment variable.
1619 The value is a colon-separated list of directories that
1620 are searched left-to-right in order.
1621 </para>
1622 </glossdef>
1623 </glossentry>
1624
1625 </glossdiv>
1626
1627
1628 <glossdiv id='var-glossary-g'><title>G</title>
1629
1630 <glossentry id='var-GITDIR'><glossterm>GITDIR</glossterm>
1631 <glossdef>
1632 <para>
1633 The directory in which a local copy of a Git repository
1634 is stored when it is cloned.
1635 </para>
1636 </glossdef>
1637 </glossentry>
1638
1639 </glossdiv>
1640
1641
1642 <glossdiv id='var-glossary-h'><title>H</title>
1643
1644 <glossentry id='var-HGDIR'><glossterm>HGDIR</glossterm>
1645 <glossdef>
1646 <para>
1647 The directory in which files checked out of a Mercurial
1648 system are stored.
1649 </para>
1650 </glossdef>
1651 </glossentry>
1652
1653 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
1654 <glossdef>
1655 <para>Website where more information about the software the recipe is building
1656 can be found.</para>
1657 </glossdef>
1658 </glossentry>
1659
1660 </glossdiv>
1661
1662 <glossdiv id='var-glossary-i'><title>I</title>
1663
1664 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
1665 <glossdef>
1666 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001667 Causes the named class or classes to be inherited globally.
1668 Anonymous functions in the class or classes
1669 are not executed for the
1670 base configuration and in each individual recipe.
1671 The OpenEmbedded build system ignores changes to
1672 <filename>INHERIT</filename> in individual recipes.
1673 </para>
1674
1675 <para>
1676 For more information on <filename>INHERIT</filename>, see
1677 the
1678 "<link linkend="inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</link>"
1679 section.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001680 </para>
1681 </glossdef>
1682 </glossentry>
1683
1684 </glossdiv>
1685
1686<!--
1687 <glossdiv id='var-glossary-j'><title>J</title>
1688 </glossdiv>
1689
1690 <glossdiv id='var-glossary-k'><title>K</title>
1691 </glossdiv>
1692-->
1693
1694 <glossdiv id='var-glossary-l'><title>L</title>
1695
1696 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
1697 <glossdef>
1698 <para>Lists the layers, separated by spaces, upon which this recipe depends.
1699 Optionally, you can specify a specific layer version for a dependency
1700 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
1701 to be compared against
1702 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>
1703 in this case).
1704 BitBake produces an error if any dependency is missing or
1705 the version numbers do not match exactly (if specified).</para>
1706 <para>
1707 You use this variable in the <filename>conf/layer.conf</filename> file.
1708 You must also use the specific layer name as a suffix
1709 to the variable (e.g. <filename>LAYERDEPENDS_mylayer</filename>).</para>
1710 </glossdef>
1711 </glossentry>
1712
1713 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
1714 <glossdef>
1715 <para>When used inside the <filename>layer.conf</filename> configuration
1716 file, this variable provides the path of the current layer.
1717 This variable is not available outside of <filename>layer.conf</filename>
1718 and references are expanded immediately when parsing of the file completes.</para>
1719 </glossdef>
1720 </glossentry>
1721
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001722 <glossentry id='var-LAYERDIR_RE'><glossterm>LAYERDIR_RE</glossterm>
1723 <glossdef>
1724 <para>When used inside the <filename>layer.conf</filename> configuration
1725 file, this variable provides the path of the current layer,
1726 escaped for use in a regular expression
1727 (<link linkend='var-BBFILE_PATTERN'><filename>BBFILE_PATTERN</filename></link>).
1728 This variable is not available outside of <filename>layer.conf</filename>
1729 and references are expanded immediately when parsing of the file completes.</para>
1730 </glossdef>
1731 </glossentry>
1732
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001733 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
1734 <glossdef>
1735 <para>Optionally specifies the version of a layer as a single number.
1736 You can use this variable within
1737 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
1738 for another layer in order to depend on a specific version
1739 of the layer.</para>
1740 <para>
1741 You use this variable in the <filename>conf/layer.conf</filename> file.
1742 You must also use the specific layer name as a suffix
1743 to the variable (e.g. <filename>LAYERDEPENDS_mylayer</filename>).</para>
1744 </glossdef>
1745 </glossentry>
1746
1747 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
1748 <glossdef>
1749 <para>
1750 The list of source licenses for the recipe.
1751 </para>
1752 </glossdef>
1753 </glossentry>
1754
1755 </glossdiv>
1756
1757 <glossdiv id='var-glossary-m'><title>M</title>
1758
1759 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
1760 <glossdef>
1761 <para>
1762 Specifies additional paths from which BitBake gets source code.
1763 When the build system searches for source code, it first
1764 tries the local download directory.
1765 If that location fails, the build system tries locations
1766 defined by
1767 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
1768 the upstream source, and then locations specified by
1769 <filename>MIRRORS</filename> in that order.
1770 </para>
1771 </glossdef>
1772 </glossentry>
1773
1774 <glossentry id='var-MULTI_PROVIDER_WHITELIST'><glossterm>MULTI_PROVIDER_WHITELIST</glossterm>
1775 <glossdef>
1776 <para>
1777 Allows you to suppress BitBake warnings caused when
1778 building two separate recipes that provide the same
1779 output.
1780 </para>
1781
1782 <para>
1783 Bitbake normally issues a warning when building two
1784 different recipes where each provides the same output.
1785 This scenario is usually something the user does not
1786 want.
1787 However, cases do exist where it makes sense, particularly
1788 in the <filename>virtual/*</filename> namespace.
1789 You can use this variable to suppress BitBake's warnings.
1790 </para>
1791
1792 <para>
1793 To use the variable, list provider names (e.g.
1794 recipe names, <filename>virtual/kernel</filename>,
1795 and so forth).
1796 </para>
1797 </glossdef>
1798 </glossentry>
1799
1800 </glossdiv>
1801
1802<!--
1803 <glossdiv id='var-glossary-n'><title>N</title>
1804 </glossdiv>
1805-->
1806
1807 <glossdiv id='var-glossary-o'><title>O</title>
1808
1809 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
1810 <glossdef>
1811 <para>
1812 BitBake uses <filename>OVERRIDES</filename> to control
1813 what variables are overridden after BitBake parses
1814 recipes and configuration files.
1815 </para>
1816
1817 <para>
1818 Following is a simple example that uses an overrides
1819 list based on machine architectures:
1820 <literallayout class='monospaced'>
1821 OVERRIDES = "arm:x86:mips:powerpc"
1822 </literallayout>
1823 You can find information on how to use
1824 <filename>OVERRIDES</filename> in the
1825 "<link linkend='conditional-syntax-overrides'>Conditional Syntax (Overrides)</link>"
1826 section.
1827 </para>
1828 </glossdef>
1829 </glossentry>
1830 </glossdiv>
1831
1832 <glossdiv id='var-glossary-p'><title>P</title>
1833
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001834 <glossentry id='var-P4DIR'><glossterm>P4DIR</glossterm>
1835 <glossdef>
1836 <para>
1837 The directory in which a local copy of a Perforce depot
1838 is stored when it is fetched.
1839 </para>
1840 </glossdef>
1841 </glossentry>
1842
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001843 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
1844 <glossdef>
1845 <para>The list of packages the recipe creates.
1846 </para>
1847 </glossdef>
1848 </glossentry>
1849
1850 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
1851 <glossdef>
1852 <para>
1853 A promise that your recipe satisfies runtime dependencies
1854 for optional modules that are found in other recipes.
1855 <filename>PACKAGES_DYNAMIC</filename>
1856 does not actually satisfy the dependencies, it only states that
1857 they should be satisfied.
1858 For example, if a hard, runtime dependency
1859 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
1860 of another package is satisfied during the build
1861 through the <filename>PACKAGES_DYNAMIC</filename>
1862 variable, but a package with the module name is never actually
1863 produced, then the other package will be broken.
1864 </para>
1865 </glossdef>
1866 </glossentry>
1867
1868 <glossentry id='var-PE'><glossterm>PE</glossterm>
1869 <glossdef>
1870 <para>
1871 The epoch of the recipe.
1872 By default, this variable is unset.
1873 The variable is used to make upgrades possible when the
1874 versioning scheme changes in some backwards incompatible
1875 way.
1876 </para>
1877 </glossdef>
1878 </glossentry>
1879
1880 <glossentry id='var-PERSISTENT_DIR'><glossterm>PERSISTENT_DIR</glossterm>
1881 <glossdef>
1882 <para>
1883 Specifies the directory BitBake uses to store data that
1884 should be preserved between builds.
1885 In particular, the data stored is the data that uses
1886 BitBake's persistent data API and the data used by the
1887 PR Server and PR Service.
1888 </para>
1889 </glossdef>
1890 </glossentry>
1891
1892 <glossentry id='var-PF'><glossterm>PF</glossterm>
1893 <glossdef>
1894 <para>
1895 Specifies the recipe or package name and includes all version and revision
1896 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
1897 <filename>bash-4.2-r1/</filename>).
1898 </para>
1899 </glossdef>
1900 </glossentry>
1901
1902 <glossentry id='var-PN'><glossterm>PN</glossterm>
1903 <glossdef>
1904 <para>The recipe name.</para>
1905 </glossdef>
1906 </glossentry>
1907
1908 <glossentry id='var-PR'><glossterm>PR</glossterm>
1909 <glossdef>
1910 <para>The revision of the recipe.
1911 </para>
1912 </glossdef>
1913 </glossentry>
1914
1915 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
1916 <glossdef>
1917 <para>
1918 Determines which recipe should be given preference when
1919 multiple recipes provide the same item.
1920 You should always suffix the variable with the name of the
1921 provided item, and you should set it to the
1922 <link linkend='var-PN'><filename>PN</filename></link>
1923 of the recipe to which you want to give precedence.
1924 Some examples:
1925 <literallayout class='monospaced'>
1926 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
1927 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
1928 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
1929 </literallayout>
1930 </para>
1931 </glossdef>
1932 </glossentry>
1933
1934 <glossentry id='var-PREFERRED_PROVIDERS'><glossterm>PREFERRED_PROVIDERS</glossterm>
1935 <glossdef>
1936 <para>
1937 Determines which recipe should be given preference for
1938 cases where multiple recipes provide the same item.
1939 Functionally,
1940 <filename>PREFERRED_PROVIDERS</filename> is identical to
1941 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>.
1942 However, the <filename>PREFERRED_PROVIDERS</filename>
1943 variable lets you define preferences for multiple
1944 situations using the following form:
1945 <literallayout class='monospaced'>
1946 PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..."
1947 </literallayout>
1948 This form is a convenient replacement for the following:
1949 <literallayout class='monospaced'>
1950 PREFERRED_PROVIDER_xxx = "yyy"
1951 PREFERRED_PROVIDER_aaa = "bbb"
1952 </literallayout>
1953 </para>
1954 </glossdef>
1955 </glossentry>
1956
1957 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
1958 <glossdef>
1959 <para>
1960 If there are multiple versions of recipes available, this
1961 variable determines which recipe should be given preference.
1962 You must always suffix the variable with the
1963 <link linkend='var-PN'><filename>PN</filename></link>
1964 you want to select, and you should set
1965 <link linkend='var-PV'><filename>PV</filename></link>
1966 accordingly for precedence.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001967 </para>
1968
1969 <para>
1970 The <filename>PREFERRED_VERSION</filename> variable
1971 supports limited wildcard use through the
1972 "<filename>%</filename>" character.
1973 You can use the character to match any number of
1974 characters, which can be useful when specifying versions
1975 that contain long revision numbers that potentially change.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001976 Here are two examples:
1977 <literallayout class='monospaced'>
1978 PREFERRED_VERSION_python = "2.7.3"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001979 PREFERRED_VERSION_linux-yocto = "4.12%"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001980 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001981 <note><title>Important</title>
1982 The use of the "<filename>%</filename>" character
1983 is limited in that it only works at the end of the
1984 string.
1985 You cannot use the wildcard character in any other
1986 location of the string.
1987 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001988 </para>
1989 </glossdef>
1990 </glossentry>
1991
1992 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
1993 <glossdef>
1994 <para>
1995 Specifies additional paths from which BitBake gets source code.
1996 When the build system searches for source code, it first
1997 tries the local download directory.
1998 If that location fails, the build system tries locations
1999 defined by <filename>PREMIRRORS</filename>, the upstream
2000 source, and then locations specified by
2001 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
2002 in that order.
2003 </para>
2004
2005 <para>
2006 Typically, you would add a specific server for the
2007 build system to attempt before any others by adding
2008 something like the following to your configuration:
2009 <literallayout class='monospaced'>
2010 PREMIRRORS_prepend = "\
2011 git://.*/.* http://www.yoctoproject.org/sources/ \n \
2012 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
2013 http://.*/.* http://www.yoctoproject.org/sources/ \n \
2014 https://.*/.* http://www.yoctoproject.org/sources/ \n"
2015 </literallayout>
2016 These changes cause the build system to intercept
2017 Git, FTP, HTTP, and HTTPS requests and direct them to
2018 the <filename>http://</filename> sources mirror.
2019 You can use <filename>file://</filename> URLs to point
2020 to local directories or network shares as well.
2021 </para>
2022 </glossdef>
2023 </glossentry>
2024
2025 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
2026 <glossdef>
2027 <para>
2028 A list of aliases by which a particular recipe can be
2029 known.
2030 By default, a recipe's own
2031 <filename><link linkend='var-PN'>PN</link></filename>
2032 is implicitly already in its <filename>PROVIDES</filename>
2033 list.
2034 If a recipe uses <filename>PROVIDES</filename>, the
2035 additional aliases are synonyms for the recipe and can
2036 be useful satisfying dependencies of other recipes during
2037 the build as specified by
2038 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
2039 </para>
2040
2041 <para>
2042 Consider the following example
2043 <filename>PROVIDES</filename> statement from a recipe
2044 file <filename>libav_0.8.11.bb</filename>:
2045 <literallayout class='monospaced'>
2046 PROVIDES += "libpostproc"
2047 </literallayout>
2048 The <filename>PROVIDES</filename> statement results in
2049 the "libav" recipe also being known as "libpostproc".
2050 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002051
2052 <para>
2053 In addition to providing recipes under alternate names,
2054 the <filename>PROVIDES</filename> mechanism is also used
2055 to implement virtual targets.
2056 A virtual target is a name that corresponds to some
2057 particular functionality (e.g. a Linux kernel).
2058 Recipes that provide the functionality in question list the
2059 virtual target in <filename>PROVIDES</filename>.
2060 Recipes that depend on the functionality in question can
2061 include the virtual target in
2062 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
2063 to leave the choice of provider open.
2064 </para>
2065
2066 <para>
2067 Conventionally, virtual targets have names on the form
2068 "virtual/function" (e.g. "virtual/kernel").
2069 The slash is simply part of the name and has no
2070 syntactical significance.
2071 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002072 </glossdef>
2073 </glossentry>
2074
2075 <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
2076 <glossdef>
2077 <para>
2078 The network based
2079 <link linkend='var-PR'><filename>PR</filename></link>
2080 service host and port.
2081 </para>
2082
2083 <para>
2084 Following is an example of how the <filename>PRSERV_HOST</filename> variable is
2085 set:
2086 <literallayout class='monospaced'>
2087 PRSERV_HOST = "localhost:0"
2088 </literallayout>
2089 You must set the variable if you want to automatically
2090 start a local PR service.
2091 You can set <filename>PRSERV_HOST</filename> to other
2092 values to use a remote PR service.
2093 </para>
2094 </glossdef>
2095 </glossentry>
2096
2097 <glossentry id='var-PV'><glossterm>PV</glossterm>
2098 <glossdef>
2099 <para>The version of the recipe.
2100 </para>
2101 </glossdef>
2102 </glossentry>
2103
2104 </glossdiv>
2105
2106<!--
2107 <glossdiv id='var-glossary-q'><title>Q</title>
2108 </glossdiv>
2109-->
2110
2111 <glossdiv id='var-glossary-r'><title>R</title>
2112
2113 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
2114 <glossdef>
2115 <para>
2116 Lists a package's runtime dependencies (i.e. other packages)
2117 that must be installed in order for the built package to run
2118 correctly.
2119 If a package in this list cannot be found during the build,
2120 you will get a build error.
2121 </para>
2122
2123 <para>
2124 Because the <filename>RDEPENDS</filename> variable applies
2125 to packages being built, you should always use the variable
2126 in a form with an attached package name.
2127 For example, suppose you are building a development package
2128 that depends on the <filename>perl</filename> package.
2129 In this case, you would use the following
2130 <filename>RDEPENDS</filename> statement:
2131 <literallayout class='monospaced'>
2132 RDEPENDS_${PN}-dev += "perl"
2133 </literallayout>
2134 In the example, the development package depends on
2135 the <filename>perl</filename> package.
2136 Thus, the <filename>RDEPENDS</filename> variable has the
2137 <filename>${PN}-dev</filename> package name as part of the
2138 variable.
2139 </para>
2140
2141 <para>
2142 BitBake supports specifying versioned dependencies.
2143 Although the syntax varies depending on the packaging
2144 format, BitBake hides these differences from you.
2145 Here is the general syntax to specify versions with
2146 the <filename>RDEPENDS</filename> variable:
2147 <literallayout class='monospaced'>
2148 RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
2149 </literallayout>
2150 For <filename>operator</filename>, you can specify the
2151 following:
2152 <literallayout class='monospaced'>
2153 =
2154 &lt;
2155 &gt;
2156 &lt;=
2157 &gt;=
2158 </literallayout>
2159 For example, the following sets up a dependency on version
2160 1.2 or greater of the package <filename>foo</filename>:
2161 <literallayout class='monospaced'>
2162 RDEPENDS_${PN} = "foo (>= 1.2)"
2163 </literallayout>
2164 </para>
2165
2166 <para>
2167 For information on build-time dependencies, see the
2168 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
2169 variable.
2170 </para>
2171 </glossdef>
2172 </glossentry>
2173
Brad Bishop316dfdd2018-06-25 12:45:53 -04002174 <glossentry id='var-REPODIR'><glossterm>REPODIR</glossterm>
2175 <glossdef>
2176 <para>
2177 The directory in which a local copy of a
2178 <filename>google-repo</filename> directory is stored
2179 when it is synced.
2180 </para>
2181 </glossdef>
2182 </glossentry>
2183
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002184 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
2185 <glossdef>
2186 <para>
2187 A list of package name aliases that a package also provides.
2188 These aliases are useful for satisfying runtime dependencies
2189 of other packages both during the build and on the target
2190 (as specified by
2191 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
2192 </para>
2193 <para>
2194 As with all package-controlling variables, you must always
2195 use the variable in conjunction with a package name override.
2196 Here is an example:
2197 <literallayout class='monospaced'>
2198 RPROVIDES_${PN} = "widget-abi-2"
2199 </literallayout>
2200 </para>
2201 </glossdef>
2202 </glossentry>
2203
2204 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
2205 <glossdef>
2206 <para>
2207 A list of packages that extends the usability of a package
2208 being built.
2209 The package being built does not depend on this list of
2210 packages in order to successfully build, but needs them for
2211 the extended usability.
2212 To specify runtime dependencies for packages, see the
2213 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
2214 variable.
2215 </para>
2216
2217 <para>
2218 BitBake supports specifying versioned recommends.
2219 Although the syntax varies depending on the packaging
2220 format, BitBake hides these differences from you.
2221 Here is the general syntax to specify versions with
2222 the <filename>RRECOMMENDS</filename> variable:
2223 <literallayout class='monospaced'>
2224 RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
2225 </literallayout>
2226 For <filename>operator</filename>, you can specify the
2227 following:
2228 <literallayout class='monospaced'>
2229 =
2230 &lt;
2231 &gt;
2232 &lt;=
2233 &gt;=
2234 </literallayout>
2235 For example, the following sets up a recommend on version
2236 1.2 or greater of the package <filename>foo</filename>:
2237 <literallayout class='monospaced'>
2238 RRECOMMENDS_${PN} = "foo (>= 1.2)"
2239 </literallayout>
2240 </para>
2241 </glossdef>
2242 </glossentry>
2243
2244 </glossdiv>
2245
2246 <glossdiv id='var-glossary-s'><title>S</title>
2247
2248 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
2249 <glossdef>
2250 <para>The section in which packages should be categorized.</para>
2251 </glossdef>
2252 </glossentry>
2253
2254 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
2255 <glossdef>
2256 <para>
2257 The list of source files - local or remote.
2258 This variable tells BitBake which bits
2259 to pull for the build and how to pull them.
2260 For example, if the recipe or append file needs to
2261 fetch a single tarball from the Internet, the recipe or
2262 append file uses a <filename>SRC_URI</filename>
2263 entry that specifies that tarball.
2264 On the other hand, if the recipe or append file needs to
2265 fetch a tarball and include a custom file, the recipe or
2266 append file needs an <filename>SRC_URI</filename> variable
2267 that specifies all those sources.</para>
2268 <para>The following list explains the available URI protocols:
2269 <itemizedlist>
2270 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
2271 Fetches files, which are usually files shipped with
2272 the metadata,
2273 from the local machine.
2274 The path is relative to the
2275 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
2276 variable.</para></listitem>
2277 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
2278 Bazaar revision control repository.</para></listitem>
2279 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
2280 Git revision control repository.</para></listitem>
2281 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
2282 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
2283 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
2284 a repo (Git) repository.</para></listitem>
2285 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
2286 the Internet using HTTP.</para></listitem>
2287 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
2288 from the Internet using HTTPS.</para></listitem>
2289 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
2290 from the Internet using FTP.</para></listitem>
2291 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
2292 a CVS revision control repository.</para></listitem>
2293 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
2294 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
2295 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
2296 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
2297 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
2298 a secure shell.</para></listitem>
2299 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
2300 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
2301 </itemizedlist>
2302 </para>
2303 <para>Here are some additional options worth mentioning:
2304 <itemizedlist>
2305 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
2306 whether or not to unpack the file if it is an archive.
2307 The default action is to unpack the file.</para></listitem>
2308 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
2309 (or extracts its contents) into the specified
2310 subdirectory.
2311 This option is useful for unusual tarballs or other archives that
2312 do not have their files already in a subdirectory within the archive.
2313 </para></listitem>
2314 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
2315 name to be used for association with <filename>SRC_URI</filename> checksums
2316 when you have more than one file specified in <filename>SRC_URI</filename>.
2317 </para></listitem>
2318 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
2319 the filename used when storing the downloaded file.</para></listitem>
2320 </itemizedlist>
2321 </para>
2322 </glossdef>
2323 </glossentry>
2324
2325 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
2326 <glossdef>
2327 <para>
2328 The date of the source code used to build the package.
2329 This variable applies only if the source was fetched from a Source Code Manager (SCM).
2330 </para>
2331 </glossdef>
2332 </glossentry>
2333
2334 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
2335 <glossdef>
2336 <para>
2337 The revision of the source code used to build the package.
2338 This variable applies only when using Subversion, Git, Mercurial and Bazaar.
2339 If you want to build a fixed revision and you want
2340 to avoid performing a query on the remote repository every time
2341 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
2342 full revision identifier and not just a tag.
2343 </para>
2344 </glossdef>
2345 </glossentry>
2346
2347 <glossentry id='var-SRCREV_FORMAT'><glossterm>SRCREV_FORMAT</glossterm>
2348 <glossdef>
2349 <para>
2350 Helps construct valid
2351 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2352 values when multiple source controlled URLs are used in
2353 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
2354 </para>
2355
2356 <para>
2357 The system needs help constructing these values under these
2358 circumstances.
2359 Each component in the <filename>SRC_URI</filename>
2360 is assigned a name and these are referenced
2361 in the <filename>SRCREV_FORMAT</filename> variable.
2362 Consider an example with URLs named "machine" and "meta".
2363 In this case, <filename>SRCREV_FORMAT</filename> could look
2364 like "machine_meta" and those names would have the SCM
2365 versions substituted into each position.
2366 Only one <filename>AUTOINC</filename> placeholder is added
2367 and if needed.
2368 And, this placeholder is placed at the start of the
2369 returned string.
2370 </para>
2371 </glossdef>
2372 </glossentry>
2373
2374 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
2375 <glossdef>
2376 <para>
2377 Specifies the base path used to create recipe stamp files.
2378 The path to an actual stamp file is constructed by evaluating this
2379 string and then appending additional information.
2380 </para>
2381 </glossdef>
2382 </glossentry>
2383
2384 <glossentry id='var-STAMPCLEAN'><glossterm>STAMPCLEAN</glossterm>
2385 <glossdef>
2386 <para>
2387 Specifies the base path used to create recipe stamp files.
2388 Unlike the
2389 <link linkend='var-STAMP'><filename>STAMP</filename></link>
2390 variable, <filename>STAMPCLEAN</filename> can contain
2391 wildcards to match the range of files a clean operation
2392 should remove.
2393 BitBake uses a clean operation to remove any other stamps
2394 it should be removing when creating a new stamp.
2395 </para>
2396 </glossdef>
2397 </glossentry>
2398
2399 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
2400 <glossdef>
2401 <para>
2402 A short summary for the recipe, which is 72 characters or less.
2403 </para>
2404 </glossdef>
2405 </glossentry>
2406
2407 <glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm>
2408 <glossdef>
2409 <para>
2410 The directory in which files checked out of a Subversion
2411 system are stored.
2412 </para>
2413 </glossdef>
2414 </glossentry>
2415
2416 </glossdiv>
2417
2418 <glossdiv id='var-glossary-t'><title>T</title>
2419
2420 <glossentry id='var-T'><glossterm>T</glossterm>
2421 <glossdef>
2422 <para>Points to a directory were BitBake places
2423 temporary files, which consist mostly of task logs and
2424 scripts, when building a particular recipe.
2425 </para>
2426 </glossdef>
2427 </glossentry>
2428
2429 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
2430 <glossdef>
2431 <para>
2432 Points to the build directory.
2433 BitBake automatically sets this variable.
2434 </para>
2435 </glossdef>
2436 </glossentry>
2437
2438 </glossdiv>
2439
2440<!--
2441 <glossdiv id='var-glossary-u'><title>U</title>
2442 </glossdiv>
2443
2444 <glossdiv id='var-glossary-v'><title>V</title>
2445 </glossdiv>
2446
2447 <glossdiv id='var-glossary-w'><title>W</title>
2448 </glossdiv>
2449
2450 <glossdiv id='var-glossary-x'><title>X</title>
2451 </glossdiv>
2452
2453 <glossdiv id='var-glossary-y'><title>Y</title>
2454 </glossdiv>
2455
2456 <glossdiv id='var-glossary-z'><title>Z</title>
2457 </glossdiv>
2458-->
2459
2460
2461</glossary>
2462</chapter>
2463<!--
2464vim: expandtab tw=80 ts=4
2465-->