summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
diff options
context:
space:
mode:
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.xml1790
1 files changed, 1790 insertions, 0 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
new file mode 100644
index 0000000000..0dd543bcc0
--- /dev/null
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -0,0 +1,1790 @@
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 </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'),d)[0] or 'defaultpkgname'}"
331 PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE'),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 &lt;classname&gt;_&lt;functionname&gt;
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 &lt;functionname&gt;
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, tasks can also be deleted.
1069 This is done simply with <filename>deltask</filename> command.
1070 For example, to delete the example task used in the previous
1071 sections, you would use:
1072 <literallayout class='monospaced'>
1073 deltask printdate
1074 </literallayout>
1075 </para>
1076 </section>
1077
1078 <section id='passing-information-into-the-build-task-environment'>
1079 <title>Passing Information Into the Build Task Environment</title>
1080
1081 <para>
1082 When running a task, BitBake tightly controls the execution
1083 environment of the build tasks to make
1084 sure unwanted contamination from the build machine cannot
1085 influence the build.
1086 Consequently, if you do want something to get passed into the
1087 build task environment, you must take these two steps:
1088 <orderedlist>
1089 <listitem><para>
1090 Tell BitBake to load what you want from the environment
1091 into the datastore.
1092 You can do so through the
1093 <link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>
1094 variable.
1095 For example, assume you want to prevent the build system from
1096 accessing your <filename>$HOME/.ccache</filename>
1097 directory.
1098 The following command tells BitBake to load
1099 <filename>CCACHE_DIR</filename> from the environment into
1100 the datastore:
1101 <literallayout class='monospaced'>
1102 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
1103 </literallayout></para></listitem>
1104 <listitem><para>
1105 Tell BitBake to export what you have loaded into the
1106 datastore to the task environment of every running task.
1107 Loading something from the environment into the datastore
1108 (previous step) only makes it available in the datastore.
1109 To export it to the task environment of every running task,
1110 use a command similar to the following in your local configuration
1111 file <filename>local.conf</filename> or your
1112 distribution configuration file:
1113 <literallayout class='monospaced'>
1114 export CCACHE_DIR
1115 </literallayout>
1116 <note>
1117 A side effect of the previous steps is that BitBake
1118 records the variable as a dependency of the build process
1119 in things like the setscene checksums.
1120 If doing so results in unnecessary rebuilds of tasks, you can
1121 whitelist the variable so that the setscene code
1122 ignores the dependency when it creates checksums.
1123 </note></para></listitem>
1124 </orderedlist>
1125 </para>
1126
1127 <para>
1128 Sometimes, it is useful to be able to obtain information
1129 from the original execution environment.
1130 Bitbake saves a copy of the original environment into
1131 a special variable named
1132 <link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link>.
1133 </para>
1134
1135 <para>
1136 The <filename>BB_ORIGENV</filename> variable returns a datastore
1137 object that can be queried using the standard datastore operators
1138 such as <filename>getVar()</filename>.
1139 The datastore object is useful, for example, to find the original
1140 <filename>DISPLAY</filename> variable.
1141 Here is an example:
1142 <literallayout class='monospaced'>
1143 BB_ORIGENV - add example?
1144
1145 origenv = d.getVar("BB_ORIGENV", False)
1146 bar = origenv.getVar("BAR", False)
1147 </literallayout>
1148 The previous example returns <filename>BAR</filename> from the original
1149 execution environment.
1150 </para>
1151
1152 <para>
1153 By default, BitBake cleans the environment to include only those
1154 things exported or listed in its whitelist to ensure that the build
1155 environment is reproducible and consistent.
1156 </para>
1157 </section>
1158 </section>
1159
1160 <section id='variable-flags'>
1161 <title>Variable Flags</title>
1162
1163 <para>
1164 Variable flags (varflags) help control a task's functionality
1165 and dependencies.
1166 BitBake reads and writes varflags to the datastore using the following
1167 command forms:
1168 <literallayout class='monospaced'>
1169 &lt;variable&gt; = d.getVarFlags("&lt;variable&gt;")
1170 self.d.setVarFlags("FOO", {"func": True})
1171 </literallayout>
1172 </para>
1173
1174 <para>
1175 When working with varflags, the same syntax, with the exception of
1176 overrides, applies.
1177 In other words, you can set, append, and prepend varflags just like
1178 variables.
1179 See the
1180 "<link linkend='variable-flag-syntax'>Variable Flag Syntax</link>"
1181 section for details.
1182 </para>
1183
1184 <para>
1185 BitBake has a defined set of varflags available for recipes and
1186 classes.
1187 Tasks support a number of these flags which control various
1188 functionality of the task:
1189 <itemizedlist>
1190 <listitem><para><emphasis>dirs:</emphasis>
1191 Directories that should be created before the task runs.
1192 </para></listitem>
1193 <listitem><para><emphasis>cleandirs:</emphasis>
1194 Empty directories that should created before the task runs.
1195 </para></listitem>
1196 <listitem><para><emphasis>noexec:</emphasis>
1197 Marks the tasks as being empty and no execution required.
1198 The <filename>noexec</filename> flag can be used to set up
1199 tasks as dependency placeholders, or to disable tasks defined
1200 elsewhere that are not needed in a particular recipe.
1201 </para></listitem>
1202 <listitem><para><emphasis>nostamp:</emphasis>
1203 Tells BitBake to not generate a stamp file for a task,
1204 which implies the task should always be executed.
1205 </para></listitem>
1206 <listitem><para><emphasis>umask:</emphasis>
1207 The umask to run the task under.
1208 </para></listitem>
1209 <listitem><para><emphasis>deptask:</emphasis>
1210 Controls task build-time dependencies.
1211 See the
1212 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1213 variable and the
1214 "<link linkend='build-dependencies'>Build Dependencies</link>"
1215 section for more information.
1216 </para></listitem>
1217 <listitem><para><emphasis>rdeptask:</emphasis>
1218 Controls task runtime dependencies.
1219 See the
1220 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1221 variable, the
1222 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1223 variable, and the
1224 "<link linkend='runtime-dependencies'>Runtime Dependencies</link>"
1225 section for more information.
1226 </para></listitem>
1227 <listitem><para><emphasis>recrdeptask:</emphasis>
1228 Controls task recursive runtime dependencies.
1229 See the
1230 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1231 variable, the
1232 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1233 variable, and the
1234 "<link linkend='recursive-dependencies'>Recursive Dependencies</link>"
1235 section for more information.
1236 </para></listitem>
1237 <listitem><para><emphasis>depends:</emphasis>
1238 Controls inter-task dependencies.
1239 See the
1240 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1241 variable and the
1242 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
1243 section for more information.
1244 </para></listitem>
1245 <listitem><para><emphasis>rdepends:</emphasis>
1246 Controls inter-task runtime dependencies.
1247 See the
1248 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1249 variable, the
1250 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1251 variable, and the
1252 "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>"
1253 section for more information.
1254 </para></listitem>
1255 <listitem><para><emphasis>postfuncs:</emphasis>
1256 List of functions to call after the completion of the task.
1257 </para></listitem>
1258 <listitem><para><emphasis>prefuncs:</emphasis>
1259 List of functions to call before the task executes.
1260 </para></listitem>
1261 <listitem><para><emphasis>stamp-extra-info:</emphasis>
1262 Extra stamp information to append to the task's stamp.
1263 As an example, OpenEmbedded uses this flag to allow
1264 machine-specific tasks.
1265 </para></listitem>
1266 </itemizedlist>
1267 </para>
1268
1269 <para>
1270 Several varflags are useful for controlling how signatures are
1271 calculated for variables.
1272 For more information on this process, see the
1273 "<link linkend='checksums'>Checksums (Signatures)</link>"
1274 section.
1275 <itemizedlist>
1276 <listitem><para><emphasis>vardeps:</emphasis>
1277 Specifies a space-separated list of additional
1278 variables to add to a variable's dependencies
1279 for the purposes of calculating its signature.
1280 Adding variables to this list is useful, for example, when
1281 a function refers to a variable in a manner that
1282 does not allow BitBake to automatically determine
1283 that the variable is referred to.
1284 </para></listitem>
1285 <listitem><para><emphasis>vardepvalue:</emphasis>
1286 If set, instructs BitBake to ignore the actual
1287 value of the variable and instead use the specified
1288 value when calculating the variable's signature.
1289 </para></listitem>
1290 <listitem><para><emphasis>vardepsexclude:</emphasis>
1291 Specifies a space-separated list of variables
1292 that should be excluded from a variable's dependencies
1293 for the purposes of calculating its signature.
1294 </para></listitem>
1295 <listitem><para><emphasis>vardepvalueexclude:</emphasis>
1296 Specifies a pipe-separated list of strings to exclude
1297 from the variable's value when calculating the
1298 variable's signature.
1299 </para></listitem>
1300 </itemizedlist>
1301 </para>
1302 </section>
1303
1304 <section id='events'>
1305 <title>Events</title>
1306
1307 <para>
1308 BitBake allows installation of event handlers within
1309 recipe and class files.
1310 Events are triggered at certain points during operation,
1311 such as the beginning of an operation against a given recipe
1312 (<filename>*.bb</filename> file), the start of a given task,
1313 task failure, task success, and so forth.
1314 The intent is to make it easy to do things like email
1315 notification on build failure.
1316 </para>
1317
1318 <para>
1319 Following is an example event handler that
1320 prints the name of the event and the content of
1321 the <filename>FILE</filename> variable:
1322 <literallayout class='monospaced'>
1323 addhandler myclass_eventhandler
1324 python myclass_eventhandler() {
1325 from bb.event import getName
1326 from bb import data
1327 print("The name of the Event is %s" % getName(e))
1328 print("The file we run for is %s" % data.getVar('FILE', e.data, True))
1329 }
1330 </literallayout>
1331 This event handler gets called every time an event is
1332 triggered.
1333 A global variable "<filename>e</filename>" is defined and
1334 "<filename>e.data</filename>" contains an instance of
1335 "<filename>bb.data</filename>".
1336 With the <filename>getName(e)</filename> method, one can get
1337 the name of the triggered event.
1338 </para>
1339
1340 <para>
1341 Because you probably are only interested in a subset of events,
1342 you would likely use the <filename>[eventmask]</filename> flag
1343 for your event handler to be sure that only certain events
1344 trigger the handler.
1345 Given the previous example, suppose you only wanted the
1346 <filename>bb.build.TaskFailed</filename> event to trigger that
1347 event handler.
1348 Use the flag as follows:
1349 <literallayout class='monospaced'>
1350 addhandler myclass_eventhandler
1351 myclass_eventhandler[eventmask] = "bb.build.TaskFailed"
1352 python myclass_eventhandler() {
1353 from bb.event import getName
1354 from bb import data
1355 print("The name of the Event is %s" % getName(e))
1356 print("The file we run for is %s" % data.getVar('FILE', e.data, True))
1357 }
1358 </literallayout>
1359 </para>
1360
1361 <para>
1362 During a standard build, the following common events might occur:
1363 <itemizedlist>
1364 <listitem><para>
1365 <filename>bb.event.ConfigParsed()</filename>
1366 </para></listitem>
1367 <listitem><para>
1368 <filename>bb.event.ParseStarted()</filename>
1369 </para></listitem>
1370 <listitem><para>
1371 <filename>bb.event.ParseProgress()</filename>
1372 </para></listitem>
1373 <listitem><para>
1374 <filename>bb.event.ParseCompleted()</filename>
1375 </para></listitem>
1376 <listitem><para>
1377 <filename>bb.event.BuildStarted()</filename>
1378 </para></listitem>
1379 <listitem><para>
1380 <filename>bb.build.TaskStarted()</filename>
1381 </para></listitem>
1382 <listitem><para>
1383 <filename>bb.build.TaskInvalid()</filename>
1384 </para></listitem>
1385 <listitem><para>
1386 <filename>bb.build.TaskFailedSilent()</filename>
1387 </para></listitem>
1388 <listitem><para>
1389 <filename>bb.build.TaskFailed()</filename>
1390 </para></listitem>
1391 <listitem><para>
1392 <filename>bb.build.TaskSucceeded()</filename>
1393 </para></listitem>
1394 <listitem><para>
1395 <filename>bb.event.BuildCompleted()</filename>
1396 </para></listitem>
1397 <listitem><para>
1398 <filename>bb.cooker.CookerExit()</filename>
1399 </para></listitem>
1400 </itemizedlist>
1401 Here is a list of other events that occur based on specific requests
1402 to the server:
1403 <itemizedlist>
1404 <listitem><para>
1405 <filename>bb.event.TreeDataPreparationStarted()</filename>
1406 </para></listitem>
1407 <listitem><para>
1408 <filename>bb.event.TreeDataPreparationProgress</filename>
1409 </para></listitem>
1410 <listitem><para>
1411 <filename>bb.event.TreeDataPreparationCompleted</filename>
1412 </para></listitem>
1413 <listitem><para>
1414 <filename>bb.event.DepTreeGenerated</filename>
1415 </para></listitem>
1416 <listitem><para>
1417 <filename>bb.event.CoreBaseFilesFound</filename>
1418 </para></listitem>
1419 <listitem><para>
1420 <filename>bb.event.ConfigFilePathFound</filename>
1421 </para></listitem>
1422 <listitem><para>
1423 <filename>bb.event.FilesMatchingFound</filename>
1424 </para></listitem>
1425 <listitem><para>
1426 <filename>bb.event.ConfigFilesFound</filename>
1427 </para></listitem>
1428 <listitem><para>
1429 <filename>bb.event.TargetsTreeGenerated</filename>
1430 </para></listitem>
1431 </itemizedlist>
1432 </para>
1433 </section>
1434
1435 <section id='variants-class-extension-mechanism'>
1436 <title>Variants - Class Extension Mechanism</title>
1437
1438 <para>
1439 BitBake supports two features that facilitate creating
1440 from a single recipe file multiple incarnations of that
1441 recipe file where all incarnations are buildable.
1442 These features are enabled through the
1443 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
1444 and
1445 <link linkend='var-BBVERSIONS'><filename>BBVERSIONS</filename></link>
1446 variables.
1447 <note>
1448 The mechanism for this class extension is extremely
1449 specific to the implementation.
1450 Usually, the recipe's
1451 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>,
1452 <link linkend='var-PN'><filename>PN</filename></link>, and
1453 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1454 variables would need to be modified by the extension class.
1455 For specific examples, see the OE-Core
1456 <filename>native</filename>, <filename>nativesdk</filename>,
1457 and <filename>multilib</filename> classes.
1458 </note>
1459 <itemizedlist>
1460 <listitem><para><emphasis><filename>BBCLASSEXTEND</filename>:</emphasis>
1461 This variable is a space separated list of classes used to "extend" the
1462 recipe for each variant.
1463 Here is an example that results in a second incarnation of the current
1464 recipe being available.
1465 This second incarnation will have the "native" class inherited.
1466 <literallayout class='monospaced'>
1467 BBCLASSEXTEND = "native"
1468 </literallayout></para></listitem>
1469 <listitem><para><emphasis><filename>BBVERSIONS</filename>:</emphasis>
1470 This variable allows a single recipe to build multiple versions of a
1471 project from a single recipe file.
1472 You can also specify conditional metadata
1473 (using the
1474 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
1475 mechanism) for a single version, or an optionally named range of versions.
1476 Here is an example:
1477 <literallayout class='monospaced'>
1478 BBVERSIONS = "1.0 2.0 git"
1479 SRC_URI_git = "git://someurl/somepath.git"
1480
1481 BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 1.0.[7-9]:1.0.7+"
1482 SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"
1483 </literallayout>
1484 The name of the range defaults to the original version of the
1485 recipe.
1486 For example, in OpenEmbedded, the recipe file
1487 <filename>foo_1.0.0+.bb</filename> creates a default name range
1488 of <filename>1.0.0+</filename>.
1489 This is useful because the range name is not only placed
1490 into overrides, but it is also made available for the metadata to use
1491 in the variable that defines the base recipe versions for use in
1492 <filename>file://</filename> search paths
1493 (<link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>).
1494 </para></listitem>
1495 </itemizedlist>
1496 </para>
1497 </section>
1498
1499 <section id='dependencies'>
1500 <title>Dependencies</title>
1501
1502 <para>
1503 To allow for efficient operation given multiple processes
1504 executing in parallel, BitBake handles dependencies at
1505 the task level.
1506 BitBake supports a robust method to handle these dependencies.
1507 </para>
1508
1509 <para>
1510 This section describes several types of dependency mechanisms.
1511 </para>
1512
1513 <section id='dependencies-internal-to-the-bb-file'>
1514 <title>Dependencies Internal to the <filename>.bb</filename> File</title>
1515
1516 <para>
1517 BitBake uses the <filename>addtask</filename> directive
1518 to manage dependencies that are internal to a given recipe
1519 file.
1520 You can use the <filename>addtask</filename> directive to
1521 indicate when a task is dependent on other tasks or when
1522 other tasks depend on that recipe.
1523 Here is an example:
1524 <literallayout class='monospaced'>
1525 addtask printdate after do_fetch before do_build
1526 </literallayout>
1527 In this example, the <filename>printdate</filename> task is
1528 depends on the completion of the <filename>do_fetch</filename>
1529 task.
1530 And, the <filename>do_build</filename> depends on the completion
1531 of the <filename>printdate</filename> task.
1532 </para>
1533 </section>
1534
1535 <section id='build-dependencies'>
1536 <title>Build Dependencies</title>
1537
1538 <para>
1539 BitBake uses the
1540 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1541 variable to manage build time dependencies.
1542 The "deptask" varflag for tasks signifies the task of each
1543 item listed in <filename>DEPENDS</filename> that must
1544 complete before that task can be executed.
1545 Here is an example:
1546 <literallayout class='monospaced'>
1547 do_configure[deptask] = "do_populate_sysroot"
1548 </literallayout>
1549 In this example, the <filename>do_populate_sysroot</filename>
1550 task of each item in <filename>DEPENDS</filename> must complete before
1551 <filename>do_configure</filename> can execute.
1552 </para>
1553 </section>
1554
1555 <section id='runtime-dependencies'>
1556 <title>Runtime Dependencies</title>
1557
1558 <para>
1559 BitBake uses the
1560 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>,
1561 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>, and
1562 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
1563 variables to manage runtime dependencies.
1564 </para>
1565
1566 <para>
1567 The <filename>PACKAGES</filename> variable lists runtime
1568 packages.
1569 Each of those packages can have <filename>RDEPENDS</filename> and
1570 <filename>RRECOMMENDS</filename> runtime dependencies.
1571 The "rdeptask" flag for tasks is used to signify the task of each
1572 item runtime dependency which must have completed before that
1573 task can be executed.
1574 <literallayout class='monospaced'>
1575 do_package_qa[rdeptask] = "do_packagedata"
1576 </literallayout>
1577 In the previous example, the <filename>do_packagedata</filename>
1578 task of each item in <filename>RDEPENDS</filename> must have
1579 completed before <filename>do_package_qa</filename> can execute.
1580 </para>
1581 </section>
1582
1583 <section id='recursive-dependencies'>
1584 <title>Recursive Dependencies</title>
1585
1586 <para>
1587 BitBake uses the "recrdeptask" flag to manage
1588 recursive task dependencies.
1589 BitBake looks through the build-time and runtime
1590 dependencies of the current recipe, looks through
1591 the task's inter-task
1592 dependencies, and then adds dependencies for the
1593 listed task.
1594 Once BitBake has accomplished this, it recursively works through
1595 the dependencies of those tasks.
1596 Iterative passes continue until all dependencies are discovered
1597 and added.
1598 </para>
1599
1600 <para>
1601 You might want to not only have BitBake look for
1602 dependencies of those tasks, but also have BitBake look
1603 for build-time and runtime dependencies of the dependent
1604 tasks as well.
1605 If that is the case, you need to reference the task name
1606 itself in the task list:
1607 <literallayout class='monospaced'>
1608 do_a[recrdeptask] = "do_a do_b"
1609 </literallayout>
1610 </para>
1611 </section>
1612
1613 <section id='inter-task-dependencies'>
1614 <title>Inter-Task Dependencies</title>
1615
1616 <para>
1617 BitBake uses the "depends" flag in a more generic form
1618 to manage inter-task dependencies.
1619 This more generic form allows for inter-dependency
1620 checks for specific tasks rather than checks for
1621 the data in <filename>DEPENDS</filename>.
1622 Here is an example:
1623 <literallayout class='monospaced'>
1624 do_patch[depends] = "quilt-native:do_populate_sysroot"
1625 </literallayout>
1626 In this example, the <filename>do_populate_sysroot</filename>
1627 task of the target <filename>quilt-native</filename>
1628 must have completed before the
1629 <filename>do_patch</filename> task can execute.
1630 </para>
1631
1632 <para>
1633 The "rdepends" flag works in a similar way but takes targets
1634 in the runtime namespace instead of the build-time dependency
1635 namespace.
1636 </para>
1637 </section>
1638 </section>
1639
1640 <section id='accessing-datastore-variables-using-python'>
1641 <title>Accessing Datastore Variables Using Python</title>
1642
1643 <para>
1644 It is often necessary to access variables in the
1645 BitBake datastore using Python functions.
1646 The Bitbake datastore has an API that allows you this
1647 access.
1648 Here is a list of available operations:
1649 </para>
1650
1651 <para>
1652 <informaltable frame='none'>
1653 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
1654 <colspec colname='c1' colwidth='1*'/>
1655 <colspec colname='c2' colwidth='1*'/>
1656 <thead>
1657 <row>
1658 <entry align="left"><emphasis>Operation</emphasis></entry>
1659 <entry align="left"><emphasis>Description</emphasis></entry>
1660 </row>
1661 </thead>
1662 <tbody>
1663 <row>
1664 <entry align="left"><filename>d.getVar("X", expand=False)</filename></entry>
1665 <entry align="left">Returns the value of variable "X".
1666 Using "expand=True" expands the value.</entry>
1667 </row>
1668 <row>
1669 <entry align="left"><filename>d.setVar("X", "value")</filename></entry>
1670 <entry align="left">Sets the variable "X" to "value".</entry>
1671 </row>
1672 <row>
1673 <entry align="left"><filename>d.appendVar("X", "value")</filename></entry>
1674 <entry align="left">Adds "value" to the end of the variable "X".</entry>
1675 </row>
1676 <row>
1677 <entry align="left"><filename>d.prependVar("X", "value")</filename></entry>
1678 <entry align="left">Adds "value" to the start of the variable "X".</entry>
1679 </row>
1680 <row>
1681 <entry align="left"><filename>d.delVar("X")</filename></entry>
1682 <entry align="left">Deletes the variable "X" from the datastore.</entry>
1683 </row>
1684 <row>
1685 <entry align="left"><filename>d.renameVar("X", "Y")</filename></entry>
1686 <entry align="left">Renames the variable "X" to "Y".</entry>
1687 </row>
1688 <row>
1689 <entry align="left"><filename>d.getVarFlag("X", flag, expand=False)</filename></entry>
1690 <entry align="left">Gets then named flag from the variable "X".
1691 Using "expand=True" expands the named flag.</entry>
1692 </row>
1693 <row>
1694 <entry align="left"><filename>d.setVarFlag("X", flag, "value")</filename></entry>
1695 <entry align="left">Sets the named flag for variable "X" to "value".</entry>
1696 </row>
1697 <row>
1698 <entry align="left"><filename>d.appendVarFlag("X", flag, "value")</filename></entry>
1699 <entry align="left">Appends "value" to the named flag on the
1700 variable "X".</entry>
1701 </row>
1702 <row>
1703 <entry align="left"><filename>d.prependVarFlag("X", flag, "value")</filename></entry>
1704 <entry align="left">Prepends "value" to the named flag on
1705 the variable "X".</entry>
1706 </row>
1707 <row>
1708 <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry>
1709 <entry align="left">Deletes the named flag on the variable
1710 "X" from the datastore.</entry>
1711 </row>
1712 <row>
1713 <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry>
1714 <entry align="left">Sets the flags specified in
1715 the <filename>flagsdict()</filename> parameter.
1716 <filename>setVarFlags</filename> does not clear previous flags.
1717 Think of this operation as <filename>addVarFlags</filename>.</entry>
1718 </row>
1719 <row>
1720 <entry align="left"><filename>d.getVarFlags("X")</filename></entry>
1721 <entry align="left">Returns a <filename>flagsdict</filename> of the flags for
1722 the variable "X".</entry>
1723 </row>
1724 <row>
1725 <entry align="left"><filename>d.delVarFlags("X")</filename></entry>
1726 <entry align="left">Deletes all the flags for the variable "X".</entry>
1727 </row>
1728 </tbody>
1729 </tgroup>
1730 </informaltable>
1731 </para>
1732 </section>
1733
1734 <section id='task-checksums-and-setscene'>
1735 <title>Task Checksums and Setscene</title>
1736
1737 <para>
1738 BitBake uses checksums (or signatures) along with the setscene
1739 to determine if a task needs to be run.
1740 This section describes the process.
1741 To help understand how BitBake does this, the section assumes an
1742 OpenEmbedded metadata-based example.
1743 </para>
1744
1745 <para>
1746 This list is a place holder of content existed from previous work
1747 on the manual.
1748 Some or all of it probably needs integrated into the subsections
1749 that make up this section.
1750 For now, I have just provided a short glossary-like description
1751 for each variable.
1752 Ultimately, this list goes away.
1753 <itemizedlist>
1754 <listitem><para><filename>STAMP</filename>:
1755 The base path to create stamp files.</para></listitem>
1756 <listitem><para><filename>STAMPCLEAN</filename>
1757 Again, the base path to create stamp files but can use wildcards
1758 for matching a range of files for clean operations.
1759 </para></listitem>
1760 <listitem><para><filename>BB_STAMP_WHITELIST</filename>
1761 Lists stamp files that are looked at when the stamp policy
1762 is "whitelist".
1763 </para></listitem>
1764 <listitem><para><filename>BB_STAMP_POLICY</filename>
1765 Defines the mode for comparing timestamps of stamp files.
1766 </para></listitem>
1767 <listitem><para><filename>BB_HASHCHECK_FUNCTION</filename>
1768 Specifies the name of the function to call during
1769 the "setscene" part of the task's execution in order
1770 to validate the list of task hashes.
1771 </para></listitem>
1772 <listitem><para><filename>BB_SETSCENE_VERIFY_FUNCTION</filename>
1773 Specifies a function to call that verifies the list of
1774 planned task execution before the main task execution
1775 happens.
1776 </para></listitem>
1777 <listitem><para><filename>BB_SETSCENE_DEPVALID</filename>
1778 Specifies a function BitBake calls that determines
1779 whether BitBake requires a setscene dependency to
1780 be met.
1781 </para></listitem>
1782 <listitem><para><filename>BB_TASKHASH</filename>
1783 Within an executing task, this variable holds the hash
1784 of the task as returned by the currently enabled
1785 signature generator.
1786 </para></listitem>
1787 </itemizedlist>
1788 </para>
1789 </section>
1790</chapter>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-19 15:39:59 +0000