blob: c4bd1f2584200fd85ad0b11db2462e21d0ae68b5 [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 -->
Brad Bishop19323692019-04-05 15:28:33 -04006<chapter id='ref-bb-variables-glos'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05007
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
Brad Bishop19323692019-04-05 15:28:33 -040037<glossary id='ref-bb-variables-glossary'>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050038
39 <para>
Brad Bishop19323692019-04-05 15:28:33 -040040 <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>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050049<!-- <link linkend='var-glossary-j'>J</link> -->
50<!-- <link linkend='var-KARCH'>K</link> -->
Brad Bishop19323692019-04-05 15:28:33 -040051 <link linkend='var-bb-LAYERDEPENDS'>L</link>
52 <link linkend='var-bb-MIRRORS'>M</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050053<!-- <link linkend='var-glossary-n'>N</link> -->
Brad Bishop19323692019-04-05 15:28:33 -040054 <link linkend='var-bb-OVERRIDES'>O</link>
55 <link linkend='var-bb-P4DIR'>P</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050056<!-- <link linkend='var-QMAKE_PROFILES'>Q</link> -->
Brad Bishop19323692019-04-05 15:28:33 -040057 <link linkend='var-bb-RDEPENDS'>R</link>
58 <link linkend='var-bb-SECTION'>S</link>
59 <link linkend='var-bb-T'>T</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050060<!-- <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
Brad Bishop19323692019-04-05 15:28:33 -040068 <glossdiv id='var-bb-glossary-a'><title>A</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050069
Brad Bishop19323692019-04-05 15:28:33 -040070 <glossentry id='var-bb-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050071 <glossdef>
72 <para>
73 Lists recipe names
Brad Bishop19323692019-04-05 15:28:33 -040074 (<link linkend='var-bb-PN'><filename>PN</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050075 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
Brad Bishop19323692019-04-05 15:28:33 -040094 <glossdiv id='var-bb-glossary-b'><title>B</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050095
Brad Bishop19323692019-04-05 15:28:33 -040096 <glossentry id='var-bb-B'><glossterm>B</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050097 <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
Brad Bishop19323692019-04-05 15:28:33 -0400105 <glossentry id='var-bb-BB_ALLOWED_NETWORKS'><glossterm>BB_ALLOWED_NETWORKS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500106 <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
Brad Bishop19323692019-04-05 15:28:33 -0400114 <link linkend='var-bb-BB_NO_NETWORK'><filename>BB_NO_NETWORK</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500115 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
Brad Bishop19323692019-04-05 15:28:33 -0400154 <link linkend='var-bb-PREMIRRORS'><filename>PREMIRRORS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500155 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
Brad Bishop19323692019-04-05 15:28:33 -0400160 <link linkend='var-bb-SRC_URI'><filename>SRC_URI</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500161 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
Brad Bishop19323692019-04-05 15:28:33 -0400170 <glossentry id='var-bb-BB_CONSOLELOG'><glossterm>BB_CONSOLELOG</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500171 <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
Brad Bishop19323692019-04-05 15:28:33 -0400179 <glossentry id='var-bb-BB_CURRENTTASK'><glossterm>BB_CURRENTTASK</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500180 <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
Brad Bishop19323692019-04-05 15:28:33 -0400189 <glossentry id='var-bb-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500190 <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
Brad Bishop19323692019-04-05 15:28:33 -0400211 <glossentry id='var-bb-BB_DEFAULT_TASK'><glossterm>BB_DEFAULT_TASK</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500212 <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
Brad Bishop19323692019-04-05 15:28:33 -0400222 <glossentry id='var-bb-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500223 <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
Brad Bishop19323692019-04-05 15:28:33 -0400248 <link linkend='var-bb-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500249 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
Brad Bishop19323692019-04-05 15:28:33 -0400278 the <link linkend='var-bb-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500279 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
Brad Bishop19323692019-04-05 15:28:33 -0400312 <glossentry id='var-bb-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500313 <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
Brad Bishop19323692019-04-05 15:28:33 -0400322 <link linkend='var-bb-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500323 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
Brad Bishop19323692019-04-05 15:28:33 -0400377 <glossentry id='var-bb-BB_ENV_WHITELIST'><glossterm>BB_ENV_WHITELIST</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500378 <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:
Brad Bishop19323692019-04-05 15:28:33 -0400385 <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>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500388 and
Brad Bishop19323692019-04-05 15:28:33 -0400389 <link linkend='var-bb-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500390 <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
Brad Bishop19323692019-04-05 15:28:33 -0400398 <glossentry id='var-bb-BB_ENV_EXTRAWHITE'><glossterm>BB_ENV_EXTRAWHITE</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500399 <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
Brad Bishop19323692019-04-05 15:28:33 -0400406 <link linkend='var-bb-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500407 <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
Brad Bishop19323692019-04-05 15:28:33 -0400415 <glossentry id='var-bb-BB_FETCH_PREMIRRORONLY'><glossterm>BB_FETCH_PREMIRRORONLY</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500416 <glossdef>
417 <para>
418 When set to "1", causes BitBake's fetcher module to only
419 search
Brad Bishop19323692019-04-05 15:28:33 -0400420 <link linkend='var-bb-PREMIRRORS'><filename>PREMIRRORS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500421 for files.
422 BitBake will not search the main
Brad Bishop19323692019-04-05 15:28:33 -0400423 <link linkend='var-bb-SRC_URI'><filename>SRC_URI</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500424 or
Brad Bishop19323692019-04-05 15:28:33 -0400425 <link linkend='var-bb-MIRRORS'><filename>MIRRORS</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500426 </para>
427 </glossdef>
428 </glossentry>
429
Brad Bishop19323692019-04-05 15:28:33 -0400430 <glossentry id='var-bb-BB_FILENAME'><glossterm>BB_FILENAME</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500431 <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
Brad Bishop19323692019-04-05 15:28:33 -0400443 <glossentry id='var-bb-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500444 <glossdef>
445 <para>
446 Causes tarballs of the Git repositories, including the
447 Git metadata, to be placed in the
Brad Bishop19323692019-04-05 15:28:33 -0400448 <link linkend='var-bb-DL_DIR'><filename>DL_DIR</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500449 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
Brad Bishop19323692019-04-05 15:28:33 -0400464 <glossentry id='var-bb-BB_HASHCONFIG_WHITELIST'><glossterm>BB_HASHCONFIG_WHITELIST</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500465 <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
Brad Bishop19323692019-04-05 15:28:33 -0400488 <glossentry id='var-bb-BB_HASHBASE_WHITELIST'><glossterm>BB_HASHBASE_WHITELIST</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500489 <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
Brad Bishop19323692019-04-05 15:28:33 -0400503 <glossentry id='var-bb-BB_HASHCHECK_FUNCTION'><glossterm>BB_HASHCHECK_FUNCTION</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500504 <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
Brad Bishop19323692019-04-05 15:28:33 -0400527 <glossentry id='var-bb-BB_INVALIDCONF'><glossterm>BB_INVALIDCONF</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500528 <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
Andrew Geissler82c905d2020-04-13 13:39:40 -0500542 <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
Brad Bishop19323692019-04-05 15:28:33 -0400553 <glossentry id='var-bb-BB_LOGFMT'><glossterm>BB_LOGFMT</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500554 <glossdef>
555 <para>
556 Specifies the name of the log files saved into
Brad Bishop19323692019-04-05 15:28:33 -0400557 <filename>${</filename><link linkend='var-bb-T'><filename>T</filename></link><filename>}</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500558 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
Brad Bishop19323692019-04-05 15:28:33 -0400570 <glossentry id='var-bb-BB_NICE_LEVEL'><glossterm>BB_NICE_LEVEL</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500571 <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
Brad Bishop19323692019-04-05 15:28:33 -0400578 <link linkend='var-bb-BB_TASK_NICE_LEVEL'><filename>BB_TASK_NICE_LEVEL</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500579 for additional information.
580 </para>
581 </glossdef>
582 </glossentry>
583
Brad Bishop19323692019-04-05 15:28:33 -0400584 <glossentry id='var-bb-BB_NO_NETWORK'><glossterm>BB_NO_NETWORK</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500585 <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
Brad Bishop19323692019-04-05 15:28:33 -0400601 <glossentry id='var-bb-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500602 <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
Brad Bishop19323692019-04-05 15:28:33 -0400613 <glossentry id='var-bb-BB_NUMBER_PARSE_THREADS'><glossterm>BB_NUMBER_PARSE_THREADS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500614 <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
Brad Bishop19323692019-04-05 15:28:33 -0400623 <glossentry id='var-bb-BB_ORIGENV'><glossterm>BB_ORIGENV</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500624 <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
Brad Bishop19323692019-04-05 15:28:33 -0400639 <glossentry id='var-bb-BB_PRESERVE_ENV'><glossterm>BB_PRESERVE_ENV</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500640 <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
Brad Bishop19323692019-04-05 15:28:33 -0400653 <glossentry id='var-bb-BB_RUNFMT'><glossterm>BB_RUNFMT</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500654 <glossdef>
655 <para>
656 Specifies the name of the executable script files
657 (i.e. run files) saved into
Brad Bishop19323692019-04-05 15:28:33 -0400658 <filename>${</filename><link linkend='var-bb-T'><filename>T</filename></link><filename>}</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500659 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
Brad Bishop19323692019-04-05 15:28:33 -0400671 <glossentry id='var-bb-BB_RUNTASK'><glossterm>BB_RUNTASK</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500672 <glossdef>
673 <para>
674 Contains the name of the currently executing task.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800675 The value includes the "do_" prefix.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500676 For example, if the currently executing task is
677 <filename>do_config</filename>, the value is
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800678 "do_config".
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500679 </para>
680 </glossdef>
681 </glossentry>
682
Brad Bishop19323692019-04-05 15:28:33 -0400683 <glossentry id='var-bb-BB_SCHEDULER'><glossterm>BB_SCHEDULER</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500684 <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
Brad Bishop19323692019-04-05 15:28:33 -0400709 <glossentry id='var-bb-BB_SCHEDULERS'><glossterm>BB_SCHEDULERS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500710 <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
Brad Bishop19323692019-04-05 15:28:33 -0400719 <link linkend='var-bb-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500720 variable.
721 </para>
722 </glossdef>
723 </glossentry>
724
Brad Bishop19323692019-04-05 15:28:33 -0400725 <glossentry id='var-bb-BB_SETSCENE_DEPVALID'><glossterm>BB_SETSCENE_DEPVALID</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500726 <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
Brad Bishop19323692019-04-05 15:28:33 -0400745 <glossentry id='var-bb-BB_SETSCENE_VERIFY_FUNCTION2'><glossterm>BB_SETSCENE_VERIFY_FUNCTION2</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500746 <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
Brad Bishop19323692019-04-05 15:28:33 -0400766 <glossentry id='var-bb-BB_SIGNATURE_EXCLUDE_FLAGS'><glossterm>BB_SIGNATURE_EXCLUDE_FLAGS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500767 <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
Brad Bishop19323692019-04-05 15:28:33 -0400785 <glossentry id='var-bb-BB_SIGNATURE_HANDLER'><glossterm>BB_SIGNATURE_HANDLER</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500786 <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
Brad Bishop19323692019-04-05 15:28:33 -0400804 <glossentry id='var-bb-BB_SRCREV_POLICY'><glossterm>BB_SRCREV_POLICY</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500805 <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
Brad Bishop19323692019-04-05 15:28:33 -0400831 <glossentry id='var-bb-BB_STAMP_POLICY'><glossterm>BB_STAMP_POLICY</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500832 <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
Brad Bishop19323692019-04-05 15:28:33 -0400850 <link linkend='var-bb-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500851 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
Brad Bishop19323692019-04-05 15:28:33 -0400862 <glossentry id='var-bb-BB_STAMP_WHITELIST'><glossterm>BB_STAMP_WHITELIST</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500863 <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
Brad Bishop19323692019-04-05 15:28:33 -0400868 <link linkend='var-bb-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500869 variable.
870 </para>
871 </glossdef>
872 </glossentry>
873
Brad Bishop19323692019-04-05 15:28:33 -0400874 <glossentry id='var-bb-BB_STRICT_CHECKSUM'><glossterm>BB_STRICT_CHECKSUM</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500875 <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
Brad Bishop19323692019-04-05 15:28:33 -0400885 <glossentry id='var-bb-BB_TASK_IONICE_LEVEL'><glossterm>BB_TASK_IONICE_LEVEL</glossterm>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500886 <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
Brad Bishop19323692019-04-05 15:28:33 -0400896 <link linkend='var-bb-BB_TASK_NICE_LEVEL'><filename>BB_TASK_NICE_LEVEL</filename></link>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500897 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
Brad Bishop19323692019-04-05 15:28:33 -0400935 <glossentry id='var-bb-BB_TASK_NICE_LEVEL'><glossterm>BB_TASK_NICE_LEVEL</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500936 <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
Brad Bishop19323692019-04-05 15:28:33 -0400954 <glossentry id='var-bb-BB_TASKHASH'><glossterm>BB_TASKHASH</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500955 <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
Brad Bishop19323692019-04-05 15:28:33 -0400964 <glossentry id='var-bb-BB_VERBOSE_LOGS'><glossterm>BB_VERBOSE_LOGS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500965 <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
Brad Bishop19323692019-04-05 15:28:33 -0400974 <glossentry id='var-bb-BB_WORKERCONTEXT'><glossterm>BB_WORKERCONTEXT</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500975 <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
Brad Bishop19323692019-04-05 15:28:33 -0400987 <glossentry id='var-bb-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500988 <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
Brad Bishop316dfdd2018-06-25 12:45:53 -0400993 OpenEmbedded-Core metadata are "natives" such as
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500994 <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.
Brad Bishop316dfdd2018-06-25 12:45:53 -04001009 The "native" variants are from the OpenEmbedded-Core
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001010 metadata:
1011 <literallayout class='monospaced'>
1012 BBCLASSEXTEND =+ "native nativesdk"
1013 BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>"
1014 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001015 <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
Brad Bishop19323692019-04-05 15:28:33 -04001023 <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001024 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>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001038 </para>
1039 </glossdef>
1040 </glossentry>
1041
Brad Bishop19323692019-04-05 15:28:33 -04001042 <glossentry id='var-bb-BBDEBUG'><glossterm>BBDEBUG</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001043 <glossdef>
1044 <para>
1045 Sets the BitBake debug output level to a specific value
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001046 as incremented by the <filename>-D</filename> command line
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001047 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
Brad Bishop19323692019-04-05 15:28:33 -04001056 <glossentry id='var-bb-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001057 <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
Brad Bishop19323692019-04-05 15:28:33 -04001067 <glossentry id='var-bb-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001068 <glossdef>
1069 <para>Variable that expands to match files from
Brad Bishop19323692019-04-05 15:28:33 -04001070 <link linkend='var-bb-BBFILES'><filename>BBFILES</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001071 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
Brad Bishop19323692019-04-05 15:28:33 -04001078 <glossentry id='var-bb-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001079 <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
Brad Bishop19323692019-04-05 15:28:33 -04001088 (<link linkend='var-bb-PV'><filename>PV</filename></link> variable).
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001089 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
Brad Bishop19323692019-04-05 15:28:33 -04001097 <filename><link linkend='var-bb-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001098 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
Brad Bishop19323692019-04-05 15:28:33 -04001109 <glossentry id='var-bb-BBFILES'><glossterm>BBFILES</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001110 <glossdef>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001111 <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>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001124 </glossdef>
1125 </glossentry>
1126
Brad Bishop19323692019-04-05 15:28:33 -04001127 <glossentry id='var-bb-BBINCLUDED'><glossterm>BBINCLUDED</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001128 <glossdef>
1129 <para>
1130 Contains a space-separated list of all of all files that
1131 BitBake's parser included during parsing of the current
1132 file.
1133 </para>
1134 </glossdef>
1135 </glossentry>
1136
Brad Bishop19323692019-04-05 15:28:33 -04001137 <glossentry id='var-bb-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001138 <glossdef>
1139 <para>
1140 If set to a value, enables printing the task log when
1141 reporting a failed task.
1142 </para>
1143 </glossdef>
1144 </glossentry>
1145
Brad Bishop19323692019-04-05 15:28:33 -04001146 <glossentry id='var-bb-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001147 <glossdef>
1148 <para>
1149 If
Brad Bishop19323692019-04-05 15:28:33 -04001150 <link linkend='var-bb-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001151 is set, specifies the maximum number of lines from the
1152 task log file to print when reporting a failed task.
1153 If you do not set <filename>BBINCLUDELOGS_LINES</filename>,
1154 the entire log is printed.
1155 </para>
1156 </glossdef>
1157 </glossentry>
1158
Brad Bishop19323692019-04-05 15:28:33 -04001159 <glossentry id='var-bb-BBLAYERS'><glossterm>BBLAYERS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001160 <glossdef>
1161 <para>Lists the layers to enable during the build.
1162 This variable is defined in the <filename>bblayers.conf</filename> configuration
1163 file in the build directory.
1164 Here is an example:
1165 <literallayout class='monospaced'>
1166 BBLAYERS = " \
1167 /home/scottrif/poky/meta \
1168 /home/scottrif/poky/meta-yocto \
1169 /home/scottrif/poky/meta-yocto-bsp \
1170 /home/scottrif/poky/meta-mykernel \
1171 "
1172
1173 </literallayout>
1174 This example enables four layers, one of which is a custom, user-defined layer
1175 named <filename>meta-mykernel</filename>.
1176 </para>
1177 </glossdef>
1178 </glossentry>
1179
Brad Bishop19323692019-04-05 15:28:33 -04001180 <glossentry id='var-bb-BBLAYERS_FETCH_DIR'><glossterm>BBLAYERS_FETCH_DIR</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001181 <glossdef>
1182 <para>
1183 Sets the base location where layers are stored.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001184 This setting is used in conjunction with
1185 <filename>bitbake-layers layerindex-fetch</filename> and
1186 tells <filename>bitbake-layers</filename> where to place
1187 the fetched layers.
1188 </para>
1189 </glossdef>
1190 </glossentry>
1191
Brad Bishop19323692019-04-05 15:28:33 -04001192 <glossentry id='var-bb-BBMASK'><glossterm>BBMASK</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001193 <glossdef>
1194 <para>
1195 Prevents BitBake from processing recipes and recipe
1196 append files.
1197 </para>
1198
1199 <para>
1200 You can use the <filename>BBMASK</filename> variable
1201 to "hide" these <filename>.bb</filename> and
1202 <filename>.bbappend</filename> files.
1203 BitBake ignores any recipe or recipe append files that
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001204 match any of the expressions.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001205 It is as if BitBake does not see them at all.
1206 Consequently, matching files are not parsed or otherwise
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001207 used by BitBake.
1208 </para>
1209
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001210 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001211 The values you provide are passed to Python's regular
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001212 expression compiler.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001213 Consequently, the syntax follows Python's Regular
1214 Expression (re) syntax.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001215 The expressions are compared against the full paths to
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001216 the files.
1217 For complete syntax information, see Python's
1218 documentation at
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001219 <ulink url='http://docs.python.org/3/library/re.html#re'></ulink>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001220 </para>
1221
1222 <para>
1223 The following example uses a complete regular expression
1224 to tell BitBake to ignore all recipe and recipe append
1225 files in the <filename>meta-ti/recipes-misc/</filename>
1226 directory:
1227 <literallayout class='monospaced'>
1228 BBMASK = "meta-ti/recipes-misc/"
1229 </literallayout>
1230 If you want to mask out multiple directories or recipes,
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001231 you can specify multiple regular expression fragments.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001232 This next example masks out multiple directories and
1233 individual recipes:
1234 <literallayout class='monospaced'>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001235 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
1236 BBMASK += "/meta-oe/recipes-support/"
1237 BBMASK += "/meta-foo/.*/openldap"
1238 BBMASK += "opencv.*\.bbappend"
1239 BBMASK += "lzma"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001240 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001241 <note>
1242 When specifying a directory name, use the trailing
1243 slash character to ensure you match just that directory
1244 name.
1245 </note>
1246 </para>
1247 </glossdef>
1248 </glossentry>
1249
Brad Bishop19323692019-04-05 15:28:33 -04001250 <glossentry id='var-bb-BBMULTICONFIG'><glossterm>BBMULTICONFIG</glossterm>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001251 <info>
1252 BBMULTICONFIG[doc] = "Enables BitBake to perform multiple configuration builds and lists each separate configuration (multiconfig)."
1253 </info>
1254 <glossdef>
1255 <para role="glossdeffirst">
1256<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
1257 Enables BitBake to perform multiple configuration builds
1258 and lists each separate configuration (multiconfig).
1259 You can use this variable to cause BitBake to build
1260 multiple targets where each target has a separate
1261 configuration.
1262 Define <filename>BBMULTICONFIG</filename> in your
1263 <filename>conf/local.conf</filename> configuration file.
1264 </para>
1265
1266 <para>
1267 As an example, the following line specifies three
1268 multiconfigs, each having a separate configuration file:
1269 <literallayout class='monospaced'>
1270 BBMULTIFONFIG = "configA configB configC"
1271 </literallayout>
1272 Each configuration file you use must reside in the
1273 build directory within a directory named
1274 <filename>conf/multiconfig</filename> (e.g.
1275 <replaceable>build_directory</replaceable><filename>/conf/multiconfig/configA.conf</filename>).
1276 </para>
1277
1278 <para>
1279 For information on how to use
1280 <filename>BBMULTICONFIG</filename> in an environment that
1281 supports building targets with multiple configurations,
1282 see the
1283 "<link linkend='executing-a-multiple-configuration-build'>Executing a Multiple Configuration Build</link>"
1284 section.
1285 </para>
1286 </glossdef>
1287 </glossentry>
1288
Brad Bishop19323692019-04-05 15:28:33 -04001289 <glossentry id='var-bb-BBPATH'><glossterm>BBPATH</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001290 <glossdef>
1291 <para>
1292 Used by BitBake to locate class
1293 (<filename>.bbclass</filename>) and configuration
1294 (<filename>.conf</filename>) files.
1295 This variable is analogous to the
1296 <filename>PATH</filename> variable.
1297 </para>
1298
1299 <para>
1300 If you run BitBake from a directory outside of the
1301 build directory,
1302 you must be sure to set
1303 <filename>BBPATH</filename> to point to the
1304 build directory.
1305 Set the variable as you would any environment variable
1306 and then run BitBake:
1307 <literallayout class='monospaced'>
1308 $ BBPATH="<replaceable>build_directory</replaceable>"
1309 $ export BBPATH
1310 $ bitbake <replaceable>target</replaceable>
1311 </literallayout>
1312 </para>
1313 </glossdef>
1314 </glossentry>
1315
Brad Bishop19323692019-04-05 15:28:33 -04001316 <glossentry id='var-bb-BBSERVER'><glossterm>BBSERVER</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001317 <glossdef>
1318 <para>
1319 Points to the server that runs memory-resident BitBake.
1320 The variable is only used when you employ memory-resident
1321 BitBake.
1322 </para>
1323 </glossdef>
1324 </glossentry>
1325
Brad Bishop19323692019-04-05 15:28:33 -04001326 <glossentry id='var-bb-BBTARGETS'><glossterm>BBTARGETS</glossterm>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05001327 <glossdef>
1328 <para>
1329 Allows you to use a configuration file to add to the list
1330 of command-line target recipes you want to build.
1331 </para>
1332 </glossdef>
1333 </glossentry>
1334
Brad Bishop19323692019-04-05 15:28:33 -04001335 <glossentry id='var-bb-BBVERSIONS'><glossterm>BBVERSIONS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001336 <glossdef>
1337 <para>
1338 Allows a single recipe to build multiple versions of a
1339 project from a single recipe file.
1340 You also able to specify conditional metadata
1341 using the
Brad Bishop19323692019-04-05 15:28:33 -04001342 <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001343 mechanism for a single version or for an optionally named
1344 range of versions.
1345 </para>
1346
1347 <para>
1348 For more information on <filename>BBVERSIONS</filename>,
1349 see the
1350 "<link linkend='variants-class-extension-mechanism'>Variants - Class Extension Mechanism</link>"
1351 section.
1352 </para>
1353 </glossdef>
1354 </glossentry>
1355
Brad Bishop19323692019-04-05 15:28:33 -04001356 <glossentry id='var-bb-BITBAKE_UI'><glossterm>BITBAKE_UI</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001357 <glossdef>
1358 <para>
1359 Used to specify the UI module to use when running BitBake.
1360 Using this variable is equivalent to using the
1361 <filename>-u</filename> command-line option.
1362 <note>
1363 You must set this variable in the external environment
1364 in order for it to work.
1365 </note>
1366 </para>
1367 </glossdef>
1368 </glossentry>
1369
Brad Bishop19323692019-04-05 15:28:33 -04001370 <glossentry id='var-bb-BUILDNAME'><glossterm>BUILDNAME</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001371 <glossdef>
1372 <para>
1373 A name assigned to the build.
1374 The name defaults to a datetime stamp of when the build was
1375 started but can be defined by the metadata.
1376 </para>
1377 </glossdef>
1378 </glossentry>
1379
Brad Bishop19323692019-04-05 15:28:33 -04001380 <glossentry id='var-bb-BZRDIR'><glossterm>BZRDIR</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001381 <glossdef>
1382 <para>
1383 The directory in which files checked out of a Bazaar
1384 system are stored.
1385 </para>
1386 </glossdef>
1387 </glossentry>
1388
1389 </glossdiv>
1390
Brad Bishop19323692019-04-05 15:28:33 -04001391 <glossdiv id='var-bb-glossary-c'><title>C</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001392
Brad Bishop19323692019-04-05 15:28:33 -04001393 <glossentry id='var-bb-CACHE'><glossterm>CACHE</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001394 <glossdef>
1395 <para>
1396 Specifies the directory BitBake uses to store a cache
1397 of the metadata so it does not need to be parsed every
1398 time BitBake is started.
1399 </para>
1400 </glossdef>
1401 </glossentry>
1402
Brad Bishop19323692019-04-05 15:28:33 -04001403 <glossentry id='var-bb-CVSDIR'><glossterm>CVSDIR</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001404 <glossdef>
1405 <para>
1406 The directory in which files checked out under the
1407 CVS system are stored.
1408 </para>
1409 </glossdef>
1410 </glossentry>
1411
1412 </glossdiv>
1413
Brad Bishop19323692019-04-05 15:28:33 -04001414 <glossdiv id='var-bb-glossary-d'><title>D</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001415
Brad Bishop19323692019-04-05 15:28:33 -04001416 <glossentry id='var-bb-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001417 <glossdef>
1418 <para>
1419 Specifies a weak bias for recipe selection priority.
1420 </para>
1421 <para>
1422 The most common usage of this is variable is to set
1423 it to "-1" within a recipe for a development version of a
1424 piece of software.
1425 Using the variable in this way causes the stable version
1426 of the recipe to build by default in the absence of
Brad Bishop19323692019-04-05 15:28:33 -04001427 <filename><link linkend='var-bb-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001428 being used to build the development version.
1429 </para>
1430 <note>
1431 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
1432 is weak and is overridden by
Brad Bishop19323692019-04-05 15:28:33 -04001433 <filename><link linkend='var-bb-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001434 if that variable is different between two layers
1435 that contain different versions of the same recipe.
1436 </note>
1437 </glossdef>
1438 </glossentry>
1439
Brad Bishop19323692019-04-05 15:28:33 -04001440 <glossentry id='var-bb-DEPENDS'><glossterm>DEPENDS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001441 <glossdef>
1442 <para>
1443 Lists a recipe's build-time dependencies
1444 (i.e. other recipe files).
1445 </para>
1446
1447 <para>
1448 Consider this simple example for two recipes named "a" and
1449 "b" that produce similarly named packages.
1450 In this example, the <filename>DEPENDS</filename>
1451 statement appears in the "a" recipe:
1452 <literallayout class='monospaced'>
1453 DEPENDS = "b"
1454 </literallayout>
1455 Here, the dependency is such that the
1456 <filename>do_configure</filename> task for recipe "a"
1457 depends on the <filename>do_populate_sysroot</filename>
1458 task of recipe "b".
1459 This means anything that recipe "b" puts into sysroot
1460 is available when recipe "a" is configuring itself.
1461 </para>
1462
1463 <para>
1464 For information on runtime dependencies, see the
Brad Bishop19323692019-04-05 15:28:33 -04001465 <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001466 variable.
1467 </para>
1468 </glossdef>
1469 </glossentry>
1470
Brad Bishop19323692019-04-05 15:28:33 -04001471 <glossentry id='var-bb-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001472 <glossdef>
1473 <para>
1474 A long description for the recipe.
1475 </para>
1476 </glossdef>
1477 </glossentry>
1478
Brad Bishop19323692019-04-05 15:28:33 -04001479 <glossentry id='var-bb-DL_DIR'><glossterm>DL_DIR</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001480 <glossdef>
1481 <para>
1482 The central download directory used by the build process to
1483 store downloads.
1484 By default, <filename>DL_DIR</filename> gets files
1485 suitable for mirroring for everything except Git
1486 repositories.
1487 If you want tarballs of Git repositories, use the
Brad Bishop19323692019-04-05 15:28:33 -04001488 <link linkend='var-bb-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001489 variable.
1490 </para>
1491 </glossdef>
1492
1493 </glossentry>
1494 </glossdiv>
1495
Brad Bishop19323692019-04-05 15:28:33 -04001496 <glossdiv id='var-bb-glossary-e'><title>E</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001497
Brad Bishop19323692019-04-05 15:28:33 -04001498 <glossentry id='var-bb-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001499 <glossdef>
1500 <para>
1501 Directs BitBake to exclude a recipe from world builds (i.e.
1502 <filename>bitbake world</filename>).
1503 During world builds, BitBake locates, parses and builds all
1504 recipes found in every layer exposed in the
1505 <filename>bblayers.conf</filename> configuration file.
1506 </para>
1507
1508 <para>
1509 To exclude a recipe from a world build using this variable,
1510 set the variable to "1" in the recipe.
1511 </para>
1512
1513 <note>
1514 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
1515 may still be built during a world build in order to satisfy
1516 dependencies of other recipes.
1517 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
1518 only ensures that the recipe is not explicitly added
1519 to the list of build targets in a world build.
1520 </note>
1521 </glossdef>
1522 </glossentry>
1523
1524 </glossdiv>
1525
Brad Bishop19323692019-04-05 15:28:33 -04001526 <glossdiv id='var-bb-glossary-f'><title>F</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001527
Brad Bishop19323692019-04-05 15:28:33 -04001528 <glossentry id='var-bb-FAKEROOT'><glossterm>FAKEROOT</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001529 <glossdef>
1530 <para>
1531 Contains the command to use when running a shell script
1532 in a fakeroot environment.
1533 The <filename>FAKEROOT</filename> variable is obsolete
1534 and has been replaced by the other
1535 <filename>FAKEROOT*</filename> variables.
1536 See these entries in the glossary for more information.
1537 </para>
1538 </glossdef>
1539 </glossentry>
1540
Brad Bishop19323692019-04-05 15:28:33 -04001541 <glossentry id='var-bb-FAKEROOTBASEENV'><glossterm>FAKEROOTBASEENV</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001542 <glossdef>
1543 <para>
1544 Lists environment variables to set when executing
1545 the command defined by
Brad Bishop19323692019-04-05 15:28:33 -04001546 <link linkend='var-bb-FAKEROOTCMD'><filename>FAKEROOTCMD</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001547 that starts the bitbake-worker process
1548 in the fakeroot environment.
1549 </para>
1550 </glossdef>
1551 </glossentry>
1552
Brad Bishop19323692019-04-05 15:28:33 -04001553 <glossentry id='var-bb-FAKEROOTCMD'><glossterm>FAKEROOTCMD</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001554 <glossdef>
1555 <para>
1556 Contains the command that starts the bitbake-worker
1557 process in the fakeroot environment.
1558 </para>
1559 </glossdef>
1560 </glossentry>
1561
Brad Bishop19323692019-04-05 15:28:33 -04001562 <glossentry id='var-bb-FAKEROOTDIRS'><glossterm>FAKEROOTDIRS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001563 <glossdef>
1564 <para>
1565 Lists directories to create before running a task in
1566 the fakeroot environment.
1567 </para>
1568 </glossdef>
1569 </glossentry>
1570
Brad Bishop19323692019-04-05 15:28:33 -04001571 <glossentry id='var-bb-FAKEROOTENV'><glossterm>FAKEROOTENV</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001572 <glossdef>
1573 <para>
1574 Lists environment variables to set when running a task
1575 in the fakeroot environment.
1576 For additional information on environment variables and
1577 the fakeroot environment, see the
Brad Bishop19323692019-04-05 15:28:33 -04001578 <link linkend='var-bb-FAKEROOTBASEENV'><filename>FAKEROOTBASEENV</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001579 variable.
1580 </para>
1581 </glossdef>
1582 </glossentry>
1583
Brad Bishop19323692019-04-05 15:28:33 -04001584 <glossentry id='var-bb-FAKEROOTNOENV'><glossterm>FAKEROOTNOENV</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001585 <glossdef>
1586 <para>
1587 Lists environment variables to set when running a task
1588 that is not in the fakeroot environment.
1589 For additional information on environment variables and
1590 the fakeroot environment, see the
Brad Bishop19323692019-04-05 15:28:33 -04001591 <link linkend='var-bb-FAKEROOTENV'><filename>FAKEROOTENV</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001592 variable.
1593 </para>
1594 </glossdef>
1595 </glossentry>
1596
Brad Bishop19323692019-04-05 15:28:33 -04001597 <glossentry id='var-bb-FETCHCMD'><glossterm>FETCHCMD</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001598 <glossdef>
1599 <para>
1600 Defines the command the BitBake fetcher module
1601 executes when running fetch operations.
1602 You need to use an override suffix when you use the
1603 variable (e.g. <filename>FETCHCMD_git</filename>
1604 or <filename>FETCHCMD_svn</filename>).
1605 </para>
1606 </glossdef>
1607 </glossentry>
1608
Brad Bishop19323692019-04-05 15:28:33 -04001609 <glossentry id='var-bb-FILE'><glossterm>FILE</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001610 <glossdef>
1611 <para>
1612 Points at the current file.
1613 BitBake sets this variable during the parsing process
1614 to identify the file being parsed.
1615 BitBake also sets this variable when a recipe is being
1616 executed to identify the recipe file.
1617 </para>
1618 </glossdef>
1619 </glossentry>
1620
Brad Bishop19323692019-04-05 15:28:33 -04001621 <glossentry id='var-bb-FILESPATH'><glossterm>FILESPATH</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001622 <glossdef>
1623 <para>
1624 Specifies directories BitBake uses when searching for
1625 patches and files.
1626 The "local" fetcher module uses these directories when
1627 handling <filename>file://</filename> URLs.
1628 The variable behaves like a shell <filename>PATH</filename>
1629 environment variable.
1630 The value is a colon-separated list of directories that
1631 are searched left-to-right in order.
1632 </para>
1633 </glossdef>
1634 </glossentry>
1635
1636 </glossdiv>
1637
1638
Brad Bishop19323692019-04-05 15:28:33 -04001639 <glossdiv id='var-bb-glossary-g'><title>G</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001640
Brad Bishop19323692019-04-05 15:28:33 -04001641 <glossentry id='var-bb-GITDIR'><glossterm>GITDIR</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001642 <glossdef>
1643 <para>
1644 The directory in which a local copy of a Git repository
1645 is stored when it is cloned.
1646 </para>
1647 </glossdef>
1648 </glossentry>
1649
1650 </glossdiv>
1651
1652
Brad Bishop19323692019-04-05 15:28:33 -04001653 <glossdiv id='var-bb-glossary-h'><title>H</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001654
Brad Bishop19323692019-04-05 15:28:33 -04001655 <glossentry id='var-bb-HGDIR'><glossterm>HGDIR</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001656 <glossdef>
1657 <para>
1658 The directory in which files checked out of a Mercurial
1659 system are stored.
1660 </para>
1661 </glossdef>
1662 </glossentry>
1663
Brad Bishop19323692019-04-05 15:28:33 -04001664 <glossentry id='var-bb-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001665 <glossdef>
1666 <para>Website where more information about the software the recipe is building
1667 can be found.</para>
1668 </glossdef>
1669 </glossentry>
1670
1671 </glossdiv>
1672
Brad Bishop19323692019-04-05 15:28:33 -04001673 <glossdiv id='var-bb-glossary-i'><title>I</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001674
Brad Bishop19323692019-04-05 15:28:33 -04001675 <glossentry id='var-bb-INHERIT'><glossterm>INHERIT</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001676 <glossdef>
1677 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001678 Causes the named class or classes to be inherited globally.
1679 Anonymous functions in the class or classes
1680 are not executed for the
1681 base configuration and in each individual recipe.
1682 The OpenEmbedded build system ignores changes to
1683 <filename>INHERIT</filename> in individual recipes.
1684 </para>
1685
1686 <para>
1687 For more information on <filename>INHERIT</filename>, see
1688 the
1689 "<link linkend="inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</link>"
1690 section.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001691 </para>
1692 </glossdef>
1693 </glossentry>
1694
1695 </glossdiv>
1696
1697<!--
1698 <glossdiv id='var-glossary-j'><title>J</title>
1699 </glossdiv>
1700
1701 <glossdiv id='var-glossary-k'><title>K</title>
1702 </glossdiv>
1703-->
1704
Brad Bishop19323692019-04-05 15:28:33 -04001705 <glossdiv id='var-bb-glossary-l'><title>L</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001706
Brad Bishop19323692019-04-05 15:28:33 -04001707 <glossentry id='var-bb-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001708 <glossdef>
1709 <para>Lists the layers, separated by spaces, upon which this recipe depends.
1710 Optionally, you can specify a specific layer version for a dependency
1711 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
1712 to be compared against
Brad Bishop19323692019-04-05 15:28:33 -04001713 <link linkend='var-bb-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001714 in this case).
1715 BitBake produces an error if any dependency is missing or
1716 the version numbers do not match exactly (if specified).</para>
1717 <para>
1718 You use this variable in the <filename>conf/layer.conf</filename> file.
1719 You must also use the specific layer name as a suffix
1720 to the variable (e.g. <filename>LAYERDEPENDS_mylayer</filename>).</para>
1721 </glossdef>
1722 </glossentry>
1723
Brad Bishop19323692019-04-05 15:28:33 -04001724 <glossentry id='var-bb-LAYERDIR'><glossterm>LAYERDIR</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001725 <glossdef>
1726 <para>When used inside the <filename>layer.conf</filename> configuration
1727 file, this variable provides the path of the current layer.
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
Brad Bishop19323692019-04-05 15:28:33 -04001733 <glossentry id='var-bb-LAYERDIR_RE'><glossterm>LAYERDIR_RE</glossterm>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001734 <glossdef>
1735 <para>When used inside the <filename>layer.conf</filename> configuration
1736 file, this variable provides the path of the current layer,
1737 escaped for use in a regular expression
Brad Bishop19323692019-04-05 15:28:33 -04001738 (<link linkend='var-bb-BBFILE_PATTERN'><filename>BBFILE_PATTERN</filename></link>).
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001739 This variable is not available outside of <filename>layer.conf</filename>
1740 and references are expanded immediately when parsing of the file completes.</para>
1741 </glossdef>
1742 </glossentry>
1743
Brad Bishop19323692019-04-05 15:28:33 -04001744 <glossentry id='var-bb-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001745 <glossdef>
1746 <para>Optionally specifies the version of a layer as a single number.
1747 You can use this variable within
Brad Bishop19323692019-04-05 15:28:33 -04001748 <link linkend='var-bb-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001749 for another layer in order to depend on a specific version
1750 of the layer.</para>
1751 <para>
1752 You use this variable in the <filename>conf/layer.conf</filename> file.
1753 You must also use the specific layer name as a suffix
1754 to the variable (e.g. <filename>LAYERDEPENDS_mylayer</filename>).</para>
1755 </glossdef>
1756 </glossentry>
1757
Brad Bishop19323692019-04-05 15:28:33 -04001758 <glossentry id='var-bb-LICENSE'><glossterm>LICENSE</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001759 <glossdef>
1760 <para>
1761 The list of source licenses for the recipe.
1762 </para>
1763 </glossdef>
1764 </glossentry>
1765
1766 </glossdiv>
1767
Brad Bishop19323692019-04-05 15:28:33 -04001768 <glossdiv id='var-bb-glossary-m'><title>M</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001769
Brad Bishop19323692019-04-05 15:28:33 -04001770 <glossentry id='var-bb-MIRRORS'><glossterm>MIRRORS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001771 <glossdef>
1772 <para>
1773 Specifies additional paths from which BitBake gets source code.
1774 When the build system searches for source code, it first
1775 tries the local download directory.
1776 If that location fails, the build system tries locations
1777 defined by
Brad Bishop19323692019-04-05 15:28:33 -04001778 <link linkend='var-bb-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001779 the upstream source, and then locations specified by
1780 <filename>MIRRORS</filename> in that order.
1781 </para>
1782 </glossdef>
1783 </glossentry>
1784
Brad Bishop19323692019-04-05 15:28:33 -04001785 <glossentry id='var-bb-MULTI_PROVIDER_WHITELIST'><glossterm>MULTI_PROVIDER_WHITELIST</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001786 <glossdef>
1787 <para>
1788 Allows you to suppress BitBake warnings caused when
1789 building two separate recipes that provide the same
1790 output.
1791 </para>
1792
1793 <para>
Andrew Geissler82c905d2020-04-13 13:39:40 -05001794 BitBake normally issues a warning when building two
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001795 different recipes where each provides the same output.
1796 This scenario is usually something the user does not
1797 want.
1798 However, cases do exist where it makes sense, particularly
1799 in the <filename>virtual/*</filename> namespace.
1800 You can use this variable to suppress BitBake's warnings.
1801 </para>
1802
1803 <para>
1804 To use the variable, list provider names (e.g.
1805 recipe names, <filename>virtual/kernel</filename>,
1806 and so forth).
1807 </para>
1808 </glossdef>
1809 </glossentry>
1810
1811 </glossdiv>
1812
1813<!--
1814 <glossdiv id='var-glossary-n'><title>N</title>
1815 </glossdiv>
1816-->
1817
Brad Bishop19323692019-04-05 15:28:33 -04001818 <glossdiv id='var-bb-glossary-o'><title>O</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001819
Brad Bishop19323692019-04-05 15:28:33 -04001820 <glossentry id='var-bb-OVERRIDES'><glossterm>OVERRIDES</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001821 <glossdef>
1822 <para>
1823 BitBake uses <filename>OVERRIDES</filename> to control
1824 what variables are overridden after BitBake parses
1825 recipes and configuration files.
1826 </para>
1827
1828 <para>
1829 Following is a simple example that uses an overrides
1830 list based on machine architectures:
1831 <literallayout class='monospaced'>
1832 OVERRIDES = "arm:x86:mips:powerpc"
1833 </literallayout>
1834 You can find information on how to use
1835 <filename>OVERRIDES</filename> in the
1836 "<link linkend='conditional-syntax-overrides'>Conditional Syntax (Overrides)</link>"
1837 section.
1838 </para>
1839 </glossdef>
1840 </glossentry>
1841 </glossdiv>
1842
Brad Bishop19323692019-04-05 15:28:33 -04001843 <glossdiv id='var-bb-glossary-p'><title>P</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001844
Brad Bishop19323692019-04-05 15:28:33 -04001845 <glossentry id='var-bb-P4DIR'><glossterm>P4DIR</glossterm>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001846 <glossdef>
1847 <para>
1848 The directory in which a local copy of a Perforce depot
1849 is stored when it is fetched.
1850 </para>
1851 </glossdef>
1852 </glossentry>
1853
Brad Bishop19323692019-04-05 15:28:33 -04001854 <glossentry id='var-bb-PACKAGES'><glossterm>PACKAGES</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001855 <glossdef>
1856 <para>The list of packages the recipe creates.
1857 </para>
1858 </glossdef>
1859 </glossentry>
1860
Brad Bishop19323692019-04-05 15:28:33 -04001861 <glossentry id='var-bb-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001862 <glossdef>
1863 <para>
1864 A promise that your recipe satisfies runtime dependencies
1865 for optional modules that are found in other recipes.
1866 <filename>PACKAGES_DYNAMIC</filename>
1867 does not actually satisfy the dependencies, it only states that
1868 they should be satisfied.
1869 For example, if a hard, runtime dependency
Brad Bishop19323692019-04-05 15:28:33 -04001870 (<link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link>)
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001871 of another package is satisfied during the build
1872 through the <filename>PACKAGES_DYNAMIC</filename>
1873 variable, but a package with the module name is never actually
1874 produced, then the other package will be broken.
1875 </para>
1876 </glossdef>
1877 </glossentry>
1878
Brad Bishop19323692019-04-05 15:28:33 -04001879 <glossentry id='var-bb-PE'><glossterm>PE</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001880 <glossdef>
1881 <para>
1882 The epoch of the recipe.
1883 By default, this variable is unset.
1884 The variable is used to make upgrades possible when the
1885 versioning scheme changes in some backwards incompatible
1886 way.
1887 </para>
1888 </glossdef>
1889 </glossentry>
1890
Brad Bishop19323692019-04-05 15:28:33 -04001891 <glossentry id='var-bb-PERSISTENT_DIR'><glossterm>PERSISTENT_DIR</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001892 <glossdef>
1893 <para>
1894 Specifies the directory BitBake uses to store data that
1895 should be preserved between builds.
1896 In particular, the data stored is the data that uses
1897 BitBake's persistent data API and the data used by the
1898 PR Server and PR Service.
1899 </para>
1900 </glossdef>
1901 </glossentry>
1902
Brad Bishop19323692019-04-05 15:28:33 -04001903 <glossentry id='var-bb-PF'><glossterm>PF</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001904 <glossdef>
1905 <para>
1906 Specifies the recipe or package name and includes all version and revision
1907 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
1908 <filename>bash-4.2-r1/</filename>).
1909 </para>
1910 </glossdef>
1911 </glossentry>
1912
Brad Bishop19323692019-04-05 15:28:33 -04001913 <glossentry id='var-bb-PN'><glossterm>PN</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001914 <glossdef>
1915 <para>The recipe name.</para>
1916 </glossdef>
1917 </glossentry>
1918
Brad Bishop19323692019-04-05 15:28:33 -04001919 <glossentry id='var-bb-PR'><glossterm>PR</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001920 <glossdef>
1921 <para>The revision of the recipe.
1922 </para>
1923 </glossdef>
1924 </glossentry>
1925
Brad Bishop19323692019-04-05 15:28:33 -04001926 <glossentry id='var-bb-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001927 <glossdef>
1928 <para>
1929 Determines which recipe should be given preference when
1930 multiple recipes provide the same item.
1931 You should always suffix the variable with the name of the
1932 provided item, and you should set it to the
Brad Bishop19323692019-04-05 15:28:33 -04001933 <link linkend='var-bb-PN'><filename>PN</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001934 of the recipe to which you want to give precedence.
1935 Some examples:
1936 <literallayout class='monospaced'>
1937 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
1938 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
1939 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
1940 </literallayout>
1941 </para>
1942 </glossdef>
1943 </glossentry>
1944
Brad Bishop19323692019-04-05 15:28:33 -04001945 <glossentry id='var-bb-PREFERRED_PROVIDERS'><glossterm>PREFERRED_PROVIDERS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001946 <glossdef>
1947 <para>
1948 Determines which recipe should be given preference for
1949 cases where multiple recipes provide the same item.
1950 Functionally,
1951 <filename>PREFERRED_PROVIDERS</filename> is identical to
Brad Bishop19323692019-04-05 15:28:33 -04001952 <link linkend='var-bb-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001953 However, the <filename>PREFERRED_PROVIDERS</filename>
1954 variable lets you define preferences for multiple
1955 situations using the following form:
1956 <literallayout class='monospaced'>
1957 PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..."
1958 </literallayout>
1959 This form is a convenient replacement for the following:
1960 <literallayout class='monospaced'>
1961 PREFERRED_PROVIDER_xxx = "yyy"
1962 PREFERRED_PROVIDER_aaa = "bbb"
1963 </literallayout>
1964 </para>
1965 </glossdef>
1966 </glossentry>
1967
Brad Bishop19323692019-04-05 15:28:33 -04001968 <glossentry id='var-bb-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001969 <glossdef>
1970 <para>
1971 If there are multiple versions of recipes available, this
1972 variable determines which recipe should be given preference.
1973 You must always suffix the variable with the
Brad Bishop19323692019-04-05 15:28:33 -04001974 <link linkend='var-bb-PN'><filename>PN</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001975 you want to select, and you should set
Brad Bishop19323692019-04-05 15:28:33 -04001976 <link linkend='var-bb-PV'><filename>PV</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001977 accordingly for precedence.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001978 </para>
1979
1980 <para>
1981 The <filename>PREFERRED_VERSION</filename> variable
1982 supports limited wildcard use through the
1983 "<filename>%</filename>" character.
1984 You can use the character to match any number of
1985 characters, which can be useful when specifying versions
1986 that contain long revision numbers that potentially change.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001987 Here are two examples:
1988 <literallayout class='monospaced'>
1989 PREFERRED_VERSION_python = "2.7.3"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001990 PREFERRED_VERSION_linux-yocto = "4.12%"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001991 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001992 <note><title>Important</title>
1993 The use of the "<filename>%</filename>" character
1994 is limited in that it only works at the end of the
1995 string.
1996 You cannot use the wildcard character in any other
1997 location of the string.
1998 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001999 </para>
2000 </glossdef>
2001 </glossentry>
2002
Brad Bishop19323692019-04-05 15:28:33 -04002003 <glossentry id='var-bb-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002004 <glossdef>
2005 <para>
2006 Specifies additional paths from which BitBake gets source code.
2007 When the build system searches for source code, it first
2008 tries the local download directory.
2009 If that location fails, the build system tries locations
2010 defined by <filename>PREMIRRORS</filename>, the upstream
2011 source, and then locations specified by
Brad Bishop19323692019-04-05 15:28:33 -04002012 <link linkend='var-bb-MIRRORS'><filename>MIRRORS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002013 in that order.
2014 </para>
2015
2016 <para>
2017 Typically, you would add a specific server for the
2018 build system to attempt before any others by adding
2019 something like the following to your configuration:
2020 <literallayout class='monospaced'>
2021 PREMIRRORS_prepend = "\
2022 git://.*/.* http://www.yoctoproject.org/sources/ \n \
2023 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
2024 http://.*/.* http://www.yoctoproject.org/sources/ \n \
2025 https://.*/.* http://www.yoctoproject.org/sources/ \n"
2026 </literallayout>
2027 These changes cause the build system to intercept
2028 Git, FTP, HTTP, and HTTPS requests and direct them to
2029 the <filename>http://</filename> sources mirror.
2030 You can use <filename>file://</filename> URLs to point
2031 to local directories or network shares as well.
2032 </para>
2033 </glossdef>
2034 </glossentry>
2035
Brad Bishop19323692019-04-05 15:28:33 -04002036 <glossentry id='var-bb-PROVIDES'><glossterm>PROVIDES</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002037 <glossdef>
2038 <para>
2039 A list of aliases by which a particular recipe can be
2040 known.
2041 By default, a recipe's own
Brad Bishop19323692019-04-05 15:28:33 -04002042 <filename><link linkend='var-bb-PN'>PN</link></filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002043 is implicitly already in its <filename>PROVIDES</filename>
2044 list.
2045 If a recipe uses <filename>PROVIDES</filename>, the
2046 additional aliases are synonyms for the recipe and can
2047 be useful satisfying dependencies of other recipes during
2048 the build as specified by
Brad Bishop19323692019-04-05 15:28:33 -04002049 <filename><link linkend='var-bb-DEPENDS'>DEPENDS</link></filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002050 </para>
2051
2052 <para>
2053 Consider the following example
2054 <filename>PROVIDES</filename> statement from a recipe
2055 file <filename>libav_0.8.11.bb</filename>:
2056 <literallayout class='monospaced'>
2057 PROVIDES += "libpostproc"
2058 </literallayout>
2059 The <filename>PROVIDES</filename> statement results in
2060 the "libav" recipe also being known as "libpostproc".
2061 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002062
2063 <para>
2064 In addition to providing recipes under alternate names,
2065 the <filename>PROVIDES</filename> mechanism is also used
2066 to implement virtual targets.
2067 A virtual target is a name that corresponds to some
2068 particular functionality (e.g. a Linux kernel).
2069 Recipes that provide the functionality in question list the
2070 virtual target in <filename>PROVIDES</filename>.
2071 Recipes that depend on the functionality in question can
2072 include the virtual target in
Brad Bishop19323692019-04-05 15:28:33 -04002073 <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002074 to leave the choice of provider open.
2075 </para>
2076
2077 <para>
2078 Conventionally, virtual targets have names on the form
2079 "virtual/function" (e.g. "virtual/kernel").
2080 The slash is simply part of the name and has no
2081 syntactical significance.
2082 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002083 </glossdef>
2084 </glossentry>
2085
Brad Bishop19323692019-04-05 15:28:33 -04002086 <glossentry id='var-bb-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002087 <glossdef>
2088 <para>
2089 The network based
Brad Bishop19323692019-04-05 15:28:33 -04002090 <link linkend='var-bb-PR'><filename>PR</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002091 service host and port.
2092 </para>
2093
2094 <para>
2095 Following is an example of how the <filename>PRSERV_HOST</filename> variable is
2096 set:
2097 <literallayout class='monospaced'>
2098 PRSERV_HOST = "localhost:0"
2099 </literallayout>
2100 You must set the variable if you want to automatically
2101 start a local PR service.
2102 You can set <filename>PRSERV_HOST</filename> to other
2103 values to use a remote PR service.
2104 </para>
2105 </glossdef>
2106 </glossentry>
2107
Brad Bishop19323692019-04-05 15:28:33 -04002108 <glossentry id='var-bb-PV'><glossterm>PV</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002109 <glossdef>
2110 <para>The version of the recipe.
2111 </para>
2112 </glossdef>
2113 </glossentry>
2114
2115 </glossdiv>
2116
2117<!--
2118 <glossdiv id='var-glossary-q'><title>Q</title>
2119 </glossdiv>
2120-->
2121
Brad Bishop19323692019-04-05 15:28:33 -04002122 <glossdiv id='var-bb-glossary-r'><title>R</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002123
Brad Bishop19323692019-04-05 15:28:33 -04002124 <glossentry id='var-bb-RDEPENDS'><glossterm>RDEPENDS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002125 <glossdef>
2126 <para>
2127 Lists a package's runtime dependencies (i.e. other packages)
2128 that must be installed in order for the built package to run
2129 correctly.
2130 If a package in this list cannot be found during the build,
2131 you will get a build error.
2132 </para>
2133
2134 <para>
2135 Because the <filename>RDEPENDS</filename> variable applies
2136 to packages being built, you should always use the variable
2137 in a form with an attached package name.
2138 For example, suppose you are building a development package
2139 that depends on the <filename>perl</filename> package.
2140 In this case, you would use the following
2141 <filename>RDEPENDS</filename> statement:
2142 <literallayout class='monospaced'>
2143 RDEPENDS_${PN}-dev += "perl"
2144 </literallayout>
2145 In the example, the development package depends on
2146 the <filename>perl</filename> package.
2147 Thus, the <filename>RDEPENDS</filename> variable has the
2148 <filename>${PN}-dev</filename> package name as part of the
2149 variable.
2150 </para>
2151
2152 <para>
2153 BitBake supports specifying versioned dependencies.
2154 Although the syntax varies depending on the packaging
2155 format, BitBake hides these differences from you.
2156 Here is the general syntax to specify versions with
2157 the <filename>RDEPENDS</filename> variable:
2158 <literallayout class='monospaced'>
2159 RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
2160 </literallayout>
2161 For <filename>operator</filename>, you can specify the
2162 following:
2163 <literallayout class='monospaced'>
2164 =
2165 &lt;
2166 &gt;
2167 &lt;=
2168 &gt;=
2169 </literallayout>
2170 For example, the following sets up a dependency on version
2171 1.2 or greater of the package <filename>foo</filename>:
2172 <literallayout class='monospaced'>
2173 RDEPENDS_${PN} = "foo (>= 1.2)"
2174 </literallayout>
2175 </para>
2176
2177 <para>
2178 For information on build-time dependencies, see the
Brad Bishop19323692019-04-05 15:28:33 -04002179 <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002180 variable.
2181 </para>
2182 </glossdef>
2183 </glossentry>
2184
Brad Bishop19323692019-04-05 15:28:33 -04002185 <glossentry id='var-bb-REPODIR'><glossterm>REPODIR</glossterm>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002186 <glossdef>
2187 <para>
2188 The directory in which a local copy of a
2189 <filename>google-repo</filename> directory is stored
2190 when it is synced.
2191 </para>
2192 </glossdef>
2193 </glossentry>
2194
Brad Bishop19323692019-04-05 15:28:33 -04002195 <glossentry id='var-bb-RPROVIDES'><glossterm>RPROVIDES</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002196 <glossdef>
2197 <para>
2198 A list of package name aliases that a package also provides.
2199 These aliases are useful for satisfying runtime dependencies
2200 of other packages both during the build and on the target
2201 (as specified by
Brad Bishop19323692019-04-05 15:28:33 -04002202 <filename><link linkend='var-bb-RDEPENDS'>RDEPENDS</link></filename>).
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002203 </para>
2204 <para>
2205 As with all package-controlling variables, you must always
2206 use the variable in conjunction with a package name override.
2207 Here is an example:
2208 <literallayout class='monospaced'>
2209 RPROVIDES_${PN} = "widget-abi-2"
2210 </literallayout>
2211 </para>
2212 </glossdef>
2213 </glossentry>
2214
Brad Bishop19323692019-04-05 15:28:33 -04002215 <glossentry id='var-bb-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002216 <glossdef>
2217 <para>
2218 A list of packages that extends the usability of a package
2219 being built.
2220 The package being built does not depend on this list of
2221 packages in order to successfully build, but needs them for
2222 the extended usability.
2223 To specify runtime dependencies for packages, see the
Brad Bishop19323692019-04-05 15:28:33 -04002224 <filename><link linkend='var-bb-RDEPENDS'>RDEPENDS</link></filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002225 variable.
2226 </para>
2227
2228 <para>
2229 BitBake supports specifying versioned recommends.
2230 Although the syntax varies depending on the packaging
2231 format, BitBake hides these differences from you.
2232 Here is the general syntax to specify versions with
2233 the <filename>RRECOMMENDS</filename> variable:
2234 <literallayout class='monospaced'>
2235 RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
2236 </literallayout>
2237 For <filename>operator</filename>, you can specify the
2238 following:
2239 <literallayout class='monospaced'>
2240 =
2241 &lt;
2242 &gt;
2243 &lt;=
2244 &gt;=
2245 </literallayout>
2246 For example, the following sets up a recommend on version
2247 1.2 or greater of the package <filename>foo</filename>:
2248 <literallayout class='monospaced'>
2249 RRECOMMENDS_${PN} = "foo (>= 1.2)"
2250 </literallayout>
2251 </para>
2252 </glossdef>
2253 </glossentry>
2254
2255 </glossdiv>
2256
Brad Bishop19323692019-04-05 15:28:33 -04002257 <glossdiv id='var-bb-glossary-s'><title>S</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002258
Brad Bishop19323692019-04-05 15:28:33 -04002259 <glossentry id='var-bb-SECTION'><glossterm>SECTION</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002260 <glossdef>
2261 <para>The section in which packages should be categorized.</para>
2262 </glossdef>
2263 </glossentry>
2264
Brad Bishop19323692019-04-05 15:28:33 -04002265 <glossentry id='var-bb-SRC_URI'><glossterm>SRC_URI</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002266 <glossdef>
2267 <para>
2268 The list of source files - local or remote.
2269 This variable tells BitBake which bits
2270 to pull for the build and how to pull them.
2271 For example, if the recipe or append file needs to
2272 fetch a single tarball from the Internet, the recipe or
2273 append file uses a <filename>SRC_URI</filename>
2274 entry that specifies that tarball.
2275 On the other hand, if the recipe or append file needs to
2276 fetch a tarball and include a custom file, the recipe or
2277 append file needs an <filename>SRC_URI</filename> variable
2278 that specifies all those sources.</para>
2279 <para>The following list explains the available URI protocols:
2280 <itemizedlist>
2281 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
2282 Fetches files, which are usually files shipped with
2283 the metadata,
2284 from the local machine.
2285 The path is relative to the
Brad Bishop19323692019-04-05 15:28:33 -04002286 <link linkend='var-bb-FILESPATH'><filename>FILESPATH</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002287 variable.</para></listitem>
2288 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
2289 Bazaar revision control repository.</para></listitem>
2290 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
2291 Git revision control repository.</para></listitem>
2292 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
2293 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
2294 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
2295 a repo (Git) repository.</para></listitem>
2296 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
2297 the Internet using HTTP.</para></listitem>
2298 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
2299 from the Internet using HTTPS.</para></listitem>
2300 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
2301 from the Internet using FTP.</para></listitem>
2302 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
2303 a CVS revision control repository.</para></listitem>
2304 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
2305 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
2306 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
2307 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
2308 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
2309 a secure shell.</para></listitem>
2310 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
2311 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
2312 </itemizedlist>
2313 </para>
2314 <para>Here are some additional options worth mentioning:
2315 <itemizedlist>
2316 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
2317 whether or not to unpack the file if it is an archive.
2318 The default action is to unpack the file.</para></listitem>
2319 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
2320 (or extracts its contents) into the specified
2321 subdirectory.
2322 This option is useful for unusual tarballs or other archives that
2323 do not have their files already in a subdirectory within the archive.
2324 </para></listitem>
2325 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
2326 name to be used for association with <filename>SRC_URI</filename> checksums
2327 when you have more than one file specified in <filename>SRC_URI</filename>.
2328 </para></listitem>
2329 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
2330 the filename used when storing the downloaded file.</para></listitem>
2331 </itemizedlist>
2332 </para>
2333 </glossdef>
2334 </glossentry>
2335
Brad Bishop19323692019-04-05 15:28:33 -04002336 <glossentry id='var-bb-SRCDATE'><glossterm>SRCDATE</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002337 <glossdef>
2338 <para>
2339 The date of the source code used to build the package.
2340 This variable applies only if the source was fetched from a Source Code Manager (SCM).
2341 </para>
2342 </glossdef>
2343 </glossentry>
2344
Brad Bishop19323692019-04-05 15:28:33 -04002345 <glossentry id='var-bb-SRCREV'><glossterm>SRCREV</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002346 <glossdef>
2347 <para>
2348 The revision of the source code used to build the package.
2349 This variable applies only when using Subversion, Git, Mercurial and Bazaar.
2350 If you want to build a fixed revision and you want
2351 to avoid performing a query on the remote repository every time
2352 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
2353 full revision identifier and not just a tag.
2354 </para>
2355 </glossdef>
2356 </glossentry>
2357
Brad Bishop19323692019-04-05 15:28:33 -04002358 <glossentry id='var-bb-SRCREV_FORMAT'><glossterm>SRCREV_FORMAT</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002359 <glossdef>
2360 <para>
2361 Helps construct valid
Brad Bishop19323692019-04-05 15:28:33 -04002362 <link linkend='var-bb-SRCREV'><filename>SRCREV</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002363 values when multiple source controlled URLs are used in
Brad Bishop19323692019-04-05 15:28:33 -04002364 <link linkend='var-bb-SRC_URI'><filename>SRC_URI</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002365 </para>
2366
2367 <para>
2368 The system needs help constructing these values under these
2369 circumstances.
2370 Each component in the <filename>SRC_URI</filename>
2371 is assigned a name and these are referenced
2372 in the <filename>SRCREV_FORMAT</filename> variable.
2373 Consider an example with URLs named "machine" and "meta".
2374 In this case, <filename>SRCREV_FORMAT</filename> could look
2375 like "machine_meta" and those names would have the SCM
2376 versions substituted into each position.
2377 Only one <filename>AUTOINC</filename> placeholder is added
2378 and if needed.
2379 And, this placeholder is placed at the start of the
2380 returned string.
2381 </para>
2382 </glossdef>
2383 </glossentry>
2384
Brad Bishop19323692019-04-05 15:28:33 -04002385 <glossentry id='var-bb-STAMP'><glossterm>STAMP</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002386 <glossdef>
2387 <para>
2388 Specifies the base path used to create recipe stamp files.
2389 The path to an actual stamp file is constructed by evaluating this
2390 string and then appending additional information.
2391 </para>
2392 </glossdef>
2393 </glossentry>
2394
Brad Bishop19323692019-04-05 15:28:33 -04002395 <glossentry id='var-bb-STAMPCLEAN'><glossterm>STAMPCLEAN</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002396 <glossdef>
2397 <para>
2398 Specifies the base path used to create recipe stamp files.
2399 Unlike the
Brad Bishop19323692019-04-05 15:28:33 -04002400 <link linkend='var-bb-STAMP'><filename>STAMP</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002401 variable, <filename>STAMPCLEAN</filename> can contain
2402 wildcards to match the range of files a clean operation
2403 should remove.
2404 BitBake uses a clean operation to remove any other stamps
2405 it should be removing when creating a new stamp.
2406 </para>
2407 </glossdef>
2408 </glossentry>
2409
Brad Bishop19323692019-04-05 15:28:33 -04002410 <glossentry id='var-bb-SUMMARY'><glossterm>SUMMARY</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002411 <glossdef>
2412 <para>
2413 A short summary for the recipe, which is 72 characters or less.
2414 </para>
2415 </glossdef>
2416 </glossentry>
2417
Brad Bishop19323692019-04-05 15:28:33 -04002418 <glossentry id='var-bb-SVNDIR'><glossterm>SVNDIR</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002419 <glossdef>
2420 <para>
2421 The directory in which files checked out of a Subversion
2422 system are stored.
2423 </para>
2424 </glossdef>
2425 </glossentry>
2426
2427 </glossdiv>
2428
Brad Bishop19323692019-04-05 15:28:33 -04002429 <glossdiv id='var-bb-glossary-t'><title>T</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002430
Brad Bishop19323692019-04-05 15:28:33 -04002431 <glossentry id='var-bb-T'><glossterm>T</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002432 <glossdef>
2433 <para>Points to a directory were BitBake places
2434 temporary files, which consist mostly of task logs and
2435 scripts, when building a particular recipe.
2436 </para>
2437 </glossdef>
2438 </glossentry>
2439
Brad Bishop19323692019-04-05 15:28:33 -04002440 <glossentry id='var-bb-TOPDIR'><glossterm>TOPDIR</glossterm>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002441 <glossdef>
2442 <para>
2443 Points to the build directory.
2444 BitBake automatically sets this variable.
2445 </para>
2446 </glossdef>
2447 </glossentry>
2448
2449 </glossdiv>
2450
2451<!--
2452 <glossdiv id='var-glossary-u'><title>U</title>
2453 </glossdiv>
2454
2455 <glossdiv id='var-glossary-v'><title>V</title>
2456 </glossdiv>
2457
2458 <glossdiv id='var-glossary-w'><title>W</title>
2459 </glossdiv>
2460
2461 <glossdiv id='var-glossary-x'><title>X</title>
2462 </glossdiv>
2463
2464 <glossdiv id='var-glossary-y'><title>Y</title>
2465 </glossdiv>
2466
2467 <glossdiv id='var-glossary-z'><title>Z</title>
2468 </glossdiv>
2469-->
2470
2471
2472</glossary>
2473</chapter>
2474<!--
2475vim: expandtab tw=80 ts=4
2476-->