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