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