blob: 1b9d80010818c703f5647a8e29e724d283f72786 [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<chapter id="bitbake-user-manual-metadata">
5 <title>Syntax and Operators</title>
6
7 <para>
8 Bitbake files have their own syntax.
9 The syntax has similarities to several
10 other languages but also has some unique features.
11 This section describes the available syntax and operators
12 as well as provides examples.
13 </para>
14
15 <section id='basic-syntax'>
16 <title>Basic Syntax</title>
17
18 <para>
19 This section provides some basic syntax examples.
20 </para>
21
22 <section id='basic-variable-setting'>
23 <title>Basic Variable Setting</title>
24
25 <para>
26 The following example sets <filename>VARIABLE</filename> to
27 "value".
28 This assignment occurs immediately as the statement is parsed.
29 It is a "hard" assignment.
30 <literallayout class='monospaced'>
31 VARIABLE = "value"
32 </literallayout>
33 As expected, if you include leading or trailing spaces as part of
34 an assignment, the spaces are retained:
35 <literallayout class='monospaced'>
36 VARIABLE = " value"
37 VARIABLE = "value "
38 </literallayout>
39 Setting <filename>VARIABLE</filename> to "" sets it to an empty string,
40 while setting the variable to " " sets it to a blank space
41 (i.e. these are not the same values).
42 <literallayout class='monospaced'>
43 VARIABLE = ""
44 VARIABLE = " "
45 </literallayout>
46 </para>
47 </section>
48
49 <section id='variable-expansion'>
50 <title>Variable Expansion</title>
51
52 <para>
53 BitBake supports variables referencing one another's
54 contents using a syntax that is similar to shell scripting.
55 Following is an example that results in <filename>A</filename>
56 containing "aval" and <filename>B</filename> evaluating to
57 "preavalpost" based on that current value of
58 <filename>A</filename>.
59 <literallayout class='monospaced'>
60 A = "aval"
61 B = "pre${A}post"
62 </literallayout>
63 You should realize that whenever <filename>B</filename> is
64 referenced, its evaluation will depend on the state of
65 <filename>A</filename> at that time.
66 Thus, later evaluations of <filename>B</filename> in the
67 previous example could result in different values
68 depending on the value of <filename>A</filename>.
69 </para>
70 </section>
71
72 <section id='setting-a-default-value'>
73 <title>Setting a default value (?=)</title>
74
75 <para>
76 You can use the "?=" operator to achieve a "softer" assignment
77 for a variable.
78 This type of assignment allows you to define a variable if it
79 is undefined when the statement is parsed, but to leave the
80 value alone if the variable has a value.
81 Here is an example:
82 <literallayout class='monospaced'>
83 A ?= "aval"
84 </literallayout>
85 If <filename>A</filename> is set at the time this statement is parsed,
86 the variable retains its value.
87 However, if <filename>A</filename> is not set,
88 the variable is set to "aval".
89 <note>
90 This assignment is immediate.
91 Consequently, if multiple "?=" assignments
92 to a single variable exist, the first of those ends up getting
93 used.
94 </note>
95 </para>
96 </section>
97
98 <section id='setting-a-weak-default-value'>
99 <title>Setting a weak default value (??=)</title>
100
101 <para>
102 It is possible to use a "weaker" assignment than in the
103 previous section by using the "??=" operator.
104 This assignment behaves identical to "?=" except that the
105 assignment is made at the end of the parsing process rather
106 than immediately.
107 Consequently, when multiple "??=" assignments exist, the last
108 one is used.
109 Also, any "=" or "?=" assignment will override the value set with
110 "??=".
111 Here is an example:
112 <literallayout class='monospaced'>
113 A ??= "somevalue"
114 A ??= "someothervalue"
115 </literallayout>
116 If <filename>A</filename> is set before the above statements are parsed,
117 the variable retains its value.
118 If <filename>A</filename> is not set,
119 the variable is set to "someothervalue".
120 </para>
121
122 <para>
123 Again, this assignment is a "lazy" or "weak" assignment
124 because it does not occur until the end
125 of the parsing process.
126 </para>
127 </section>
128
129 <section id='immediate-variable-expansion'>
130 <title>Immediate variable expansion (:=)</title>
131
132 <para>
133 The ":=" operator results in a variable's
134 contents being expanded immediately,
135 rather than when the variable is actually used:
136 <literallayout class='monospaced'>
137 T = "123"
138 A := "${B} ${A} test ${T}"
139 T = "456"
140 B = "${T} bval"
141 C = "cval"
142 C := "${C}append"
143 </literallayout>
144 In this example, <filename>A</filename> contains
145 "test 123" because <filename>${B}</filename> and
146 <filename>${A}</filename> at the time of parsing are undefined,
147 which leaves "test 123".
148 And, the variable <filename>C</filename>
149 contains "cvalappend" since <filename>${C}</filename> immediately
150 expands to "cval".
151 </para>
152 </section>
153
154 <section id='appending-and-prepending'>
155 <title>Appending (+=) and prepending (=+) With Spaces</title>
156
157 <para>
158 Appending and prepending values is common and can be accomplished
159 using the "+=" and "=+" operators.
160 These operators insert a space between the current
161 value and prepended or appended value.
162 </para>
163
164 <para>
165 These operators take immediate effect during parsing.
166 Here are some examples:
167 <literallayout class='monospaced'>
168 B = "bval"
169 B += "additionaldata"
170 C = "cval"
171 C =+ "test"
172 </literallayout>
173 The variable <filename>B</filename> contains
174 "bval additionaldata" and <filename>C</filename>
175 contains "test cval".
176 </para>
177 </section>
178
179 <section id='appending-and-prepending-without-spaces'>
180 <title>Appending (.=) and Prepending (=.) Without Spaces</title>
181
182 <para>
183 If you want to append or prepend values without an
184 inserted space, use the ".=" and "=." operators.
185 </para>
186
187 <para>
188 These operators take immediate effect during parsing.
189 Here are some examples:
190 <literallayout class='monospaced'>
191 B = "bval"
192 B .= "additionaldata"
193 C = "cval"
194 C =. "test"
195 </literallayout>
196 The variable <filename>B</filename> contains
197 "bvaladditionaldata" and
198 <filename>C</filename> contains "testcval".
199 </para>
200 </section>
201
202 <section id='appending-and-prepending-override-style-syntax'>
203 <title>Appending and Prepending (Override Style Syntax)</title>
204
205 <para>
206 You can also append and prepend a variable's value
207 using an override style syntax.
208 When you use this syntax, no spaces are inserted.
209 </para>
210
211 <para>
212 These operators differ from the ":=", ".=", "=.", "+=", and "=+"
213 operators in that their effects are deferred
214 until after parsing completes rather than being immediately
215 applied.
216 Here are some examples:
217 <literallayout class='monospaced'>
218 B = "bval"
219 B_append = " additional data"
220 C = "cval"
221 C_prepend = "additional data "
222 D = "dval"
223 D_append = "additional data"
224 </literallayout>
225 The variable <filename>B</filename> becomes
226 "bval additional data" and <filename>C</filename> becomes
227 "additional data cval".
228 The variable <filename>D</filename> becomes
229 "dvaladditional data".
230 <note>
231 You must control all spacing when you use the
232 override syntax.
233 </note>
234 </para>
235 </section>
236
237 <section id='removing-override-style-syntax'>
238 <title>Removal (Override Style Syntax)</title>
239
240 <para>
241 You can remove values from lists using the removal
242 override style syntax.
243 Specifying a value for removal causes all occurrences of that
244 value to be removed from the variable.
245 </para>
246
247 <para>
248 When you use this syntax, BitBake expects one or more strings.
249 Surrounding spaces are removed as well.
250 Here is an example:
251 <literallayout class='monospaced'>
252 FOO = "123 456 789 123456 123 456 123 456"
253 FOO_remove = "123"
254 FOO_remove = "456"
255 FOO2 = "abc def ghi abcdef abc def abc def"
256 FOO2_remove = "abc def"
257 </literallayout>
258 The variable <filename>FOO</filename> becomes
259 "789 123456" and <filename>FOO2</filename> becomes
260 "ghi abcdef".
261 </para>
262 </section>
263
264 <section id='variable-flag-syntax'>
265 <title>Variable Flag Syntax</title>
266
267 <para>
268 Variable flags are BitBake's implementation of variable properties
269 or attributes.
270 It is a way of tagging extra information onto a variable.
271 You can find more out about variable flags in general in the
272 "<link linkend='variable-flags'>Variable Flags</link>"
273 section.
274 </para>
275
276 <para>
277 You can define, append, and prepend values to variable flags.
278 All the standard syntax operations previously mentioned work
279 for variable flags except for override style syntax
280 (i.e. <filename>_prepend</filename>, <filename>_append</filename>,
281 and <filename>_remove</filename>).
282 </para>
283
284 <para>
285 Here are some examples showing how to set variable flags:
286 <literallayout class='monospaced'>
287 FOO[a] = "abc"
288 FOO[b] = "123"
289 FOO[a] += "456"
290 </literallayout>
291 The variable <filename>FOO</filename> has two flags:
292 <filename>a</filename> and <filename>b</filename>.
293 The flags are immediately set to "abc" and "123", respectively.
294 The <filename>a</filename> flag becomes "abc 456".
295 </para>
296
297 <para>
298 No need exists to pre-define variable flags.
299 You can simply start using them.
300 One extremely common application
301 is to attach some brief documentation to a BitBake variable as
302 follows:
303 <literallayout class='monospaced'>
304 CACHE[doc] = "The directory holding the cache of the metadata."
305 </literallayout>
306 </para>
307 </section>
308
309 <section id='inline-python-variable-expansion'>
310 <title>Inline Python Variable Expansion</title>
311
312 <para>
313 You can use inline Python variable expansion to
314 set variables.
315 Here is an example:
316 <literallayout class='monospaced'>
317 DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
318 </literallayout>
319 This example results in the <filename>DATE</filename>
320 variable being set to the current date.
321 </para>
322
323 <para>
324 Probably the most common use of this feature is to extract
325 the value of variables from BitBake's internal data dictionary,
326 <filename>d</filename>.
327 The following lines select the values of a package name
328 and its version number, respectively:
329 <literallayout class='monospaced'>
330 PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
331 PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"
332 </literallayout>
333 </para>
334 </section>
335
336 <section id='providing-pathnames'>
337 <title>Providing Pathnames</title>
338
339 <para>
340 When specifying pathnames for use with BitBake,
341 do not use the tilde ("~") character as a shortcut
342 for your home directory.
343 Doing so might cause BitBake to not recognize the
344 path since BitBake does not expand this character in
345 the same way a shell would.
346 </para>
347
348 <para>
349 Instead, provide a fuller path as the following
350 example illustrates:
351 <literallayout class='monospaced'>
352 BBLAYERS ?= " \
353 /home/scott-lenovo/LayerA \
354 "
355 </literallayout>
356 </para>
357 </section>
358 </section>
359
360 <section id='conditional-syntax-overrides'>
361 <title>Conditional Syntax (Overrides)</title>
362
363 <para>
364 BitBake uses
365 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
366 to control what variables are overridden after BitBake
367 parses recipes and configuration files.
368 This section describes how you can use
369 <filename>OVERRIDES</filename> as conditional metadata,
370 talks about key expansion in relationship to
371 <filename>OVERRIDES</filename>, and provides some examples
372 to help with understanding.
373 </para>
374
375 <section id='conditional-metadata'>
376 <title>Conditional Metadata</title>
377
378 <para>
379 You can use <filename>OVERRIDES</filename> to conditionally select
380 a specific version of a variable and to conditionally
381 append or prepend the value of a variable.
382 <itemizedlist>
383 <listitem><para><emphasis>Selecting a Variable:</emphasis>
384 The <filename>OVERRIDES</filename> variable is
385 a colon-character-separated list that contains items
386 for which you want to satisfy conditions.
387 Thus, if you have a variable that is conditional on “arm”, and “arm”
388 is in <filename>OVERRIDES</filename>, then the “arm”-specific
389 version of the variable is used rather than the non-conditional
390 version.
391 Here is an example:
392 <literallayout class='monospaced'>
393 OVERRIDES = "architecture:os:machine"
394 TEST = "default"
395 TEST_os = "osspecific"
396 TEST_nooverride = "othercondvalue"
397 </literallayout>
398 In this example, the <filename>OVERRIDES</filename>
399 variable lists three overrides:
400 "architecture", "os", and "machine".
401 The variable <filename>TEST</filename> by itself has a default
402 value of "default".
403 You select the os-specific version of the <filename>TEST</filename>
404 variable by appending the "os" override to the variable
405 (i.e.<filename>TEST_os</filename>).
406 </para>
407
408 <para>
409 To better understand this, consider a practical example
410 that assumes an OpenEmbedded metadata-based Linux
411 kernel recipe file.
412 The following lines from the recipe file first set
413 the kernel branch variable <filename>KBRANCH</filename>
414 to a default value, then conditionally override that
415 value based on the architecture of the build:
416 <literallayout class='monospaced'>
417 KBRANCH = "standard/base"
418 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
419 KBRANCH_qemumips = "standard/mti-malta32"
420 KBRANCH_qemuppc = "standard/qemuppc"
421 KBRANCH_qemux86 = "standard/common-pc/base"
422 KBRANCH_qemux86-64 = "standard/common-pc-64/base"
423 KBRANCH_qemumips64 = "standard/mti-malta64"
424 </literallayout>
425 </para></listitem>
426 <listitem><para><emphasis>Appending and Prepending:</emphasis>
427 BitBake also supports append and prepend operations to
428 variable values based on whether a specific item is
429 listed in <filename>OVERRIDES</filename>.
430 Here is an example:
431 <literallayout class='monospaced'>
432 DEPENDS = "glibc ncurses"
433 OVERRIDES = "machine:local"
434 DEPENDS_append_machine = "libmad"
435 </literallayout>
436 In this example, <filename>DEPENDS</filename> becomes
437 "glibc ncurses libmad".
438 </para>
439
440 <para>
441 Again, using an OpenEmbedded metadata-based
442 kernel recipe file as an example, the
443 following lines will conditionally append to the
444 <filename>KERNEL_FEATURES</filename> variable based
445 on the architecture:
446 <literallayout class='monospaced'>
447 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
448 KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc"
449 KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc"
450 </literallayout>
451 </para></listitem>
452 </itemizedlist>
453 </para>
454 </section>
455
456 <section id='key-expansion'>
457 <title>Key Expansion</title>
458
459 <para>
460 Key expansion happens when the BitBake datastore is finalized
461 just before BitBake expands overrides.
462 To better understand this, consider the following example:
463 <literallayout class='monospaced'>
464 A${B} = "X"
465 B = "2"
466 A2 = "Y"
467 </literallayout>
468 In this case, after all the parsing is complete, and
469 before any overrides are handled, BitBake expands
470 <filename>${B}</filename> into "2".
471 This expansion causes <filename>A2</filename>, which was
472 set to "Y" before the expansion, to become "X".
473 </para>
474 </section>
475
476 <section id='variable-interaction-worked-examples'>
477 <title>Examples</title>
478
479 <para>
480 Despite the previous explanations that show the different forms of
481 variable definitions, it can be hard to work
482 out exactly what happens when variable operators, conditional
483 overrides, and unconditional overrides are combined.
484 This section presents some common scenarios along
485 with explanations for variable interactions that
486 typically confuse users.
487 </para>
488
489 <para>
490 There is often confusion concerning the order in which
491 overrides and various "append" operators take effect.
492 Recall that an append or prepend operation using "_append"
493 and "_prepend" does not result in an immediate assignment
494 as would "+=", ".=", "=+", or "=.".
495 Consider the following example:
496 <literallayout class='monospaced'>
497 OVERRIDES = "foo"
498 A = "Z"
499 A_foo_append = "X"
500 </literallayout>
501 For this case, <filename>A</filename> is
502 unconditionally set to "Z" and "X" is
503 unconditionally and immediately appended to the variable
504 <filename>A_foo</filename>.
505 Because overrides have not been applied yet,
506 <filename>A_foo</filename> is set to "X" due to the append
507 and <filename>A</filename> simply equals "Z".
508 </para>
509
510 <para>
511 Applying overrides, however, changes things.
512 Since "foo" is listed in <filename>OVERRIDES</filename>,
513 the conditional variable <filename>A</filename> is replaced
514 with the "foo" version, which is equal to "X".
515 So effectively, <filename>A_foo</filename> replaces <filename>A</filename>.
516 </para>
517
518 <para>
519 This next example changes the order of the override and
520 the append:
521 <literallayout class='monospaced'>
522 OVERRIDES = "foo"
523 A = "Z"
524 A_append_foo = "X"
525 </literallayout>
526 For this case, before overrides are handled,
527 <filename>A</filename> is set to "Z" and <filename>A_append_foo</filename>
528 is set to "X".
529 Once the override for "foo" is applied, however,
530 <filename>A</filename> gets appended with "X".
531 Consequently, <filename>A</filename> becomes "ZX".
532 Notice that spaces are not appended.
533 </para>
534
535 <para>
536 This next example has the order of the appends and overrides reversed
537 back as in the first example:
538 <literallayout class='monospaced'>
539 OVERRIDES = "foo"
540 A = "Y"
541 A_foo_append = "Z"
542 A_foo_append += "X"
543 </literallayout>
544 For this case, before any overrides are resolved,
545 <filename>A</filename> is set to "Y" using an immediate assignment.
546 After this immediate assignment, <filename>A_foo</filename> is set
547 to "Z", and then further appended with
548 "X" leaving the variable set to "Z X".
549 Finally, applying the override for "foo" results in the conditional
550 variable <filename>A</filename> becoming "Z X" (i.e.
551 <filename>A</filename> is replaced with <filename>A_foo</filename>).
552 </para>
553
554 <para>
555 This final example mixes in some varying operators:
556 <literallayout class='monospaced'>
557 A = "1"
558 A_append = "2"
559 A_append = "3"
560 A += "4"
561 A .= "5"
562 </literallayout>
563 For this case, the type of append operators are affecting the
564 order of assignments as BitBake passes through the code
565 multiple times.
566 Initially, <filename>A</filename> is set to "1 45" because
567 of the three statements that use immediate operators.
568 After these assignments are made, BitBake applies the
569 <filename>_append</filename> operations.
570 Those operations result in <filename>A</filename> becoming "1 4523".
571 </para>
572 </section>
573 </section>
574
575 <section id='sharing-functionality'>
576 <title>Sharing Functionality</title>
577
578 <para>
579 BitBake allows for metadata sharing through include files
580 (<filename>.inc</filename>) and class files
581 (<filename>.bbclass</filename>).
582 For example, suppose you have a piece of common functionality
583 such as a task definition that you want to share between
584 more than one recipe.
585 In this case, creating a <filename>.bbclass</filename>
586 file that contains the common functionality and then using
587 the <filename>inherit</filename> directive in your recipes to
588 inherit the class would be a common way to share the task.
589 </para>
590
591 <para>
592 This section presents the mechanisms BitBake provides to
593 allow you to share functionality between recipes.
594 Specifically, the mechanisms include <filename>include</filename>,
595 <filename>inherit</filename>, <filename>INHERIT</filename>, and
596 <filename>require</filename> directives.
597 </para>
598
599 <section id='locating-include-and-class-files'>
600 <title>Locating Include and Class Files</title>
601
602 <para>
603 BitBake uses the
604 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
605 variable to locate needed include and class files.
606 The <filename>BBPATH</filename> variable is analogous to
607 the environment variable <filename>PATH</filename>.
608 </para>
609
610 <para>
611 In order for include and class files to be found by BitBake,
612 they need to be located in a "classes" subdirectory that can
613 be found in <filename>BBPATH</filename>.
614 </para>
615 </section>
616
617 <section id='inherit-directive'>
618 <title><filename>inherit</filename> Directive</title>
619
620 <para>
621 When writing a recipe or class file, you can use the
622 <filename>inherit</filename> directive to inherit the
623 functionality of a class (<filename>.bbclass</filename>).
624 BitBake only supports this directive when used within recipe
625 and class files (i.e. <filename>.bb</filename> and
626 <filename>.bbclass</filename>).
627 </para>
628
629 <para>
630 The <filename>inherit</filename> directive is a rudimentary
631 means of specifying what classes of functionality your
632 recipes require.
633 For example, you can easily abstract out the tasks involved in
634 building a package that uses Autoconf and Automake and put
635 those tasks into a class file that can be used by your recipe.
636 </para>
637
638 <para>
639 As an example, your recipes could use the following directive
640 to inherit an <filename>autotools.bbclass</filename> file.
641 The class file would contain common functionality for using
642 Autotools that could be shared across recipes:
643 <literallayout class='monospaced'>
644 inherit autotools
645 </literallayout>
646 In this case, BitBake would search for the directory
647 <filename>classes/autotools.bbclass</filename>
648 in <filename>BBPATH</filename>.
649 <note>
650 You can override any values and functions of the
651 inherited class within your recipe by doing so
652 after the "inherit" statement.
653 </note>
654 </para>
655 </section>
656
657 <section id='include-directive'>
658 <title><filename>include</filename> Directive</title>
659
660 <para>
661 BitBake understands the <filename>include</filename>
662 directive.
663 This directive causes BitBake to parse whatever file you specify,
664 and to insert that file at that location.
665 The directive is much like its equivalent in Make except
666 that if the path specified on the include line is a relative
667 path, BitBake locates the first file it can find
668 within <filename>BBPATH</filename>.
669 </para>
670
671 <para>
672 As an example, suppose you needed a recipe to include some
673 self-test definitions:
674 <literallayout class='monospaced'>
675 include test_defs.inc
676 </literallayout>
677 <note>
678 The <filename>include</filename> directive does not
679 produce an error when the file cannot be found.
680 Consequently, it is recommended that if the file you
681 are including is expected to exist, you should use
682 <link linkend='require-inclusion'><filename>require</filename></link>
683 instead of <filename>include</filename>.
684 Doing so makes sure that an error is produced if the
685 file cannot be found.
686 </note>
687 </para>
688 </section>
689
690 <section id='require-inclusion'>
691 <title><filename>require</filename> Directive</title>
692
693 <para>
694 BitBake understands the <filename>require</filename>
695 directive.
696 This directive behaves just like the
697 <filename>include</filename> directive with the exception that
698 BitBake raises a parsing error if the file to be included cannot
699 be found.
700 Thus, any file you require is inserted into the file that is
701 being parsed at the location of the directive.
702 </para>
703
704 <para>
705 Similar to how BitBake handles
706 <link linkend='include-directive'><filename>include</filename></link>,
707 if the path specified
708 on the require line is a relative path, BitBake locates
709 the first file it can find within <filename>BBPATH</filename>.
710 </para>
711
712 <para>
713 As an example, suppose you have two versions of a recipe
714 (e.g. <filename>foo_1.2.2.bb</filename> and
715 <filename>foo_2.0.0.bb</filename>) where
716 each version contains some identical functionality that could be
717 shared.
718 You could create an include file named <filename>foo.inc</filename>
719 that contains the common definitions needed to build "foo".
720 You need to be sure <filename>foo.inc</filename> is located in the
721 same directory as your two recipe files as well.
722 Once these conditions are set up, you can share the functionality
723 using a <filename>require</filename> directive from within each
724 recipe:
725 <literallayout class='monospaced'>
726 require foo.inc
727 </literallayout>
728 </para>
729 </section>
730
731 <section id='inherit-configuration-directive'>
732 <title><filename>INHERIT</filename> Configuration Directive</title>
733
734 <para>
735 When creating a configuration file (<filename>.conf</filename>),
736 you can use the <filename>INHERIT</filename> directive to
737 inherit a class.
738 BitBake only supports this directive when used within
739 a configuration file.
740 </para>
741
742 <para>
743 As an example, suppose you needed to inherit a class
744 file called <filename>abc.bbclass</filename> from a
745 configuration file as follows:
746 <literallayout class='monospaced'>
747 INHERIT += "abc"
748 </literallayout>
749 This configuration directive causes the named
750 class to be inherited at the point of the directive
751 during parsing.
752 As with the <filename>inherit</filename> directive, the
753 <filename>.bbclass</filename> file must be located in a
754 "classes" subdirectory in one of the directories specified
755 in <filename>BBPATH</filename>.
756 <note>
757 Because <filename>.conf</filename> files are parsed
758 first during BitBake's execution, using
759 <filename>INHERIT</filename> to inherit a class effectively
760 inherits the class globally (i.e. for all recipes).
761 </note>
762 </para>
763 </section>
764 </section>
765
766 <section id='functions'>
767 <title>Functions</title>
768
769 <para>
770 As with most languages, functions are the building blocks that
771 are used to build up operations into tasks.
772 BitBake supports these types of functions:
773 <itemizedlist>
774 <listitem><para><emphasis>Shell Functions:</emphasis>
775 Functions written in shell script and executed either
776 directly as functions, tasks, or both.
777 They can also be called by other shell functions.
778 </para></listitem>
779 <listitem><para><emphasis>BitBake Style Python Functions:</emphasis>
780 Functions written in Python and executed by BitBake or other
781 Python functions using <filename>bb.build.exec_func()</filename>.
782 </para></listitem>
783 <listitem><para><emphasis>Python Functions:</emphasis>
784 Functions written in Python and executed by Python.
785 </para></listitem>
786 <listitem><para><emphasis>Anonymous Python Functions:</emphasis>
787 Python functions executed automatically during
788 parsing.
789 </para></listitem>
790 </itemizedlist>
791 Regardless of the type of function, you can only
792 define them in class (<filename>.bbclass</filename>)
793 and recipe (<filename>.bb</filename> or <filename>.inc</filename>)
794 files.
795 </para>
796
797 <section id='shell-functions'>
798 <title>Shell Functions</title>
799
800 <para>
801 Functions written in shell script and executed either
802 directly as functions, tasks, or both.
803 They can also be called by other shell functions.
804 Here is an example shell function definition:
805 <literallayout class='monospaced'>
806 some_function () {
807 echo "Hello World"
808 }
809 </literallayout>
810 When you create these types of functions in your recipe
811 or class files, you need to follow the shell programming
812 rules.
813 The scripts are executed by <filename>/bin/sh</filename>,
814 which may not be a bash shell but might be something
815 such as <filename>dash</filename>.
816 You should not use Bash-specific script (bashisms).
817 </para>
818 </section>
819
820 <section id='bitbake-style-python-functions'>
821 <title>BitBake Style Python Functions</title>
822
823 <para>
824 These functions are written in Python and executed by
825 BitBake or other Python functions using
826 <filename>bb.build.exec_func()</filename>.
827 </para>
828
829 <para>
830 An example BitBake function is:
831 <literallayout class='monospaced'>
832 python some_python_function () {
833 d.setVar("TEXT", "Hello World")
834 print d.getVar("TEXT", True)
835 }
836 </literallayout>
837 Because the Python "bb" and "os" modules are already
838 imported, you do not need to import these modules.
839 Also in these types of functions, the datastore ("d")
840 is a global variable and is always automatically
841 available.
842 </para>
843 </section>
844
845 <section id='python-functions'>
846 <title>Python Functions</title>
847
848 <para>
849 These functions are written in Python and are executed by
850 other Python code.
851 Examples of Python functions are utility functions
852 that you intend to call from in-line Python or
853 from within other Python functions.
854 Here is an example:
855 <literallayout class='monospaced'>
856 def get_depends(d):
857 if d.getVar('SOMECONDITION', True):
858 return "dependencywithcond"
859 else:
860 return "dependency"
861 SOMECONDITION = "1"
862 DEPENDS = "${@get_depends(d)}"
863 </literallayout>
864 This would result in <filename>DEPENDS</filename>
865 containing <filename>dependencywithcond</filename>.
866 </para>
867
868 <para>
869 Here are some things to know about Python functions:
870 <itemizedlist>
871 <listitem><para>Python functions can take parameters.
872 </para></listitem>
873 <listitem><para>The BitBake datastore is not
874 automatically available.
875 Consequently, you must pass it in as a
876 parameter to the function.
877 </para></listitem>
878 <listitem><para>The "bb" and "os" Python modules are
879 automatically available.
880 You do not need to import them.
881 </para></listitem>
882 </itemizedlist>
883 </para>
884 </section>
885
886 <section id='anonymous-python-functions'>
887 <title>Anonymous Python Functions</title>
888
889 <para>
890 Sometimes it is useful to run some code during
891 parsing to set variables or to perform other operations
892 programmatically.
893 To do this, you can define an anonymous Python function.
894 Here is an example that conditionally sets a
895 variable based on the value of another variable:
896 <literallayout class='monospaced'>
897 python __anonymous () {
898 if d.getVar('SOMEVAR', True) == 'value':
899 d.setVar('ANOTHERVAR', 'value2')
900 }
901 </literallayout>
902 The "__anonymous" function name is optional, so the
903 following example is functionally equivalent to the above:
904 <literallayout class='monospaced'>
905 python () {
906 if d.getVar('SOMEVAR', True) == 'value':
907 d.setVar('ANOTHERVAR', 'value2')
908 }
909 </literallayout>
910 Because unlike other Python functions anonymous
911 Python functions are executed during parsing, the
912 "d" variable within an anonymous Python function represents
913 the datastore for the entire recipe.
914 Consequently, you can set variable values here and
915 those values can be picked up by other functions.
916 </para>
917 </section>
918
919 <section id='flexible-inheritance-for-class-functions'>
920 <title>Flexible Inheritance for Class Functions</title>
921
922 <para>
923 Through coding techniques and the use of
924 <filename>EXPORT_FUNCTIONS</filename>, BitBake supports
925 exporting a function from a class such that the
926 class function appears as the default implementation
927 of the function, but can still be called if a recipe
928 inheriting the class needs to define its own version of
929 the function.
930 </para>
931
932 <para>
933 To understand the benefits of this feature, consider
934 the basic scenario where a class defines a task function
935 and your recipe inherits the class.
936 In this basic scenario, your recipe inherits the task
937 function as defined in the class.
938 If desired, your recipe can add to the start and end of the
939 function by using the "_prepend" or "_append" operations
940 respectively, or it can redefine the function completely.
941 However, if it redefines the function, there is
942 no means for it to call the class version of the function.
943 <filename>EXPORT_FUNCTIONS</filename> provides a mechanism
944 that enables the recipe's version of the function to call
945 the original version of the function.
946 </para>
947
948 <para>
949 To make use of this technique, you need the following
950 things in place:
951 <itemizedlist>
952 <listitem><para>
953 The class needs to define the function as follows:
954 <literallayout class='monospaced'>
955 <replaceable>classname</replaceable><filename>_</filename><replaceable>functionname</replaceable>
956 </literallayout>
957 For example, if you have a class file
958 <filename>bar.bbclass</filename> and a function named
959 <filename>do_foo</filename>, the class must define the function
960 as follows:
961 <literallayout class='monospaced'>
962 bar_do_foo
963 </literallayout>
964 </para></listitem>
965 <listitem><para>
966 The class needs to contain the <filename>EXPORT_FUNCTIONS</filename>
967 statement as follows:
968 <literallayout class='monospaced'>
969 EXPORT_FUNCTIONS <replaceable>functionname</replaceable>
970 </literallayout>
971 For example, continuing with the same example, the
972 statement in the <filename>bar.bbclass</filename> would be
973 as follows:
974 <literallayout class='monospaced'>
975 EXPORT_FUNCTIONS do_foo
976 </literallayout>
977 </para></listitem>
978 <listitem><para>
979 You need to call the function appropriately from within your
980 recipe.
981 Continuing with the same example, if your recipe
982 needs to call the class version of the function,
983 it should call <filename>bar_do_foo</filename>.
984 Assuming <filename>do_foo</filename> was a shell function
985 and <filename>EXPORT_FUNCTIONS</filename> was used as above,
986 the recipe's function could conditionally call the
987 class version of the function as follows:
988 <literallayout class='monospaced'>
989 do_foo() {
990 if [ somecondition ] ; then
991 bar_do_foo
992 else
993 # Do something else
994 fi
995 }
996 </literallayout>
997 To call your modified version of the function as defined
998 in your recipe, call it as <filename>do_foo</filename>.
999 </para></listitem>
1000 </itemizedlist>
1001 With these conditions met, your single recipe
1002 can freely choose between the original function
1003 as defined in the class file and the modified function in your recipe.
1004 If you do not set up these conditions, you are limited to using one function
1005 or the other.
1006 </para>
1007 </section>
1008 </section>
1009
1010 <section id='tasks'>
1011 <title>Tasks</title>
1012
1013 <para>
1014 Tasks are BitBake execution units that originate as
1015 functions and make up the steps that BitBake needs to run
1016 for given recipe.
1017 Tasks are only supported in recipe (<filename>.bb</filename>
1018 or <filename>.inc</filename>) and class
1019 (<filename>.bbclass</filename>) files.
1020 By convention, task names begin with the string "do_".
1021 </para>
1022
1023 <para>
1024 Here is an example of a task that prints out the date:
1025 <literallayout class='monospaced'>
1026 python do_printdate () {
1027 import time
1028 print time.strftime('%Y%m%d', time.gmtime())
1029 }
1030 addtask printdate after do_fetch before do_build
1031 </literallayout>
1032 </para>
1033
1034 <section id='promoting-a-function-to-a-task'>
1035 <title>Promoting a Function to a Task</title>
1036
1037 <para>
1038 Any function can be promoted to a task by applying the
1039 <filename>addtask</filename> command.
1040 The <filename>addtask</filename> command also describes
1041 inter-task dependencies.
1042 Here is the function from the previous section but with the
1043 <filename>addtask</filename> command promoting it to a task
1044 and defining some dependencies:
1045 <literallayout class='monospaced'>
1046 python do_printdate () {
1047 import time
1048 print time.strftime('%Y%m%d', time.gmtime())
1049 }
1050 addtask printdate after do_fetch before do_build
1051 </literallayout>
1052 In the example, the function is defined and then promoted
1053 as a task.
1054 The <filename>do_printdate</filename> task becomes a dependency of
1055 the <filename>do_build</filename> task, which is the default
1056 task.
1057 And, the <filename>do_printdate</filename> task is dependent upon
1058 the <filename>do_fetch</filename> task.
1059 Execution of the <filename>do_build</filename> task results
1060 in the <filename>do_printdate</filename> task running first.
1061 </para>
1062 </section>
1063
1064 <section id='deleting-a-task'>
1065 <title>Deleting a Task</title>
1066
1067 <para>
1068 As well as being able to add tasks, you can delete them.
1069 Simply use the <filename>deltask</filename> command to
1070 delete a task.
1071 For example, to delete the example task used in the previous
1072 sections, you would use:
1073 <literallayout class='monospaced'>
1074 deltask printdate
1075 </literallayout>
1076 If you delete a task using the <filename>deltask</filename>
1077 command and the task has dependencies, the dependencies are
1078 not reconnected.
1079 For example, suppose you have three tasks named
1080 <filename>do_a</filename>, <filename>do_b</filename>, and
1081 <filename>do_c</filename>.
1082 Furthermore, <filename>do_c</filename> is dependent on
1083 <filename>do_b</filename>, which in turn is dependent on
1084 <filename>do_a</filename>.
1085 Given this scenario, if you use <filename>deltask</filename>
1086 to delete <filename>do_b</filename>, the implicit dependency
1087 relationship between <filename>do_c</filename> and
1088 <filename>do_a</filename> through <filename>do_b</filename>
1089 no longer exists, and <filename>do_c</filename> dependencies
1090 are not updated to include <filename>do_a</filename>.
1091 Thus, <filename>do_c</filename> is free to run before
1092 <filename>do_a</filename>.
1093 </para>
1094
1095 <para>
1096 If you want dependencies such as these to remain intact, use
1097 the <filename>noexec</filename> varflag to disable the task
1098 instead of using the <filename>deltask</filename> command to
1099 delete it:
1100 <literallayout class='monospaced'>
1101 do_b[noexec] = "1"
1102 </literallayout>
1103 </para>
1104 </section>
1105
1106 <section id='passing-information-into-the-build-task-environment'>
1107 <title>Passing Information Into the Build Task Environment</title>
1108
1109 <para>
1110 When running a task, BitBake tightly controls the execution
1111 environment of the build tasks to make
1112 sure unwanted contamination from the build machine cannot
1113 influence the build.
1114 Consequently, if you do want something to get passed into the
1115 build task environment, you must take these two steps:
1116 <orderedlist>
1117 <listitem><para>
1118 Tell BitBake to load what you want from the environment
1119 into the datastore.
1120 You can do so through the
1121 <link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>
1122 variable.
1123 For example, assume you want to prevent the build system from
1124 accessing your <filename>$HOME/.ccache</filename>
1125 directory.
1126 The following command tells BitBake to load
1127 <filename>CCACHE_DIR</filename> from the environment into
1128 the datastore:
1129 <literallayout class='monospaced'>
1130 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
1131 </literallayout></para></listitem>
1132 <listitem><para>
1133 Tell BitBake to export what you have loaded into the
1134 datastore to the task environment of every running task.
1135 Loading something from the environment into the datastore
1136 (previous step) only makes it available in the datastore.
1137 To export it to the task environment of every running task,
1138 use a command similar to the following in your local configuration
1139 file <filename>local.conf</filename> or your
1140 distribution configuration file:
1141 <literallayout class='monospaced'>
1142 export CCACHE_DIR
1143 </literallayout>
1144 <note>
1145 A side effect of the previous steps is that BitBake
1146 records the variable as a dependency of the build process
1147 in things like the setscene checksums.
1148 If doing so results in unnecessary rebuilds of tasks, you can
1149 whitelist the variable so that the setscene code
1150 ignores the dependency when it creates checksums.
1151 </note></para></listitem>
1152 </orderedlist>
1153 </para>
1154
1155 <para>
1156 Sometimes, it is useful to be able to obtain information
1157 from the original execution environment.
1158 Bitbake saves a copy of the original environment into
1159 a special variable named
1160 <link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link>.
1161 </para>
1162
1163 <para>
1164 The <filename>BB_ORIGENV</filename> variable returns a datastore
1165 object that can be queried using the standard datastore operators
1166 such as <filename>getVar(, False)</filename>.
1167 The datastore object is useful, for example, to find the original
1168 <filename>DISPLAY</filename> variable.
1169 Here is an example:
1170 <literallayout class='monospaced'>
1171 origenv = d.getVar("BB_ORIGENV", False)
1172 bar = origenv.getVar("BAR", False)
1173 </literallayout>
1174 The previous example returns <filename>BAR</filename> from the original
1175 execution environment.
1176 </para>
1177
1178 <para>
1179 By default, BitBake cleans the environment to include only those
1180 things exported or listed in its whitelist to ensure that the build
1181 environment is reproducible and consistent.
1182 </para>
1183 </section>
1184 </section>
1185
1186 <section id='variable-flags'>
1187 <title>Variable Flags</title>
1188
1189 <para>
1190 Variable flags (varflags) help control a task's functionality
1191 and dependencies.
1192 BitBake reads and writes varflags to the datastore using the following
1193 command forms:
1194 <literallayout class='monospaced'>
1195 <replaceable>variable</replaceable> = d.getVarFlags("<replaceable>variable</replaceable>")
1196 self.d.setVarFlags("FOO", {"func": True})
1197 </literallayout>
1198 </para>
1199
1200 <para>
1201 When working with varflags, the same syntax, with the exception of
1202 overrides, applies.
1203 In other words, you can set, append, and prepend varflags just like
1204 variables.
1205 See the
1206 "<link linkend='variable-flag-syntax'>Variable Flag Syntax</link>"
1207 section for details.
1208 </para>
1209
1210 <para>
1211 BitBake has a defined set of varflags available for recipes and
1212 classes.
1213 Tasks support a number of these flags which control various
1214 functionality of the task:
1215 <itemizedlist>
1216 <listitem><para><emphasis>cleandirs:</emphasis>
1217 Empty directories that should created before the task runs.
1218 </para></listitem>
1219 <listitem><para><emphasis>depends:</emphasis>
1220 Controls inter-task dependencies.
1221 See the
1222 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1223 variable and the
1224 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
1225 section for more information.
1226 </para></listitem>
1227 <listitem><para><emphasis>deptask:</emphasis>
1228 Controls task build-time dependencies.
1229 See the
1230 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1231 variable and the
1232 "<link linkend='build-dependencies'>Build Dependencies</link>"
1233 section for more information.
1234 </para></listitem>
1235 <listitem><para><emphasis>dirs:</emphasis>
1236 Directories that should be created before the task runs.
1237 </para></listitem>
1238 <listitem><para><emphasis>lockfiles:</emphasis>
1239 Specifies one or more lockfiles to lock while the task
1240 executes.
1241 Only one task may hold a lockfile, and any task that
1242 attempts to lock an already locked file will block until
1243 the lock is released.
1244 You can use this variable flag to accomplish mutual
1245 exclusion.
1246 </para></listitem>
1247 <listitem><para><emphasis>noexec:</emphasis>
1248 Marks the tasks as being empty and no execution required.
1249 The <filename>noexec</filename> flag can be used to set up
1250 tasks as dependency placeholders, or to disable tasks defined
1251 elsewhere that are not needed in a particular recipe.
1252 </para></listitem>
1253 <listitem><para><emphasis>nostamp:</emphasis>
1254 Tells BitBake to not generate a stamp file for a task,
1255 which implies the task should always be executed.
1256 </para></listitem>
1257 <listitem><para><emphasis>postfuncs:</emphasis>
1258 List of functions to call after the completion of the task.
1259 </para></listitem>
1260 <listitem><para><emphasis>prefuncs:</emphasis>
1261 List of functions to call before the task executes.
1262 </para></listitem>
1263 <listitem><para><emphasis>rdepends:</emphasis>
1264 Controls inter-task runtime dependencies.
1265 See the
1266 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1267 variable, the
1268 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1269 variable, and the
1270 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
1271 section for more information.
1272 </para></listitem>
1273 <listitem><para><emphasis>rdeptask:</emphasis>
1274 Controls task runtime dependencies.
1275 See the
1276 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1277 variable, the
1278 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1279 variable, and the
1280 "<link linkend='runtime-dependencies'>Runtime Dependencies</link>"
1281 section for more information.
1282 </para></listitem>
1283 <listitem><para><emphasis>recideptask:</emphasis>
1284 When set in conjunction with
1285 <filename>recrdeptask</filename>, specifies a task that
1286 should be inspected for additional dependencies.
1287 </para></listitem>
1288 <listitem><para><emphasis>recrdeptask:</emphasis>
1289 Controls task recursive runtime dependencies.
1290 See the
1291 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1292 variable, the
1293 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1294 variable, and the
1295 "<link linkend='recursive-dependencies'>Recursive Dependencies</link>"
1296 section for more information.
1297 </para></listitem>
1298 <listitem><para><emphasis>stamp-extra-info:</emphasis>
1299 Extra stamp information to append to the task's stamp.
1300 As an example, OpenEmbedded uses this flag to allow
1301 machine-specific tasks.
1302 </para></listitem>
1303 <listitem><para><emphasis>umask:</emphasis>
1304 The umask to run the task under.
1305 </para></listitem>
1306 </itemizedlist>
1307 </para>
1308
1309 <para>
1310 Several varflags are useful for controlling how signatures are
1311 calculated for variables.
1312 For more information on this process, see the
1313 "<link linkend='checksums'>Checksums (Signatures)</link>"
1314 section.
1315 <itemizedlist>
1316 <listitem><para><emphasis>vardeps:</emphasis>
1317 Specifies a space-separated list of additional
1318 variables to add to a variable's dependencies
1319 for the purposes of calculating its signature.
1320 Adding variables to this list is useful, for example, when
1321 a function refers to a variable in a manner that
1322 does not allow BitBake to automatically determine
1323 that the variable is referred to.
1324 </para></listitem>
1325 <listitem><para><emphasis>vardepsexclude:</emphasis>
1326 Specifies a space-separated list of variables
1327 that should be excluded from a variable's dependencies
1328 for the purposes of calculating its signature.
1329 </para></listitem>
1330 <listitem><para><emphasis>vardepvalue:</emphasis>
1331 If set, instructs BitBake to ignore the actual
1332 value of the variable and instead use the specified
1333 value when calculating the variable's signature.
1334 </para></listitem>
1335 <listitem><para><emphasis>vardepvalueexclude:</emphasis>
1336 Specifies a pipe-separated list of strings to exclude
1337 from the variable's value when calculating the
1338 variable's signature.
1339 </para></listitem>
1340 </itemizedlist>
1341 </para>
1342 </section>
1343
1344 <section id='events'>
1345 <title>Events</title>
1346
1347 <para>
1348 BitBake allows installation of event handlers within
1349 recipe and class files.
1350 Events are triggered at certain points during operation,
1351 such as the beginning of an operation against a given recipe
1352 (<filename>*.bb</filename> file), the start of a given task,
1353 task failure, task success, and so forth.
1354 The intent is to make it easy to do things like email
1355 notification on build failure.
1356 </para>
1357
1358 <para>
1359 Following is an example event handler that
1360 prints the name of the event and the content of
1361 the <filename>FILE</filename> variable:
1362 <literallayout class='monospaced'>
1363 addhandler myclass_eventhandler
1364 python myclass_eventhandler() {
1365 from bb.event import getName
1366 from bb import data
1367 print("The name of the Event is %s" % getName(e))
1368 print("The file we run for is %s" % data.getVar('FILE', e.data, True))
1369 }
1370 </literallayout>
1371 This event handler gets called every time an event is
1372 triggered.
1373 A global variable "<filename>e</filename>" is defined and
1374 "<filename>e.data</filename>" contains an instance of
1375 "<filename>bb.data</filename>".
1376 With the <filename>getName(e)</filename> method, one can get
1377 the name of the triggered event.
1378 </para>
1379
1380 <para>
1381 Because you probably are only interested in a subset of events,
1382 you would likely use the <filename>[eventmask]</filename> flag
1383 for your event handler to be sure that only certain events
1384 trigger the handler.
1385 Given the previous example, suppose you only wanted the
1386 <filename>bb.build.TaskFailed</filename> event to trigger that
1387 event handler.
1388 Use the flag as follows:
1389 <literallayout class='monospaced'>
1390 addhandler myclass_eventhandler
1391 myclass_eventhandler[eventmask] = "bb.build.TaskFailed"
1392 python myclass_eventhandler() {
1393 from bb.event import getName
1394 from bb import data
1395 print("The name of the Event is %s" % getName(e))
1396 print("The file we run for is %s" % data.getVar('FILE', e.data, True))
1397 }
1398 </literallayout>
1399 </para>
1400
1401 <para>
1402 During a standard build, the following common events might occur:
1403 <itemizedlist>
1404 <listitem><para>
1405 <filename>bb.event.ConfigParsed()</filename>
1406 </para></listitem>
1407 <listitem><para>
1408 <filename>bb.event.ParseStarted()</filename>
1409 </para></listitem>
1410 <listitem><para>
1411 <filename>bb.event.ParseProgress()</filename>
1412 </para></listitem>
1413 <listitem><para>
1414 <filename>bb.event.ParseCompleted()</filename>
1415 </para></listitem>
1416 <listitem><para>
1417 <filename>bb.event.BuildStarted()</filename>
1418 </para></listitem>
1419 <listitem><para>
1420 <filename>bb.build.TaskStarted()</filename>
1421 </para></listitem>
1422 <listitem><para>
1423 <filename>bb.build.TaskInvalid()</filename>
1424 </para></listitem>
1425 <listitem><para>
1426 <filename>bb.build.TaskFailedSilent()</filename>
1427 </para></listitem>
1428 <listitem><para>
1429 <filename>bb.build.TaskFailed()</filename>
1430 </para></listitem>
1431 <listitem><para>
1432 <filename>bb.build.TaskSucceeded()</filename>
1433 </para></listitem>
1434 <listitem><para>
1435 <filename>bb.event.BuildCompleted()</filename>
1436 </para></listitem>
1437 <listitem><para>
1438 <filename>bb.cooker.CookerExit()</filename>
1439 </para></listitem>
1440 </itemizedlist>
1441 Here is a list of other events that occur based on specific requests
1442 to the server:
1443 <itemizedlist>
1444 <listitem><para>
1445 <filename>bb.event.TreeDataPreparationStarted()</filename>
1446 </para></listitem>
1447 <listitem><para>
1448 <filename>bb.event.TreeDataPreparationProgress</filename>
1449 </para></listitem>
1450 <listitem><para>
1451 <filename>bb.event.TreeDataPreparationCompleted</filename>
1452 </para></listitem>
1453 <listitem><para>
1454 <filename>bb.event.DepTreeGenerated</filename>
1455 </para></listitem>
1456 <listitem><para>
1457 <filename>bb.event.CoreBaseFilesFound</filename>
1458 </para></listitem>
1459 <listitem><para>
1460 <filename>bb.event.ConfigFilePathFound</filename>
1461 </para></listitem>
1462 <listitem><para>
1463 <filename>bb.event.FilesMatchingFound</filename>
1464 </para></listitem>
1465 <listitem><para>
1466 <filename>bb.event.ConfigFilesFound</filename>
1467 </para></listitem>
1468 <listitem><para>
1469 <filename>bb.event.TargetsTreeGenerated</filename>
1470 </para></listitem>
1471 </itemizedlist>
1472 </para>
1473 </section>
1474
1475 <section id='variants-class-extension-mechanism'>
1476 <title>Variants - Class Extension Mechanism</title>
1477
1478 <para>
1479 BitBake supports two features that facilitate creating
1480 from a single recipe file multiple incarnations of that
1481 recipe file where all incarnations are buildable.
1482 These features are enabled through the
1483 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
1484 and
1485 <link linkend='var-BBVERSIONS'><filename>BBVERSIONS</filename></link>
1486 variables.
1487 <note>
1488 The mechanism for this class extension is extremely
1489 specific to the implementation.
1490 Usually, the recipe's
1491 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>,
1492 <link linkend='var-PN'><filename>PN</filename></link>, and
1493 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1494 variables would need to be modified by the extension class.
1495 For specific examples, see the OE-Core
1496 <filename>native</filename>, <filename>nativesdk</filename>,
1497 and <filename>multilib</filename> classes.
1498 </note>
1499 <itemizedlist>
1500 <listitem><para><emphasis><filename>BBCLASSEXTEND</filename>:</emphasis>
1501 This variable is a space separated list of classes used to "extend" the
1502 recipe for each variant.
1503 Here is an example that results in a second incarnation of the current
1504 recipe being available.
1505 This second incarnation will have the "native" class inherited.
1506 <literallayout class='monospaced'>
1507 BBCLASSEXTEND = "native"
1508 </literallayout></para></listitem>
1509 <listitem><para><emphasis><filename>BBVERSIONS</filename>:</emphasis>
1510 This variable allows a single recipe to build multiple versions of a
1511 project from a single recipe file.
1512 You can also specify conditional metadata
1513 (using the
1514 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1515 mechanism) for a single version, or an optionally named range of versions.
1516 Here is an example:
1517 <literallayout class='monospaced'>
1518 BBVERSIONS = "1.0 2.0 git"
1519 SRC_URI_git = "git://someurl/somepath.git"
1520
1521 BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 1.0.[7-9]:1.0.7+"
1522 SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"
1523 </literallayout>
1524 The name of the range defaults to the original version of the
1525 recipe.
1526 For example, in OpenEmbedded, the recipe file
1527 <filename>foo_1.0.0+.bb</filename> creates a default name range
1528 of <filename>1.0.0+</filename>.
1529 This is useful because the range name is not only placed
1530 into overrides, but it is also made available for the metadata to use
1531 in the variable that defines the base recipe versions for use in
1532 <filename>file://</filename> search paths
1533 (<link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>).
1534 </para></listitem>
1535 </itemizedlist>
1536 </para>
1537 </section>
1538
1539 <section id='dependencies'>
1540 <title>Dependencies</title>
1541
1542 <para>
1543 To allow for efficient operation given multiple processes
1544 executing in parallel, BitBake handles dependencies at
1545 the task level.
1546 BitBake supports a robust method to handle these dependencies.
1547 </para>
1548
1549 <para>
1550 This section describes several types of dependency mechanisms.
1551 </para>
1552
1553 <section id='dependencies-internal-to-the-bb-file'>
1554 <title>Dependencies Internal to the <filename>.bb</filename> File</title>
1555
1556 <para>
1557 BitBake uses the <filename>addtask</filename> directive
1558 to manage dependencies that are internal to a given recipe
1559 file.
1560 You can use the <filename>addtask</filename> directive to
1561 indicate when a task is dependent on other tasks or when
1562 other tasks depend on that recipe.
1563 Here is an example:
1564 <literallayout class='monospaced'>
1565 addtask printdate after do_fetch before do_build
1566 </literallayout>
1567 In this example, the <filename>printdate</filename> task is
1568 depends on the completion of the <filename>do_fetch</filename>
1569 task.
1570 And, the <filename>do_build</filename> depends on the completion
1571 of the <filename>printdate</filename> task.
1572 </para>
1573 </section>
1574
1575 <section id='build-dependencies'>
1576 <title>Build Dependencies</title>
1577
1578 <para>
1579 BitBake uses the
1580 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1581 variable to manage build time dependencies.
1582 The "deptask" varflag for tasks signifies the task of each
1583 item listed in <filename>DEPENDS</filename> that must
1584 complete before that task can be executed.
1585 Here is an example:
1586 <literallayout class='monospaced'>
1587 do_configure[deptask] = "do_populate_sysroot"
1588 </literallayout>
1589 In this example, the <filename>do_populate_sysroot</filename>
1590 task of each item in <filename>DEPENDS</filename> must complete before
1591 <filename>do_configure</filename> can execute.
1592 </para>
1593 </section>
1594
1595 <section id='runtime-dependencies'>
1596 <title>Runtime Dependencies</title>
1597
1598 <para>
1599 BitBake uses the
1600 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>,
1601 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>, and
1602 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1603 variables to manage runtime dependencies.
1604 </para>
1605
1606 <para>
1607 The <filename>PACKAGES</filename> variable lists runtime
1608 packages.
1609 Each of those packages can have <filename>RDEPENDS</filename> and
1610 <filename>RRECOMMENDS</filename> runtime dependencies.
1611 The "rdeptask" flag for tasks is used to signify the task of each
1612 item runtime dependency which must have completed before that
1613 task can be executed.
1614 <literallayout class='monospaced'>
1615 do_package_qa[rdeptask] = "do_packagedata"
1616 </literallayout>
1617 In the previous example, the <filename>do_packagedata</filename>
1618 task of each item in <filename>RDEPENDS</filename> must have
1619 completed before <filename>do_package_qa</filename> can execute.
1620 </para>
1621 </section>
1622
1623 <section id='recursive-dependencies'>
1624 <title>Recursive Dependencies</title>
1625
1626 <para>
1627 BitBake uses the "recrdeptask" flag to manage
1628 recursive task dependencies.
1629 BitBake looks through the build-time and runtime
1630 dependencies of the current recipe, looks through
1631 the task's inter-task
1632 dependencies, and then adds dependencies for the
1633 listed task.
1634 Once BitBake has accomplished this, it recursively works through
1635 the dependencies of those tasks.
1636 Iterative passes continue until all dependencies are discovered
1637 and added.
1638 </para>
1639
1640 <para>
1641 You might want to not only have BitBake look for
1642 dependencies of those tasks, but also have BitBake look
1643 for build-time and runtime dependencies of the dependent
1644 tasks as well.
1645 If that is the case, you need to reference the task name
1646 itself in the task list:
1647 <literallayout class='monospaced'>
1648 do_a[recrdeptask] = "do_a do_b"
1649 </literallayout>
1650 </para>
1651 </section>
1652
1653 <section id='inter-task-dependencies'>
1654 <title>Inter-Task Dependencies</title>
1655
1656 <para>
1657 BitBake uses the "depends" flag in a more generic form
1658 to manage inter-task dependencies.
1659 This more generic form allows for inter-dependency
1660 checks for specific tasks rather than checks for
1661 the data in <filename>DEPENDS</filename>.
1662 Here is an example:
1663 <literallayout class='monospaced'>
1664 do_patch[depends] = "quilt-native:do_populate_sysroot"
1665 </literallayout>
1666 In this example, the <filename>do_populate_sysroot</filename>
1667 task of the target <filename>quilt-native</filename>
1668 must have completed before the
1669 <filename>do_patch</filename> task can execute.
1670 </para>
1671
1672 <para>
1673 The "rdepends" flag works in a similar way but takes targets
1674 in the runtime namespace instead of the build-time dependency
1675 namespace.
1676 </para>
1677 </section>
1678 </section>
1679
1680 <section id='accessing-datastore-variables-using-python'>
1681 <title>Accessing Datastore Variables Using Python</title>
1682
1683 <para>
1684 It is often necessary to access variables in the
1685 BitBake datastore using Python functions.
1686 The Bitbake datastore has an API that allows you this
1687 access.
1688 Here is a list of available operations:
1689 </para>
1690
1691 <para>
1692 <informaltable frame='none'>
1693 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
1694 <colspec colname='c1' colwidth='1*'/>
1695 <colspec colname='c2' colwidth='1*'/>
1696 <thead>
1697 <row>
1698 <entry align="left"><emphasis>Operation</emphasis></entry>
1699 <entry align="left"><emphasis>Description</emphasis></entry>
1700 </row>
1701 </thead>
1702 <tbody>
1703 <row>
1704 <entry align="left"><filename>d.getVar("X", expand=False)</filename></entry>
1705 <entry align="left">Returns the value of variable "X".
1706 Using "expand=True" expands the value.</entry>
1707 </row>
1708 <row>
1709 <entry align="left"><filename>d.setVar("X", "value")</filename></entry>
1710 <entry align="left">Sets the variable "X" to "value".</entry>
1711 </row>
1712 <row>
1713 <entry align="left"><filename>d.appendVar("X", "value")</filename></entry>
1714 <entry align="left">Adds "value" to the end of the variable "X".</entry>
1715 </row>
1716 <row>
1717 <entry align="left"><filename>d.prependVar("X", "value")</filename></entry>
1718 <entry align="left">Adds "value" to the start of the variable "X".</entry>
1719 </row>
1720 <row>
1721 <entry align="left"><filename>d.delVar("X")</filename></entry>
1722 <entry align="left">Deletes the variable "X" from the datastore.</entry>
1723 </row>
1724 <row>
1725 <entry align="left"><filename>d.renameVar("X", "Y")</filename></entry>
1726 <entry align="left">Renames the variable "X" to "Y".</entry>
1727 </row>
1728 <row>
1729 <entry align="left"><filename>d.getVarFlag("X", flag, expand=False)</filename></entry>
1730 <entry align="left">Gets then named flag from the variable "X".
1731 Using "expand=True" expands the named flag.</entry>
1732 </row>
1733 <row>
1734 <entry align="left"><filename>d.setVarFlag("X", flag, "value")</filename></entry>
1735 <entry align="left">Sets the named flag for variable "X" to "value".</entry>
1736 </row>
1737 <row>
1738 <entry align="left"><filename>d.appendVarFlag("X", flag, "value")</filename></entry>
1739 <entry align="left">Appends "value" to the named flag on the
1740 variable "X".</entry>
1741 </row>
1742 <row>
1743 <entry align="left"><filename>d.prependVarFlag("X", flag, "value")</filename></entry>
1744 <entry align="left">Prepends "value" to the named flag on
1745 the variable "X".</entry>
1746 </row>
1747 <row>
1748 <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry>
1749 <entry align="left">Deletes the named flag on the variable
1750 "X" from the datastore.</entry>
1751 </row>
1752 <row>
1753 <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry>
1754 <entry align="left">Sets the flags specified in
1755 the <filename>flagsdict()</filename> parameter.
1756 <filename>setVarFlags</filename> does not clear previous flags.
1757 Think of this operation as <filename>addVarFlags</filename>.</entry>
1758 </row>
1759 <row>
1760 <entry align="left"><filename>d.getVarFlags("X")</filename></entry>
1761 <entry align="left">Returns a <filename>flagsdict</filename> of the flags for
1762 the variable "X".</entry>
1763 </row>
1764 <row>
1765 <entry align="left"><filename>d.delVarFlags("X")</filename></entry>
1766 <entry align="left">Deletes all the flags for the variable "X".</entry>
1767 </row>
1768 </tbody>
1769 </tgroup>
1770 </informaltable>
1771 </para>
1772 </section>
1773
1774 <section id='task-checksums-and-setscene'>
1775 <title>Task Checksums and Setscene</title>
1776
1777 <para>
1778 BitBake uses checksums (or signatures) along with the setscene
1779 to determine if a task needs to be run.
1780 This section describes the process.
1781 To help understand how BitBake does this, the section assumes an
1782 OpenEmbedded metadata-based example.
1783 </para>
1784
1785 <para>
1786 This list is a place holder of content existed from previous work
1787 on the manual.
1788 Some or all of it probably needs integrated into the subsections
1789 that make up this section.
1790 For now, I have just provided a short glossary-like description
1791 for each variable.
1792 Ultimately, this list goes away.
1793 <itemizedlist>
1794 <listitem><para><filename>STAMP</filename>:
1795 The base path to create stamp files.</para></listitem>
1796 <listitem><para><filename>STAMPCLEAN</filename>
1797 Again, the base path to create stamp files but can use wildcards
1798 for matching a range of files for clean operations.
1799 </para></listitem>
1800 <listitem><para><filename>BB_STAMP_WHITELIST</filename>
1801 Lists stamp files that are looked at when the stamp policy
1802 is "whitelist".
1803 </para></listitem>
1804 <listitem><para><filename>BB_STAMP_POLICY</filename>
1805 Defines the mode for comparing timestamps of stamp files.
1806 </para></listitem>
1807 <listitem><para><filename>BB_HASHCHECK_FUNCTION</filename>
1808 Specifies the name of the function to call during
1809 the "setscene" part of the task's execution in order
1810 to validate the list of task hashes.
1811 </para></listitem>
1812 <listitem><para><filename>BB_SETSCENE_VERIFY_FUNCTION</filename>
1813 Specifies a function to call that verifies the list of
1814 planned task execution before the main task execution
1815 happens.
1816 </para></listitem>
1817 <listitem><para><filename>BB_SETSCENE_DEPVALID</filename>
1818 Specifies a function BitBake calls that determines
1819 whether BitBake requires a setscene dependency to
1820 be met.
1821 </para></listitem>
1822 <listitem><para><filename>BB_TASKHASH</filename>
1823 Within an executing task, this variable holds the hash
1824 of the task as returned by the currently enabled
1825 signature generator.
1826 </para></listitem>
1827 </itemizedlist>
1828 </para>
1829 </section>
1830</chapter>