summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-10-05 16:38:15 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-06 13:52:25 +0100
commitdd50ad91734315575131f231f91abae1777cf52a (patch)
tree811d05fe75445ade50bf36ae27666318a9cee8a9 /bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
parentd4a59548bead7bf7a2d62fc399311f7a396e3370 (diff)
downloadpoky-dd50ad91734315575131f231f91abae1777cf52a.tar.gz
bitbake: sphinx: remove DocBook files
The BitBake documentation was migrated to Sphinx. Let's remove the deprecated DocBook files. (Bitbake rev: 427721d8ff2c8e1db8cb490074f2eed88d03852a) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml')
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml2862
1 files changed, 0 insertions, 2862 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
deleted file mode 100644
index 0ca5321618..0000000000
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ /dev/null
@@ -1,2862 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
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>
47
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>
62 </section>
63
64 <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
136 <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
178 <section id='variable-expansion'>
179 <title>Variable Expansion</title>
180
181 <para>
182 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".
187 <literallayout class='monospaced'>
188 A = "aval"
189 B = "pre${A}post"
190 </literallayout>
191 <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>
228 </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 := "test ${T}"
298 T = "456"
299 B := "${T} ${C}"
300 C = "cval"
301 C := "${C}append"
302 </literallayout>
303 In this example, <filename>A</filename> contains
304 "test 123", even though the final value of <filename>T</filename>
305 is "456".
306 The variable <filename>B</filename> will end up containing "456 cvalappend".
307 This is because references to undefined variables are preserved as is
308 during (immediate)expansion. This is in contrast to GNU Make, where undefined
309 variables expand to nothing.
310 The variable <filename>C</filename>
311 contains "cvalappend" since <filename>${C}</filename> immediately
312 expands to "cval".
313 </para>
314 </section>
315
316 <section id='appending-and-prepending'>
317 <title>Appending (+=) and prepending (=+) With Spaces</title>
318
319 <para>
320 Appending and prepending values is common and can be accomplished
321 using the "+=" and "=+" operators.
322 These operators insert a space between the current
323 value and prepended or appended value.
324 </para>
325
326 <para>
327 These operators take immediate effect during parsing.
328 Here are some examples:
329 <literallayout class='monospaced'>
330 B = "bval"
331 B += "additionaldata"
332 C = "cval"
333 C =+ "test"
334 </literallayout>
335 The variable <filename>B</filename> contains
336 "bval additionaldata" and <filename>C</filename>
337 contains "test cval".
338 </para>
339 </section>
340
341 <section id='appending-and-prepending-without-spaces'>
342 <title>Appending (.=) and Prepending (=.) Without Spaces</title>
343
344 <para>
345 If you want to append or prepend values without an
346 inserted space, use the ".=" and "=." operators.
347 </para>
348
349 <para>
350 These operators take immediate effect during parsing.
351 Here are some examples:
352 <literallayout class='monospaced'>
353 B = "bval"
354 B .= "additionaldata"
355 C = "cval"
356 C =. "test"
357 </literallayout>
358 The variable <filename>B</filename> contains
359 "bvaladditionaldata" and
360 <filename>C</filename> contains "testcval".
361 </para>
362 </section>
363
364 <section id='appending-and-prepending-override-style-syntax'>
365 <title>Appending and Prepending (Override Style Syntax)</title>
366
367 <para>
368 You can also append and prepend a variable's value
369 using an override style syntax.
370 When you use this syntax, no spaces are inserted.
371 </para>
372
373 <para>
374 These operators differ from the ":=", ".=", "=.", "+=", and "=+"
375 operators in that their effects are applied at variable
376 expansion time rather than being immediately applied.
377 Here are some examples:
378 <literallayout class='monospaced'>
379 B = "bval"
380 B_append = " additional data"
381 C = "cval"
382 C_prepend = "additional data "
383 D = "dval"
384 D_append = "additional data"
385 </literallayout>
386 The variable <filename>B</filename> becomes
387 "bval additional data" and <filename>C</filename> becomes
388 "additional data cval".
389 The variable <filename>D</filename> becomes
390 "dvaladditional data".
391 <note>
392 You must control all spacing when you use the
393 override syntax.
394 </note>
395 </para>
396
397 <para>
398 It is also possible to append and prepend to shell
399 functions and BitBake-style Python functions.
400 See the
401 "<link linkend='shell-functions'>Shell Functions</link>" and
402 "<link linkend='bitbake-style-python-functions'>BitBake-Style Python Functions</link>
403 sections for examples.
404 </para>
405 </section>
406
407 <section id='removing-override-style-syntax'>
408 <title>Removal (Override Style Syntax)</title>
409
410 <para>
411 You can remove values from lists using the removal
412 override style syntax.
413 Specifying a value for removal causes all occurrences of that
414 value to be removed from the variable.
415 </para>
416
417 <para>
418 When you use this syntax, BitBake expects one or more strings.
419 Surrounding spaces and spacing are preserved.
420 Here is an example:
421 <literallayout class='monospaced'>
422 FOO = "123 456 789 123456 123 456 123 456"
423 FOO_remove = "123"
424 FOO_remove = "456"
425 FOO2 = " abc def ghi abcdef abc def abc def def"
426 FOO2_remove = " \
427 def \
428 abc \
429 ghi \
430 "
431 </literallayout>
432 The variable <filename>FOO</filename> becomes
433 "&nbsp;&nbsp;789&nbsp;123456&nbsp;&nbsp;&nbsp;&nbsp;"
434 and <filename>FOO2</filename> becomes
435 "&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;abcdef&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;".
436 </para>
437
438 <para>
439 Like "_append" and "_prepend", "_remove"
440 is applied at variable expansion time.
441 </para>
442 </section>
443
444 <section id='override-style-operation-advantages'>
445 <title>Override Style Operation Advantages</title>
446
447 <para>
448 An advantage of the override style operations
449 "_append", "_prepend", and "_remove" as compared to the
450 "+=" and "=+" operators is that the override style
451 operators provide guaranteed operations.
452 For example, consider a class <filename>foo.bbclass</filename>
453 that needs to add the value "val" to the variable
454 <filename>FOO</filename>, and a recipe that uses
455 <filename>foo.bbclass</filename> as follows:
456 <literallayout class='monospaced'>
457 inherit foo
458
459 FOO = "initial"
460 </literallayout>
461 If <filename>foo.bbclass</filename> uses the "+=" operator,
462 as follows, then the final value of <filename>FOO</filename>
463 will be "initial", which is not what is desired:
464 <literallayout class='monospaced'>
465 FOO += "val"
466 </literallayout>
467 If, on the other hand, <filename>foo.bbclass</filename>
468 uses the "_append" operator, then the final value of
469 <filename>FOO</filename> will be "initial val", as intended:
470 <literallayout class='monospaced'>
471 FOO_append = " val"
472 </literallayout>
473 <note>
474 It is never necessary to use "+=" together with "_append".
475 The following sequence of assignments appends "barbaz" to
476 <filename>FOO</filename>:
477 <literallayout class='monospaced'>
478 FOO_append = "bar"
479 FOO_append = "baz"
480 </literallayout>
481 The only effect of changing the second assignment in the
482 previous example to use "+=" would be to add a space before
483 "baz" in the appended value (due to how the "+=" operator
484 works).
485 </note>
486 Another advantage of the override style operations is that
487 you can combine them with other overrides as described in the
488 "<link linkend='conditional-syntax-overrides'>Conditional Syntax (Overrides)</link>"
489 section.
490 </para>
491 </section>
492
493 <section id='variable-flag-syntax'>
494 <title>Variable Flag Syntax</title>
495
496 <para>
497 Variable flags are BitBake's implementation of variable properties
498 or attributes.
499 It is a way of tagging extra information onto a variable.
500 You can find more out about variable flags in general in the
501 "<link linkend='variable-flags'>Variable Flags</link>"
502 section.
503 </para>
504
505 <para>
506 You can define, append, and prepend values to variable flags.
507 All the standard syntax operations previously mentioned work
508 for variable flags except for override style syntax
509 (i.e. "_prepend", "_append", and "_remove").
510 </para>
511
512 <para>
513 Here are some examples showing how to set variable flags:
514 <literallayout class='monospaced'>
515 FOO[a] = "abc"
516 FOO[b] = "123"
517 FOO[a] += "456"
518 </literallayout>
519 The variable <filename>FOO</filename> has two flags:
520 <filename>[a]</filename> and <filename>[b]</filename>.
521 The flags are immediately set to "abc" and "123", respectively.
522 The <filename>[a]</filename> flag becomes "abc 456".
523 </para>
524
525 <para>
526 No need exists to pre-define variable flags.
527 You can simply start using them.
528 One extremely common application
529 is to attach some brief documentation to a BitBake variable as
530 follows:
531 <literallayout class='monospaced'>
532 CACHE[doc] = "The directory holding the cache of the metadata."
533 </literallayout>
534 </para>
535 </section>
536
537 <section id='inline-python-variable-expansion'>
538 <title>Inline Python Variable Expansion</title>
539
540 <para>
541 You can use inline Python variable expansion to
542 set variables.
543 Here is an example:
544 <literallayout class='monospaced'>
545 DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
546 </literallayout>
547 This example results in the <filename>DATE</filename>
548 variable being set to the current date.
549 </para>
550
551 <para>
552 Probably the most common use of this feature is to extract
553 the value of variables from BitBake's internal data dictionary,
554 <filename>d</filename>.
555 The following lines select the values of a package name
556 and its version number, respectively:
557 <literallayout class='monospaced'>
558 PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
559 PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"
560 </literallayout>
561 <note>
562 Inline Python expressions work just like variable expansions
563 insofar as the "=" and ":=" operators are concerned.
564 Given the following assignment, <filename>foo()</filename>
565 is called each time <filename>FOO</filename> is expanded:
566 <literallayout class='monospaced'>
567 FOO = "${@foo()}"
568 </literallayout>
569 Contrast this with the following immediate assignment, where
570 <filename>foo()</filename> is only called once, while the
571 assignment is parsed:
572 <literallayout class='monospaced'>
573 FOO := "${@foo()}"
574 </literallayout>
575 </note>
576 For a different way to set variables with Python code during
577 parsing, see the
578 "<link linkend='anonymous-python-functions'>Anonymous Python Functions</link>"
579 section.
580 </para>
581 </section>
582
583 <section id='unsetting-variables'>
584 <title>Unsetting variables</title>
585
586 <para>
587 It is possible to completely remove a variable or a variable flag
588 from BitBake's internal data dictionary by using the "unset" keyword.
589 Here is an example:
590 <literallayout class='monospaced'>
591 unset DATE
592 unset do_fetch[noexec]
593 </literallayout>
594 These two statements remove the <filename>DATE</filename> and the
595 <filename>do_fetch[noexec]</filename> flag.
596 </para>
597
598 </section>
599
600 <section id='providing-pathnames'>
601 <title>Providing Pathnames</title>
602
603 <para>
604 When specifying pathnames for use with BitBake,
605 do not use the tilde ("~") character as a shortcut
606 for your home directory.
607 Doing so might cause BitBake to not recognize the
608 path since BitBake does not expand this character in
609 the same way a shell would.
610 </para>
611
612 <para>
613 Instead, provide a fuller path as the following
614 example illustrates:
615 <literallayout class='monospaced'>
616 BBLAYERS ?= " \
617 /home/scott-lenovo/LayerA \
618 "
619 </literallayout>
620 </para>
621 </section>
622 </section>
623
624 <section id='exporting-variables-to-the-environment'>
625 <title>Exporting Variables to the Environment</title>
626
627 <para>
628 You can export variables to the environment of running
629 tasks by using the <filename>export</filename> keyword.
630 For example, in the following example, the
631 <filename>do_foo</filename> task prints "value from
632 the environment" when run:
633 <literallayout class='monospaced'>
634 export ENV_VARIABLE
635 ENV_VARIABLE = "value from the environment"
636
637 do_foo() {
638 bbplain "$ENV_VARIABLE"
639 }
640 </literallayout>
641 <note>
642 BitBake does not expand <filename>$ENV_VARIABLE</filename>
643 in this case because it lacks the obligatory
644 <filename>{}</filename>.
645 Rather, <filename>$ENV_VARIABLE</filename> is expanded
646 by the shell.
647 </note>
648 It does not matter whether
649 <filename>export ENV_VARIABLE</filename> appears before or
650 after assignments to <filename>ENV_VARIABLE</filename>.
651 </para>
652
653 <para>
654 It is also possible to combine <filename>export</filename>
655 with setting a value for the variable.
656 Here is an example:
657 <literallayout class='monospaced'>
658 export ENV_VARIABLE = "<replaceable>variable-value</replaceable>"
659 </literallayout>
660 In the output of <filename>bitbake -e</filename>, variables
661 that are exported to the environment are preceded by "export".
662 </para>
663
664 <para>
665 Among the variables commonly exported to the environment
666 are <filename>CC</filename> and <filename>CFLAGS</filename>,
667 which are picked up by many build systems.
668 </para>
669 </section>
670
671 <section id='conditional-syntax-overrides'>
672 <title>Conditional Syntax (Overrides)</title>
673
674 <para>
675 BitBake uses
676 <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link>
677 to control what variables are overridden after BitBake
678 parses recipes and configuration files.
679 This section describes how you can use
680 <filename>OVERRIDES</filename> as conditional metadata,
681 talks about key expansion in relationship to
682 <filename>OVERRIDES</filename>, and provides some examples
683 to help with understanding.
684 </para>
685
686 <section id='conditional-metadata'>
687 <title>Conditional Metadata</title>
688
689 <para>
690 You can use <filename>OVERRIDES</filename> to conditionally select
691 a specific version of a variable and to conditionally
692 append or prepend the value of a variable.
693 <note>
694 Overrides can only use lower-case characters.
695 Additionally, underscores are not permitted in override names
696 as they are used to separate overrides from each other and
697 from the variable name.
698 </note>
699 <itemizedlist>
700 <listitem><para><emphasis>Selecting a Variable:</emphasis>
701 The <filename>OVERRIDES</filename> variable is
702 a colon-character-separated list that contains items
703 for which you want to satisfy conditions.
704 Thus, if you have a variable that is conditional on “arm”, and “arm”
705 is in <filename>OVERRIDES</filename>, then the “arm”-specific
706 version of the variable is used rather than the non-conditional
707 version.
708 Here is an example:
709 <literallayout class='monospaced'>
710 OVERRIDES = "architecture:os:machine"
711 TEST = "default"
712 TEST_os = "osspecific"
713 TEST_nooverride = "othercondvalue"
714 </literallayout>
715 In this example, the <filename>OVERRIDES</filename>
716 variable lists three overrides:
717 "architecture", "os", and "machine".
718 The variable <filename>TEST</filename> by itself has a default
719 value of "default".
720 You select the os-specific version of the <filename>TEST</filename>
721 variable by appending the "os" override to the variable
722 (i.e.<filename>TEST_os</filename>).
723 </para>
724
725 <para>
726 To better understand this, consider a practical example
727 that assumes an OpenEmbedded metadata-based Linux
728 kernel recipe file.
729 The following lines from the recipe file first set
730 the kernel branch variable <filename>KBRANCH</filename>
731 to a default value, then conditionally override that
732 value based on the architecture of the build:
733 <literallayout class='monospaced'>
734 KBRANCH = "standard/base"
735 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
736 KBRANCH_qemumips = "standard/mti-malta32"
737 KBRANCH_qemuppc = "standard/qemuppc"
738 KBRANCH_qemux86 = "standard/common-pc/base"
739 KBRANCH_qemux86-64 = "standard/common-pc-64/base"
740 KBRANCH_qemumips64 = "standard/mti-malta64"
741 </literallayout>
742 </para></listitem>
743 <listitem><para><emphasis>Appending and Prepending:</emphasis>
744 BitBake also supports append and prepend operations to
745 variable values based on whether a specific item is
746 listed in <filename>OVERRIDES</filename>.
747 Here is an example:
748 <literallayout class='monospaced'>
749 DEPENDS = "glibc ncurses"
750 OVERRIDES = "machine:local"
751 DEPENDS_append_machine = " libmad"
752 </literallayout>
753 In this example, <filename>DEPENDS</filename> becomes
754 "glibc ncurses libmad".
755 </para>
756
757 <para>
758 Again, using an OpenEmbedded metadata-based
759 kernel recipe file as an example, the
760 following lines will conditionally append to the
761 <filename>KERNEL_FEATURES</filename> variable based
762 on the architecture:
763 <literallayout class='monospaced'>
764 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
765 KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc"
766 KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc"
767 </literallayout>
768 </para></listitem>
769 <listitem><para><emphasis>Setting a Variable for a Single Task:</emphasis>
770 BitBake supports setting a variable just for the
771 duration of a single task.
772 Here is an example:
773 <literallayout class='monospaced'>
774 FOO_task-configure = "val 1"
775 FOO_task-compile = "val 2"
776 </literallayout>
777 In the previous example, <filename>FOO</filename>
778 has the value "val 1" while the
779 <filename>do_configure</filename> task is executed,
780 and the value "val 2" while the
781 <filename>do_compile</filename> task is executed.
782 </para>
783
784 <para>Internally, this is implemented by prepending
785 the task (e.g. "task-compile:") to the value of
786 <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link>
787 for the local datastore of the <filename>do_compile</filename>
788 task.</para>
789
790 <para>You can also use this syntax with other combinations
791 (e.g. "<filename>_prepend</filename>") as shown in the
792 following example:
793 <literallayout class='monospaced'>
794 EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} "
795 </literallayout>
796 </para></listitem>
797 </itemizedlist>
798 </para>
799 </section>
800
801 <section id='key-expansion'>
802 <title>Key Expansion</title>
803
804 <para>
805 Key expansion happens when the BitBake datastore is finalized.
806 To better understand this, consider the following example:
807 <literallayout class='monospaced'>
808 A${B} = "X"
809 B = "2"
810 A2 = "Y"
811 </literallayout>
812 In this case, after all the parsing is complete,
813 BitBake expands <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"
885 A_foo_append = "X"
886 </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
891 "X" leaving the variable set to "ZX".
892 Finally, applying the override for "foo" results in the conditional
893 variable <filename>A</filename> becoming "ZX" (i.e.
894 <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
912 "_append" operations.
913 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
947 <link linkend='var-bb-BBPATH'><filename>BBPATH</filename></link>
948 variable to locate needed include and class files.
949 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>
956 </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
979 means of specifying functionality contained in class files
980 that your recipes require.
981 For example, you can easily abstract out the tasks involved in
982 building a package that uses Autoconf and Automake and put
983 those tasks into a class file and then have your recipe
984 inherit that class file.
985 </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>
1003 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>
1011 </para>
1012
1013 <para>
1014 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.
1021 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>
1060 </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>
1077 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>
1088 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>
1121 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>
1133 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>),
1164 you can use the
1165 <link linkend='var-bb-INHERIT'><filename>INHERIT</filename></link>
1166 configuration directive to inherit a class.
1167 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>
1191 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'>
1199 INHERIT += "autotools pkgconfig"
1200 </literallayout>
1201 </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>
1218 <listitem><para><emphasis>BitBake-Style Python Functions:</emphasis>
1219 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>
1257
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>
1307 </section>
1308
1309 <section id='bitbake-style-python-functions'>
1310 <title>BitBake-Style Python Functions</title>
1311
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")
1323 print d.getVar("TEXT")
1324 }
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.
1331 <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
1338 function, use <filename>d.getVar("X")</filename>.
1339 Or, for more complicated expressions, use
1340 <filename>d.expand()</filename>.
1341 </note>
1342 </para>
1343
1344 <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>
1376 </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):
1390 if d.getVar('SOMECONDITION'):
1391 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
1419 <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
1449 <filename>${</filename><link linkend='var-bb-T'><filename>T</filename></link><filename>}/run.</filename><replaceable>function-name</replaceable><filename>.</filename><replaceable>pid</replaceable>
1450 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
1512 <section id='anonymous-python-functions'>
1513 <title>Anonymous Python Functions</title>
1514
1515 <para>
1516 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:
1523 <literallayout class='monospaced'>
1524 python () {
1525 if d.getVar('SOMEVAR') == 'value':
1526 d.setVar('ANOTHERVAR', 'value2')
1527 }
1528 </literallayout>
1529 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.
1591 </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>
1689 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_".
1696 </para>
1697
1698 <section id='promoting-a-function-to-a-task'>
1699 <title>Promoting a Function to a Task</title>
1700
1701 <para>
1702 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
1706 <filename>addtask</filename> command.
1707 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:
1712 <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>
1719 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.
1794 </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
1830 the <filename>[noexec]</filename> varflag to disable the task
1831 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>
1843 When running a task, BitBake tightly controls the shell execution
1844 environment of the build tasks to make
1845 sure unwanted contamination from the build machine cannot
1846 influence the build.
1847 <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
1852 <link linkend='var-bb-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link>
1853 variable.
1854 </note>
1855 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
1862 <link linkend='var-bb-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>
1863 and
1864 <link linkend='var-bb-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>
1865 variables.
1866 For example, assume you want to prevent the build system from
1867 accessing your <filename>$HOME/.ccache</filename>
1868 directory.
1869 The following command "whitelists" the environment variable
1870 <filename>CCACHE_DIR</filename> causing BitBake to allow that
1871 variable into the datastore:
1872 <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
1903 <link linkend='var-bb-BB_ORIGENV'><filename>BB_ORIGENV</filename></link>.
1904 </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>
1920 </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>
1953 <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.
1958 </para></listitem>
1959 <listitem><para><emphasis><filename>[depends]</filename>:</emphasis>
1960 Controls inter-task dependencies.
1961 See the
1962 <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link>
1963 variable and the
1964 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
1965 section for more information.
1966 </para></listitem>
1967 <listitem><para><emphasis><filename>[deptask]</filename>:</emphasis>
1968 Controls task build-time dependencies.
1969 See the
1970 <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link>
1971 variable and the
1972 "<link linkend='build-dependencies'>Build Dependencies</link>"
1973 section for more information.
1974 </para></listitem>
1975 <listitem><para><emphasis><filename>[dirs]</filename>:</emphasis>
1976 Directories that should be created before the task runs.
1977 Directories that already exist are left as is.
1978 The last directory listed is used as the
1979 current working directory for the task.
1980 </para></listitem>
1981 <listitem><para><emphasis><filename>[lockfiles]</filename>:</emphasis>
1982 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>
1990 <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
1994 tasks as dependency placeholders, or to disable tasks defined
1995 elsewhere that are not needed in a particular recipe.
1996 </para></listitem>
1997 <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>
2008 </para></listitem>
2009 <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
2016 <link linkend='var-bb-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
2017 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>
2041 <listitem><para><emphasis><filename>[postfuncs]</filename>:</emphasis>
2042 List of functions to call after the completion of the task.
2043 </para></listitem>
2044 <listitem><para><emphasis><filename>[prefuncs]</filename>:</emphasis>
2045 List of functions to call before the task executes.
2046 </para></listitem>
2047 <listitem><para><emphasis><filename>[rdepends]</filename>:</emphasis>
2048 Controls inter-task runtime dependencies.
2049 See the
2050 <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link>
2051 variable, the
2052 <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
2053 variable, and the
2054 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
2055 section for more information.
2056 </para></listitem>
2057 <listitem><para><emphasis><filename>[rdeptask]</filename>:</emphasis>
2058 Controls task runtime dependencies.
2059 See the
2060 <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link>
2061 variable, the
2062 <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
2063 variable, and the
2064 "<link linkend='runtime-dependencies'>Runtime Dependencies</link>"
2065 section for more information.
2066 </para></listitem>
2067 <listitem><para><emphasis><filename>[recideptask]</filename>:</emphasis>
2068 When set in conjunction with
2069 <filename>recrdeptask</filename>, specifies a task that
2070 should be inspected for additional dependencies.
2071 </para></listitem>
2072 <listitem><para><emphasis><filename>[recrdeptask]</filename>:</emphasis>
2073 Controls task recursive runtime dependencies.
2074 See the
2075 <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link>
2076 variable, the
2077 <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
2078 variable, and the
2079 "<link linkend='recursive-dependencies'>Recursive Dependencies</link>"
2080 section for more information.
2081 </para></listitem>
2082 <listitem><para><emphasis><filename>[stamp-extra-info]</filename>:</emphasis>
2083 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>
2087 <listitem><para><emphasis><filename>[umask]</filename>:</emphasis>
2088 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>
2100 <listitem><para><emphasis><filename>[vardeps]</filename>:</emphasis>
2101 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>
2109 <listitem><para><emphasis><filename>[vardepsexclude]</filename>:</emphasis>
2110 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>
2114 <listitem><para><emphasis><filename>[vardepvalue]</filename>:</emphasis>
2115 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>
2119 <listitem><para><emphasis><filename>[vardepvalueexclude]</filename>:</emphasis>
2120 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>
2132 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.
2138 The intent is to make it easy to do things like email
2139 notification on build failures.
2140 </para>
2141
2142 <para>
2143 Following is an example event handler that prints the name
2144 of the event and the content of the
2145 <filename>FILE</filename> variable:
2146 <literallayout class='monospaced'>
2147 addhandler myclass_eventhandler
2148 python myclass_eventhandler() {
2149 from bb.event import getName
2150 print("The name of the Event is %s" % getName(e))
2151 print("The file we run for is %s" % d.getVar('FILE'))
2152 }
2153 myclass_eventhandler[eventmask] = "bb.event.BuildStarted bb.event.BuildCompleted"
2154 </literallayout>
2155 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
2163 the name of the triggered event.
2164 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.
2168 </para>
2169
2170 <para>
2171 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.
2177 The "BuildStarted" and "BuildCompleted" events also run in
2178 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.
2186 </para>
2187
2188 <para>
2189 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:
2193 <itemizedlist>
2194 <listitem><para>
2195 <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
2206 <link linkende='var-bb-BB_INVALIDCONF'><filename>BB_INVALIDCONF</filename></link>
2207 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.
2210 </para></listitem>
2211 <listitem><para>
2212 <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.
2221 </para></listitem>
2222 <listitem><para>
2223 <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.
2227 </para></listitem>
2228 <listitem><para>
2229 <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.
2233 </para></listitem>
2234 <listitem><para>
2235 <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.
2240 </para></listitem>
2241 <listitem><para>
2242 <filename>bb.event.BuildStarted()</filename>:
2243 Fired when a new build starts.
2244 BitBake fires multiple "BuildStarted" events (one per configuration)
2245 when multiple configuration (multiconfig) is enabled.
2246 </para></listitem>
2247 <listitem><para>
2248 <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.
2258 </para></listitem>
2259 <listitem><para>
2260 <filename>bb.build.TaskInvalid()</filename>:
2261 Fired if BitBake tries to execute a task that does not exist.
2262 </para></listitem>
2263 <listitem><para>
2264 <filename>bb.build.TaskFailedSilent()</filename>:
2265 Fired for setscene tasks that fail and should not be
2266 presented to the user verbosely.
2267 </para></listitem>
2268 <listitem><para>
2269 <filename>bb.build.TaskFailed()</filename>:
2270 Fired for normal tasks that fail.
2271 </para></listitem>
2272 <listitem><para>
2273 <filename>bb.build.TaskSucceeded()</filename>:
2274 Fired when a task successfully completes.
2275 </para></listitem>
2276 <listitem><para>
2277 <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.
2285 </para></listitem>
2286 </itemizedlist>
2287 </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:
2295 <itemizedlist>
2296 <listitem><para>
2297 <filename>bb.event.TreeDataPreparationStarted()</filename>
2298 </para></listitem>
2299 <listitem><para>
2300 <filename>bb.event.TreeDataPreparationProgress()</filename>
2301 </para></listitem>
2302 <listitem><para>
2303 <filename>bb.event.TreeDataPreparationCompleted()</filename>
2304 </para></listitem>
2305 <listitem><para>
2306 <filename>bb.event.DepTreeGenerated()</filename>
2307 </para></listitem>
2308 <listitem><para>
2309 <filename>bb.event.CoreBaseFilesFound()</filename>
2310 </para></listitem>
2311 <listitem><para>
2312 <filename>bb.event.ConfigFilePathFound()</filename>
2313 </para></listitem>
2314 <listitem><para>
2315 <filename>bb.event.FilesMatchingFound()</filename>
2316 </para></listitem>
2317 <listitem><para>
2318 <filename>bb.event.ConfigFilesFound()</filename>
2319 </para></listitem>
2320 <listitem><para>
2321 <filename>bb.event.TargetsTreeGenerated()</filename>
2322 </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
2335 <link linkend='var-bb-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
2336 and
2337 <link linkend='var-bb-BBVERSIONS'><filename>BBVERSIONS</filename></link>
2338 variables.
2339 <note>
2340 The mechanism for this class extension is extremely
2341 specific to the implementation.
2342 Usually, the recipe's
2343 <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>
2346 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
2366 <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link>
2367 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
2385 (<link linkend='var-bb-FILESPATH'><filename>FILESPATH</filename></link>).
2386 </para></listitem>
2387 </itemizedlist>
2388 </para>
2389 </section>
2390
2391 <section id='dependencies'>
2392 <title>Dependencies</title>
2393
2394 <para>
2395 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>
2415
2416 <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>
2421
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>
2436 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>
2441 task.
2442 <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>
2479 </para>
2480 </section>
2481
2482 <section id='build-dependencies'>
2483 <title>Build Dependencies</title>
2484
2485 <para>
2486 BitBake uses the
2487 <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link>
2488 variable to manage build time dependencies.
2489 The <filename>[deptask]</filename> varflag for tasks
2490 signifies the task of each
2491 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
2508 <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>
2511 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.
2519 The <filename>[rdeptask]</filename> flag for tasks is used to
2520 signify the task of each
2521 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 Although <filename>RDEPENDS</filename> contains entries from the
2530 runtime dependency namespace, BitBake knows how to map them back
2531 to the build-time dependency namespace, in which the tasks are defined.
2532 </para>
2533 </section>
2534
2535 <section id='recursive-dependencies'>
2536 <title>Recursive Dependencies</title>
2537
2538 <para>
2539 BitBake uses the <filename>[recrdeptask]</filename> flag to manage
2540 recursive task dependencies.
2541 BitBake looks through the build-time and runtime
2542 dependencies of the current recipe, looks through
2543 the task's inter-task
2544 dependencies, and then adds dependencies for the
2545 listed task.
2546 Once BitBake has accomplished this, it recursively works through
2547 the dependencies of those tasks.
2548 Iterative passes continue until all dependencies are discovered
2549 and added.
2550 </para>
2551
2552 <para>
2553 The <filename>[recrdeptask]</filename> flag is most commonly
2554 used in high-level
2555 recipes that need to wait for some task to finish "globally".
2556 For example, <filename>image.bbclass</filename> has the following:
2557 <literallayout class='monospaced'>
2558 do_rootfs[recrdeptask] += "do_packagedata"
2559 </literallayout>
2560 This statement says that the <filename>do_packagedata</filename>
2561 task of the current recipe and all recipes reachable
2562 (by way of dependencies) from the
2563 image recipe must run before the <filename>do_rootfs</filename>
2564 task can run.
2565 </para>
2566
2567 <para>
2568 BitBake allows a task to recursively depend on itself by
2569 referencing itself in the task list:
2570 <literallayout class='monospaced'>
2571 do_a[recrdeptask] = "do_a do_b"
2572 </literallayout>
2573 In the same way as before, this means that the <filename>do_a</filename>
2574 and <filename>do_b</filename> tasks of the current recipe and all
2575 recipes reachable (by way of dependencies) from the recipe
2576 must run before the <filename>do_a</filename> task can run. In this
2577 case BitBake will ignore the current recipe's <filename>do_a</filename>
2578 task circular dependency on itself.
2579 </para>
2580 </section>
2581
2582 <section id='inter-task-dependencies'>
2583 <title>Inter-Task Dependencies</title>
2584
2585 <para>
2586 BitBake uses the <filename>[depends]</filename>
2587 flag in a more generic form
2588 to manage inter-task dependencies.
2589 This more generic form allows for inter-dependency
2590 checks for specific tasks rather than checks for
2591 the data in <filename>DEPENDS</filename>.
2592 Here is an example:
2593 <literallayout class='monospaced'>
2594 do_patch[depends] = "quilt-native:do_populate_sysroot"
2595 </literallayout>
2596 In this example, the <filename>do_populate_sysroot</filename>
2597 task of the target <filename>quilt-native</filename>
2598 must have completed before the
2599 <filename>do_patch</filename> task can execute.
2600 </para>
2601
2602 <para>
2603 The <filename>[rdepends]</filename> flag works in a similar
2604 way but takes targets
2605 in the runtime namespace instead of the build-time dependency
2606 namespace.
2607 </para>
2608 </section>
2609 </section>
2610
2611 <section id='functions-you-can-call-from-within-python'>
2612 <title>Functions You Can Call From Within Python</title>
2613
2614 <para>
2615 BitBake provides many functions you can call from
2616 within Python functions.
2617 This section lists the most commonly used functions,
2618 and mentions where to find others.
2619 </para>
2620
2621 <section id='functions-for-accessing-datastore-variables'>
2622 <title>Functions for Accessing Datastore Variables</title>
2623
2624 <para>
2625 It is often necessary to access variables in the
2626 BitBake datastore using Python functions.
2627 The BitBake datastore has an API that allows you this
2628 access.
2629 Here is a list of available operations:
2630 </para>
2631
2632 <para>
2633 <informaltable frame='none'>
2634 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
2635 <colspec colname='c1' colwidth='1*'/>
2636 <colspec colname='c2' colwidth='1*'/>
2637 <thead>
2638 <row>
2639 <entry align="left"><emphasis>Operation</emphasis></entry>
2640 <entry align="left"><emphasis>Description</emphasis></entry>
2641 </row>
2642 </thead>
2643 <tbody>
2644 <row>
2645 <entry align="left"><filename>d.getVar("X", expand)</filename></entry>
2646 <entry align="left">Returns the value of variable "X".
2647 Using "expand=True" expands the value.
2648 Returns "None" if the variable "X" does not exist.</entry>
2649 </row>
2650 <row>
2651 <entry align="left"><filename>d.setVar("X", "value")</filename></entry>
2652 <entry align="left">Sets the variable "X" to "value".</entry>
2653 </row>
2654 <row>
2655 <entry align="left"><filename>d.appendVar("X", "value")</filename></entry>
2656 <entry align="left">Adds "value" to the end of the variable "X".
2657 Acts like <filename>d.setVar("X", "value")</filename>
2658 if the variable "X" does not exist.</entry>
2659 </row>
2660 <row>
2661 <entry align="left"><filename>d.prependVar("X", "value")</filename></entry>
2662 <entry align="left">Adds "value" to the start of the variable "X".
2663 Acts like <filename>d.setVar("X", "value")</filename>
2664 if the variable "X" does not exist.</entry>
2665 </row>
2666 <row>
2667 <entry align="left"><filename>d.delVar("X")</filename></entry>
2668 <entry align="left">Deletes the variable "X" from the datastore.
2669 Does nothing if the variable "X" does not exist.</entry>
2670 </row>
2671 <row>
2672 <entry align="left"><filename>d.renameVar("X", "Y")</filename></entry>
2673 <entry align="left">Renames the variable "X" to "Y".
2674 Does nothing if the variable "X" does not exist.</entry>
2675 </row>
2676 <row>
2677 <entry align="left"><filename>d.getVarFlag("X", flag, expand)</filename></entry>
2678 <entry align="left">Returns the value of variable "X".
2679 Using "expand=True" expands the value.
2680 Returns "None" if either the variable "X" or the named flag
2681 does not exist.</entry>
2682 </row>
2683 <row>
2684 <entry align="left"><filename>d.setVarFlag("X", flag, "value")</filename></entry>
2685 <entry align="left">Sets the named flag for variable "X" to "value".</entry>
2686 </row>
2687 <row>
2688 <entry align="left"><filename>d.appendVarFlag("X", flag, "value")</filename></entry>
2689 <entry align="left">Appends "value" to the named flag on the
2690 variable "X".
2691 Acts like <filename>d.setVarFlag("X", flag, "value")</filename>
2692 if the named flag does not exist.</entry>
2693 </row>
2694 <row>
2695 <entry align="left"><filename>d.prependVarFlag("X", flag, "value")</filename></entry>
2696 <entry align="left">Prepends "value" to the named flag on
2697 the variable "X".
2698 Acts like <filename>d.setVarFlag("X", flag, "value")</filename>
2699 if the named flag does not exist.</entry>
2700 </row>
2701 <row>
2702 <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry>
2703 <entry align="left">Deletes the named flag on the variable
2704 "X" from the datastore.</entry>
2705 </row>
2706 <row>
2707 <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry>
2708 <entry align="left">Sets the flags specified in
2709 the <filename>flagsdict()</filename> parameter.
2710 <filename>setVarFlags</filename> does not clear previous flags.
2711 Think of this operation as <filename>addVarFlags</filename>.</entry>
2712 </row>
2713 <row>
2714 <entry align="left"><filename>d.getVarFlags("X")</filename></entry>
2715 <entry align="left">Returns a <filename>flagsdict</filename>
2716 of the flags for the variable "X".
2717 Returns "None" if the variable "X" does not exist.</entry>
2718 </row>
2719 <row>
2720 <entry align="left"><filename>d.delVarFlags("X")</filename></entry>
2721 <entry align="left">Deletes all the flags for the variable "X".
2722 Does nothing if the variable "X" does not exist.</entry>
2723 </row>
2724 <row>
2725 <entry align="left"><filename>d.expand(expression)</filename></entry>
2726 <entry align="left">Expands variable references in the specified
2727 string expression.
2728 References to variables that do not exist are left as is.
2729 For example, <filename>d.expand("foo ${X}")</filename>
2730 expands to the literal string "foo ${X}" if the
2731 variable "X" does not exist.</entry>
2732 </row>
2733 </tbody>
2734 </tgroup>
2735 </informaltable>
2736 </para>
2737 </section>
2738
2739 <section id='other-functions'>
2740 <title>Other Functions</title>
2741
2742 <para>
2743 You can find many other functions that can be called
2744 from Python by looking at the source code of the
2745 <filename>bb</filename> module, which is in
2746 <filename>bitbake/lib/bb</filename>.
2747 For example,
2748 <filename>bitbake/lib/bb/utils.py</filename> includes
2749 the commonly used functions
2750 <filename>bb.utils.contains()</filename> and
2751 <filename>bb.utils.mkdirhier()</filename>, which come
2752 with docstrings.
2753 </para>
2754 </section>
2755 </section>
2756
2757 <section id='task-checksums-and-setscene'>
2758 <title>Task Checksums and Setscene</title>
2759
2760 <para>
2761 BitBake uses checksums (or signatures) along with the setscene
2762 to determine if a task needs to be run.
2763 This section describes the process.
2764 To help understand how BitBake does this, the section assumes an
2765 OpenEmbedded metadata-based example.
2766 </para>
2767
2768 <para>
2769 These checksums are stored in
2770 <link linkend='var-bb-STAMP'><filename>STAMP</filename></link>.
2771 You can examine the checksums using the following BitBake command:
2772 <literallayout class='monospaced'>
2773 $ bitbake-dumpsigs
2774 </literallayout>
2775 This command returns the signature data in a readable format
2776 that allows you to examine the inputs used when the
2777 OpenEmbedded build system generates signatures.
2778 For example, using <filename>bitbake-dumpsigs</filename>
2779 allows you to examine the <filename>do_compile</filename>
2780 task's “sigdata” for a C application (e.g.
2781 <filename>bash</filename>).
2782 Running the command also reveals that the “CC” variable is part of
2783 the inputs that are hashed.
2784 Any changes to this variable would invalidate the stamp and
2785 cause the <filename>do_compile</filename> task to run.
2786 </para>
2787
2788 <para>
2789 The following list describes related variables:
2790 <itemizedlist>
2791 <listitem><para>
2792 <link linkend='var-bb-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></link>:
2793 Specifies the name of the function to call during
2794 the "setscene" part of the task's execution in order
2795 to validate the list of task hashes.
2796 </para></listitem>
2797 <listitem><para>
2798 <link linkend='var-bb-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></link>:
2799 Specifies a function BitBake calls that determines
2800 whether BitBake requires a setscene dependency to
2801 be met.
2802 </para></listitem>
2803 <listitem><para>
2804 <link linkend='var-bb-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></link>:
2805 Specifies a function to call that verifies the list of
2806 planned task execution before the main task execution
2807 happens.
2808 </para></listitem>
2809 <listitem><para>
2810 <link linkend='var-bb-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link>:
2811 Defines the mode for comparing timestamps of stamp files.
2812 </para></listitem>
2813 <listitem><para>
2814 <link linkend='var-bb-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link>:
2815 Lists stamp files that are looked at when the stamp policy
2816 is "whitelist".
2817 </para></listitem>
2818 <listitem><para>
2819 <link linkend='var-bb-BB_TASKHASH'><filename>BB_TASKHASH</filename></link>:
2820 Within an executing task, this variable holds the hash
2821 of the task as returned by the currently enabled
2822 signature generator.
2823 </para></listitem>
2824 <listitem><para>
2825 <link linkend='var-bb-STAMP'><filename>STAMP</filename></link>:
2826 The base path to create stamp files.
2827 </para></listitem>
2828 <listitem><para>
2829 <link linkend='var-bb-STAMPCLEAN'><filename>STAMPCLEAN</filename></link>:
2830 Again, the base path to create stamp files but can use wildcards
2831 for matching a range of files for clean operations.
2832 </para></listitem>
2833 </itemizedlist>
2834 </para>
2835 </section>
2836
2837 <section id='wildcard-support-in-variables'>
2838 <title>Wildcard Support in Variables</title>
2839
2840 <para>
2841 Support for wildcard use in variables varies depending on the
2842 context in which it is used.
2843 For example, some variables and file names allow limited use of
2844 wildcards through the "<filename>%</filename>" and
2845 "<filename>*</filename>" characters.
2846 Other variables or names support Python's
2847 <ulink url='https://docs.python.org/3/library/glob.html'><filename>glob</filename></ulink>
2848 syntax,
2849 <ulink url='https://docs.python.org/3/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>
2850 syntax, or
2851 <ulink url='https://docs.python.org/3/library/re.html#re'><filename>Regular Expression (re)</filename></ulink>
2852 syntax.
2853 </para>
2854
2855 <para>
2856 For variables that have wildcard suport, the
2857 documentation describes which form of wildcard, its
2858 use, and its limitations.
2859 </para>
2860 </section>
2861
2862</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-08-15 20:38:07 +0000