blob: 88622421db0cb8265c38fb7ea42bbfec9a86d4ca [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
4<chapter id="bitbake-user-manual-metadata">
5 <title>Syntax and Operators</title>
6
7 <para>
8 Bitbake files have their own syntax.
9 The syntax has similarities to several
10 other languages but also has some unique features.
11 This section describes the available syntax and operators
12 as well as provides examples.
13 </para>
14
15 <section id='basic-syntax'>
16 <title>Basic Syntax</title>
17
18 <para>
19 This section provides some basic syntax examples.
20 </para>
21
22 <section id='basic-variable-setting'>
23 <title>Basic Variable Setting</title>
24
25 <para>
26 The following example sets <filename>VARIABLE</filename> to
27 "value".
28 This assignment occurs immediately as the statement is parsed.
29 It is a "hard" assignment.
30 <literallayout class='monospaced'>
31 VARIABLE = "value"
32 </literallayout>
33 As expected, if you include leading or trailing spaces as part of
34 an assignment, the spaces are retained:
35 <literallayout class='monospaced'>
36 VARIABLE = " value"
37 VARIABLE = "value "
38 </literallayout>
39 Setting <filename>VARIABLE</filename> to "" sets it to an empty string,
40 while setting the variable to " " sets it to a blank space
41 (i.e. these are not the same values).
42 <literallayout class='monospaced'>
43 VARIABLE = ""
44 VARIABLE = " "
45 </literallayout>
46 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -060047
48 <para>
49 You can use single quotes instead of double quotes
50 when setting a variable's value.
51 Doing so allows you to use values that contain the double
52 quote character:
53 <literallayout class='monospaced'>
54 VARIABLE = 'I have a " in my value'
55 </literallayout>
56 <note>
57 Unlike in Bourne shells, single quotes work identically
58 to double quotes in all other ways.
59 They do not suppress variable expansions.
60 </note>
61 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050062 </section>
63
Brad Bishopc342db32019-05-15 21:57:59 -040064 <section id='modifying-existing-variables'>
65 <title>Modifying Existing Variables</title>
66
67 <para>
68 Sometimes you need to modify existing variables.
69 Following are some cases where you might find you want to
70 modify an existing variable:
71 <itemizedlist>
72 <listitem><para>
73 Customize a recipe that uses the variable.
74 </para></listitem>
75 <listitem><para>
76 Change a variable's default value used in a
77 <filename>*.bbclass</filename> file.
78 </para></listitem>
79 <listitem><para>
80 Change the variable in a <filename>*.bbappend</filename>
81 file to override the variable in the original recipe.
82 </para></listitem>
83 <listitem><para>
84 Change the variable in a configuration file so that the
85 value overrides an existing configuration.
86 </para></listitem>
87 </itemizedlist>
88 </para>
89
90 <para>
91 Changing a variable value can sometimes depend on how the
92 value was originally assigned and also on the desired
93 intent of the change.
94 In particular, when you append a value to a variable that
95 has a default value, the resulting value might not be what
96 you expect.
97 In this case, the value you provide might replace the value
98 rather than append to the default value.
99 </para>
100
101 <para>
102 If after you have changed a variable's value and something
103 unexplained occurs, you can use BitBake to check the actual
104 value of the suspect variable.
105 You can make these checks for both configuration and recipe
106 level changes:
107 <itemizedlist>
108 <listitem><para>
109 For configuration changes, use the following:
110 <literallayout class='monospaced'>
111 $ bitbake -e
112 </literallayout>
113 This command displays variable values after the
114 configuration files (i.e. <filename>local.conf</filename>,
115 <filename>bblayers.conf</filename>,
116 <filename>bitbake.conf</filename> and so forth) have
117 been parsed.
118 <note>
119 Variables that are exported to the environment are
120 preceded by the string "export" in the command's
121 output.
122 </note>
123 </para></listitem>
124 <listitem><para>
125 For recipe changes, use the following:
126 <literallayout class='monospaced'>
127 $ bitbake <replaceable>recipe</replaceable> -e | grep VARIABLE="
128 </literallayout>
129 This command checks to see if the variable actually
130 makes it into a specific recipe.
131 </para></listitem>
132 </itemizedlist>
133 </para>
134 </section>
135
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500136 <section id='line-joining'>
137 <title>Line Joining</title>
138
139 <para>
140 Outside of
141 <link linkend='functions'>functions</link>, BitBake joins
142 any line ending in a backslash character ("\")
143 with the following line before parsing statements.
144 The most common use for the "\" character is to split variable
145 assignments over multiple lines, as in the following example:
146 <literallayout class='monospaced'>
147 FOO = "bar \
148 baz \
149 qaz"
150 </literallayout>
151 Both the "\" character and the newline character
152 that follow it are removed when joining lines.
153 Thus, no newline characters end up in the value of
154 <filename>FOO</filename>.
155 </para>
156
157 <para>
158 Consider this additional example where the two
159 assignments both assign "barbaz" to
160 <filename>FOO</filename>:
161 <literallayout class='monospaced'>
162 FOO = "barbaz"
163
164 FOO = "bar\
165 baz"
166 </literallayout>
167 <note>
168 BitBake does not interpret escape sequences like
169 "\n" in variable values.
170 For these to have an effect, the value must be passed
171 to some utility that interprets escape sequences,
172 such as <filename>printf</filename> or
173 <filename>echo -n</filename>.
174 </note>
175 </para>
176 </section>
177
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500178 <section id='variable-expansion'>
179 <title>Variable Expansion</title>
180
181 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600182 Variables can reference the contents of other variables
183 using a syntax that is similar to variable expansion in
184 Bourne shells.
185 The following assignments
186 result in A containing "aval" and B evaluating to "preavalpost".
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500187 <literallayout class='monospaced'>
188 A = "aval"
189 B = "pre${A}post"
190 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600191 <note>
192 Unlike in Bourne shells, the curly braces are mandatory:
193 Only <filename>${FOO}</filename> and not
194 <filename>$FOO</filename> is recognized as an expansion of
195 <filename>FOO</filename>.
196 </note>
197 The "=" operator does not immediately expand variable
198 references in the right-hand side.
199 Instead, expansion is deferred until the variable assigned to
200 is actually used.
201 The result depends on the current values of the referenced
202 variables.
203 The following example should clarify this behavior:
204 <literallayout class='monospaced'>
205 A = "${B} baz"
206 B = "${C} bar"
207 C = "foo"
208 *At this point, ${A} equals "foo bar baz"*
209 C = "qux"
210 *At this point, ${A} equals "qux bar baz"*
211 B = "norf"
212 *At this point, ${A} equals "norf baz"*
213 </literallayout>
214 Contrast this behavior with the
215 <link linkend='immediate-variable-expansion'>immediate variable expansion</link>
216 operator (i.e. ":=").
217 </para>
218
219 <para>
220 If the variable expansion syntax is used on a variable that
221 does not exist, the string is kept as is.
222 For example, given the following assignment,
223 <filename>BAR</filename> expands to the literal string
224 "${FOO}" as long as <filename>FOO</filename> does not exist.
225 <literallayout class='monospaced'>
226 BAR = "${FOO}"
227 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500228 </para>
229 </section>
230
231 <section id='setting-a-default-value'>
232 <title>Setting a default value (?=)</title>
233
234 <para>
235 You can use the "?=" operator to achieve a "softer" assignment
236 for a variable.
237 This type of assignment allows you to define a variable if it
238 is undefined when the statement is parsed, but to leave the
239 value alone if the variable has a value.
240 Here is an example:
241 <literallayout class='monospaced'>
242 A ?= "aval"
243 </literallayout>
244 If <filename>A</filename> is set at the time this statement is parsed,
245 the variable retains its value.
246 However, if <filename>A</filename> is not set,
247 the variable is set to "aval".
248 <note>
249 This assignment is immediate.
250 Consequently, if multiple "?=" assignments
251 to a single variable exist, the first of those ends up getting
252 used.
253 </note>
254 </para>
255 </section>
256
257 <section id='setting-a-weak-default-value'>
258 <title>Setting a weak default value (??=)</title>
259
260 <para>
261 It is possible to use a "weaker" assignment than in the
262 previous section by using the "??=" operator.
263 This assignment behaves identical to "?=" except that the
264 assignment is made at the end of the parsing process rather
265 than immediately.
266 Consequently, when multiple "??=" assignments exist, the last
267 one is used.
268 Also, any "=" or "?=" assignment will override the value set with
269 "??=".
270 Here is an example:
271 <literallayout class='monospaced'>
272 A ??= "somevalue"
273 A ??= "someothervalue"
274 </literallayout>
275 If <filename>A</filename> is set before the above statements are parsed,
276 the variable retains its value.
277 If <filename>A</filename> is not set,
278 the variable is set to "someothervalue".
279 </para>
280
281 <para>
282 Again, this assignment is a "lazy" or "weak" assignment
283 because it does not occur until the end
284 of the parsing process.
285 </para>
286 </section>
287
288 <section id='immediate-variable-expansion'>
289 <title>Immediate variable expansion (:=)</title>
290
291 <para>
292 The ":=" operator results in a variable's
293 contents being expanded immediately,
294 rather than when the variable is actually used:
295 <literallayout class='monospaced'>
296 T = "123"
297 A := "${B} ${A} test ${T}"
298 T = "456"
299 B = "${T} bval"
300 C = "cval"
301 C := "${C}append"
302 </literallayout>
303 In this example, <filename>A</filename> contains
304 "test 123" because <filename>${B}</filename> and
305 <filename>${A}</filename> at the time of parsing are undefined,
306 which leaves "test 123".
307 And, the variable <filename>C</filename>
308 contains "cvalappend" since <filename>${C}</filename> immediately
309 expands to "cval".
310 </para>
311 </section>
312
313 <section id='appending-and-prepending'>
314 <title>Appending (+=) and prepending (=+) With Spaces</title>
315
316 <para>
317 Appending and prepending values is common and can be accomplished
318 using the "+=" and "=+" operators.
319 These operators insert a space between the current
320 value and prepended or appended value.
321 </para>
322
323 <para>
324 These operators take immediate effect during parsing.
325 Here are some examples:
326 <literallayout class='monospaced'>
327 B = "bval"
328 B += "additionaldata"
329 C = "cval"
330 C =+ "test"
331 </literallayout>
332 The variable <filename>B</filename> contains
333 "bval additionaldata" and <filename>C</filename>
334 contains "test cval".
335 </para>
336 </section>
337
338 <section id='appending-and-prepending-without-spaces'>
339 <title>Appending (.=) and Prepending (=.) Without Spaces</title>
340
341 <para>
342 If you want to append or prepend values without an
343 inserted space, use the ".=" and "=." operators.
344 </para>
345
346 <para>
347 These operators take immediate effect during parsing.
348 Here are some examples:
349 <literallayout class='monospaced'>
350 B = "bval"
351 B .= "additionaldata"
352 C = "cval"
353 C =. "test"
354 </literallayout>
355 The variable <filename>B</filename> contains
356 "bvaladditionaldata" and
357 <filename>C</filename> contains "testcval".
358 </para>
359 </section>
360
361 <section id='appending-and-prepending-override-style-syntax'>
362 <title>Appending and Prepending (Override Style Syntax)</title>
363
364 <para>
365 You can also append and prepend a variable's value
366 using an override style syntax.
367 When you use this syntax, no spaces are inserted.
368 </para>
369
370 <para>
371 These operators differ from the ":=", ".=", "=.", "+=", and "=+"
372 operators in that their effects are deferred
373 until after parsing completes rather than being immediately
374 applied.
375 Here are some examples:
376 <literallayout class='monospaced'>
377 B = "bval"
378 B_append = " additional data"
379 C = "cval"
380 C_prepend = "additional data "
381 D = "dval"
382 D_append = "additional data"
383 </literallayout>
384 The variable <filename>B</filename> becomes
385 "bval additional data" and <filename>C</filename> becomes
386 "additional data cval".
387 The variable <filename>D</filename> becomes
388 "dvaladditional data".
389 <note>
390 You must control all spacing when you use the
391 override syntax.
392 </note>
393 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600394
395 <para>
396 It is also possible to append and prepend to shell
397 functions and BitBake-style Python functions.
398 See the
399 "<link linkend='shell-functions'>Shell Functions</link>" and
400 "<link linkend='bitbake-style-python-functions'>BitBake-Style Python Functions</link>
401 sections for examples.
402 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500403 </section>
404
405 <section id='removing-override-style-syntax'>
406 <title>Removal (Override Style Syntax)</title>
407
408 <para>
409 You can remove values from lists using the removal
410 override style syntax.
411 Specifying a value for removal causes all occurrences of that
412 value to be removed from the variable.
413 </para>
414
415 <para>
416 When you use this syntax, BitBake expects one or more strings.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800417 Surrounding spaces and spacing are preserved.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500418 Here is an example:
419 <literallayout class='monospaced'>
420 FOO = "123 456 789 123456 123 456 123 456"
421 FOO_remove = "123"
422 FOO_remove = "456"
Brad Bishop79641f22019-09-10 07:20:22 -0400423 FOO2 = " abc def ghi abcdef abc def abc def def"
424 FOO2_remove = " \
425 def \
426 abc \
427 ghi \
428 "
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500429 </literallayout>
430 The variable <filename>FOO</filename> becomes
Brad Bishop79641f22019-09-10 07:20:22 -0400431 "&nbsp;&nbsp;789&nbsp;123456&nbsp;&nbsp;&nbsp;&nbsp;"
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800432 and <filename>FOO2</filename> becomes
Brad Bishop79641f22019-09-10 07:20:22 -0400433 "&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;jkl&nbsp;&nbsp;abcdef&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;".
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500434 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600435
436 <para>
437 Like "_append" and "_prepend", "_remove"
438 is deferred until after parsing completes.
439 </para>
440 </section>
441
442 <section id='override-style-operation-advantages'>
443 <title>Override Style Operation Advantages</title>
444
445 <para>
446 An advantage of the override style operations
447 "_append", "_prepend", and "_remove" as compared to the
448 "+=" and "=+" operators is that the override style
449 operators provide guaranteed operations.
450 For example, consider a class <filename>foo.bbclass</filename>
451 that needs to add the value "val" to the variable
452 <filename>FOO</filename>, and a recipe that uses
453 <filename>foo.bbclass</filename> as follows:
454 <literallayout class='monospaced'>
455 inherit foo
456
457 FOO = "initial"
458 </literallayout>
459 If <filename>foo.bbclass</filename> uses the "+=" operator,
460 as follows, then the final value of <filename>FOO</filename>
461 will be "initial", which is not what is desired:
462 <literallayout class='monospaced'>
463 FOO += "val"
464 </literallayout>
465 If, on the other hand, <filename>foo.bbclass</filename>
466 uses the "_append" operator, then the final value of
467 <filename>FOO</filename> will be "initial val", as intended:
468 <literallayout class='monospaced'>
469 FOO_append = " val"
470 </literallayout>
471 <note>
472 It is never necessary to use "+=" together with "_append".
473 The following sequence of assignments appends "barbaz" to
474 <filename>FOO</filename>:
475 <literallayout class='monospaced'>
476 FOO_append = "bar"
477 FOO_append = "baz"
478 </literallayout>
479 The only effect of changing the second assignment in the
480 previous example to use "+=" would be to add a space before
481 "baz" in the appended value (due to how the "+=" operator
482 works).
483 </note>
484 Another advantage of the override style operations is that
485 you can combine them with other overrides as described in the
486 "<link linkend='conditional-syntax-overrides'>Conditional Syntax (Overrides)</link>"
487 section.
488 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500489 </section>
490
491 <section id='variable-flag-syntax'>
492 <title>Variable Flag Syntax</title>
493
494 <para>
495 Variable flags are BitBake's implementation of variable properties
496 or attributes.
497 It is a way of tagging extra information onto a variable.
498 You can find more out about variable flags in general in the
499 "<link linkend='variable-flags'>Variable Flags</link>"
500 section.
501 </para>
502
503 <para>
504 You can define, append, and prepend values to variable flags.
505 All the standard syntax operations previously mentioned work
506 for variable flags except for override style syntax
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600507 (i.e. "_prepend", "_append", and "_remove").
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500508 </para>
509
510 <para>
511 Here are some examples showing how to set variable flags:
512 <literallayout class='monospaced'>
513 FOO[a] = "abc"
514 FOO[b] = "123"
515 FOO[a] += "456"
516 </literallayout>
517 The variable <filename>FOO</filename> has two flags:
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600518 <filename>[a]</filename> and <filename>[b]</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500519 The flags are immediately set to "abc" and "123", respectively.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600520 The <filename>[a]</filename> flag becomes "abc 456".
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500521 </para>
522
523 <para>
524 No need exists to pre-define variable flags.
525 You can simply start using them.
526 One extremely common application
527 is to attach some brief documentation to a BitBake variable as
528 follows:
529 <literallayout class='monospaced'>
530 CACHE[doc] = "The directory holding the cache of the metadata."
531 </literallayout>
532 </para>
533 </section>
534
535 <section id='inline-python-variable-expansion'>
536 <title>Inline Python Variable Expansion</title>
537
538 <para>
539 You can use inline Python variable expansion to
540 set variables.
541 Here is an example:
542 <literallayout class='monospaced'>
543 DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
544 </literallayout>
545 This example results in the <filename>DATE</filename>
546 variable being set to the current date.
547 </para>
548
549 <para>
550 Probably the most common use of this feature is to extract
551 the value of variables from BitBake's internal data dictionary,
552 <filename>d</filename>.
553 The following lines select the values of a package name
554 and its version number, respectively:
555 <literallayout class='monospaced'>
556 PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
557 PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"
558 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600559 <note>
560 Inline Python expressions work just like variable expansions
561 insofar as the "=" and ":=" operators are concerned.
562 Given the following assignment, <filename>foo()</filename>
563 is called each time <filename>FOO</filename> is expanded:
564 <literallayout class='monospaced'>
565 FOO = "${@foo()}"
566 </literallayout>
567 Contrast this with the following immediate assignment, where
568 <filename>foo()</filename> is only called once, while the
569 assignment is parsed:
570 <literallayout class='monospaced'>
571 FOO := "${@foo()}"
572 </literallayout>
573 </note>
574 For a different way to set variables with Python code during
575 parsing, see the
576 "<link linkend='anonymous-python-functions'>Anonymous Python Functions</link>"
577 section.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500578 </para>
579 </section>
580
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600581 <section id='unsetting-variables'>
Brad Bishopb1114e52019-02-13 07:56:10 -0500582 <title>Unsetting variables</title>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600583
584 <para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500585 It is possible to completely remove a variable or a variable flag
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600586 from BitBake's internal data dictionary by using the "unset" keyword.
587 Here is an example:
588 <literallayout class='monospaced'>
589 unset DATE
590 unset do_fetch[noexec]
591 </literallayout>
Brad Bishop6e60e8b2018-02-01 10:27:11 -0500592 These two statements remove the <filename>DATE</filename> and the
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600593 <filename>do_fetch[noexec]</filename> flag.
594 </para>
595
596 </section>
597
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500598 <section id='providing-pathnames'>
599 <title>Providing Pathnames</title>
600
601 <para>
602 When specifying pathnames for use with BitBake,
603 do not use the tilde ("~") character as a shortcut
604 for your home directory.
605 Doing so might cause BitBake to not recognize the
606 path since BitBake does not expand this character in
607 the same way a shell would.
608 </para>
609
610 <para>
611 Instead, provide a fuller path as the following
612 example illustrates:
613 <literallayout class='monospaced'>
614 BBLAYERS ?= " \
615 /home/scott-lenovo/LayerA \
616 "
617 </literallayout>
618 </para>
619 </section>
620 </section>
621
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600622 <section id='exporting-variables-to-the-environment'>
623 <title>Exporting Variables to the Environment</title>
624
625 <para>
626 You can export variables to the environment of running
627 tasks by using the <filename>export</filename> keyword.
628 For example, in the following example, the
629 <filename>do_foo</filename> task prints "value from
630 the environment" when run:
631 <literallayout class='monospaced'>
632 export ENV_VARIABLE
633 ENV_VARIABLE = "value from the environment"
634
635 do_foo() {
636 bbplain "$ENV_VARIABLE"
637 }
638 </literallayout>
639 <note>
640 BitBake does not expand <filename>$ENV_VARIABLE</filename>
641 in this case because it lacks the obligatory
642 <filename>{}</filename>.
643 Rather, <filename>$ENV_VARIABLE</filename> is expanded
644 by the shell.
645 </note>
646 It does not matter whether
647 <filename>export ENV_VARIABLE</filename> appears before or
648 after assignments to <filename>ENV_VARIABLE</filename>.
649 </para>
650
651 <para>
652 It is also possible to combine <filename>export</filename>
653 with setting a value for the variable.
654 Here is an example:
655 <literallayout class='monospaced'>
656 export ENV_VARIABLE = "<replaceable>variable-value</replaceable>"
657 </literallayout>
658 In the output of <filename>bitbake -e</filename>, variables
659 that are exported to the environment are preceded by "export".
660 </para>
661
662 <para>
663 Among the variables commonly exported to the environment
664 are <filename>CC</filename> and <filename>CFLAGS</filename>,
665 which are picked up by many build systems.
666 </para>
667 </section>
668
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500669 <section id='conditional-syntax-overrides'>
670 <title>Conditional Syntax (Overrides)</title>
671
672 <para>
673 BitBake uses
Brad Bishop19323692019-04-05 15:28:33 -0400674 <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500675 to control what variables are overridden after BitBake
676 parses recipes and configuration files.
677 This section describes how you can use
678 <filename>OVERRIDES</filename> as conditional metadata,
679 talks about key expansion in relationship to
680 <filename>OVERRIDES</filename>, and provides some examples
681 to help with understanding.
682 </para>
683
684 <section id='conditional-metadata'>
685 <title>Conditional Metadata</title>
686
687 <para>
688 You can use <filename>OVERRIDES</filename> to conditionally select
689 a specific version of a variable and to conditionally
690 append or prepend the value of a variable.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500691 <note>
692 Overrides can only use lower-case characters.
693 Additionally, underscores are not permitted in override names
694 as they are used to separate overrides from each other and
695 from the variable name.
696 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500697 <itemizedlist>
698 <listitem><para><emphasis>Selecting a Variable:</emphasis>
699 The <filename>OVERRIDES</filename> variable is
700 a colon-character-separated list that contains items
701 for which you want to satisfy conditions.
702 Thus, if you have a variable that is conditional on “arm”, and “arm”
703 is in <filename>OVERRIDES</filename>, then the “arm”-specific
704 version of the variable is used rather than the non-conditional
705 version.
706 Here is an example:
707 <literallayout class='monospaced'>
708 OVERRIDES = "architecture:os:machine"
709 TEST = "default"
710 TEST_os = "osspecific"
711 TEST_nooverride = "othercondvalue"
712 </literallayout>
713 In this example, the <filename>OVERRIDES</filename>
714 variable lists three overrides:
715 "architecture", "os", and "machine".
716 The variable <filename>TEST</filename> by itself has a default
717 value of "default".
718 You select the os-specific version of the <filename>TEST</filename>
719 variable by appending the "os" override to the variable
720 (i.e.<filename>TEST_os</filename>).
721 </para>
722
723 <para>
724 To better understand this, consider a practical example
725 that assumes an OpenEmbedded metadata-based Linux
726 kernel recipe file.
727 The following lines from the recipe file first set
728 the kernel branch variable <filename>KBRANCH</filename>
729 to a default value, then conditionally override that
730 value based on the architecture of the build:
731 <literallayout class='monospaced'>
732 KBRANCH = "standard/base"
733 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
734 KBRANCH_qemumips = "standard/mti-malta32"
735 KBRANCH_qemuppc = "standard/qemuppc"
736 KBRANCH_qemux86 = "standard/common-pc/base"
737 KBRANCH_qemux86-64 = "standard/common-pc-64/base"
738 KBRANCH_qemumips64 = "standard/mti-malta64"
739 </literallayout>
740 </para></listitem>
741 <listitem><para><emphasis>Appending and Prepending:</emphasis>
742 BitBake also supports append and prepend operations to
743 variable values based on whether a specific item is
744 listed in <filename>OVERRIDES</filename>.
745 Here is an example:
746 <literallayout class='monospaced'>
747 DEPENDS = "glibc ncurses"
748 OVERRIDES = "machine:local"
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500749 DEPENDS_append_machine = " libmad"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500750 </literallayout>
751 In this example, <filename>DEPENDS</filename> becomes
752 "glibc ncurses libmad".
753 </para>
754
755 <para>
756 Again, using an OpenEmbedded metadata-based
757 kernel recipe file as an example, the
758 following lines will conditionally append to the
759 <filename>KERNEL_FEATURES</filename> variable based
760 on the architecture:
761 <literallayout class='monospaced'>
762 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
763 KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc"
764 KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc"
765 </literallayout>
766 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600767 <listitem><para><emphasis>Setting a Variable for a Single Task:</emphasis>
768 BitBake supports setting a variable just for the
769 duration of a single task.
770 Here is an example:
771 <literallayout class='monospaced'>
772 FOO_task-configure = "val 1"
773 FOO_task-compile = "val 2"
774 </literallayout>
775 In the previous example, <filename>FOO</filename>
776 has the value "val 1" while the
777 <filename>do_configure</filename> task is executed,
778 and the value "val 2" while the
779 <filename>do_compile</filename> task is executed.
780 </para>
781
782 <para>Internally, this is implemented by prepending
783 the task (e.g. "task-compile:") to the value of
Brad Bishop19323692019-04-05 15:28:33 -0400784 <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600785 for the local datastore of the <filename>do_compile</filename>
786 task.</para>
787
788 <para>You can also use this syntax with other combinations
789 (e.g. "<filename>_prepend</filename>") as shown in the
790 following example:
791 <literallayout class='monospaced'>
792 EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} "
793 </literallayout>
794 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500795 </itemizedlist>
796 </para>
797 </section>
798
799 <section id='key-expansion'>
800 <title>Key Expansion</title>
801
802 <para>
803 Key expansion happens when the BitBake datastore is finalized
804 just before BitBake expands overrides.
805 To better understand this, consider the following example:
806 <literallayout class='monospaced'>
807 A${B} = "X"
808 B = "2"
809 A2 = "Y"
810 </literallayout>
811 In this case, after all the parsing is complete, and
812 before any overrides are handled, BitBake expands
813 <filename>${B}</filename> into "2".
814 This expansion causes <filename>A2</filename>, which was
815 set to "Y" before the expansion, to become "X".
816 </para>
817 </section>
818
819 <section id='variable-interaction-worked-examples'>
820 <title>Examples</title>
821
822 <para>
823 Despite the previous explanations that show the different forms of
824 variable definitions, it can be hard to work
825 out exactly what happens when variable operators, conditional
826 overrides, and unconditional overrides are combined.
827 This section presents some common scenarios along
828 with explanations for variable interactions that
829 typically confuse users.
830 </para>
831
832 <para>
833 There is often confusion concerning the order in which
834 overrides and various "append" operators take effect.
835 Recall that an append or prepend operation using "_append"
836 and "_prepend" does not result in an immediate assignment
837 as would "+=", ".=", "=+", or "=.".
838 Consider the following example:
839 <literallayout class='monospaced'>
840 OVERRIDES = "foo"
841 A = "Z"
842 A_foo_append = "X"
843 </literallayout>
844 For this case, <filename>A</filename> is
845 unconditionally set to "Z" and "X" is
846 unconditionally and immediately appended to the variable
847 <filename>A_foo</filename>.
848 Because overrides have not been applied yet,
849 <filename>A_foo</filename> is set to "X" due to the append
850 and <filename>A</filename> simply equals "Z".
851 </para>
852
853 <para>
854 Applying overrides, however, changes things.
855 Since "foo" is listed in <filename>OVERRIDES</filename>,
856 the conditional variable <filename>A</filename> is replaced
857 with the "foo" version, which is equal to "X".
858 So effectively, <filename>A_foo</filename> replaces <filename>A</filename>.
859 </para>
860
861 <para>
862 This next example changes the order of the override and
863 the append:
864 <literallayout class='monospaced'>
865 OVERRIDES = "foo"
866 A = "Z"
867 A_append_foo = "X"
868 </literallayout>
869 For this case, before overrides are handled,
870 <filename>A</filename> is set to "Z" and <filename>A_append_foo</filename>
871 is set to "X".
872 Once the override for "foo" is applied, however,
873 <filename>A</filename> gets appended with "X".
874 Consequently, <filename>A</filename> becomes "ZX".
875 Notice that spaces are not appended.
876 </para>
877
878 <para>
879 This next example has the order of the appends and overrides reversed
880 back as in the first example:
881 <literallayout class='monospaced'>
882 OVERRIDES = "foo"
883 A = "Y"
884 A_foo_append = "Z"
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600885 A_foo_append = "X"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500886 </literallayout>
887 For this case, before any overrides are resolved,
888 <filename>A</filename> is set to "Y" using an immediate assignment.
889 After this immediate assignment, <filename>A_foo</filename> is set
890 to "Z", and then further appended with
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600891 "X" leaving the variable set to "ZX".
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500892 Finally, applying the override for "foo" results in the conditional
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600893 variable <filename>A</filename> becoming "ZX" (i.e.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500894 <filename>A</filename> is replaced with <filename>A_foo</filename>).
895 </para>
896
897 <para>
898 This final example mixes in some varying operators:
899 <literallayout class='monospaced'>
900 A = "1"
901 A_append = "2"
902 A_append = "3"
903 A += "4"
904 A .= "5"
905 </literallayout>
906 For this case, the type of append operators are affecting the
907 order of assignments as BitBake passes through the code
908 multiple times.
909 Initially, <filename>A</filename> is set to "1 45" because
910 of the three statements that use immediate operators.
911 After these assignments are made, BitBake applies the
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600912 "_append" operations.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500913 Those operations result in <filename>A</filename> becoming "1 4523".
914 </para>
915 </section>
916 </section>
917
918 <section id='sharing-functionality'>
919 <title>Sharing Functionality</title>
920
921 <para>
922 BitBake allows for metadata sharing through include files
923 (<filename>.inc</filename>) and class files
924 (<filename>.bbclass</filename>).
925 For example, suppose you have a piece of common functionality
926 such as a task definition that you want to share between
927 more than one recipe.
928 In this case, creating a <filename>.bbclass</filename>
929 file that contains the common functionality and then using
930 the <filename>inherit</filename> directive in your recipes to
931 inherit the class would be a common way to share the task.
932 </para>
933
934 <para>
935 This section presents the mechanisms BitBake provides to
936 allow you to share functionality between recipes.
937 Specifically, the mechanisms include <filename>include</filename>,
938 <filename>inherit</filename>, <filename>INHERIT</filename>, and
939 <filename>require</filename> directives.
940 </para>
941
942 <section id='locating-include-and-class-files'>
943 <title>Locating Include and Class Files</title>
944
945 <para>
946 BitBake uses the
Brad Bishop19323692019-04-05 15:28:33 -0400947 <link linkend='var-bb-BBPATH'><filename>BBPATH</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500948 variable to locate needed include and class files.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500949 Additionally, BitBake searches the current directory for
950 <filename>include</filename> and <filename>require</filename>
951 directives.
952 <note>
953 The <filename>BBPATH</filename> variable is analogous to
954 the environment variable <filename>PATH</filename>.
955 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500956 </para>
957
958 <para>
959 In order for include and class files to be found by BitBake,
960 they need to be located in a "classes" subdirectory that can
961 be found in <filename>BBPATH</filename>.
962 </para>
963 </section>
964
965 <section id='inherit-directive'>
966 <title><filename>inherit</filename> Directive</title>
967
968 <para>
969 When writing a recipe or class file, you can use the
970 <filename>inherit</filename> directive to inherit the
971 functionality of a class (<filename>.bbclass</filename>).
972 BitBake only supports this directive when used within recipe
973 and class files (i.e. <filename>.bb</filename> and
974 <filename>.bbclass</filename>).
975 </para>
976
977 <para>
978 The <filename>inherit</filename> directive is a rudimentary
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500979 means of specifying functionality contained in class files
980 that your recipes require.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500981 For example, you can easily abstract out the tasks involved in
982 building a package that uses Autoconf and Automake and put
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500983 those tasks into a class file and then have your recipe
984 inherit that class file.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500985 </para>
986
987 <para>
988 As an example, your recipes could use the following directive
989 to inherit an <filename>autotools.bbclass</filename> file.
990 The class file would contain common functionality for using
991 Autotools that could be shared across recipes:
992 <literallayout class='monospaced'>
993 inherit autotools
994 </literallayout>
995 In this case, BitBake would search for the directory
996 <filename>classes/autotools.bbclass</filename>
997 in <filename>BBPATH</filename>.
998 <note>
999 You can override any values and functions of the
1000 inherited class within your recipe by doing so
1001 after the "inherit" statement.
1002 </note>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001003 If you want to use the directive to inherit
1004 multiple classes, separate them with spaces.
1005 The following example shows how to inherit both the
1006 <filename>buildhistory</filename> and <filename>rm_work</filename>
1007 classes:
1008 <literallayout class='monospaced'>
1009 inherit buildhistory rm_work
1010 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001011 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001012
1013 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001014 An advantage with the inherit directive as compared to both
1015 the
1016 <link linkend='include-directive'>include</link> and
1017 <link linkend='require-inclusion'>require</link> directives
1018 is that you can inherit class files conditionally.
1019 You can accomplish this by using a variable expression
1020 after the <filename>inherit</filename> statement.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001021 Here is an example:
1022 <literallayout class='monospaced'>
1023 inherit ${VARNAME}
1024 </literallayout>
1025 If <filename>VARNAME</filename> is going to be set, it needs
1026 to be set before the <filename>inherit</filename> statement
1027 is parsed.
1028 One way to achieve a conditional inherit in this case is to use
1029 overrides:
1030 <literallayout class='monospaced'>
1031 VARIABLE = ""
1032 VARIABLE_someoverride = "myclass"
1033 </literallayout>
1034 </para>
1035
1036 <para>
1037 Another method is by using anonymous Python.
1038 Here is an example:
1039 <literallayout class='monospaced'>
1040 python () {
1041 if condition == value:
1042 d.setVar('VARIABLE', 'myclass')
1043 else:
1044 d.setVar('VARIABLE', '')
1045 }
1046 </literallayout>
1047 </para>
1048
1049 <para>
1050 Alternatively, you could use an in-line Python expression
1051 in the following form:
1052 <literallayout class='monospaced'>
1053 inherit ${@'classname' if condition else ''}
1054 inherit ${@functionname(params)}
1055 </literallayout>
1056 In all cases, if the expression evaluates to an empty
1057 string, the statement does not trigger a syntax error
1058 because it becomes a no-op.
1059 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001060 </section>
1061
1062 <section id='include-directive'>
1063 <title><filename>include</filename> Directive</title>
1064
1065 <para>
1066 BitBake understands the <filename>include</filename>
1067 directive.
1068 This directive causes BitBake to parse whatever file you specify,
1069 and to insert that file at that location.
1070 The directive is much like its equivalent in Make except
1071 that if the path specified on the include line is a relative
1072 path, BitBake locates the first file it can find
1073 within <filename>BBPATH</filename>.
1074 </para>
1075
1076 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001077 The include directive is a more generic method of including
1078 functionality as compared to the
1079 <link linkend='inherit-directive'>inherit</link> directive,
1080 which is restricted to class (i.e. <filename>.bbclass</filename>)
1081 files.
1082 The include directive is applicable for any other kind of
1083 shared or encapsulated functionality or configuration that
1084 does not suit a <filename>.bbclass</filename> file.
1085 </para>
1086
1087 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001088 As an example, suppose you needed a recipe to include some
1089 self-test definitions:
1090 <literallayout class='monospaced'>
1091 include test_defs.inc
1092 </literallayout>
1093 <note>
1094 The <filename>include</filename> directive does not
1095 produce an error when the file cannot be found.
1096 Consequently, it is recommended that if the file you
1097 are including is expected to exist, you should use
1098 <link linkend='require-inclusion'><filename>require</filename></link>
1099 instead of <filename>include</filename>.
1100 Doing so makes sure that an error is produced if the
1101 file cannot be found.
1102 </note>
1103 </para>
1104 </section>
1105
1106 <section id='require-inclusion'>
1107 <title><filename>require</filename> Directive</title>
1108
1109 <para>
1110 BitBake understands the <filename>require</filename>
1111 directive.
1112 This directive behaves just like the
1113 <filename>include</filename> directive with the exception that
1114 BitBake raises a parsing error if the file to be included cannot
1115 be found.
1116 Thus, any file you require is inserted into the file that is
1117 being parsed at the location of the directive.
1118 </para>
1119
1120 <para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001121 The require directive, like the include directive previously
1122 described, is a more generic method of including
1123 functionality as compared to the
1124 <link linkend='inherit-directive'>inherit</link> directive,
1125 which is restricted to class (i.e. <filename>.bbclass</filename>)
1126 files.
1127 The require directive is applicable for any other kind of
1128 shared or encapsulated functionality or configuration that
1129 does not suit a <filename>.bbclass</filename> file.
1130 </para>
1131
1132 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001133 Similar to how BitBake handles
1134 <link linkend='include-directive'><filename>include</filename></link>,
1135 if the path specified
1136 on the require line is a relative path, BitBake locates
1137 the first file it can find within <filename>BBPATH</filename>.
1138 </para>
1139
1140 <para>
1141 As an example, suppose you have two versions of a recipe
1142 (e.g. <filename>foo_1.2.2.bb</filename> and
1143 <filename>foo_2.0.0.bb</filename>) where
1144 each version contains some identical functionality that could be
1145 shared.
1146 You could create an include file named <filename>foo.inc</filename>
1147 that contains the common definitions needed to build "foo".
1148 You need to be sure <filename>foo.inc</filename> is located in the
1149 same directory as your two recipe files as well.
1150 Once these conditions are set up, you can share the functionality
1151 using a <filename>require</filename> directive from within each
1152 recipe:
1153 <literallayout class='monospaced'>
1154 require foo.inc
1155 </literallayout>
1156 </para>
1157 </section>
1158
1159 <section id='inherit-configuration-directive'>
1160 <title><filename>INHERIT</filename> Configuration Directive</title>
1161
1162 <para>
1163 When creating a configuration file (<filename>.conf</filename>),
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001164 you can use the
Brad Bishop19323692019-04-05 15:28:33 -04001165 <link linkend='var-bb-INHERIT'><filename>INHERIT</filename></link>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001166 configuration directive to inherit a class.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001167 BitBake only supports this directive when used within
1168 a configuration file.
1169 </para>
1170
1171 <para>
1172 As an example, suppose you needed to inherit a class
1173 file called <filename>abc.bbclass</filename> from a
1174 configuration file as follows:
1175 <literallayout class='monospaced'>
1176 INHERIT += "abc"
1177 </literallayout>
1178 This configuration directive causes the named
1179 class to be inherited at the point of the directive
1180 during parsing.
1181 As with the <filename>inherit</filename> directive, the
1182 <filename>.bbclass</filename> file must be located in a
1183 "classes" subdirectory in one of the directories specified
1184 in <filename>BBPATH</filename>.
1185 <note>
1186 Because <filename>.conf</filename> files are parsed
1187 first during BitBake's execution, using
1188 <filename>INHERIT</filename> to inherit a class effectively
1189 inherits the class globally (i.e. for all recipes).
1190 </note>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001191 If you want to use the directive to inherit
1192 multiple classes, you can provide them on the same line in the
1193 <filename>local.conf</filename> file.
1194 Use spaces to separate the classes.
1195 The following example shows how to inherit both the
1196 <filename>autotools</filename> and <filename>pkgconfig</filename>
1197 classes:
1198 <literallayout class='monospaced'>
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001199 INHERIT += "autotools pkgconfig"
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001200 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001201 </para>
1202 </section>
1203 </section>
1204
1205 <section id='functions'>
1206 <title>Functions</title>
1207
1208 <para>
1209 As with most languages, functions are the building blocks that
1210 are used to build up operations into tasks.
1211 BitBake supports these types of functions:
1212 <itemizedlist>
1213 <listitem><para><emphasis>Shell Functions:</emphasis>
1214 Functions written in shell script and executed either
1215 directly as functions, tasks, or both.
1216 They can also be called by other shell functions.
1217 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001218 <listitem><para><emphasis>BitBake-Style Python Functions:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001219 Functions written in Python and executed by BitBake or other
1220 Python functions using <filename>bb.build.exec_func()</filename>.
1221 </para></listitem>
1222 <listitem><para><emphasis>Python Functions:</emphasis>
1223 Functions written in Python and executed by Python.
1224 </para></listitem>
1225 <listitem><para><emphasis>Anonymous Python Functions:</emphasis>
1226 Python functions executed automatically during
1227 parsing.
1228 </para></listitem>
1229 </itemizedlist>
1230 Regardless of the type of function, you can only
1231 define them in class (<filename>.bbclass</filename>)
1232 and recipe (<filename>.bb</filename> or <filename>.inc</filename>)
1233 files.
1234 </para>
1235
1236 <section id='shell-functions'>
1237 <title>Shell Functions</title>
1238
1239 <para>
1240 Functions written in shell script and executed either
1241 directly as functions, tasks, or both.
1242 They can also be called by other shell functions.
1243 Here is an example shell function definition:
1244 <literallayout class='monospaced'>
1245 some_function () {
1246 echo "Hello World"
1247 }
1248 </literallayout>
1249 When you create these types of functions in your recipe
1250 or class files, you need to follow the shell programming
1251 rules.
1252 The scripts are executed by <filename>/bin/sh</filename>,
1253 which may not be a bash shell but might be something
1254 such as <filename>dash</filename>.
1255 You should not use Bash-specific script (bashisms).
1256 </para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001257
1258 <para>
1259 Overrides and override-style operators like
1260 <filename>_append</filename> and
1261 <filename>_prepend</filename> can also be applied to
1262 shell functions.
1263 Most commonly, this application would be used in a
1264 <filename>.bbappend</filename> file to modify functions in
1265 the main recipe.
1266 It can also be used to modify functions inherited from
1267 classes.
1268 </para>
1269
1270 <para>
1271 As an example, consider the following:
1272 <literallayout class='monospaced'>
1273 do_foo() {
1274 bbplain first
1275 fn
1276 }
1277
1278 fn_prepend() {
1279 bbplain second
1280 }
1281
1282 fn() {
1283 bbplain third
1284 }
1285
1286 do_foo_append() {
1287 bbplain fourth
1288 }
1289 </literallayout>
1290 Running <filename>do_foo</filename>
1291 prints the following:
1292 <literallayout class='monospaced'>
1293 recipename do_foo: first
1294 recipename do_foo: second
1295 recipename do_foo: third
1296 recipename do_foo: fourth
1297 </literallayout>
1298 <note>
1299 Overrides and override-style operators can
1300 be applied to any shell function, not just
1301 <link linkend='tasks'>tasks</link>.
1302 </note>
1303 You can use the <filename>bitbake -e</filename>&nbsp;<replaceable>recipename</replaceable>
1304 command to view the final assembled function
1305 after all overrides have been applied.
1306 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001307 </section>
1308
1309 <section id='bitbake-style-python-functions'>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001310 <title>BitBake-Style Python Functions</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001311
1312 <para>
1313 These functions are written in Python and executed by
1314 BitBake or other Python functions using
1315 <filename>bb.build.exec_func()</filename>.
1316 </para>
1317
1318 <para>
1319 An example BitBake function is:
1320 <literallayout class='monospaced'>
1321 python some_python_function () {
1322 d.setVar("TEXT", "Hello World")
Brad Bishop6e60e8b2018-02-01 10:27:11 -05001323 print d.getVar("TEXT")
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001324 }
1325 </literallayout>
1326 Because the Python "bb" and "os" modules are already
1327 imported, you do not need to import these modules.
1328 Also in these types of functions, the datastore ("d")
1329 is a global variable and is always automatically
1330 available.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001331 <note>
1332 Variable expressions (e.g. <filename>${X}</filename>)
1333 are no longer expanded within Python functions.
1334 This behavior is intentional in order to allow you
1335 to freely set variable values to expandable expressions
1336 without having them expanded prematurely.
1337 If you do wish to expand a variable within a Python
Brad Bishop6e60e8b2018-02-01 10:27:11 -05001338 function, use <filename>d.getVar("X")</filename>.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001339 Or, for more complicated expressions, use
1340 <filename>d.expand()</filename>.
1341 </note>
1342 </para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001343
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001344 <para>
1345 Similar to shell functions, you can also apply overrides
1346 and override-style operators to BitBake-style Python
1347 functions.
1348 </para>
1349
1350 <para>
1351 As an example, consider the following:
1352 <literallayout class='monospaced'>
1353 python do_foo_prepend() {
1354 bb.plain("first")
1355 }
1356
1357 python do_foo() {
1358 bb.plain("second")
1359 }
1360
1361 python do_foo_append() {
1362 bb.plain("third")
1363 }
1364 </literallayout>
1365 Running <filename>do_foo</filename> prints
1366 the following:
1367 <literallayout class='monospaced'>
1368 recipename do_foo: first
1369 recipename do_foo: second
1370 recipename do_foo: third
1371 </literallayout>
1372 You can use the <filename>bitbake -e</filename>&nbsp;<replaceable>recipename</replaceable>
1373 command to view the final assembled function
1374 after all overrides have been applied.
1375 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001376 </section>
1377
1378 <section id='python-functions'>
1379 <title>Python Functions</title>
1380
1381 <para>
1382 These functions are written in Python and are executed by
1383 other Python code.
1384 Examples of Python functions are utility functions
1385 that you intend to call from in-line Python or
1386 from within other Python functions.
1387 Here is an example:
1388 <literallayout class='monospaced'>
1389 def get_depends(d):
Brad Bishop6e60e8b2018-02-01 10:27:11 -05001390 if d.getVar('SOMECONDITION'):
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001391 return "dependencywithcond"
1392 else:
1393 return "dependency"
1394 SOMECONDITION = "1"
1395 DEPENDS = "${@get_depends(d)}"
1396 </literallayout>
1397 This would result in <filename>DEPENDS</filename>
1398 containing <filename>dependencywithcond</filename>.
1399 </para>
1400
1401 <para>
1402 Here are some things to know about Python functions:
1403 <itemizedlist>
1404 <listitem><para>Python functions can take parameters.
1405 </para></listitem>
1406 <listitem><para>The BitBake datastore is not
1407 automatically available.
1408 Consequently, you must pass it in as a
1409 parameter to the function.
1410 </para></listitem>
1411 <listitem><para>The "bb" and "os" Python modules are
1412 automatically available.
1413 You do not need to import them.
1414 </para></listitem>
1415 </itemizedlist>
1416 </para>
1417 </section>
1418
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001419 <section id='bitbake-style-python-functions-versus-python-functions'>
1420 <title>Bitbake-Style Python Functions Versus Python Functions</title>
1421
1422 <para>
1423 Following are some important differences between
1424 BitBake-style Python functions and regular Python
1425 functions defined with "def":
1426 <itemizedlist>
1427 <listitem><para>
1428 Only BitBake-style Python functions can be
1429 <link linkend='tasks'>tasks</link>.
1430 </para></listitem>
1431 <listitem><para>
1432 Overrides and override-style operators can only
1433 be applied to BitBake-style Python functions.
1434 </para></listitem>
1435 <listitem><para>
1436 Only regular Python functions can take arguments
1437 and return values.
1438 </para></listitem>
1439 <listitem><para>
1440 <link linkend='variable-flags'>Variable flags</link>
1441 such as <filename>[dirs]</filename>,
1442 <filename>[cleandirs]</filename>, and
1443 <filename>[lockfiles]</filename> can be used
1444 on BitBake-style Python functions, but not on
1445 regular Python functions.
1446 </para></listitem>
1447 <listitem><para>
1448 BitBake-style Python functions generate a separate
Brad Bishop19323692019-04-05 15:28:33 -04001449 <filename>${</filename><link linkend='var-bb-T'><filename>T</filename></link><filename>}/run.</filename><replaceable>function-name</replaceable><filename>.</filename><replaceable>pid</replaceable>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001450 script that is executed to run the function, and also
1451 generate a log file in
1452 <filename>${T}/log.</filename><replaceable>function-name</replaceable><filename>.</filename><replaceable>pid</replaceable>
1453 if they are executed as tasks.</para>
1454
1455 <para>
1456 Regular Python functions execute "inline" and do not
1457 generate any files in <filename>${T}</filename>.
1458 </para></listitem>
1459 <listitem><para>
1460 Regular Python functions are called with the usual
1461 Python syntax.
1462 BitBake-style Python functions are usually tasks and
1463 are called directly by BitBake, but can also be called
1464 manually from Python code by using the
1465 <filename>bb.build.exec_func()</filename> function.
1466 Here is an example:
1467 <literallayout class='monospaced'>
1468 bb.build.exec_func("my_bitbake_style_function", d)
1469 </literallayout>
1470 <note>
1471 <filename>bb.build.exec_func()</filename> can also
1472 be used to run shell functions from Python code.
1473 If you want to run a shell function before a Python
1474 function within the same task, then you can use a
1475 parent helper Python function that starts by running
1476 the shell function with
1477 <filename>bb.build.exec_func()</filename> and then
1478 runs the Python code.
1479 </note></para>
1480
1481 <para>To detect errors from functions executed with
1482 <filename>bb.build.exec_func()</filename>, you
1483 can catch the <filename>bb.build.FuncFailed</filename>
1484 exception.
1485 <note>
1486 Functions in metadata (recipes and classes) should
1487 not themselves raise
1488 <filename>bb.build.FuncFailed</filename>.
1489 Rather, <filename>bb.build.FuncFailed</filename>
1490 should be viewed as a general indicator that the
1491 called function failed by raising an exception.
1492 For example, an exception raised by
1493 <filename>bb.fatal()</filename> will be caught inside
1494 <filename>bb.build.exec_func()</filename>, and a
1495 <filename>bb.build.FuncFailed</filename> will be raised
1496 in response.
1497 </note>
1498 </para></listitem>
1499 </itemizedlist>
1500 </para>
1501
1502 <para>
1503 Due to their simplicity, you should prefer regular Python functions
1504 over BitBake-style Python functions unless you need a feature specific
1505 to BitBake-style Python functions.
1506 Regular Python functions in metadata are a more recent invention than
1507 BitBake-style Python functions, and older code tends to use
1508 <filename>bb.build.exec_func()</filename> more often.
1509 </para>
1510 </section>
1511
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001512 <section id='anonymous-python-functions'>
1513 <title>Anonymous Python Functions</title>
1514
1515 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001516 Sometimes it is useful to set variables or perform
1517 other operations programmatically during parsing.
1518 To do this, you can define special Python functions,
1519 called anonymous Python functions, that run at the
1520 end of parsing.
1521 For example, the following conditionally sets a variable
1522 based on the value of another variable:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001523 <literallayout class='monospaced'>
1524 python () {
Brad Bishop6e60e8b2018-02-01 10:27:11 -05001525 if d.getVar('SOMEVAR') == 'value':
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001526 d.setVar('ANOTHERVAR', 'value2')
1527 }
1528 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001529 An equivalent way to mark a function as an anonymous
1530 function is to give it the name "__anonymous", rather
1531 than no name.
1532 </para>
1533
1534 <para>
1535 Anonymous Python functions always run at the end
1536 of parsing, regardless of where they are defined.
1537 If a recipe contains many anonymous functions, they
1538 run in the same order as they are defined within the
1539 recipe.
1540 As an example, consider the following snippet:
1541 <literallayout class='monospaced'>
1542 python () {
1543 d.setVar('FOO', 'foo 2')
1544 }
1545
1546 FOO = "foo 1"
1547
1548 python () {
1549 d.appendVar('BAR', ' bar 2')
1550 }
1551
1552 BAR = "bar 1"
1553 </literallayout>
1554 The previous example is conceptually equivalent to the
1555 following snippet:
1556 <literallayout class='monospaced'>
1557 FOO = "foo 1"
1558 BAR = "bar 1"
1559 FOO = "foo 2"
1560 BAR += "bar 2"
1561 </literallayout>
1562 <filename>FOO</filename> ends up with the value "foo 2",
1563 and <filename>BAR</filename> with the value "bar 1 bar 2".
1564 Just as in the second snippet, the values set for the
1565 variables within the anonymous functions become available
1566 to tasks, which always run after parsing.
1567 </para>
1568
1569 <para>
1570 Overrides and override-style operators such as
1571 "<filename>_append</filename>" are applied before
1572 anonymous functions run.
1573 In the following example, <filename>FOO</filename> ends
1574 up with the value "foo from anonymous":
1575 <literallayout class='monospaced'>
1576 FOO = "foo"
1577 FOO_append = " from outside"
1578
1579 python () {
1580 d.setVar("FOO", "foo from anonymous")
1581 }
1582 </literallayout>
1583 For methods you can use with anonymous Python functions,
1584 see the
1585 "<link linkend='functions-you-can-call-from-within-python'>Functions You Can Call From Within Python</link>"
1586 section.
1587 For a different method to run Python code during parsing,
1588 see the
1589 "<link linkend='inline-python-variable-expansion'>Inline Python Variable Expansion</link>"
1590 section.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001591 </para>
1592 </section>
1593
1594 <section id='flexible-inheritance-for-class-functions'>
1595 <title>Flexible Inheritance for Class Functions</title>
1596
1597 <para>
1598 Through coding techniques and the use of
1599 <filename>EXPORT_FUNCTIONS</filename>, BitBake supports
1600 exporting a function from a class such that the
1601 class function appears as the default implementation
1602 of the function, but can still be called if a recipe
1603 inheriting the class needs to define its own version of
1604 the function.
1605 </para>
1606
1607 <para>
1608 To understand the benefits of this feature, consider
1609 the basic scenario where a class defines a task function
1610 and your recipe inherits the class.
1611 In this basic scenario, your recipe inherits the task
1612 function as defined in the class.
1613 If desired, your recipe can add to the start and end of the
1614 function by using the "_prepend" or "_append" operations
1615 respectively, or it can redefine the function completely.
1616 However, if it redefines the function, there is
1617 no means for it to call the class version of the function.
1618 <filename>EXPORT_FUNCTIONS</filename> provides a mechanism
1619 that enables the recipe's version of the function to call
1620 the original version of the function.
1621 </para>
1622
1623 <para>
1624 To make use of this technique, you need the following
1625 things in place:
1626 <itemizedlist>
1627 <listitem><para>
1628 The class needs to define the function as follows:
1629 <literallayout class='monospaced'>
1630 <replaceable>classname</replaceable><filename>_</filename><replaceable>functionname</replaceable>
1631 </literallayout>
1632 For example, if you have a class file
1633 <filename>bar.bbclass</filename> and a function named
1634 <filename>do_foo</filename>, the class must define the function
1635 as follows:
1636 <literallayout class='monospaced'>
1637 bar_do_foo
1638 </literallayout>
1639 </para></listitem>
1640 <listitem><para>
1641 The class needs to contain the <filename>EXPORT_FUNCTIONS</filename>
1642 statement as follows:
1643 <literallayout class='monospaced'>
1644 EXPORT_FUNCTIONS <replaceable>functionname</replaceable>
1645 </literallayout>
1646 For example, continuing with the same example, the
1647 statement in the <filename>bar.bbclass</filename> would be
1648 as follows:
1649 <literallayout class='monospaced'>
1650 EXPORT_FUNCTIONS do_foo
1651 </literallayout>
1652 </para></listitem>
1653 <listitem><para>
1654 You need to call the function appropriately from within your
1655 recipe.
1656 Continuing with the same example, if your recipe
1657 needs to call the class version of the function,
1658 it should call <filename>bar_do_foo</filename>.
1659 Assuming <filename>do_foo</filename> was a shell function
1660 and <filename>EXPORT_FUNCTIONS</filename> was used as above,
1661 the recipe's function could conditionally call the
1662 class version of the function as follows:
1663 <literallayout class='monospaced'>
1664 do_foo() {
1665 if [ somecondition ] ; then
1666 bar_do_foo
1667 else
1668 # Do something else
1669 fi
1670 }
1671 </literallayout>
1672 To call your modified version of the function as defined
1673 in your recipe, call it as <filename>do_foo</filename>.
1674 </para></listitem>
1675 </itemizedlist>
1676 With these conditions met, your single recipe
1677 can freely choose between the original function
1678 as defined in the class file and the modified function in your recipe.
1679 If you do not set up these conditions, you are limited to using one function
1680 or the other.
1681 </para>
1682 </section>
1683 </section>
1684
1685 <section id='tasks'>
1686 <title>Tasks</title>
1687
1688 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001689 Tasks are BitBake execution units that make up the
1690 steps that BitBake can run for a given recipe.
1691 Tasks are only supported in recipes and classes
1692 (i.e. in <filename>.bb</filename> files and files
1693 included or inherited from <filename>.bb</filename>
1694 files).
1695 By convention, tasks have names that start with "do_".
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001696 </para>
1697
1698 <section id='promoting-a-function-to-a-task'>
1699 <title>Promoting a Function to a Task</title>
1700
1701 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001702 Tasks are either
1703 <link linkend='shell-functions'>shell functions</link> or
1704 <link linkend='bitbake-style-python-functions'>BitBake-style Python functions</link>
1705 that have been promoted to tasks by using the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001706 <filename>addtask</filename> command.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001707 The <filename>addtask</filename> command can also
1708 optionally describe dependencies between the
1709 task and other tasks.
1710 Here is an example that shows how to define a task
1711 and declare some dependencies:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001712 <literallayout class='monospaced'>
1713 python do_printdate () {
1714 import time
1715 print time.strftime('%Y%m%d', time.gmtime())
1716 }
1717 addtask printdate after do_fetch before do_build
1718 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001719 The first argument to <filename>addtask</filename>
1720 is the name of the function to promote to
1721 a task.
1722 If the name does not start with "do_", "do_" is
1723 implicitly added, which enforces the convention that
1724 all task names start with "do_".
1725 </para>
1726
1727 <para>
1728 In the previous example, the
1729 <filename>do_printdate</filename> task becomes a
1730 dependency of the <filename>do_build</filename>
1731 task, which is the default task (i.e. the task run by
1732 the <filename>bitbake</filename> command unless
1733 another task is specified explicitly).
1734 Additionally, the <filename>do_printdate</filename>
1735 task becomes dependent upon the
1736 <filename>do_fetch</filename> task.
1737 Running the <filename>do_build</filename> task
1738 results in the <filename>do_printdate</filename>
1739 task running first.
1740 <note>
1741 If you try out the previous example, you might see that
1742 the <filename>do_printdate</filename> task is only run
1743 the first time you build the recipe with
1744 the <filename>bitbake</filename> command.
1745 This is because BitBake considers the task "up-to-date"
1746 after that initial run.
1747 If you want to force the task to always be rerun for
1748 experimentation purposes, you can make BitBake always
1749 consider the task "out-of-date" by using the
1750 <filename>[</filename><link linkend='variable-flags'><filename>nostamp</filename></link><filename>]</filename>
1751 variable flag, as follows:
1752 <literallayout class='monospaced'>
1753 do_printdate[nostamp] = "1"
1754 </literallayout>
1755 You can also explicitly run the task and provide the
1756 <filename>-f</filename> option as follows:
1757 <literallayout class='monospaced'>
1758 $ bitbake <replaceable>recipe</replaceable> -c printdate -f
1759 </literallayout>
1760 When manually selecting a task to run with the
1761 <filename>bitbake</filename>&nbsp;<replaceable>recipe</replaceable>&nbsp;<filename>-c</filename>&nbsp;<replaceable>task</replaceable>
1762 command, you can omit the "do_" prefix as part of the
1763 task name.
1764 </note>
1765 </para>
1766
1767 <para>
1768 You might wonder about the practical effects of using
1769 <filename>addtask</filename> without specifying any
1770 dependencies as is done in the following example:
1771 <literallayout class='monospaced'>
1772 addtask printdate
1773 </literallayout>
1774 In this example, assuming dependencies have not been
1775 added through some other means, the only way to run
1776 the task is by explicitly selecting it with
1777 <filename>bitbake</filename>&nbsp;<replaceable>recipe</replaceable>&nbsp;<filename>-c printdate</filename>.
1778 You can use the
1779 <filename>do_listtasks</filename> task to list all tasks
1780 defined in a recipe as shown in the following example:
1781 <literallayout class='monospaced'>
1782 $ bitbake <replaceable>recipe</replaceable> -c listtasks
1783 </literallayout>
1784 For more information on task dependencies, see the
1785 "<link linkend='dependencies'>Dependencies</link>"
1786 section.
1787 </para>
1788
1789 <para>
1790 See the
1791 "<link linkend='variable-flags'>Variable Flags</link>"
1792 section for information on variable flags you can use with
1793 tasks.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001794 </para>
1795 </section>
1796
1797 <section id='deleting-a-task'>
1798 <title>Deleting a Task</title>
1799
1800 <para>
1801 As well as being able to add tasks, you can delete them.
1802 Simply use the <filename>deltask</filename> command to
1803 delete a task.
1804 For example, to delete the example task used in the previous
1805 sections, you would use:
1806 <literallayout class='monospaced'>
1807 deltask printdate
1808 </literallayout>
1809 If you delete a task using the <filename>deltask</filename>
1810 command and the task has dependencies, the dependencies are
1811 not reconnected.
1812 For example, suppose you have three tasks named
1813 <filename>do_a</filename>, <filename>do_b</filename>, and
1814 <filename>do_c</filename>.
1815 Furthermore, <filename>do_c</filename> is dependent on
1816 <filename>do_b</filename>, which in turn is dependent on
1817 <filename>do_a</filename>.
1818 Given this scenario, if you use <filename>deltask</filename>
1819 to delete <filename>do_b</filename>, the implicit dependency
1820 relationship between <filename>do_c</filename> and
1821 <filename>do_a</filename> through <filename>do_b</filename>
1822 no longer exists, and <filename>do_c</filename> dependencies
1823 are not updated to include <filename>do_a</filename>.
1824 Thus, <filename>do_c</filename> is free to run before
1825 <filename>do_a</filename>.
1826 </para>
1827
1828 <para>
1829 If you want dependencies such as these to remain intact, use
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001830 the <filename>[noexec]</filename> varflag to disable the task
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001831 instead of using the <filename>deltask</filename> command to
1832 delete it:
1833 <literallayout class='monospaced'>
1834 do_b[noexec] = "1"
1835 </literallayout>
1836 </para>
1837 </section>
1838
1839 <section id='passing-information-into-the-build-task-environment'>
1840 <title>Passing Information Into the Build Task Environment</title>
1841
1842 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001843 When running a task, BitBake tightly controls the shell execution
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001844 environment of the build tasks to make
1845 sure unwanted contamination from the build machine cannot
1846 influence the build.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001847 <note>
1848 By default, BitBake cleans the environment to include only those
1849 things exported or listed in its whitelist to ensure that the build
1850 environment is reproducible and consistent.
1851 You can prevent this "cleaning" by setting the
Brad Bishop19323692019-04-05 15:28:33 -04001852 <link linkend='var-bb-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001853 variable.
1854 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001855 Consequently, if you do want something to get passed into the
1856 build task environment, you must take these two steps:
1857 <orderedlist>
1858 <listitem><para>
1859 Tell BitBake to load what you want from the environment
1860 into the datastore.
1861 You can do so through the
Brad Bishop19323692019-04-05 15:28:33 -04001862 <link linkend='var-bb-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001863 and
Brad Bishop19323692019-04-05 15:28:33 -04001864 <link linkend='var-bb-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001865 variables.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001866 For example, assume you want to prevent the build system from
1867 accessing your <filename>$HOME/.ccache</filename>
1868 directory.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001869 The following command "whitelists" the environment variable
1870 <filename>CCACHE_DIR</filename> causing BitBack to allow that
1871 variable into the datastore:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001872 <literallayout class='monospaced'>
1873 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
1874 </literallayout></para></listitem>
1875 <listitem><para>
1876 Tell BitBake to export what you have loaded into the
1877 datastore to the task environment of every running task.
1878 Loading something from the environment into the datastore
1879 (previous step) only makes it available in the datastore.
1880 To export it to the task environment of every running task,
1881 use a command similar to the following in your local configuration
1882 file <filename>local.conf</filename> or your
1883 distribution configuration file:
1884 <literallayout class='monospaced'>
1885 export CCACHE_DIR
1886 </literallayout>
1887 <note>
1888 A side effect of the previous steps is that BitBake
1889 records the variable as a dependency of the build process
1890 in things like the setscene checksums.
1891 If doing so results in unnecessary rebuilds of tasks, you can
1892 whitelist the variable so that the setscene code
1893 ignores the dependency when it creates checksums.
1894 </note></para></listitem>
1895 </orderedlist>
1896 </para>
1897
1898 <para>
1899 Sometimes, it is useful to be able to obtain information
1900 from the original execution environment.
1901 Bitbake saves a copy of the original environment into
1902 a special variable named
Brad Bishop19323692019-04-05 15:28:33 -04001903 <link linkend='var-bb-BB_ORIGENV'><filename>BB_ORIGENV</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001904 </para>
1905
1906 <para>
1907 The <filename>BB_ORIGENV</filename> variable returns a datastore
1908 object that can be queried using the standard datastore operators
1909 such as <filename>getVar(, False)</filename>.
1910 The datastore object is useful, for example, to find the original
1911 <filename>DISPLAY</filename> variable.
1912 Here is an example:
1913 <literallayout class='monospaced'>
1914 origenv = d.getVar("BB_ORIGENV", False)
1915 bar = origenv.getVar("BAR", False)
1916 </literallayout>
1917 The previous example returns <filename>BAR</filename> from the original
1918 execution environment.
1919 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001920 </section>
1921 </section>
1922
1923 <section id='variable-flags'>
1924 <title>Variable Flags</title>
1925
1926 <para>
1927 Variable flags (varflags) help control a task's functionality
1928 and dependencies.
1929 BitBake reads and writes varflags to the datastore using the following
1930 command forms:
1931 <literallayout class='monospaced'>
1932 <replaceable>variable</replaceable> = d.getVarFlags("<replaceable>variable</replaceable>")
1933 self.d.setVarFlags("FOO", {"func": True})
1934 </literallayout>
1935 </para>
1936
1937 <para>
1938 When working with varflags, the same syntax, with the exception of
1939 overrides, applies.
1940 In other words, you can set, append, and prepend varflags just like
1941 variables.
1942 See the
1943 "<link linkend='variable-flag-syntax'>Variable Flag Syntax</link>"
1944 section for details.
1945 </para>
1946
1947 <para>
1948 BitBake has a defined set of varflags available for recipes and
1949 classes.
1950 Tasks support a number of these flags which control various
1951 functionality of the task:
1952 <itemizedlist>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001953 <listitem><para><emphasis><filename>[cleandirs]</filename>:</emphasis>
1954 Empty directories that should be created before the
1955 task runs.
1956 Directories that already exist are removed and recreated
1957 to empty them.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001958 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001959 <listitem><para><emphasis><filename>[depends]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001960 Controls inter-task dependencies.
1961 See the
Brad Bishop19323692019-04-05 15:28:33 -04001962 <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001963 variable and the
1964 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
1965 section for more information.
1966 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001967 <listitem><para><emphasis><filename>[deptask]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001968 Controls task build-time dependencies.
1969 See the
Brad Bishop19323692019-04-05 15:28:33 -04001970 <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001971 variable and the
1972 "<link linkend='build-dependencies'>Build Dependencies</link>"
1973 section for more information.
1974 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001975 <listitem><para><emphasis><filename>[dirs]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001976 Directories that should be created before the task runs.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001977 Directories that already exist are left as is.
1978 The last directory listed is used as the
1979 current working directory for the task.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001980 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001981 <listitem><para><emphasis><filename>[lockfiles]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001982 Specifies one or more lockfiles to lock while the task
1983 executes.
1984 Only one task may hold a lockfile, and any task that
1985 attempts to lock an already locked file will block until
1986 the lock is released.
1987 You can use this variable flag to accomplish mutual
1988 exclusion.
1989 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001990 <listitem><para><emphasis><filename>[noexec]</filename>:</emphasis>
1991 When set to "1", marks the task as being empty, with
1992 no execution required.
1993 You can use the <filename>[noexec]</filename> flag to set up
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001994 tasks as dependency placeholders, or to disable tasks defined
1995 elsewhere that are not needed in a particular recipe.
1996 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001997 <listitem><para><emphasis><filename>[nostamp]</filename>:</emphasis>
1998 When set to "1", tells BitBake to not generate a stamp
1999 file for a task, which implies the task should always
2000 be executed.
2001 <note><title>Caution</title>
2002 Any task that depends (possibly indirectly) on a
2003 <filename>[nostamp]</filename> task will always be
2004 executed as well.
2005 This can cause unnecessary rebuilding if you are
2006 not careful.
2007 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002008 </para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08002009 <listitem><para><emphasis><filename>[number_threads]</filename>:</emphasis>
2010 Limits tasks to a specific number of simultaneous threads
2011 during execution.
2012 This varflag is useful when your build host has a large number
2013 of cores but certain tasks need to be rate-limited due to various
2014 kinds of resource constraints (e.g. to avoid network throttling).
2015 <filename>number_threads</filename> works similarly to the
Brad Bishop19323692019-04-05 15:28:33 -04002016 <link linkend='var-bb-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08002017 variable but is task-specific.</para>
2018
2019 <para>Set the value globally.
2020 For example, the following makes sure the
2021 <filename>do_fetch</filename> task uses no more than two
2022 simultaneous execution threads:
2023 <literallayout class='monospaced'>
2024 do_fetch[number_threads] = "2"
2025 </literallayout>
2026 <note><title>Warnings</title>
2027 <itemizedlist>
2028 <listitem><para>
2029 Setting the varflag in individual recipes rather
2030 than globally can result in unpredictable behavior.
2031 </para></listitem>
2032 <listitem><para>
2033 Setting the varflag to a value greater than the
2034 value used in the <filename>BB_NUMBER_THREADS</filename>
2035 variable causes <filename>number_threads</filename>
2036 to have no effect.
2037 </para></listitem>
2038 </itemizedlist>
2039 </note>
2040 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002041 <listitem><para><emphasis><filename>[postfuncs]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002042 List of functions to call after the completion of the task.
2043 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002044 <listitem><para><emphasis><filename>[prefuncs]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002045 List of functions to call before the task executes.
2046 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002047 <listitem><para><emphasis><filename>[rdepends]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002048 Controls inter-task runtime dependencies.
2049 See the
Brad Bishop19323692019-04-05 15:28:33 -04002050 <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002051 variable, the
Brad Bishop19323692019-04-05 15:28:33 -04002052 <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002053 variable, and the
2054 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
2055 section for more information.
2056 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002057 <listitem><para><emphasis><filename>[rdeptask]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002058 Controls task runtime dependencies.
2059 See the
Brad Bishop19323692019-04-05 15:28:33 -04002060 <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002061 variable, the
Brad Bishop19323692019-04-05 15:28:33 -04002062 <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002063 variable, and the
2064 "<link linkend='runtime-dependencies'>Runtime Dependencies</link>"
2065 section for more information.
2066 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002067 <listitem><para><emphasis><filename>[recideptask]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002068 When set in conjunction with
2069 <filename>recrdeptask</filename>, specifies a task that
2070 should be inspected for additional dependencies.
2071 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002072 <listitem><para><emphasis><filename>[recrdeptask]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002073 Controls task recursive runtime dependencies.
2074 See the
Brad Bishop19323692019-04-05 15:28:33 -04002075 <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002076 variable, the
Brad Bishop19323692019-04-05 15:28:33 -04002077 <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002078 variable, and the
2079 "<link linkend='recursive-dependencies'>Recursive Dependencies</link>"
2080 section for more information.
2081 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002082 <listitem><para><emphasis><filename>[stamp-extra-info]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002083 Extra stamp information to append to the task's stamp.
2084 As an example, OpenEmbedded uses this flag to allow
2085 machine-specific tasks.
2086 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002087 <listitem><para><emphasis><filename>[umask]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002088 The umask to run the task under.
2089 </para></listitem>
2090 </itemizedlist>
2091 </para>
2092
2093 <para>
2094 Several varflags are useful for controlling how signatures are
2095 calculated for variables.
2096 For more information on this process, see the
2097 "<link linkend='checksums'>Checksums (Signatures)</link>"
2098 section.
2099 <itemizedlist>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002100 <listitem><para><emphasis><filename>[vardeps]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002101 Specifies a space-separated list of additional
2102 variables to add to a variable's dependencies
2103 for the purposes of calculating its signature.
2104 Adding variables to this list is useful, for example, when
2105 a function refers to a variable in a manner that
2106 does not allow BitBake to automatically determine
2107 that the variable is referred to.
2108 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002109 <listitem><para><emphasis><filename>[vardepsexclude]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002110 Specifies a space-separated list of variables
2111 that should be excluded from a variable's dependencies
2112 for the purposes of calculating its signature.
2113 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002114 <listitem><para><emphasis><filename>[vardepvalue]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002115 If set, instructs BitBake to ignore the actual
2116 value of the variable and instead use the specified
2117 value when calculating the variable's signature.
2118 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002119 <listitem><para><emphasis><filename>[vardepvalueexclude]</filename>:</emphasis>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002120 Specifies a pipe-separated list of strings to exclude
2121 from the variable's value when calculating the
2122 variable's signature.
2123 </para></listitem>
2124 </itemizedlist>
2125 </para>
2126 </section>
2127
2128 <section id='events'>
2129 <title>Events</title>
2130
2131 <para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002132 BitBake allows installation of event handlers within recipe
2133 and class files.
2134 Events are triggered at certain points during operation, such
2135 as the beginning of operation against a given recipe
2136 (i.e. <filename>*.bb</filename>), the start of a given task,
2137 a task failure, a task success, and so forth.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002138 The intent is to make it easy to do things like email
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002139 notification on build failures.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002140 </para>
2141
2142 <para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002143 Following is an example event handler that prints the name
2144 of the event and the content of the
2145 <filename>FILE</filename> variable:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002146 <literallayout class='monospaced'>
2147 addhandler myclass_eventhandler
2148 python myclass_eventhandler() {
2149 from bb.event import getName
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002150 print("The name of the Event is %s" % getName(e))
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002151 print("The file we run for is %s" % d.getVar('FILE'))
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002152 }
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002153 myclass_eventhandler[eventmask] = "bb.event.BuildStarted bb.event.BuildCompleted"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002154 </literallayout>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002155 In the previous example, an eventmask has been set so that
2156 the handler only sees the "BuildStarted" and "BuildCompleted"
2157 events.
2158 This event handler gets called every time an event matching
2159 the eventmask is triggered.
2160 A global variable "e" is defined, which represents the current
2161 event.
2162 With the <filename>getName(e)</filename> method, you can get
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002163 the name of the triggered event.
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002164 The global datastore is available as "d".
2165 In legacy code, you might see "e.data" used to get the datastore.
2166 However, realize that "e.data" is deprecated and you should use
2167 "d" going forward.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002168 </para>
2169
2170 <para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002171 The context of the datastore is appropriate to the event
2172 in question.
2173 For example, "BuildStarted" and "BuildCompleted" events run
2174 before any tasks are executed so would be in the global
2175 configuration datastore namespace.
2176 No recipe-specific metadata exists in that namespace.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002177 The "BuildStarted" and "BuildCompleted" events also run in
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002178 the main cooker/server process rather than any worker context.
2179 Thus, any changes made to the datastore would be seen by other
2180 cooker/server events within the current build but not seen
2181 outside of that build or in any worker context.
2182 Task events run in the actual tasks in question consequently
2183 have recipe-specific and task-specific contents.
2184 These events run in the worker context and are discarded at
2185 the end of task execution.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002186 </para>
2187
2188 <para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002189 During a standard build, the following common events might
2190 occur.
2191 The following events are the most common kinds of events that
2192 most metadata might have an interest in viewing:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002193 <itemizedlist>
2194 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002195 <filename>bb.event.ConfigParsed()</filename>:
2196 Fired when the base configuration; which consists of
2197 <filename>bitbake.conf</filename>,
2198 <filename>base.bbclass</filename> and any global
2199 <filename>INHERIT</filename> statements; has been parsed.
2200 You can see multiple such events when each of the
2201 workers parse the base configuration or if the server
2202 changes configuration and reparses.
2203 Any given datastore only has one such event executed
2204 against it, however.
2205 If
Brad Bishop19323692019-04-05 15:28:33 -04002206 <link linkende='var-bb-BB_INVALIDCONF'><filename>BB_INVALIDCONF</filename></link>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002207 is set in the datastore by the event handler, the
2208 configuration is reparsed and a new event triggered,
2209 allowing the metadata to update configuration.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002210 </para></listitem>
2211 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002212 <filename>bb.event.HeartbeatEvent()</filename>:
2213 Fires at regular time intervals of one second.
2214 You can configure the interval time using the
2215 <filename>BB_HEARTBEAT_EVENT</filename> variable.
2216 The event's "time" attribute is the
2217 <filename>time.time()</filename> value when the
2218 event is triggered.
2219 This event is useful for activities such as
2220 system state monitoring.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002221 </para></listitem>
2222 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002223 <filename>bb.event.ParseStarted()</filename>:
2224 Fired when BitBake is about to start parsing recipes.
2225 This event's "total" attribute represents the number of
2226 recipes BitBake plans to parse.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002227 </para></listitem>
2228 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002229 <filename>bb.event.ParseProgress()</filename>:
2230 Fired as parsing progresses.
2231 This event's "current" attribute is the number of
2232 recipes parsed as well as the "total" attribute.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002233 </para></listitem>
2234 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002235 <filename>bb.event.ParseCompleted()</filename>:
2236 Fired when parsing is complete.
2237 This event's "cached", "parsed", "skipped", "virtuals",
2238 "masked", and "errors" attributes provide statistics
2239 for the parsing results.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002240 </para></listitem>
2241 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002242 <filename>bb.event.BuildStarted()</filename>:
2243 Fired when a new build starts.
Brad Bishop316dfdd2018-06-25 12:45:53 -04002244 BitBake fires multiple "BuildStarted" events (one per configuration)
2245 when multiple configuration (multiconfig) is enabled.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002246 </para></listitem>
2247 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002248 <filename>bb.build.TaskStarted()</filename>:
2249 Fired when a task starts.
2250 This event's "taskfile" attribute points to the recipe
2251 from which the task originates.
2252 The "taskname" attribute, which is the task's name,
2253 includes the <filename>do_</filename> prefix, and the
2254 "logfile" attribute point to where the task's output is
2255 stored.
2256 Finally, the "time" attribute is the task's execution start
2257 time.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002258 </para></listitem>
2259 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002260 <filename>bb.build.TaskInvalid()</filename>:
2261 Fired if BitBake tries to execute a task that does not exist.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002262 </para></listitem>
2263 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002264 <filename>bb.build.TaskFailedSilent()</filename>:
2265 Fired for setscene tasks that fail and should not be
2266 presented to the user verbosely.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002267 </para></listitem>
2268 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002269 <filename>bb.build.TaskFailed()</filename>:
2270 Fired for normal tasks that fail.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002271 </para></listitem>
2272 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002273 <filename>bb.build.TaskSucceeded()</filename>:
2274 Fired when a task successfully completes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002275 </para></listitem>
2276 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002277 <filename>bb.event.BuildCompleted()</filename>:
2278 Fired when a build finishes.
2279 </para></listitem>
2280 <listitem><para>
2281 <filename>bb.cooker.CookerExit()</filename>:
2282 Fired when the BitBake server/cooker shuts down.
2283 This event is usually only seen by the UIs as a
2284 sign they should also shutdown.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002285 </para></listitem>
2286 </itemizedlist>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002287 </para>
2288
2289 <para>
2290 This next list of example events occur based on specific
2291 requests to the server.
2292 These events are often used to communicate larger pieces of
2293 information from the BitBake server to other parts of
2294 BitBake such as user interfaces:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002295 <itemizedlist>
2296 <listitem><para>
2297 <filename>bb.event.TreeDataPreparationStarted()</filename>
2298 </para></listitem>
2299 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002300 <filename>bb.event.TreeDataPreparationProgress()</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002301 </para></listitem>
2302 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002303 <filename>bb.event.TreeDataPreparationCompleted()</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002304 </para></listitem>
2305 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002306 <filename>bb.event.DepTreeGenerated()</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002307 </para></listitem>
2308 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002309 <filename>bb.event.CoreBaseFilesFound()</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002310 </para></listitem>
2311 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002312 <filename>bb.event.ConfigFilePathFound()</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002313 </para></listitem>
2314 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002315 <filename>bb.event.FilesMatchingFound()</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002316 </para></listitem>
2317 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002318 <filename>bb.event.ConfigFilesFound()</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002319 </para></listitem>
2320 <listitem><para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002321 <filename>bb.event.TargetsTreeGenerated()</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002322 </para></listitem>
2323 </itemizedlist>
2324 </para>
2325 </section>
2326
2327 <section id='variants-class-extension-mechanism'>
2328 <title>Variants - Class Extension Mechanism</title>
2329
2330 <para>
2331 BitBake supports two features that facilitate creating
2332 from a single recipe file multiple incarnations of that
2333 recipe file where all incarnations are buildable.
2334 These features are enabled through the
Brad Bishop19323692019-04-05 15:28:33 -04002335 <link linkend='var-bb-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002336 and
Brad Bishop19323692019-04-05 15:28:33 -04002337 <link linkend='var-bb-BBVERSIONS'><filename>BBVERSIONS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002338 variables.
2339 <note>
2340 The mechanism for this class extension is extremely
2341 specific to the implementation.
2342 Usually, the recipe's
Brad Bishop19323692019-04-05 15:28:33 -04002343 <link linkend='var-bb-PROVIDES'><filename>PROVIDES</filename></link>,
2344 <link linkend='var-bb-PN'><filename>PN</filename></link>, and
2345 <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002346 variables would need to be modified by the extension class.
2347 For specific examples, see the OE-Core
2348 <filename>native</filename>, <filename>nativesdk</filename>,
2349 and <filename>multilib</filename> classes.
2350 </note>
2351 <itemizedlist>
2352 <listitem><para><emphasis><filename>BBCLASSEXTEND</filename>:</emphasis>
2353 This variable is a space separated list of classes used to "extend" the
2354 recipe for each variant.
2355 Here is an example that results in a second incarnation of the current
2356 recipe being available.
2357 This second incarnation will have the "native" class inherited.
2358 <literallayout class='monospaced'>
2359 BBCLASSEXTEND = "native"
2360 </literallayout></para></listitem>
2361 <listitem><para><emphasis><filename>BBVERSIONS</filename>:</emphasis>
2362 This variable allows a single recipe to build multiple versions of a
2363 project from a single recipe file.
2364 You can also specify conditional metadata
2365 (using the
Brad Bishop19323692019-04-05 15:28:33 -04002366 <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002367 mechanism) for a single version, or an optionally named range of versions.
2368 Here is an example:
2369 <literallayout class='monospaced'>
2370 BBVERSIONS = "1.0 2.0 git"
2371 SRC_URI_git = "git://someurl/somepath.git"
2372
2373 BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 1.0.[7-9]:1.0.7+"
2374 SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"
2375 </literallayout>
2376 The name of the range defaults to the original version of the
2377 recipe.
2378 For example, in OpenEmbedded, the recipe file
2379 <filename>foo_1.0.0+.bb</filename> creates a default name range
2380 of <filename>1.0.0+</filename>.
2381 This is useful because the range name is not only placed
2382 into overrides, but it is also made available for the metadata to use
2383 in the variable that defines the base recipe versions for use in
2384 <filename>file://</filename> search paths
Brad Bishop19323692019-04-05 15:28:33 -04002385 (<link linkend='var-bb-FILESPATH'><filename>FILESPATH</filename></link>).
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002386 </para></listitem>
2387 </itemizedlist>
2388 </para>
2389 </section>
2390
2391 <section id='dependencies'>
2392 <title>Dependencies</title>
2393
2394 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002395 To allow for efficient parallel processing, BitBake handles
2396 dependencies at the task level.
2397 Dependencies can exist both between tasks within a single recipe
2398 and between tasks in different recipes.
2399 Following are examples of each:
2400 <itemizedlist>
2401 <listitem><para>For tasks within a single recipe, a
2402 recipe's <filename>do_configure</filename>
2403 task might need to complete before its
2404 <filename>do_compile</filename> task can run.
2405 </para></listitem>
2406 <listitem><para>For tasks in different recipes, one
2407 recipe's <filename>do_configure</filename>
2408 task might require another recipe's
2409 <filename>do_populate_sysroot</filename>
2410 task to finish first such that the libraries and headers
2411 provided by the other recipe are available.
2412 </para></listitem>
2413 </itemizedlist>
2414 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002415
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002416 <para>
2417 This section describes several ways to declare dependencies.
2418 Remember, even though dependencies are declared in different ways, they
2419 are all simply dependencies between tasks.
2420 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002421
2422 <section id='dependencies-internal-to-the-bb-file'>
2423 <title>Dependencies Internal to the <filename>.bb</filename> File</title>
2424
2425 <para>
2426 BitBake uses the <filename>addtask</filename> directive
2427 to manage dependencies that are internal to a given recipe
2428 file.
2429 You can use the <filename>addtask</filename> directive to
2430 indicate when a task is dependent on other tasks or when
2431 other tasks depend on that recipe.
2432 Here is an example:
2433 <literallayout class='monospaced'>
2434 addtask printdate after do_fetch before do_build
2435 </literallayout>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002436 In this example, the <filename>do_printdate</filename>
2437 task depends on the completion of the
2438 <filename>do_fetch</filename> task, and the
2439 <filename>do_build</filename> task depends on the
2440 completion of the <filename>do_printdate</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002441 task.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002442 <note><para>
2443 For a task to run, it must be a direct or indirect
2444 dependency of some other task that is scheduled to
2445 run.</para>
2446
2447 <para>For illustration, here are some examples:
2448 <itemizedlist>
2449 <listitem><para>
2450 The directive
2451 <filename>addtask mytask before do_configure</filename>
2452 causes <filename>do_mytask</filename> to run before
2453 <filename>do_configure</filename> runs.
2454 Be aware that <filename>do_mytask</filename> still only
2455 runs if its <link linkend='checksums'>input checksum</link>
2456 has changed since the last time it was run.
2457 Changes to the input checksum of
2458 <filename>do_mytask</filename> also indirectly cause
2459 <filename>do_configure</filename> to run.
2460 </para></listitem>
2461 <listitem><para>
2462 The directive
2463 <filename>addtask mytask after do_configure</filename>
2464 by itself never causes <filename>do_mytask</filename>
2465 to run.
2466 <filename>do_mytask</filename> can still be run manually
2467 as follows:
2468 <literallayout class='monospaced'>
2469 $ bitbake <replaceable>recipe</replaceable> -c mytask
2470 </literallayout>
2471 Declaring <filename>do_mytask</filename> as a dependency
2472 of some other task that is scheduled to run also causes
2473 it to run.
2474 Regardless, the task runs after
2475 <filename>do_configure</filename>.
2476 </para></listitem>
2477 </itemizedlist></para>
2478 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002479 </para>
2480 </section>
2481
2482 <section id='build-dependencies'>
2483 <title>Build Dependencies</title>
2484
2485 <para>
2486 BitBake uses the
Brad Bishop19323692019-04-05 15:28:33 -04002487 <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002488 variable to manage build time dependencies.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002489 The <filename>[deptask]</filename> varflag for tasks
2490 signifies the task of each
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002491 item listed in <filename>DEPENDS</filename> that must
2492 complete before that task can be executed.
2493 Here is an example:
2494 <literallayout class='monospaced'>
2495 do_configure[deptask] = "do_populate_sysroot"
2496 </literallayout>
2497 In this example, the <filename>do_populate_sysroot</filename>
2498 task of each item in <filename>DEPENDS</filename> must complete before
2499 <filename>do_configure</filename> can execute.
2500 </para>
2501 </section>
2502
2503 <section id='runtime-dependencies'>
2504 <title>Runtime Dependencies</title>
2505
2506 <para>
2507 BitBake uses the
Brad Bishop19323692019-04-05 15:28:33 -04002508 <link linkend='var-bb-PACKAGES'><filename>PACKAGES</filename></link>,
2509 <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link>, and
2510 <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002511 variables to manage runtime dependencies.
2512 </para>
2513
2514 <para>
2515 The <filename>PACKAGES</filename> variable lists runtime
2516 packages.
2517 Each of those packages can have <filename>RDEPENDS</filename> and
2518 <filename>RRECOMMENDS</filename> runtime dependencies.
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002519 The <filename>[rdeptask]</filename> flag for tasks is used to
2520 signify the task of each
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002521 item runtime dependency which must have completed before that
2522 task can be executed.
2523 <literallayout class='monospaced'>
2524 do_package_qa[rdeptask] = "do_packagedata"
2525 </literallayout>
2526 In the previous example, the <filename>do_packagedata</filename>
2527 task of each item in <filename>RDEPENDS</filename> must have
2528 completed before <filename>do_package_qa</filename> can execute.
2529 </para>
2530 </section>
2531
2532 <section id='recursive-dependencies'>
2533 <title>Recursive Dependencies</title>
2534
2535 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002536 BitBake uses the <filename>[recrdeptask]</filename> flag to manage
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002537 recursive task dependencies.
2538 BitBake looks through the build-time and runtime
2539 dependencies of the current recipe, looks through
2540 the task's inter-task
2541 dependencies, and then adds dependencies for the
2542 listed task.
2543 Once BitBake has accomplished this, it recursively works through
2544 the dependencies of those tasks.
2545 Iterative passes continue until all dependencies are discovered
2546 and added.
2547 </para>
2548
2549 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002550 The <filename>[recrdeptask]</filename> flag is most commonly
2551 used in high-level
2552 recipes that need to wait for some task to finish "globally".
2553 For example, <filename>image.bbclass</filename> has the following:
2554 <literallayout class='monospaced'>
2555 do_rootfs[recrdeptask] += "do_packagedata"
2556 </literallayout>
2557 This statement says that the <filename>do_packagedata</filename>
2558 task of the current recipe and all recipes reachable
2559 (by way of dependencies) from the
2560 image recipe must run before the <filename>do_rootfs</filename>
2561 task can run.
2562 </para>
2563
2564 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002565 You might want to not only have BitBake look for
2566 dependencies of those tasks, but also have BitBake look
2567 for build-time and runtime dependencies of the dependent
2568 tasks as well.
2569 If that is the case, you need to reference the task name
2570 itself in the task list:
2571 <literallayout class='monospaced'>
2572 do_a[recrdeptask] = "do_a do_b"
2573 </literallayout>
2574 </para>
2575 </section>
2576
2577 <section id='inter-task-dependencies'>
2578 <title>Inter-Task Dependencies</title>
2579
2580 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002581 BitBake uses the <filename>[depends]</filename>
2582 flag in a more generic form
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002583 to manage inter-task dependencies.
2584 This more generic form allows for inter-dependency
2585 checks for specific tasks rather than checks for
2586 the data in <filename>DEPENDS</filename>.
2587 Here is an example:
2588 <literallayout class='monospaced'>
2589 do_patch[depends] = "quilt-native:do_populate_sysroot"
2590 </literallayout>
2591 In this example, the <filename>do_populate_sysroot</filename>
2592 task of the target <filename>quilt-native</filename>
2593 must have completed before the
2594 <filename>do_patch</filename> task can execute.
2595 </para>
2596
2597 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002598 The <filename>[rdepends]</filename> flag works in a similar
2599 way but takes targets
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002600 in the runtime namespace instead of the build-time dependency
2601 namespace.
2602 </para>
2603 </section>
2604 </section>
2605
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002606 <section id='functions-you-can-call-from-within-python'>
2607 <title>Functions You Can Call From Within Python</title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002608
2609 <para>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002610 BitBake provides many functions you can call from
2611 within Python functions.
2612 This section lists the most commonly used functions,
2613 and mentions where to find others.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002614 </para>
2615
Patrick Williamsc0f7c042017-02-23 20:41:17 -06002616 <section id='functions-for-accessing-datastore-variables'>
2617 <title>Functions for Accessing Datastore Variables</title>
2618
2619 <para>
2620 It is often necessary to access variables in the
2621 BitBake datastore using Python functions.
2622 The Bitbake datastore has an API that allows you this
2623 access.
2624 Here is a list of available operations:
2625 </para>
2626
2627 <para>
2628 <informaltable frame='none'>
2629 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
2630 <colspec colname='c1' colwidth='1*'/>
2631 <colspec colname='c2' colwidth='1*'/>
2632 <thead>
2633 <row>
2634 <entry align="left"><emphasis>Operation</emphasis></entry>
2635 <entry align="left"><emphasis>Description</emphasis></entry>
2636 </row>
2637 </thead>
2638 <tbody>
2639 <row>
2640 <entry align="left"><filename>d.getVar("X", expand)</filename></entry>
2641 <entry align="left">Returns the value of variable "X".
2642 Using "expand=True" expands the value.
2643 Returns "None" if the variable "X" does not exist.</entry>
2644 </row>
2645 <row>
2646 <entry align="left"><filename>d.setVar("X", "value")</filename></entry>
2647 <entry align="left">Sets the variable "X" to "value".</entry>
2648 </row>
2649 <row>
2650 <entry align="left"><filename>d.appendVar("X", "value")</filename></entry>
2651 <entry align="left">Adds "value" to the end of the variable "X".
2652 Acts like <filename>d.setVar("X", "value")</filename>
2653 if the variable "X" does not exist.</entry>
2654 </row>
2655 <row>
2656 <entry align="left"><filename>d.prependVar("X", "value")</filename></entry>
2657 <entry align="left">Adds "value" to the start of the variable "X".
2658 Acts like <filename>d.setVar("X", "value")</filename>
2659 if the variable "X" does not exist.</entry>
2660 </row>
2661 <row>
2662 <entry align="left"><filename>d.delVar("X")</filename></entry>
2663 <entry align="left">Deletes the variable "X" from the datastore.
2664 Does nothing if the variable "X" does not exist.</entry>
2665 </row>
2666 <row>
2667 <entry align="left"><filename>d.renameVar("X", "Y")</filename></entry>
2668 <entry align="left">Renames the variable "X" to "Y".
2669 Does nothing if the variable "X" does not exist.</entry>
2670 </row>
2671 <row>
2672 <entry align="left"><filename>d.getVarFlag("X", flag, expand)</filename></entry>
2673 <entry align="left">Returns the value of variable "X".
2674 Using "expand=True" expands the value.
2675 Returns "None" if either the variable "X" or the named flag
2676 does not exist.</entry>
2677 </row>
2678 <row>
2679 <entry align="left"><filename>d.setVarFlag("X", flag, "value")</filename></entry>
2680 <entry align="left">Sets the named flag for variable "X" to "value".</entry>
2681 </row>
2682 <row>
2683 <entry align="left"><filename>d.appendVarFlag("X", flag, "value")</filename></entry>
2684 <entry align="left">Appends "value" to the named flag on the
2685 variable "X".
2686 Acts like <filename>d.setVarFlag("X", flag, "value")</filename>
2687 if the named flag does not exist.</entry>
2688 </row>
2689 <row>
2690 <entry align="left"><filename>d.prependVarFlag("X", flag, "value")</filename></entry>
2691 <entry align="left">Prepends "value" to the named flag on
2692 the variable "X".
2693 Acts like <filename>d.setVarFlag("X", flag, "value")</filename>
2694 if the named flag does not exist.</entry>
2695 </row>
2696 <row>
2697 <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry>
2698 <entry align="left">Deletes the named flag on the variable
2699 "X" from the datastore.</entry>
2700 </row>
2701 <row>
2702 <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry>
2703 <entry align="left">Sets the flags specified in
2704 the <filename>flagsdict()</filename> parameter.
2705 <filename>setVarFlags</filename> does not clear previous flags.
2706 Think of this operation as <filename>addVarFlags</filename>.</entry>
2707 </row>
2708 <row>
2709 <entry align="left"><filename>d.getVarFlags("X")</filename></entry>
2710 <entry align="left">Returns a <filename>flagsdict</filename>
2711 of the flags for the variable "X".
2712 Returns "None" if the variable "X" does not exist.</entry>
2713 </row>
2714 <row>
2715 <entry align="left"><filename>d.delVarFlags("X")</filename></entry>
2716 <entry align="left">Deletes all the flags for the variable "X".
2717 Does nothing if the variable "X" does not exist.</entry>
2718 </row>
2719 <row>
2720 <entry align="left"><filename>d.expand(expression)</filename></entry>
2721 <entry align="left">Expands variable references in the specified
2722 string expression.
2723 References to variables that do not exist are left as is.
2724 For example, <filename>d.expand("foo ${X}")</filename>
2725 expands to the literal string "foo ${X}" if the
2726 variable "X" does not exist.</entry>
2727 </row>
2728 </tbody>
2729 </tgroup>
2730 </informaltable>
2731 </para>
2732 </section>
2733
2734 <section id='other-functions'>
2735 <title>Other Functions</title>
2736
2737 <para>
2738 You can find many other functions that can be called
2739 from Python by looking at the source code of the
2740 <filename>bb</filename> module, which is in
2741 <filename>bitbake/lib/bb</filename>.
2742 For example,
2743 <filename>bitbake/lib/bb/utils.py</filename> includes
2744 the commonly used functions
2745 <filename>bb.utils.contains()</filename> and
2746 <filename>bb.utils.mkdirhier()</filename>, which come
2747 with docstrings.
2748 </para>
2749 </section>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002750 </section>
2751
2752 <section id='task-checksums-and-setscene'>
2753 <title>Task Checksums and Setscene</title>
2754
2755 <para>
2756 BitBake uses checksums (or signatures) along with the setscene
2757 to determine if a task needs to be run.
2758 This section describes the process.
2759 To help understand how BitBake does this, the section assumes an
2760 OpenEmbedded metadata-based example.
2761 </para>
2762
2763 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002764 These checksums are stored in
Brad Bishop19323692019-04-05 15:28:33 -04002765 <link linkend='var-bb-STAMP'><filename>STAMP</filename></link>.
Brad Bishop316dfdd2018-06-25 12:45:53 -04002766 You can examine the checksums using the following BitBake command:
2767 <literallayout class='monospaced'>
2768 $ bitbake-dumpsigs
2769 </literallayout>
2770 This command returns the signature data in a readable format
2771 that allows you to examine the inputs used when the
2772 OpenEmbedded build system generates signatures.
2773 For example, using <filename>bitbake-dumpsigs</filename>
2774 allows you to examine the <filename>do_compile</filename>
2775 task's “sigdata” for a C application (e.g.
2776 <filename>bash</filename>).
2777 Running the command also reveals that the “CC” variable is part of
2778 the inputs that are hashed.
2779 Any changes to this variable would invalidate the stamp and
2780 cause the <filename>do_compile</filename> task to run.
2781 </para>
2782
2783 <para>
2784 The following list describes related variables:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002785 <itemizedlist>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002786 <listitem><para>
Brad Bishop19323692019-04-05 15:28:33 -04002787 <link linkend='var-bb-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002788 Specifies the name of the function to call during
2789 the "setscene" part of the task's execution in order
2790 to validate the list of task hashes.
2791 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002792 <listitem><para>
Brad Bishop19323692019-04-05 15:28:33 -04002793 <link linkend='var-bb-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002794 Specifies a function BitBake calls that determines
2795 whether BitBake requires a setscene dependency to
2796 be met.
2797 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002798 <listitem><para>
Brad Bishop19323692019-04-05 15:28:33 -04002799 <link linkend='var-bb-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></link>:
Brad Bishop316dfdd2018-06-25 12:45:53 -04002800 Specifies a function to call that verifies the list of
2801 planned task execution before the main task execution
2802 happens.
2803 </para></listitem>
2804 <listitem><para>
Brad Bishop19323692019-04-05 15:28:33 -04002805 <link linkend='var-bb-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link>:
Brad Bishop316dfdd2018-06-25 12:45:53 -04002806 Defines the mode for comparing timestamps of stamp files.
2807 </para></listitem>
2808 <listitem><para>
Brad Bishop19323692019-04-05 15:28:33 -04002809 <link linkend='var-bb-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link>:
Brad Bishop316dfdd2018-06-25 12:45:53 -04002810 Lists stamp files that are looked at when the stamp policy
2811 is "whitelist".
2812 </para></listitem>
2813 <listitem><para>
Brad Bishop19323692019-04-05 15:28:33 -04002814 <link linkend='var-bb-BB_TASKHASH'><filename>BB_TASKHASH</filename></link>:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002815 Within an executing task, this variable holds the hash
2816 of the task as returned by the currently enabled
2817 signature generator.
2818 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04002819 <listitem><para>
Brad Bishop19323692019-04-05 15:28:33 -04002820 <link linkend='var-bb-STAMP'><filename>STAMP</filename></link>:
Brad Bishop316dfdd2018-06-25 12:45:53 -04002821 The base path to create stamp files.
2822 </para></listitem>
2823 <listitem><para>
Brad Bishop19323692019-04-05 15:28:33 -04002824 <link linkend='var-bb-STAMPCLEAN'><filename>STAMPCLEAN</filename></link>:
Brad Bishop316dfdd2018-06-25 12:45:53 -04002825 Again, the base path to create stamp files but can use wildcards
2826 for matching a range of files for clean operations.
2827 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002828 </itemizedlist>
2829 </para>
2830 </section>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08002831
2832 <section id='wildcard-support-in-variables'>
2833 <title>Wildcard Support in Variables</title>
2834
2835 <para>
2836 Support for wildcard use in variables varies depending on the
2837 context in which it is used.
2838 For example, some variables and file names allow limited use of
2839 wildcards through the "<filename>%</filename>" and
2840 "<filename>*</filename>" characters.
2841 Other variables or names support Python's
2842 <ulink url='https://docs.python.org/3/library/glob.html'><filename>glob</filename></ulink>
2843 syntax,
2844 <ulink url='https://docs.python.org/3/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>
2845 syntax, or
2846 <ulink url='https://docs.python.org/3/library/re.html#re'><filename>Regular Expression (re)</filename></ulink>
2847 syntax.
2848 </para>
2849
2850 <para>
2851 For variables that have wildcard suport, the
2852 documentation describes which form of wildcard, its
2853 use, and its limitations.
2854 </para>
2855 </section>
2856
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002857</chapter>