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