diff options
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.xml | 2862 |
1 files changed, 0 insertions, 2862 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml deleted file mode 100644 index 0ca5321618..0000000000 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml +++ /dev/null | |||
@@ -1,2862 +0,0 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | ||
3 | |||
4 | <chapter id="bitbake-user-manual-metadata"> | ||
5 | <title>Syntax and Operators</title> | ||
6 | |||
7 | <para> | ||
8 | BitBake files have their own syntax. | ||
9 | The syntax has similarities to several | ||
10 | other languages but also has some unique features. | ||
11 | This section describes the available syntax and operators | ||
12 | as well as provides examples. | ||
13 | </para> | ||
14 | |||
15 | <section id='basic-syntax'> | ||
16 | <title>Basic Syntax</title> | ||
17 | |||
18 | <para> | ||
19 | This section provides some basic syntax examples. | ||
20 | </para> | ||
21 | |||
22 | <section id='basic-variable-setting'> | ||
23 | <title>Basic Variable Setting</title> | ||
24 | |||
25 | <para> | ||
26 | The following example sets <filename>VARIABLE</filename> to | ||
27 | "value". | ||
28 | This assignment occurs immediately as the statement is parsed. | ||
29 | It is a "hard" assignment. | ||
30 | <literallayout class='monospaced'> | ||
31 | VARIABLE = "value" | ||
32 | </literallayout> | ||
33 | As expected, if you include leading or trailing spaces as part of | ||
34 | an assignment, the spaces are retained: | ||
35 | <literallayout class='monospaced'> | ||
36 | VARIABLE = " value" | ||
37 | VARIABLE = "value " | ||
38 | </literallayout> | ||
39 | Setting <filename>VARIABLE</filename> to "" sets it to an empty string, | ||
40 | while setting the variable to " " sets it to a blank space | ||
41 | (i.e. these are not the same values). | ||
42 | <literallayout class='monospaced'> | ||
43 | VARIABLE = "" | ||
44 | VARIABLE = " " | ||
45 | </literallayout> | ||
46 | </para> | ||
47 | |||
48 | <para> | ||
49 | You can use single quotes instead of double quotes | ||
50 | when setting a variable's value. | ||
51 | Doing so allows you to use values that contain the double | ||
52 | quote character: | ||
53 | <literallayout class='monospaced'> | ||
54 | VARIABLE = 'I have a " in my value' | ||
55 | </literallayout> | ||
56 | <note> | ||
57 | Unlike in Bourne shells, single quotes work identically | ||
58 | to double quotes in all other ways. | ||
59 | They do not suppress variable expansions. | ||
60 | </note> | ||
61 | </para> | ||
62 | </section> | ||
63 | |||
64 | <section id='modifying-existing-variables'> | ||
65 | <title>Modifying Existing Variables</title> | ||
66 | |||
67 | <para> | ||
68 | Sometimes you need to modify existing variables. | ||
69 | Following are some cases where you might find you want to | ||
70 | modify an existing variable: | ||
71 | <itemizedlist> | ||
72 | <listitem><para> | ||
73 | Customize a recipe that uses the variable. | ||
74 | </para></listitem> | ||
75 | <listitem><para> | ||
76 | Change a variable's default value used in a | ||
77 | <filename>*.bbclass</filename> file. | ||
78 | </para></listitem> | ||
79 | <listitem><para> | ||
80 | Change the variable in a <filename>*.bbappend</filename> | ||
81 | file to override the variable in the original recipe. | ||
82 | </para></listitem> | ||
83 | <listitem><para> | ||
84 | Change the variable in a configuration file so that the | ||
85 | value overrides an existing configuration. | ||
86 | </para></listitem> | ||
87 | </itemizedlist> | ||
88 | </para> | ||
89 | |||
90 | <para> | ||
91 | Changing a variable value can sometimes depend on how the | ||
92 | value was originally assigned and also on the desired | ||
93 | intent of the change. | ||
94 | In particular, when you append a value to a variable that | ||
95 | has a default value, the resulting value might not be what | ||
96 | you expect. | ||
97 | In this case, the value you provide might replace the value | ||
98 | rather than append to the default value. | ||
99 | </para> | ||
100 | |||
101 | <para> | ||
102 | If after you have changed a variable's value and something | ||
103 | unexplained occurs, you can use BitBake to check the actual | ||
104 | value of the suspect variable. | ||
105 | You can make these checks for both configuration and recipe | ||
106 | level changes: | ||
107 | <itemizedlist> | ||
108 | <listitem><para> | ||
109 | For configuration changes, use the following: | ||
110 | <literallayout class='monospaced'> | ||
111 | $ bitbake -e | ||
112 | </literallayout> | ||
113 | This command displays variable values after the | ||
114 | configuration files (i.e. <filename>local.conf</filename>, | ||
115 | <filename>bblayers.conf</filename>, | ||
116 | <filename>bitbake.conf</filename> and so forth) have | ||
117 | been parsed. | ||
118 | <note> | ||
119 | Variables that are exported to the environment are | ||
120 | preceded by the string "export" in the command's | ||
121 | output. | ||
122 | </note> | ||
123 | </para></listitem> | ||
124 | <listitem><para> | ||
125 | For recipe changes, use the following: | ||
126 | <literallayout class='monospaced'> | ||
127 | $ bitbake <replaceable>recipe</replaceable> -e | grep VARIABLE=" | ||
128 | </literallayout> | ||
129 | This command checks to see if the variable actually | ||
130 | makes it into a specific recipe. | ||
131 | </para></listitem> | ||
132 | </itemizedlist> | ||
133 | </para> | ||
134 | </section> | ||
135 | |||
136 | <section id='line-joining'> | ||
137 | <title>Line Joining</title> | ||
138 | |||
139 | <para> | ||
140 | Outside of | ||
141 | <link linkend='functions'>functions</link>, BitBake joins | ||
142 | any line ending in a backslash character ("\") | ||
143 | with the following line before parsing statements. | ||
144 | The most common use for the "\" character is to split variable | ||
145 | assignments over multiple lines, as in the following example: | ||
146 | <literallayout class='monospaced'> | ||
147 | FOO = "bar \ | ||
148 | baz \ | ||
149 | qaz" | ||
150 | </literallayout> | ||
151 | Both the "\" character and the newline character | ||
152 | that follow it are removed when joining lines. | ||
153 | Thus, no newline characters end up in the value of | ||
154 | <filename>FOO</filename>. | ||
155 | </para> | ||
156 | |||
157 | <para> | ||
158 | Consider this additional example where the two | ||
159 | assignments both assign "barbaz" to | ||
160 | <filename>FOO</filename>: | ||
161 | <literallayout class='monospaced'> | ||
162 | FOO = "barbaz" | ||
163 | |||
164 | FOO = "bar\ | ||
165 | baz" | ||
166 | </literallayout> | ||
167 | <note> | ||
168 | BitBake does not interpret escape sequences like | ||
169 | "\n" in variable values. | ||
170 | For these to have an effect, the value must be passed | ||
171 | to some utility that interprets escape sequences, | ||
172 | such as <filename>printf</filename> or | ||
173 | <filename>echo -n</filename>. | ||
174 | </note> | ||
175 | </para> | ||
176 | </section> | ||
177 | |||
178 | <section id='variable-expansion'> | ||
179 | <title>Variable Expansion</title> | ||
180 | |||
181 | <para> | ||
182 | Variables can reference the contents of other variables | ||
183 | using a syntax that is similar to variable expansion in | ||
184 | Bourne shells. | ||
185 | The following assignments | ||
186 | result in A containing "aval" and B evaluating to "preavalpost". | ||
187 | <literallayout class='monospaced'> | ||
188 | A = "aval" | ||
189 | B = "pre${A}post" | ||
190 | </literallayout> | ||
191 | <note> | ||
192 | Unlike in Bourne shells, the curly braces are mandatory: | ||
193 | Only <filename>${FOO}</filename> and not | ||
194 | <filename>$FOO</filename> is recognized as an expansion of | ||
195 | <filename>FOO</filename>. | ||
196 | </note> | ||
197 | The "=" operator does not immediately expand variable | ||
198 | references in the right-hand side. | ||
199 | Instead, expansion is deferred until the variable assigned to | ||
200 | is actually used. | ||
201 | The result depends on the current values of the referenced | ||
202 | variables. | ||
203 | The following example should clarify this behavior: | ||
204 | <literallayout class='monospaced'> | ||
205 | A = "${B} baz" | ||
206 | B = "${C} bar" | ||
207 | C = "foo" | ||
208 | *At this point, ${A} equals "foo bar baz"* | ||
209 | C = "qux" | ||
210 | *At this point, ${A} equals "qux bar baz"* | ||
211 | B = "norf" | ||
212 | *At this point, ${A} equals "norf baz"* | ||
213 | </literallayout> | ||
214 | Contrast this behavior with the | ||
215 | <link linkend='immediate-variable-expansion'>immediate variable expansion</link> | ||
216 | operator (i.e. ":="). | ||
217 | </para> | ||
218 | |||
219 | <para> | ||
220 | If the variable expansion syntax is used on a variable that | ||
221 | does not exist, the string is kept as is. | ||
222 | For example, given the following assignment, | ||
223 | <filename>BAR</filename> expands to the literal string | ||
224 | "${FOO}" as long as <filename>FOO</filename> does not exist. | ||
225 | <literallayout class='monospaced'> | ||
226 | BAR = "${FOO}" | ||
227 | </literallayout> | ||
228 | </para> | ||
229 | </section> | ||
230 | |||
231 | <section id='setting-a-default-value'> | ||
232 | <title>Setting a default value (?=)</title> | ||
233 | |||
234 | <para> | ||
235 | You can use the "?=" operator to achieve a "softer" assignment | ||
236 | for a variable. | ||
237 | This type of assignment allows you to define a variable if it | ||
238 | is undefined when the statement is parsed, but to leave the | ||
239 | value alone if the variable has a value. | ||
240 | Here is an example: | ||
241 | <literallayout class='monospaced'> | ||
242 | A ?= "aval" | ||
243 | </literallayout> | ||
244 | If <filename>A</filename> is set at the time this statement is parsed, | ||
245 | the variable retains its value. | ||
246 | However, if <filename>A</filename> is not set, | ||
247 | the variable is set to "aval". | ||
248 | <note> | ||
249 | This assignment is immediate. | ||
250 | Consequently, if multiple "?=" assignments | ||
251 | to a single variable exist, the first of those ends up getting | ||
252 | used. | ||
253 | </note> | ||
254 | </para> | ||
255 | </section> | ||
256 | |||
257 | <section id='setting-a-weak-default-value'> | ||
258 | <title>Setting a weak default value (??=)</title> | ||
259 | |||
260 | <para> | ||
261 | It is possible to use a "weaker" assignment than in the | ||
262 | previous section by using the "??=" operator. | ||
263 | This assignment behaves identical to "?=" except that the | ||
264 | assignment is made at the end of the parsing process rather | ||
265 | than immediately. | ||
266 | Consequently, when multiple "??=" assignments exist, the last | ||
267 | one is used. | ||
268 | Also, any "=" or "?=" assignment will override the value set with | ||
269 | "??=". | ||
270 | Here is an example: | ||
271 | <literallayout class='monospaced'> | ||
272 | A ??= "somevalue" | ||
273 | A ??= "someothervalue" | ||
274 | </literallayout> | ||
275 | If <filename>A</filename> is set before the above statements are parsed, | ||
276 | the variable retains its value. | ||
277 | If <filename>A</filename> is not set, | ||
278 | the variable is set to "someothervalue". | ||
279 | </para> | ||
280 | |||
281 | <para> | ||
282 | Again, this assignment is a "lazy" or "weak" assignment | ||
283 | because it does not occur until the end | ||
284 | of the parsing process. | ||
285 | </para> | ||
286 | </section> | ||
287 | |||
288 | <section id='immediate-variable-expansion'> | ||
289 | <title>Immediate variable expansion (:=)</title> | ||
290 | |||
291 | <para> | ||
292 | The ":=" operator results in a variable's | ||
293 | contents being expanded immediately, | ||
294 | rather than when the variable is actually used: | ||
295 | <literallayout class='monospaced'> | ||
296 | T = "123" | ||
297 | A := "test ${T}" | ||
298 | T = "456" | ||
299 | B := "${T} ${C}" | ||
300 | C = "cval" | ||
301 | C := "${C}append" | ||
302 | </literallayout> | ||
303 | In this example, <filename>A</filename> contains | ||
304 | "test 123", even though the final value of <filename>T</filename> | ||
305 | is "456". | ||
306 | The variable <filename>B</filename> will end up containing "456 cvalappend". | ||
307 | This is because references to undefined variables are preserved as is | ||
308 | during (immediate)expansion. This is in contrast to GNU Make, where undefined | ||
309 | variables expand to nothing. | ||
310 | The variable <filename>C</filename> | ||
311 | contains "cvalappend" since <filename>${C}</filename> immediately | ||
312 | expands to "cval". | ||
313 | </para> | ||
314 | </section> | ||
315 | |||
316 | <section id='appending-and-prepending'> | ||
317 | <title>Appending (+=) and prepending (=+) With Spaces</title> | ||
318 | |||
319 | <para> | ||
320 | Appending and prepending values is common and can be accomplished | ||
321 | using the "+=" and "=+" operators. | ||
322 | These operators insert a space between the current | ||
323 | value and prepended or appended value. | ||
324 | </para> | ||
325 | |||
326 | <para> | ||
327 | These operators take immediate effect during parsing. | ||
328 | Here are some examples: | ||
329 | <literallayout class='monospaced'> | ||
330 | B = "bval" | ||
331 | B += "additionaldata" | ||
332 | C = "cval" | ||
333 | C =+ "test" | ||
334 | </literallayout> | ||
335 | The variable <filename>B</filename> contains | ||
336 | "bval additionaldata" and <filename>C</filename> | ||
337 | contains "test cval". | ||
338 | </para> | ||
339 | </section> | ||
340 | |||
341 | <section id='appending-and-prepending-without-spaces'> | ||
342 | <title>Appending (.=) and Prepending (=.) Without Spaces</title> | ||
343 | |||
344 | <para> | ||
345 | If you want to append or prepend values without an | ||
346 | inserted space, use the ".=" and "=." operators. | ||
347 | </para> | ||
348 | |||
349 | <para> | ||
350 | These operators take immediate effect during parsing. | ||
351 | Here are some examples: | ||
352 | <literallayout class='monospaced'> | ||
353 | B = "bval" | ||
354 | B .= "additionaldata" | ||
355 | C = "cval" | ||
356 | C =. "test" | ||
357 | </literallayout> | ||
358 | The variable <filename>B</filename> contains | ||
359 | "bvaladditionaldata" and | ||
360 | <filename>C</filename> contains "testcval". | ||
361 | </para> | ||
362 | </section> | ||
363 | |||
364 | <section id='appending-and-prepending-override-style-syntax'> | ||
365 | <title>Appending and Prepending (Override Style Syntax)</title> | ||
366 | |||
367 | <para> | ||
368 | You can also append and prepend a variable's value | ||
369 | using an override style syntax. | ||
370 | When you use this syntax, no spaces are inserted. | ||
371 | </para> | ||
372 | |||
373 | <para> | ||
374 | These operators differ from the ":=", ".=", "=.", "+=", and "=+" | ||
375 | operators in that their effects are applied at variable | ||
376 | expansion time rather than being immediately applied. | ||
377 | Here are some examples: | ||
378 | <literallayout class='monospaced'> | ||
379 | B = "bval" | ||
380 | B_append = " additional data" | ||
381 | C = "cval" | ||
382 | C_prepend = "additional data " | ||
383 | D = "dval" | ||
384 | D_append = "additional data" | ||
385 | </literallayout> | ||
386 | The variable <filename>B</filename> becomes | ||
387 | "bval additional data" and <filename>C</filename> becomes | ||
388 | "additional data cval". | ||
389 | The variable <filename>D</filename> becomes | ||
390 | "dvaladditional data". | ||
391 | <note> | ||
392 | You must control all spacing when you use the | ||
393 | override syntax. | ||
394 | </note> | ||
395 | </para> | ||
396 | |||
397 | <para> | ||
398 | It is also possible to append and prepend to shell | ||
399 | functions and BitBake-style Python functions. | ||
400 | See the | ||
401 | "<link linkend='shell-functions'>Shell Functions</link>" and | ||
402 | "<link linkend='bitbake-style-python-functions'>BitBake-Style Python Functions</link> | ||
403 | sections for examples. | ||
404 | </para> | ||
405 | </section> | ||
406 | |||
407 | <section id='removing-override-style-syntax'> | ||
408 | <title>Removal (Override Style Syntax)</title> | ||
409 | |||
410 | <para> | ||
411 | You can remove values from lists using the removal | ||
412 | override style syntax. | ||
413 | Specifying a value for removal causes all occurrences of that | ||
414 | value to be removed from the variable. | ||
415 | </para> | ||
416 | |||
417 | <para> | ||
418 | When you use this syntax, BitBake expects one or more strings. | ||
419 | Surrounding spaces and spacing are preserved. | ||
420 | Here is an example: | ||
421 | <literallayout class='monospaced'> | ||
422 | FOO = "123 456 789 123456 123 456 123 456" | ||
423 | FOO_remove = "123" | ||
424 | FOO_remove = "456" | ||
425 | FOO2 = " abc def ghi abcdef abc def abc def def" | ||
426 | FOO2_remove = " \ | ||
427 | def \ | ||
428 | abc \ | ||
429 | ghi \ | ||
430 | " | ||
431 | </literallayout> | ||
432 | The variable <filename>FOO</filename> becomes | ||
433 | " 789 123456 " | ||
434 | and <filename>FOO2</filename> becomes | ||
435 | " abcdef ". | ||
436 | </para> | ||
437 | |||
438 | <para> | ||
439 | Like "_append" and "_prepend", "_remove" | ||
440 | is applied at variable expansion time. | ||
441 | </para> | ||
442 | </section> | ||
443 | |||
444 | <section id='override-style-operation-advantages'> | ||
445 | <title>Override Style Operation Advantages</title> | ||
446 | |||
447 | <para> | ||
448 | An advantage of the override style operations | ||
449 | "_append", "_prepend", and "_remove" as compared to the | ||
450 | "+=" and "=+" operators is that the override style | ||
451 | operators provide guaranteed operations. | ||
452 | For example, consider a class <filename>foo.bbclass</filename> | ||
453 | that needs to add the value "val" to the variable | ||
454 | <filename>FOO</filename>, and a recipe that uses | ||
455 | <filename>foo.bbclass</filename> as follows: | ||
456 | <literallayout class='monospaced'> | ||
457 | inherit foo | ||
458 | |||
459 | FOO = "initial" | ||
460 | </literallayout> | ||
461 | If <filename>foo.bbclass</filename> uses the "+=" operator, | ||
462 | as follows, then the final value of <filename>FOO</filename> | ||
463 | will be "initial", which is not what is desired: | ||
464 | <literallayout class='monospaced'> | ||
465 | FOO += "val" | ||
466 | </literallayout> | ||
467 | If, on the other hand, <filename>foo.bbclass</filename> | ||
468 | uses the "_append" operator, then the final value of | ||
469 | <filename>FOO</filename> will be "initial val", as intended: | ||
470 | <literallayout class='monospaced'> | ||
471 | FOO_append = " val" | ||
472 | </literallayout> | ||
473 | <note> | ||
474 | It is never necessary to use "+=" together with "_append". | ||
475 | The following sequence of assignments appends "barbaz" to | ||
476 | <filename>FOO</filename>: | ||
477 | <literallayout class='monospaced'> | ||
478 | FOO_append = "bar" | ||
479 | FOO_append = "baz" | ||
480 | </literallayout> | ||
481 | The only effect of changing the second assignment in the | ||
482 | previous example to use "+=" would be to add a space before | ||
483 | "baz" in the appended value (due to how the "+=" operator | ||
484 | works). | ||
485 | </note> | ||
486 | Another advantage of the override style operations is that | ||
487 | you can combine them with other overrides as described in the | ||
488 | "<link linkend='conditional-syntax-overrides'>Conditional Syntax (Overrides)</link>" | ||
489 | section. | ||
490 | </para> | ||
491 | </section> | ||
492 | |||
493 | <section id='variable-flag-syntax'> | ||
494 | <title>Variable Flag Syntax</title> | ||
495 | |||
496 | <para> | ||
497 | Variable flags are BitBake's implementation of variable properties | ||
498 | or attributes. | ||
499 | It is a way of tagging extra information onto a variable. | ||
500 | You can find more out about variable flags in general in the | ||
501 | "<link linkend='variable-flags'>Variable Flags</link>" | ||
502 | section. | ||
503 | </para> | ||
504 | |||
505 | <para> | ||
506 | You can define, append, and prepend values to variable flags. | ||
507 | All the standard syntax operations previously mentioned work | ||
508 | for variable flags except for override style syntax | ||
509 | (i.e. "_prepend", "_append", and "_remove"). | ||
510 | </para> | ||
511 | |||
512 | <para> | ||
513 | Here are some examples showing how to set variable flags: | ||
514 | <literallayout class='monospaced'> | ||
515 | FOO[a] = "abc" | ||
516 | FOO[b] = "123" | ||
517 | FOO[a] += "456" | ||
518 | </literallayout> | ||
519 | The variable <filename>FOO</filename> has two flags: | ||
520 | <filename>[a]</filename> and <filename>[b]</filename>. | ||
521 | The flags are immediately set to "abc" and "123", respectively. | ||
522 | The <filename>[a]</filename> flag becomes "abc 456". | ||
523 | </para> | ||
524 | |||
525 | <para> | ||
526 | No need exists to pre-define variable flags. | ||
527 | You can simply start using them. | ||
528 | One extremely common application | ||
529 | is to attach some brief documentation to a BitBake variable as | ||
530 | follows: | ||
531 | <literallayout class='monospaced'> | ||
532 | CACHE[doc] = "The directory holding the cache of the metadata." | ||
533 | </literallayout> | ||
534 | </para> | ||
535 | </section> | ||
536 | |||
537 | <section id='inline-python-variable-expansion'> | ||
538 | <title>Inline Python Variable Expansion</title> | ||
539 | |||
540 | <para> | ||
541 | You can use inline Python variable expansion to | ||
542 | set variables. | ||
543 | Here is an example: | ||
544 | <literallayout class='monospaced'> | ||
545 | DATE = "${@time.strftime('%Y%m%d',time.gmtime())}" | ||
546 | </literallayout> | ||
547 | This example results in the <filename>DATE</filename> | ||
548 | variable being set to the current date. | ||
549 | </para> | ||
550 | |||
551 | <para> | ||
552 | Probably the most common use of this feature is to extract | ||
553 | the value of variables from BitBake's internal data dictionary, | ||
554 | <filename>d</filename>. | ||
555 | The following lines select the values of a package name | ||
556 | and its version number, respectively: | ||
557 | <literallayout class='monospaced'> | ||
558 | PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" | ||
559 | PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" | ||
560 | </literallayout> | ||
561 | <note> | ||
562 | Inline Python expressions work just like variable expansions | ||
563 | insofar as the "=" and ":=" operators are concerned. | ||
564 | Given the following assignment, <filename>foo()</filename> | ||
565 | is called each time <filename>FOO</filename> is expanded: | ||
566 | <literallayout class='monospaced'> | ||
567 | FOO = "${@foo()}" | ||
568 | </literallayout> | ||
569 | Contrast this with the following immediate assignment, where | ||
570 | <filename>foo()</filename> is only called once, while the | ||
571 | assignment is parsed: | ||
572 | <literallayout class='monospaced'> | ||
573 | FOO := "${@foo()}" | ||
574 | </literallayout> | ||
575 | </note> | ||
576 | For a different way to set variables with Python code during | ||
577 | parsing, see the | ||
578 | "<link linkend='anonymous-python-functions'>Anonymous Python Functions</link>" | ||
579 | section. | ||
580 | </para> | ||
581 | </section> | ||
582 | |||
583 | <section id='unsetting-variables'> | ||
584 | <title>Unsetting variables</title> | ||
585 | |||
586 | <para> | ||
587 | It is possible to completely remove a variable or a variable flag | ||
588 | from BitBake's internal data dictionary by using the "unset" keyword. | ||
589 | Here is an example: | ||
590 | <literallayout class='monospaced'> | ||
591 | unset DATE | ||
592 | unset do_fetch[noexec] | ||
593 | </literallayout> | ||
594 | These two statements remove the <filename>DATE</filename> and the | ||
595 | <filename>do_fetch[noexec]</filename> flag. | ||
596 | </para> | ||
597 | |||
598 | </section> | ||
599 | |||
600 | <section id='providing-pathnames'> | ||
601 | <title>Providing Pathnames</title> | ||
602 | |||
603 | <para> | ||
604 | When specifying pathnames for use with BitBake, | ||
605 | do not use the tilde ("~") character as a shortcut | ||
606 | for your home directory. | ||
607 | Doing so might cause BitBake to not recognize the | ||
608 | path since BitBake does not expand this character in | ||
609 | the same way a shell would. | ||
610 | </para> | ||
611 | |||
612 | <para> | ||
613 | Instead, provide a fuller path as the following | ||
614 | example illustrates: | ||
615 | <literallayout class='monospaced'> | ||
616 | BBLAYERS ?= " \ | ||
617 | /home/scott-lenovo/LayerA \ | ||
618 | " | ||
619 | </literallayout> | ||
620 | </para> | ||
621 | </section> | ||
622 | </section> | ||
623 | |||
624 | <section id='exporting-variables-to-the-environment'> | ||
625 | <title>Exporting Variables to the Environment</title> | ||
626 | |||
627 | <para> | ||
628 | You can export variables to the environment of running | ||
629 | tasks by using the <filename>export</filename> keyword. | ||
630 | For example, in the following example, the | ||
631 | <filename>do_foo</filename> task prints "value from | ||
632 | the environment" when run: | ||
633 | <literallayout class='monospaced'> | ||
634 | export ENV_VARIABLE | ||
635 | ENV_VARIABLE = "value from the environment" | ||
636 | |||
637 | do_foo() { | ||
638 | bbplain "$ENV_VARIABLE" | ||
639 | } | ||
640 | </literallayout> | ||
641 | <note> | ||
642 | BitBake does not expand <filename>$ENV_VARIABLE</filename> | ||
643 | in this case because it lacks the obligatory | ||
644 | <filename>{}</filename>. | ||
645 | Rather, <filename>$ENV_VARIABLE</filename> is expanded | ||
646 | by the shell. | ||
647 | </note> | ||
648 | It does not matter whether | ||
649 | <filename>export ENV_VARIABLE</filename> appears before or | ||
650 | after assignments to <filename>ENV_VARIABLE</filename>. | ||
651 | </para> | ||
652 | |||
653 | <para> | ||
654 | It is also possible to combine <filename>export</filename> | ||
655 | with setting a value for the variable. | ||
656 | Here is an example: | ||
657 | <literallayout class='monospaced'> | ||
658 | export ENV_VARIABLE = "<replaceable>variable-value</replaceable>" | ||
659 | </literallayout> | ||
660 | In the output of <filename>bitbake -e</filename>, variables | ||
661 | that are exported to the environment are preceded by "export". | ||
662 | </para> | ||
663 | |||
664 | <para> | ||
665 | Among the variables commonly exported to the environment | ||
666 | are <filename>CC</filename> and <filename>CFLAGS</filename>, | ||
667 | which are picked up by many build systems. | ||
668 | </para> | ||
669 | </section> | ||
670 | |||
671 | <section id='conditional-syntax-overrides'> | ||
672 | <title>Conditional Syntax (Overrides)</title> | ||
673 | |||
674 | <para> | ||
675 | BitBake uses | ||
676 | <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link> | ||
677 | to control what variables are overridden after BitBake | ||
678 | parses recipes and configuration files. | ||
679 | This section describes how you can use | ||
680 | <filename>OVERRIDES</filename> as conditional metadata, | ||
681 | talks about key expansion in relationship to | ||
682 | <filename>OVERRIDES</filename>, and provides some examples | ||
683 | to help with understanding. | ||
684 | </para> | ||
685 | |||
686 | <section id='conditional-metadata'> | ||
687 | <title>Conditional Metadata</title> | ||
688 | |||
689 | <para> | ||
690 | You can use <filename>OVERRIDES</filename> to conditionally select | ||
691 | a specific version of a variable and to conditionally | ||
692 | append or prepend the value of a variable. | ||
693 | <note> | ||
694 | Overrides can only use lower-case characters. | ||
695 | Additionally, underscores are not permitted in override names | ||
696 | as they are used to separate overrides from each other and | ||
697 | from the variable name. | ||
698 | </note> | ||
699 | <itemizedlist> | ||
700 | <listitem><para><emphasis>Selecting a Variable:</emphasis> | ||
701 | The <filename>OVERRIDES</filename> variable is | ||
702 | a colon-character-separated list that contains items | ||
703 | for which you want to satisfy conditions. | ||
704 | Thus, if you have a variable that is conditional on “arm”, and “arm” | ||
705 | is in <filename>OVERRIDES</filename>, then the “arm”-specific | ||
706 | version of the variable is used rather than the non-conditional | ||
707 | version. | ||
708 | Here is an example: | ||
709 | <literallayout class='monospaced'> | ||
710 | OVERRIDES = "architecture:os:machine" | ||
711 | TEST = "default" | ||
712 | TEST_os = "osspecific" | ||
713 | TEST_nooverride = "othercondvalue" | ||
714 | </literallayout> | ||
715 | In this example, the <filename>OVERRIDES</filename> | ||
716 | variable lists three overrides: | ||
717 | "architecture", "os", and "machine". | ||
718 | The variable <filename>TEST</filename> by itself has a default | ||
719 | value of "default". | ||
720 | You select the os-specific version of the <filename>TEST</filename> | ||
721 | variable by appending the "os" override to the variable | ||
722 | (i.e.<filename>TEST_os</filename>). | ||
723 | </para> | ||
724 | |||
725 | <para> | ||
726 | To better understand this, consider a practical example | ||
727 | that assumes an OpenEmbedded metadata-based Linux | ||
728 | kernel recipe file. | ||
729 | The following lines from the recipe file first set | ||
730 | the kernel branch variable <filename>KBRANCH</filename> | ||
731 | to a default value, then conditionally override that | ||
732 | value based on the architecture of the build: | ||
733 | <literallayout class='monospaced'> | ||
734 | KBRANCH = "standard/base" | ||
735 | KBRANCH_qemuarm = "standard/arm-versatile-926ejs" | ||
736 | KBRANCH_qemumips = "standard/mti-malta32" | ||
737 | KBRANCH_qemuppc = "standard/qemuppc" | ||
738 | KBRANCH_qemux86 = "standard/common-pc/base" | ||
739 | KBRANCH_qemux86-64 = "standard/common-pc-64/base" | ||
740 | KBRANCH_qemumips64 = "standard/mti-malta64" | ||
741 | </literallayout> | ||
742 | </para></listitem> | ||
743 | <listitem><para><emphasis>Appending and Prepending:</emphasis> | ||
744 | BitBake also supports append and prepend operations to | ||
745 | variable values based on whether a specific item is | ||
746 | listed in <filename>OVERRIDES</filename>. | ||
747 | Here is an example: | ||
748 | <literallayout class='monospaced'> | ||
749 | DEPENDS = "glibc ncurses" | ||
750 | OVERRIDES = "machine:local" | ||
751 | DEPENDS_append_machine = " libmad" | ||
752 | </literallayout> | ||
753 | In this example, <filename>DEPENDS</filename> becomes | ||
754 | "glibc ncurses libmad". | ||
755 | </para> | ||
756 | |||
757 | <para> | ||
758 | Again, using an OpenEmbedded metadata-based | ||
759 | kernel recipe file as an example, the | ||
760 | following lines will conditionally append to the | ||
761 | <filename>KERNEL_FEATURES</filename> variable based | ||
762 | on the architecture: | ||
763 | <literallayout class='monospaced'> | ||
764 | KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}" | ||
765 | KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc" | ||
766 | KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc" | ||
767 | </literallayout> | ||
768 | </para></listitem> | ||
769 | <listitem><para><emphasis>Setting a Variable for a Single Task:</emphasis> | ||
770 | BitBake supports setting a variable just for the | ||
771 | duration of a single task. | ||
772 | Here is an example: | ||
773 | <literallayout class='monospaced'> | ||
774 | FOO_task-configure = "val 1" | ||
775 | FOO_task-compile = "val 2" | ||
776 | </literallayout> | ||
777 | In the previous example, <filename>FOO</filename> | ||
778 | has the value "val 1" while the | ||
779 | <filename>do_configure</filename> task is executed, | ||
780 | and the value "val 2" while the | ||
781 | <filename>do_compile</filename> task is executed. | ||
782 | </para> | ||
783 | |||
784 | <para>Internally, this is implemented by prepending | ||
785 | the task (e.g. "task-compile:") to the value of | ||
786 | <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link> | ||
787 | for the local datastore of the <filename>do_compile</filename> | ||
788 | task.</para> | ||
789 | |||
790 | <para>You can also use this syntax with other combinations | ||
791 | (e.g. "<filename>_prepend</filename>") as shown in the | ||
792 | following example: | ||
793 | <literallayout class='monospaced'> | ||
794 | EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} " | ||
795 | </literallayout> | ||
796 | </para></listitem> | ||
797 | </itemizedlist> | ||
798 | </para> | ||
799 | </section> | ||
800 | |||
801 | <section id='key-expansion'> | ||
802 | <title>Key Expansion</title> | ||
803 | |||
804 | <para> | ||
805 | Key expansion happens when the BitBake datastore is finalized. | ||
806 | To better understand this, consider the following example: | ||
807 | <literallayout class='monospaced'> | ||
808 | A${B} = "X" | ||
809 | B = "2" | ||
810 | A2 = "Y" | ||
811 | </literallayout> | ||
812 | In this case, after all the parsing is complete, | ||
813 | BitBake expands <filename>${B}</filename> into "2". | ||
814 | This expansion causes <filename>A2</filename>, which was | ||
815 | set to "Y" before the expansion, to become "X". | ||
816 | </para> | ||
817 | </section> | ||
818 | |||
819 | <section id='variable-interaction-worked-examples'> | ||
820 | <title>Examples</title> | ||
821 | |||
822 | <para> | ||
823 | Despite the previous explanations that show the different forms of | ||
824 | variable definitions, it can be hard to work | ||
825 | out exactly what happens when variable operators, conditional | ||
826 | overrides, and unconditional overrides are combined. | ||
827 | This section presents some common scenarios along | ||
828 | with explanations for variable interactions that | ||
829 | typically confuse users. | ||
830 | </para> | ||
831 | |||
832 | <para> | ||
833 | There is often confusion concerning the order in which | ||
834 | overrides and various "append" operators take effect. | ||
835 | Recall that an append or prepend operation using "_append" | ||
836 | and "_prepend" does not result in an immediate assignment | ||
837 | as would "+=", ".=", "=+", or "=.". | ||
838 | Consider the following example: | ||
839 | <literallayout class='monospaced'> | ||
840 | OVERRIDES = "foo" | ||
841 | A = "Z" | ||
842 | A_foo_append = "X" | ||
843 | </literallayout> | ||
844 | For this case, <filename>A</filename> is | ||
845 | unconditionally set to "Z" and "X" is | ||
846 | unconditionally and immediately appended to the variable | ||
847 | <filename>A_foo</filename>. | ||
848 | Because overrides have not been applied yet, | ||
849 | <filename>A_foo</filename> is set to "X" due to the append | ||
850 | and <filename>A</filename> simply equals "Z". | ||
851 | </para> | ||
852 | |||
853 | <para> | ||
854 | Applying overrides, however, changes things. | ||
855 | Since "foo" is listed in <filename>OVERRIDES</filename>, | ||
856 | the conditional variable <filename>A</filename> is replaced | ||
857 | with the "foo" version, which is equal to "X". | ||
858 | So effectively, <filename>A_foo</filename> replaces <filename>A</filename>. | ||
859 | </para> | ||
860 | |||
861 | <para> | ||
862 | This next example changes the order of the override and | ||
863 | the append: | ||
864 | <literallayout class='monospaced'> | ||
865 | OVERRIDES = "foo" | ||
866 | A = "Z" | ||
867 | A_append_foo = "X" | ||
868 | </literallayout> | ||
869 | For this case, before overrides are handled, | ||
870 | <filename>A</filename> is set to "Z" and <filename>A_append_foo</filename> | ||
871 | is set to "X". | ||
872 | Once the override for "foo" is applied, however, | ||
873 | <filename>A</filename> gets appended with "X". | ||
874 | Consequently, <filename>A</filename> becomes "ZX". | ||
875 | Notice that spaces are not appended. | ||
876 | </para> | ||
877 | |||
878 | <para> | ||
879 | This next example has the order of the appends and overrides reversed | ||
880 | back as in the first example: | ||
881 | <literallayout class='monospaced'> | ||
882 | OVERRIDES = "foo" | ||
883 | A = "Y" | ||
884 | A_foo_append = "Z" | ||
885 | A_foo_append = "X" | ||
886 | </literallayout> | ||
887 | For this case, before any overrides are resolved, | ||
888 | <filename>A</filename> is set to "Y" using an immediate assignment. | ||
889 | After this immediate assignment, <filename>A_foo</filename> is set | ||
890 | to "Z", and then further appended with | ||
891 | "X" leaving the variable set to "ZX". | ||
892 | Finally, applying the override for "foo" results in the conditional | ||
893 | variable <filename>A</filename> becoming "ZX" (i.e. | ||
894 | <filename>A</filename> is replaced with <filename>A_foo</filename>). | ||
895 | </para> | ||
896 | |||
897 | <para> | ||
898 | This final example mixes in some varying operators: | ||
899 | <literallayout class='monospaced'> | ||
900 | A = "1" | ||
901 | A_append = "2" | ||
902 | A_append = "3" | ||
903 | A += "4" | ||
904 | A .= "5" | ||
905 | </literallayout> | ||
906 | For this case, the type of append operators are affecting the | ||
907 | order of assignments as BitBake passes through the code | ||
908 | multiple times. | ||
909 | Initially, <filename>A</filename> is set to "1 45" because | ||
910 | of the three statements that use immediate operators. | ||
911 | After these assignments are made, BitBake applies the | ||
912 | "_append" operations. | ||
913 | Those operations result in <filename>A</filename> becoming "1 4523". | ||
914 | </para> | ||
915 | </section> | ||
916 | </section> | ||
917 | |||
918 | <section id='sharing-functionality'> | ||
919 | <title>Sharing Functionality</title> | ||
920 | |||
921 | <para> | ||
922 | BitBake allows for metadata sharing through include files | ||
923 | (<filename>.inc</filename>) and class files | ||
924 | (<filename>.bbclass</filename>). | ||
925 | For example, suppose you have a piece of common functionality | ||
926 | such as a task definition that you want to share between | ||
927 | more than one recipe. | ||
928 | In this case, creating a <filename>.bbclass</filename> | ||
929 | file that contains the common functionality and then using | ||
930 | the <filename>inherit</filename> directive in your recipes to | ||
931 | inherit the class would be a common way to share the task. | ||
932 | </para> | ||
933 | |||
934 | <para> | ||
935 | This section presents the mechanisms BitBake provides to | ||
936 | allow you to share functionality between recipes. | ||
937 | Specifically, the mechanisms include <filename>include</filename>, | ||
938 | <filename>inherit</filename>, <filename>INHERIT</filename>, and | ||
939 | <filename>require</filename> directives. | ||
940 | </para> | ||
941 | |||
942 | <section id='locating-include-and-class-files'> | ||
943 | <title>Locating Include and Class Files</title> | ||
944 | |||
945 | <para> | ||
946 | BitBake uses the | ||
947 | <link linkend='var-bb-BBPATH'><filename>BBPATH</filename></link> | ||
948 | variable to locate needed include and class files. | ||
949 | Additionally, BitBake searches the current directory for | ||
950 | <filename>include</filename> and <filename>require</filename> | ||
951 | directives. | ||
952 | <note> | ||
953 | The <filename>BBPATH</filename> variable is analogous to | ||
954 | the environment variable <filename>PATH</filename>. | ||
955 | </note> | ||
956 | </para> | ||
957 | |||
958 | <para> | ||
959 | In order for include and class files to be found by BitBake, | ||
960 | they need to be located in a "classes" subdirectory that can | ||
961 | be found in <filename>BBPATH</filename>. | ||
962 | </para> | ||
963 | </section> | ||
964 | |||
965 | <section id='inherit-directive'> | ||
966 | <title><filename>inherit</filename> Directive</title> | ||
967 | |||
968 | <para> | ||
969 | When writing a recipe or class file, you can use the | ||
970 | <filename>inherit</filename> directive to inherit the | ||
971 | functionality of a class (<filename>.bbclass</filename>). | ||
972 | BitBake only supports this directive when used within recipe | ||
973 | and class files (i.e. <filename>.bb</filename> and | ||
974 | <filename>.bbclass</filename>). | ||
975 | </para> | ||
976 | |||
977 | <para> | ||
978 | The <filename>inherit</filename> directive is a rudimentary | ||
979 | means of specifying functionality contained in class files | ||
980 | that your recipes require. | ||
981 | For example, you can easily abstract out the tasks involved in | ||
982 | building a package that uses Autoconf and Automake and put | ||
983 | those tasks into a class file and then have your recipe | ||
984 | inherit that class file. | ||
985 | </para> | ||
986 | |||
987 | <para> | ||
988 | As an example, your recipes could use the following directive | ||
989 | to inherit an <filename>autotools.bbclass</filename> file. | ||
990 | The class file would contain common functionality for using | ||
991 | Autotools that could be shared across recipes: | ||
992 | <literallayout class='monospaced'> | ||
993 | inherit autotools | ||
994 | </literallayout> | ||
995 | In this case, BitBake would search for the directory | ||
996 | <filename>classes/autotools.bbclass</filename> | ||
997 | in <filename>BBPATH</filename>. | ||
998 | <note> | ||
999 | You can override any values and functions of the | ||
1000 | inherited class within your recipe by doing so | ||
1001 | after the "inherit" statement. | ||
1002 | </note> | ||
1003 | If you want to use the directive to inherit | ||
1004 | multiple classes, separate them with spaces. | ||
1005 | The following example shows how to inherit both the | ||
1006 | <filename>buildhistory</filename> and <filename>rm_work</filename> | ||
1007 | classes: | ||
1008 | <literallayout class='monospaced'> | ||
1009 | inherit buildhistory rm_work | ||
1010 | </literallayout> | ||
1011 | </para> | ||
1012 | |||
1013 | <para> | ||
1014 | An advantage with the inherit directive as compared to both | ||
1015 | the | ||
1016 | <link linkend='include-directive'>include</link> and | ||
1017 | <link linkend='require-inclusion'>require</link> directives | ||
1018 | is that you can inherit class files conditionally. | ||
1019 | You can accomplish this by using a variable expression | ||
1020 | after the <filename>inherit</filename> statement. | ||
1021 | Here is an example: | ||
1022 | <literallayout class='monospaced'> | ||
1023 | inherit ${VARNAME} | ||
1024 | </literallayout> | ||
1025 | If <filename>VARNAME</filename> is going to be set, it needs | ||
1026 | to be set before the <filename>inherit</filename> statement | ||
1027 | is parsed. | ||
1028 | One way to achieve a conditional inherit in this case is to use | ||
1029 | overrides: | ||
1030 | <literallayout class='monospaced'> | ||
1031 | VARIABLE = "" | ||
1032 | VARIABLE_someoverride = "myclass" | ||
1033 | </literallayout> | ||
1034 | </para> | ||
1035 | |||
1036 | <para> | ||
1037 | Another method is by using anonymous Python. | ||
1038 | Here is an example: | ||
1039 | <literallayout class='monospaced'> | ||
1040 | python () { | ||
1041 | if condition == value: | ||
1042 | d.setVar('VARIABLE', 'myclass') | ||
1043 | else: | ||
1044 | d.setVar('VARIABLE', '') | ||
1045 | } | ||
1046 | </literallayout> | ||
1047 | </para> | ||
1048 | |||
1049 | <para> | ||
1050 | Alternatively, you could use an in-line Python expression | ||
1051 | in the following form: | ||
1052 | <literallayout class='monospaced'> | ||
1053 | inherit ${@'classname' if condition else ''} | ||
1054 | inherit ${@functionname(params)} | ||
1055 | </literallayout> | ||
1056 | In all cases, if the expression evaluates to an empty | ||
1057 | string, the statement does not trigger a syntax error | ||
1058 | because it becomes a no-op. | ||
1059 | </para> | ||
1060 | </section> | ||
1061 | |||
1062 | <section id='include-directive'> | ||
1063 | <title><filename>include</filename> Directive</title> | ||
1064 | |||
1065 | <para> | ||
1066 | BitBake understands the <filename>include</filename> | ||
1067 | directive. | ||
1068 | This directive causes BitBake to parse whatever file you specify, | ||
1069 | and to insert that file at that location. | ||
1070 | The directive is much like its equivalent in Make except | ||
1071 | that if the path specified on the include line is a relative | ||
1072 | path, BitBake locates the first file it can find | ||
1073 | within <filename>BBPATH</filename>. | ||
1074 | </para> | ||
1075 | |||
1076 | <para> | ||
1077 | The include directive is a more generic method of including | ||
1078 | functionality as compared to the | ||
1079 | <link linkend='inherit-directive'>inherit</link> directive, | ||
1080 | which is restricted to class (i.e. <filename>.bbclass</filename>) | ||
1081 | files. | ||
1082 | The include directive is applicable for any other kind of | ||
1083 | shared or encapsulated functionality or configuration that | ||
1084 | does not suit a <filename>.bbclass</filename> file. | ||
1085 | </para> | ||
1086 | |||
1087 | <para> | ||
1088 | As an example, suppose you needed a recipe to include some | ||
1089 | self-test definitions: | ||
1090 | <literallayout class='monospaced'> | ||
1091 | include test_defs.inc | ||
1092 | </literallayout> | ||
1093 | <note> | ||
1094 | The <filename>include</filename> directive does not | ||
1095 | produce an error when the file cannot be found. | ||
1096 | Consequently, it is recommended that if the file you | ||
1097 | are including is expected to exist, you should use | ||
1098 | <link linkend='require-inclusion'><filename>require</filename></link> | ||
1099 | instead of <filename>include</filename>. | ||
1100 | Doing so makes sure that an error is produced if the | ||
1101 | file cannot be found. | ||
1102 | </note> | ||
1103 | </para> | ||
1104 | </section> | ||
1105 | |||
1106 | <section id='require-inclusion'> | ||
1107 | <title><filename>require</filename> Directive</title> | ||
1108 | |||
1109 | <para> | ||
1110 | BitBake understands the <filename>require</filename> | ||
1111 | directive. | ||
1112 | This directive behaves just like the | ||
1113 | <filename>include</filename> directive with the exception that | ||
1114 | BitBake raises a parsing error if the file to be included cannot | ||
1115 | be found. | ||
1116 | Thus, any file you require is inserted into the file that is | ||
1117 | being parsed at the location of the directive. | ||
1118 | </para> | ||
1119 | |||
1120 | <para> | ||
1121 | The require directive, like the include directive previously | ||
1122 | described, is a more generic method of including | ||
1123 | functionality as compared to the | ||
1124 | <link linkend='inherit-directive'>inherit</link> directive, | ||
1125 | which is restricted to class (i.e. <filename>.bbclass</filename>) | ||
1126 | files. | ||
1127 | The require directive is applicable for any other kind of | ||
1128 | shared or encapsulated functionality or configuration that | ||
1129 | does not suit a <filename>.bbclass</filename> file. | ||
1130 | </para> | ||
1131 | |||
1132 | <para> | ||
1133 | Similar to how BitBake handles | ||
1134 | <link linkend='include-directive'><filename>include</filename></link>, | ||
1135 | if the path specified | ||
1136 | on the require line is a relative path, BitBake locates | ||
1137 | the first file it can find within <filename>BBPATH</filename>. | ||
1138 | </para> | ||
1139 | |||
1140 | <para> | ||
1141 | As an example, suppose you have two versions of a recipe | ||
1142 | (e.g. <filename>foo_1.2.2.bb</filename> and | ||
1143 | <filename>foo_2.0.0.bb</filename>) where | ||
1144 | each version contains some identical functionality that could be | ||
1145 | shared. | ||
1146 | You could create an include file named <filename>foo.inc</filename> | ||
1147 | that contains the common definitions needed to build "foo". | ||
1148 | You need to be sure <filename>foo.inc</filename> is located in the | ||
1149 | same directory as your two recipe files as well. | ||
1150 | Once these conditions are set up, you can share the functionality | ||
1151 | using a <filename>require</filename> directive from within each | ||
1152 | recipe: | ||
1153 | <literallayout class='monospaced'> | ||
1154 | require foo.inc | ||
1155 | </literallayout> | ||
1156 | </para> | ||
1157 | </section> | ||
1158 | |||
1159 | <section id='inherit-configuration-directive'> | ||
1160 | <title><filename>INHERIT</filename> Configuration Directive</title> | ||
1161 | |||
1162 | <para> | ||
1163 | When creating a configuration file (<filename>.conf</filename>), | ||
1164 | you can use the | ||
1165 | <link linkend='var-bb-INHERIT'><filename>INHERIT</filename></link> | ||
1166 | configuration directive to inherit a class. | ||
1167 | BitBake only supports this directive when used within | ||
1168 | a configuration file. | ||
1169 | </para> | ||
1170 | |||
1171 | <para> | ||
1172 | As an example, suppose you needed to inherit a class | ||
1173 | file called <filename>abc.bbclass</filename> from a | ||
1174 | configuration file as follows: | ||
1175 | <literallayout class='monospaced'> | ||
1176 | INHERIT += "abc" | ||
1177 | </literallayout> | ||
1178 | This configuration directive causes the named | ||
1179 | class to be inherited at the point of the directive | ||
1180 | during parsing. | ||
1181 | As with the <filename>inherit</filename> directive, the | ||
1182 | <filename>.bbclass</filename> file must be located in a | ||
1183 | "classes" subdirectory in one of the directories specified | ||
1184 | in <filename>BBPATH</filename>. | ||
1185 | <note> | ||
1186 | Because <filename>.conf</filename> files are parsed | ||
1187 | first during BitBake's execution, using | ||
1188 | <filename>INHERIT</filename> to inherit a class effectively | ||
1189 | inherits the class globally (i.e. for all recipes). | ||
1190 | </note> | ||
1191 | If you want to use the directive to inherit | ||
1192 | multiple classes, you can provide them on the same line in the | ||
1193 | <filename>local.conf</filename> file. | ||
1194 | Use spaces to separate the classes. | ||
1195 | The following example shows how to inherit both the | ||
1196 | <filename>autotools</filename> and <filename>pkgconfig</filename> | ||
1197 | classes: | ||
1198 | <literallayout class='monospaced'> | ||
1199 | INHERIT += "autotools pkgconfig" | ||
1200 | </literallayout> | ||
1201 | </para> | ||
1202 | </section> | ||
1203 | </section> | ||
1204 | |||
1205 | <section id='functions'> | ||
1206 | <title>Functions</title> | ||
1207 | |||
1208 | <para> | ||
1209 | As with most languages, functions are the building blocks that | ||
1210 | are used to build up operations into tasks. | ||
1211 | BitBake supports these types of functions: | ||
1212 | <itemizedlist> | ||
1213 | <listitem><para><emphasis>Shell Functions:</emphasis> | ||
1214 | Functions written in shell script and executed either | ||
1215 | directly as functions, tasks, or both. | ||
1216 | They can also be called by other shell functions. | ||
1217 | </para></listitem> | ||
1218 | <listitem><para><emphasis>BitBake-Style Python Functions:</emphasis> | ||
1219 | Functions written in Python and executed by BitBake or other | ||
1220 | Python functions using <filename>bb.build.exec_func()</filename>. | ||
1221 | </para></listitem> | ||
1222 | <listitem><para><emphasis>Python Functions:</emphasis> | ||
1223 | Functions written in Python and executed by Python. | ||
1224 | </para></listitem> | ||
1225 | <listitem><para><emphasis>Anonymous Python Functions:</emphasis> | ||
1226 | Python functions executed automatically during | ||
1227 | parsing. | ||
1228 | </para></listitem> | ||
1229 | </itemizedlist> | ||
1230 | Regardless of the type of function, you can only | ||
1231 | define them in class (<filename>.bbclass</filename>) | ||
1232 | and recipe (<filename>.bb</filename> or <filename>.inc</filename>) | ||
1233 | files. | ||
1234 | </para> | ||
1235 | |||
1236 | <section id='shell-functions'> | ||
1237 | <title>Shell Functions</title> | ||
1238 | |||
1239 | <para> | ||
1240 | Functions written in shell script and executed either | ||
1241 | directly as functions, tasks, or both. | ||
1242 | They can also be called by other shell functions. | ||
1243 | Here is an example shell function definition: | ||
1244 | <literallayout class='monospaced'> | ||
1245 | some_function () { | ||
1246 | echo "Hello World" | ||
1247 | } | ||
1248 | </literallayout> | ||
1249 | When you create these types of functions in your recipe | ||
1250 | or class files, you need to follow the shell programming | ||
1251 | rules. | ||
1252 | The scripts are executed by <filename>/bin/sh</filename>, | ||
1253 | which may not be a bash shell but might be something | ||
1254 | such as <filename>dash</filename>. | ||
1255 | You should not use Bash-specific script (bashisms). | ||
1256 | </para> | ||
1257 | |||
1258 | <para> | ||
1259 | Overrides and override-style operators like | ||
1260 | <filename>_append</filename> and | ||
1261 | <filename>_prepend</filename> can also be applied to | ||
1262 | shell functions. | ||
1263 | Most commonly, this application would be used in a | ||
1264 | <filename>.bbappend</filename> file to modify functions in | ||
1265 | the main recipe. | ||
1266 | It can also be used to modify functions inherited from | ||
1267 | classes. | ||
1268 | </para> | ||
1269 | |||
1270 | <para> | ||
1271 | As an example, consider the following: | ||
1272 | <literallayout class='monospaced'> | ||
1273 | do_foo() { | ||
1274 | bbplain first | ||
1275 | fn | ||
1276 | } | ||
1277 | |||
1278 | fn_prepend() { | ||
1279 | bbplain second | ||
1280 | } | ||
1281 | |||
1282 | fn() { | ||
1283 | bbplain third | ||
1284 | } | ||
1285 | |||
1286 | do_foo_append() { | ||
1287 | bbplain fourth | ||
1288 | } | ||
1289 | </literallayout> | ||
1290 | Running <filename>do_foo</filename> | ||
1291 | prints the following: | ||
1292 | <literallayout class='monospaced'> | ||
1293 | recipename do_foo: first | ||
1294 | recipename do_foo: second | ||
1295 | recipename do_foo: third | ||
1296 | recipename do_foo: fourth | ||
1297 | </literallayout> | ||
1298 | <note> | ||
1299 | Overrides and override-style operators can | ||
1300 | be applied to any shell function, not just | ||
1301 | <link linkend='tasks'>tasks</link>. | ||
1302 | </note> | ||
1303 | You can use the <filename>bitbake -e</filename> <replaceable>recipename</replaceable> | ||
1304 | command to view the final assembled function | ||
1305 | after all overrides have been applied. | ||
1306 | </para> | ||
1307 | </section> | ||
1308 | |||
1309 | <section id='bitbake-style-python-functions'> | ||
1310 | <title>BitBake-Style Python Functions</title> | ||
1311 | |||
1312 | <para> | ||
1313 | These functions are written in Python and executed by | ||
1314 | BitBake or other Python functions using | ||
1315 | <filename>bb.build.exec_func()</filename>. | ||
1316 | </para> | ||
1317 | |||
1318 | <para> | ||
1319 | An example BitBake function is: | ||
1320 | <literallayout class='monospaced'> | ||
1321 | python some_python_function () { | ||
1322 | d.setVar("TEXT", "Hello World") | ||
1323 | print d.getVar("TEXT") | ||
1324 | } | ||
1325 | </literallayout> | ||
1326 | Because the Python "bb" and "os" modules are already | ||
1327 | imported, you do not need to import these modules. | ||
1328 | Also in these types of functions, the datastore ("d") | ||
1329 | is a global variable and is always automatically | ||
1330 | available. | ||
1331 | <note> | ||
1332 | Variable expressions (e.g. <filename>${X}</filename>) | ||
1333 | are no longer expanded within Python functions. | ||
1334 | This behavior is intentional in order to allow you | ||
1335 | to freely set variable values to expandable expressions | ||
1336 | without having them expanded prematurely. | ||
1337 | If you do wish to expand a variable within a Python | ||
1338 | function, use <filename>d.getVar("X")</filename>. | ||
1339 | Or, for more complicated expressions, use | ||
1340 | <filename>d.expand()</filename>. | ||
1341 | </note> | ||
1342 | </para> | ||
1343 | |||
1344 | <para> | ||
1345 | Similar to shell functions, you can also apply overrides | ||
1346 | and override-style operators to BitBake-style Python | ||
1347 | functions. | ||
1348 | </para> | ||
1349 | |||
1350 | <para> | ||
1351 | As an example, consider the following: | ||
1352 | <literallayout class='monospaced'> | ||
1353 | python do_foo_prepend() { | ||
1354 | bb.plain("first") | ||
1355 | } | ||
1356 | |||
1357 | python do_foo() { | ||
1358 | bb.plain("second") | ||
1359 | } | ||
1360 | |||
1361 | python do_foo_append() { | ||
1362 | bb.plain("third") | ||
1363 | } | ||
1364 | </literallayout> | ||
1365 | Running <filename>do_foo</filename> prints | ||
1366 | the following: | ||
1367 | <literallayout class='monospaced'> | ||
1368 | recipename do_foo: first | ||
1369 | recipename do_foo: second | ||
1370 | recipename do_foo: third | ||
1371 | </literallayout> | ||
1372 | You can use the <filename>bitbake -e</filename> <replaceable>recipename</replaceable> | ||
1373 | command to view the final assembled function | ||
1374 | after all overrides have been applied. | ||
1375 | </para> | ||
1376 | </section> | ||
1377 | |||
1378 | <section id='python-functions'> | ||
1379 | <title>Python Functions</title> | ||
1380 | |||
1381 | <para> | ||
1382 | These functions are written in Python and are executed by | ||
1383 | other Python code. | ||
1384 | Examples of Python functions are utility functions | ||
1385 | that you intend to call from in-line Python or | ||
1386 | from within other Python functions. | ||
1387 | Here is an example: | ||
1388 | <literallayout class='monospaced'> | ||
1389 | def get_depends(d): | ||
1390 | if d.getVar('SOMECONDITION'): | ||
1391 | return "dependencywithcond" | ||
1392 | else: | ||
1393 | return "dependency" | ||
1394 | SOMECONDITION = "1" | ||
1395 | DEPENDS = "${@get_depends(d)}" | ||
1396 | </literallayout> | ||
1397 | This would result in <filename>DEPENDS</filename> | ||
1398 | containing <filename>dependencywithcond</filename>. | ||
1399 | </para> | ||
1400 | |||
1401 | <para> | ||
1402 | Here are some things to know about Python functions: | ||
1403 | <itemizedlist> | ||
1404 | <listitem><para>Python functions can take parameters. | ||
1405 | </para></listitem> | ||
1406 | <listitem><para>The BitBake datastore is not | ||
1407 | automatically available. | ||
1408 | Consequently, you must pass it in as a | ||
1409 | parameter to the function. | ||
1410 | </para></listitem> | ||
1411 | <listitem><para>The "bb" and "os" Python modules are | ||
1412 | automatically available. | ||
1413 | You do not need to import them. | ||
1414 | </para></listitem> | ||
1415 | </itemizedlist> | ||
1416 | </para> | ||
1417 | </section> | ||
1418 | |||
1419 | <section id='bitbake-style-python-functions-versus-python-functions'> | ||
1420 | <title>BitBake-Style Python Functions Versus Python Functions</title> | ||
1421 | |||
1422 | <para> | ||
1423 | Following are some important differences between | ||
1424 | BitBake-style Python functions and regular Python | ||
1425 | functions defined with "def": | ||
1426 | <itemizedlist> | ||
1427 | <listitem><para> | ||
1428 | Only BitBake-style Python functions can be | ||
1429 | <link linkend='tasks'>tasks</link>. | ||
1430 | </para></listitem> | ||
1431 | <listitem><para> | ||
1432 | Overrides and override-style operators can only | ||
1433 | be applied to BitBake-style Python functions. | ||
1434 | </para></listitem> | ||
1435 | <listitem><para> | ||
1436 | Only regular Python functions can take arguments | ||
1437 | and return values. | ||
1438 | </para></listitem> | ||
1439 | <listitem><para> | ||
1440 | <link linkend='variable-flags'>Variable flags</link> | ||
1441 | such as <filename>[dirs]</filename>, | ||
1442 | <filename>[cleandirs]</filename>, and | ||
1443 | <filename>[lockfiles]</filename> can be used | ||
1444 | on BitBake-style Python functions, but not on | ||
1445 | regular Python functions. | ||
1446 | </para></listitem> | ||
1447 | <listitem><para> | ||
1448 | BitBake-style Python functions generate a separate | ||
1449 | <filename>${</filename><link linkend='var-bb-T'><filename>T</filename></link><filename>}/run.</filename><replaceable>function-name</replaceable><filename>.</filename><replaceable>pid</replaceable> | ||
1450 | script that is executed to run the function, and also | ||
1451 | generate a log file in | ||
1452 | <filename>${T}/log.</filename><replaceable>function-name</replaceable><filename>.</filename><replaceable>pid</replaceable> | ||
1453 | if they are executed as tasks.</para> | ||
1454 | |||
1455 | <para> | ||
1456 | Regular Python functions execute "inline" and do not | ||
1457 | generate any files in <filename>${T}</filename>. | ||
1458 | </para></listitem> | ||
1459 | <listitem><para> | ||
1460 | Regular Python functions are called with the usual | ||
1461 | Python syntax. | ||
1462 | BitBake-style Python functions are usually tasks and | ||
1463 | are called directly by BitBake, but can also be called | ||
1464 | manually from Python code by using the | ||
1465 | <filename>bb.build.exec_func()</filename> function. | ||
1466 | Here is an example: | ||
1467 | <literallayout class='monospaced'> | ||
1468 | bb.build.exec_func("my_bitbake_style_function", d) | ||
1469 | </literallayout> | ||
1470 | <note> | ||
1471 | <filename>bb.build.exec_func()</filename> can also | ||
1472 | be used to run shell functions from Python code. | ||
1473 | If you want to run a shell function before a Python | ||
1474 | function within the same task, then you can use a | ||
1475 | parent helper Python function that starts by running | ||
1476 | the shell function with | ||
1477 | <filename>bb.build.exec_func()</filename> and then | ||
1478 | runs the Python code. | ||
1479 | </note></para> | ||
1480 | |||
1481 | <para>To detect errors from functions executed with | ||
1482 | <filename>bb.build.exec_func()</filename>, you | ||
1483 | can catch the <filename>bb.build.FuncFailed</filename> | ||
1484 | exception. | ||
1485 | <note> | ||
1486 | Functions in metadata (recipes and classes) should | ||
1487 | not themselves raise | ||
1488 | <filename>bb.build.FuncFailed</filename>. | ||
1489 | Rather, <filename>bb.build.FuncFailed</filename> | ||
1490 | should be viewed as a general indicator that the | ||
1491 | called function failed by raising an exception. | ||
1492 | For example, an exception raised by | ||
1493 | <filename>bb.fatal()</filename> will be caught inside | ||
1494 | <filename>bb.build.exec_func()</filename>, and a | ||
1495 | <filename>bb.build.FuncFailed</filename> will be raised | ||
1496 | in response. | ||
1497 | </note> | ||
1498 | </para></listitem> | ||
1499 | </itemizedlist> | ||
1500 | </para> | ||
1501 | |||
1502 | <para> | ||
1503 | Due to their simplicity, you should prefer regular Python functions | ||
1504 | over BitBake-style Python functions unless you need a feature specific | ||
1505 | to BitBake-style Python functions. | ||
1506 | Regular Python functions in metadata are a more recent invention than | ||
1507 | BitBake-style Python functions, and older code tends to use | ||
1508 | <filename>bb.build.exec_func()</filename> more often. | ||
1509 | </para> | ||
1510 | </section> | ||
1511 | |||
1512 | <section id='anonymous-python-functions'> | ||
1513 | <title>Anonymous Python Functions</title> | ||
1514 | |||
1515 | <para> | ||
1516 | Sometimes it is useful to set variables or perform | ||
1517 | other operations programmatically during parsing. | ||
1518 | To do this, you can define special Python functions, | ||
1519 | called anonymous Python functions, that run at the | ||
1520 | end of parsing. | ||
1521 | For example, the following conditionally sets a variable | ||
1522 | based on the value of another variable: | ||
1523 | <literallayout class='monospaced'> | ||
1524 | python () { | ||
1525 | if d.getVar('SOMEVAR') == 'value': | ||
1526 | d.setVar('ANOTHERVAR', 'value2') | ||
1527 | } | ||
1528 | </literallayout> | ||
1529 | An equivalent way to mark a function as an anonymous | ||
1530 | function is to give it the name "__anonymous", rather | ||
1531 | than no name. | ||
1532 | </para> | ||
1533 | |||
1534 | <para> | ||
1535 | Anonymous Python functions always run at the end | ||
1536 | of parsing, regardless of where they are defined. | ||
1537 | If a recipe contains many anonymous functions, they | ||
1538 | run in the same order as they are defined within the | ||
1539 | recipe. | ||
1540 | As an example, consider the following snippet: | ||
1541 | <literallayout class='monospaced'> | ||
1542 | python () { | ||
1543 | d.setVar('FOO', 'foo 2') | ||
1544 | } | ||
1545 | |||
1546 | FOO = "foo 1" | ||
1547 | |||
1548 | python () { | ||
1549 | d.appendVar('BAR', ' bar 2') | ||
1550 | } | ||
1551 | |||
1552 | BAR = "bar 1" | ||
1553 | </literallayout> | ||
1554 | The previous example is conceptually equivalent to the | ||
1555 | following snippet: | ||
1556 | <literallayout class='monospaced'> | ||
1557 | FOO = "foo 1" | ||
1558 | BAR = "bar 1" | ||
1559 | FOO = "foo 2" | ||
1560 | BAR += "bar 2" | ||
1561 | </literallayout> | ||
1562 | <filename>FOO</filename> ends up with the value "foo 2", | ||
1563 | and <filename>BAR</filename> with the value "bar 1 bar 2". | ||
1564 | Just as in the second snippet, the values set for the | ||
1565 | variables within the anonymous functions become available | ||
1566 | to tasks, which always run after parsing. | ||
1567 | </para> | ||
1568 | |||
1569 | <para> | ||
1570 | Overrides and override-style operators such as | ||
1571 | "<filename>_append</filename>" are applied before | ||
1572 | anonymous functions run. | ||
1573 | In the following example, <filename>FOO</filename> ends | ||
1574 | up with the value "foo from anonymous": | ||
1575 | <literallayout class='monospaced'> | ||
1576 | FOO = "foo" | ||
1577 | FOO_append = " from outside" | ||
1578 | |||
1579 | python () { | ||
1580 | d.setVar("FOO", "foo from anonymous") | ||
1581 | } | ||
1582 | </literallayout> | ||
1583 | For methods you can use with anonymous Python functions, | ||
1584 | see the | ||
1585 | "<link linkend='functions-you-can-call-from-within-python'>Functions You Can Call From Within Python</link>" | ||
1586 | section. | ||
1587 | For a different method to run Python code during parsing, | ||
1588 | see the | ||
1589 | "<link linkend='inline-python-variable-expansion'>Inline Python Variable Expansion</link>" | ||
1590 | section. | ||
1591 | </para> | ||
1592 | </section> | ||
1593 | |||
1594 | <section id='flexible-inheritance-for-class-functions'> | ||
1595 | <title>Flexible Inheritance for Class Functions</title> | ||
1596 | |||
1597 | <para> | ||
1598 | Through coding techniques and the use of | ||
1599 | <filename>EXPORT_FUNCTIONS</filename>, BitBake supports | ||
1600 | exporting a function from a class such that the | ||
1601 | class function appears as the default implementation | ||
1602 | of the function, but can still be called if a recipe | ||
1603 | inheriting the class needs to define its own version of | ||
1604 | the function. | ||
1605 | </para> | ||
1606 | |||
1607 | <para> | ||
1608 | To understand the benefits of this feature, consider | ||
1609 | the basic scenario where a class defines a task function | ||
1610 | and your recipe inherits the class. | ||
1611 | In this basic scenario, your recipe inherits the task | ||
1612 | function as defined in the class. | ||
1613 | If desired, your recipe can add to the start and end of the | ||
1614 | function by using the "_prepend" or "_append" operations | ||
1615 | respectively, or it can redefine the function completely. | ||
1616 | However, if it redefines the function, there is | ||
1617 | no means for it to call the class version of the function. | ||
1618 | <filename>EXPORT_FUNCTIONS</filename> provides a mechanism | ||
1619 | that enables the recipe's version of the function to call | ||
1620 | the original version of the function. | ||
1621 | </para> | ||
1622 | |||
1623 | <para> | ||
1624 | To make use of this technique, you need the following | ||
1625 | things in place: | ||
1626 | <itemizedlist> | ||
1627 | <listitem><para> | ||
1628 | The class needs to define the function as follows: | ||
1629 | <literallayout class='monospaced'> | ||
1630 | <replaceable>classname</replaceable><filename>_</filename><replaceable>functionname</replaceable> | ||
1631 | </literallayout> | ||
1632 | For example, if you have a class file | ||
1633 | <filename>bar.bbclass</filename> and a function named | ||
1634 | <filename>do_foo</filename>, the class must define the function | ||
1635 | as follows: | ||
1636 | <literallayout class='monospaced'> | ||
1637 | bar_do_foo | ||
1638 | </literallayout> | ||
1639 | </para></listitem> | ||
1640 | <listitem><para> | ||
1641 | The class needs to contain the <filename>EXPORT_FUNCTIONS</filename> | ||
1642 | statement as follows: | ||
1643 | <literallayout class='monospaced'> | ||
1644 | EXPORT_FUNCTIONS <replaceable>functionname</replaceable> | ||
1645 | </literallayout> | ||
1646 | For example, continuing with the same example, the | ||
1647 | statement in the <filename>bar.bbclass</filename> would be | ||
1648 | as follows: | ||
1649 | <literallayout class='monospaced'> | ||
1650 | EXPORT_FUNCTIONS do_foo | ||
1651 | </literallayout> | ||
1652 | </para></listitem> | ||
1653 | <listitem><para> | ||
1654 | You need to call the function appropriately from within your | ||
1655 | recipe. | ||
1656 | Continuing with the same example, if your recipe | ||
1657 | needs to call the class version of the function, | ||
1658 | it should call <filename>bar_do_foo</filename>. | ||
1659 | Assuming <filename>do_foo</filename> was a shell function | ||
1660 | and <filename>EXPORT_FUNCTIONS</filename> was used as above, | ||
1661 | the recipe's function could conditionally call the | ||
1662 | class version of the function as follows: | ||
1663 | <literallayout class='monospaced'> | ||
1664 | do_foo() { | ||
1665 | if [ somecondition ] ; then | ||
1666 | bar_do_foo | ||
1667 | else | ||
1668 | # Do something else | ||
1669 | fi | ||
1670 | } | ||
1671 | </literallayout> | ||
1672 | To call your modified version of the function as defined | ||
1673 | in your recipe, call it as <filename>do_foo</filename>. | ||
1674 | </para></listitem> | ||
1675 | </itemizedlist> | ||
1676 | With these conditions met, your single recipe | ||
1677 | can freely choose between the original function | ||
1678 | as defined in the class file and the modified function in your recipe. | ||
1679 | If you do not set up these conditions, you are limited to using one function | ||
1680 | or the other. | ||
1681 | </para> | ||
1682 | </section> | ||
1683 | </section> | ||
1684 | |||
1685 | <section id='tasks'> | ||
1686 | <title>Tasks</title> | ||
1687 | |||
1688 | <para> | ||
1689 | Tasks are BitBake execution units that make up the | ||
1690 | steps that BitBake can run for a given recipe. | ||
1691 | Tasks are only supported in recipes and classes | ||
1692 | (i.e. in <filename>.bb</filename> files and files | ||
1693 | included or inherited from <filename>.bb</filename> | ||
1694 | files). | ||
1695 | By convention, tasks have names that start with "do_". | ||
1696 | </para> | ||
1697 | |||
1698 | <section id='promoting-a-function-to-a-task'> | ||
1699 | <title>Promoting a Function to a Task</title> | ||
1700 | |||
1701 | <para> | ||
1702 | Tasks are either | ||
1703 | <link linkend='shell-functions'>shell functions</link> or | ||
1704 | <link linkend='bitbake-style-python-functions'>BitBake-style Python functions</link> | ||
1705 | that have been promoted to tasks by using the | ||
1706 | <filename>addtask</filename> command. | ||
1707 | The <filename>addtask</filename> command can also | ||
1708 | optionally describe dependencies between the | ||
1709 | task and other tasks. | ||
1710 | Here is an example that shows how to define a task | ||
1711 | and declare some dependencies: | ||
1712 | <literallayout class='monospaced'> | ||
1713 | python do_printdate () { | ||
1714 | import time | ||
1715 | print time.strftime('%Y%m%d', time.gmtime()) | ||
1716 | } | ||
1717 | addtask printdate after do_fetch before do_build | ||
1718 | </literallayout> | ||
1719 | The first argument to <filename>addtask</filename> | ||
1720 | is the name of the function to promote to | ||
1721 | a task. | ||
1722 | If the name does not start with "do_", "do_" is | ||
1723 | implicitly added, which enforces the convention that | ||
1724 | all task names start with "do_". | ||
1725 | </para> | ||
1726 | |||
1727 | <para> | ||
1728 | In the previous example, the | ||
1729 | <filename>do_printdate</filename> task becomes a | ||
1730 | dependency of the <filename>do_build</filename> | ||
1731 | task, which is the default task (i.e. the task run by | ||
1732 | the <filename>bitbake</filename> command unless | ||
1733 | another task is specified explicitly). | ||
1734 | Additionally, the <filename>do_printdate</filename> | ||
1735 | task becomes dependent upon the | ||
1736 | <filename>do_fetch</filename> task. | ||
1737 | Running the <filename>do_build</filename> task | ||
1738 | results in the <filename>do_printdate</filename> | ||
1739 | task running first. | ||
1740 | <note> | ||
1741 | If you try out the previous example, you might see that | ||
1742 | the <filename>do_printdate</filename> task is only run | ||
1743 | the first time you build the recipe with | ||
1744 | the <filename>bitbake</filename> command. | ||
1745 | This is because BitBake considers the task "up-to-date" | ||
1746 | after that initial run. | ||
1747 | If you want to force the task to always be rerun for | ||
1748 | experimentation purposes, you can make BitBake always | ||
1749 | consider the task "out-of-date" by using the | ||
1750 | <filename>[</filename><link linkend='variable-flags'><filename>nostamp</filename></link><filename>]</filename> | ||
1751 | variable flag, as follows: | ||
1752 | <literallayout class='monospaced'> | ||
1753 | do_printdate[nostamp] = "1" | ||
1754 | </literallayout> | ||
1755 | You can also explicitly run the task and provide the | ||
1756 | <filename>-f</filename> option as follows: | ||
1757 | <literallayout class='monospaced'> | ||
1758 | $ bitbake <replaceable>recipe</replaceable> -c printdate -f | ||
1759 | </literallayout> | ||
1760 | When manually selecting a task to run with the | ||
1761 | <filename>bitbake</filename> <replaceable>recipe</replaceable> <filename>-c</filename> <replaceable>task</replaceable> | ||
1762 | command, you can omit the "do_" prefix as part of the | ||
1763 | task name. | ||
1764 | </note> | ||
1765 | </para> | ||
1766 | |||
1767 | <para> | ||
1768 | You might wonder about the practical effects of using | ||
1769 | <filename>addtask</filename> without specifying any | ||
1770 | dependencies as is done in the following example: | ||
1771 | <literallayout class='monospaced'> | ||
1772 | addtask printdate | ||
1773 | </literallayout> | ||
1774 | In this example, assuming dependencies have not been | ||
1775 | added through some other means, the only way to run | ||
1776 | the task is by explicitly selecting it with | ||
1777 | <filename>bitbake</filename> <replaceable>recipe</replaceable> <filename>-c printdate</filename>. | ||
1778 | You can use the | ||
1779 | <filename>do_listtasks</filename> task to list all tasks | ||
1780 | defined in a recipe as shown in the following example: | ||
1781 | <literallayout class='monospaced'> | ||
1782 | $ bitbake <replaceable>recipe</replaceable> -c listtasks | ||
1783 | </literallayout> | ||
1784 | For more information on task dependencies, see the | ||
1785 | "<link linkend='dependencies'>Dependencies</link>" | ||
1786 | section. | ||
1787 | </para> | ||
1788 | |||
1789 | <para> | ||
1790 | See the | ||
1791 | "<link linkend='variable-flags'>Variable Flags</link>" | ||
1792 | section for information on variable flags you can use with | ||
1793 | tasks. | ||
1794 | </para> | ||
1795 | </section> | ||
1796 | |||
1797 | <section id='deleting-a-task'> | ||
1798 | <title>Deleting a Task</title> | ||
1799 | |||
1800 | <para> | ||
1801 | As well as being able to add tasks, you can delete them. | ||
1802 | Simply use the <filename>deltask</filename> command to | ||
1803 | delete a task. | ||
1804 | For example, to delete the example task used in the previous | ||
1805 | sections, you would use: | ||
1806 | <literallayout class='monospaced'> | ||
1807 | deltask printdate | ||
1808 | </literallayout> | ||
1809 | If you delete a task using the <filename>deltask</filename> | ||
1810 | command and the task has dependencies, the dependencies are | ||
1811 | not reconnected. | ||
1812 | For example, suppose you have three tasks named | ||
1813 | <filename>do_a</filename>, <filename>do_b</filename>, and | ||
1814 | <filename>do_c</filename>. | ||
1815 | Furthermore, <filename>do_c</filename> is dependent on | ||
1816 | <filename>do_b</filename>, which in turn is dependent on | ||
1817 | <filename>do_a</filename>. | ||
1818 | Given this scenario, if you use <filename>deltask</filename> | ||
1819 | to delete <filename>do_b</filename>, the implicit dependency | ||
1820 | relationship between <filename>do_c</filename> and | ||
1821 | <filename>do_a</filename> through <filename>do_b</filename> | ||
1822 | no longer exists, and <filename>do_c</filename> dependencies | ||
1823 | are not updated to include <filename>do_a</filename>. | ||
1824 | Thus, <filename>do_c</filename> is free to run before | ||
1825 | <filename>do_a</filename>. | ||
1826 | </para> | ||
1827 | |||
1828 | <para> | ||
1829 | If you want dependencies such as these to remain intact, use | ||
1830 | the <filename>[noexec]</filename> varflag to disable the task | ||
1831 | instead of using the <filename>deltask</filename> command to | ||
1832 | delete it: | ||
1833 | <literallayout class='monospaced'> | ||
1834 | do_b[noexec] = "1" | ||
1835 | </literallayout> | ||
1836 | </para> | ||
1837 | </section> | ||
1838 | |||
1839 | <section id='passing-information-into-the-build-task-environment'> | ||
1840 | <title>Passing Information Into the Build Task Environment</title> | ||
1841 | |||
1842 | <para> | ||
1843 | When running a task, BitBake tightly controls the shell execution | ||
1844 | environment of the build tasks to make | ||
1845 | sure unwanted contamination from the build machine cannot | ||
1846 | influence the build. | ||
1847 | <note> | ||
1848 | By default, BitBake cleans the environment to include only those | ||
1849 | things exported or listed in its whitelist to ensure that the build | ||
1850 | environment is reproducible and consistent. | ||
1851 | You can prevent this "cleaning" by setting the | ||
1852 | <link linkend='var-bb-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link> | ||
1853 | variable. | ||
1854 | </note> | ||
1855 | Consequently, if you do want something to get passed into the | ||
1856 | build task environment, you must take these two steps: | ||
1857 | <orderedlist> | ||
1858 | <listitem><para> | ||
1859 | Tell BitBake to load what you want from the environment | ||
1860 | into the datastore. | ||
1861 | You can do so through the | ||
1862 | <link linkend='var-bb-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link> | ||
1863 | and | ||
1864 | <link linkend='var-bb-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link> | ||
1865 | variables. | ||
1866 | For example, assume you want to prevent the build system from | ||
1867 | accessing your <filename>$HOME/.ccache</filename> | ||
1868 | directory. | ||
1869 | The following command "whitelists" the environment variable | ||
1870 | <filename>CCACHE_DIR</filename> causing BitBake to allow that | ||
1871 | variable into the datastore: | ||
1872 | <literallayout class='monospaced'> | ||
1873 | export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" | ||
1874 | </literallayout></para></listitem> | ||
1875 | <listitem><para> | ||
1876 | Tell BitBake to export what you have loaded into the | ||
1877 | datastore to the task environment of every running task. | ||
1878 | Loading something from the environment into the datastore | ||
1879 | (previous step) only makes it available in the datastore. | ||
1880 | To export it to the task environment of every running task, | ||
1881 | use a command similar to the following in your local configuration | ||
1882 | file <filename>local.conf</filename> or your | ||
1883 | distribution configuration file: | ||
1884 | <literallayout class='monospaced'> | ||
1885 | export CCACHE_DIR | ||
1886 | </literallayout> | ||
1887 | <note> | ||
1888 | A side effect of the previous steps is that BitBake | ||
1889 | records the variable as a dependency of the build process | ||
1890 | in things like the setscene checksums. | ||
1891 | If doing so results in unnecessary rebuilds of tasks, you can | ||
1892 | whitelist the variable so that the setscene code | ||
1893 | ignores the dependency when it creates checksums. | ||
1894 | </note></para></listitem> | ||
1895 | </orderedlist> | ||
1896 | </para> | ||
1897 | |||
1898 | <para> | ||
1899 | Sometimes, it is useful to be able to obtain information | ||
1900 | from the original execution environment. | ||
1901 | BitBake saves a copy of the original environment into | ||
1902 | a special variable named | ||
1903 | <link linkend='var-bb-BB_ORIGENV'><filename>BB_ORIGENV</filename></link>. | ||
1904 | </para> | ||
1905 | |||
1906 | <para> | ||
1907 | The <filename>BB_ORIGENV</filename> variable returns a datastore | ||
1908 | object that can be queried using the standard datastore operators | ||
1909 | such as <filename>getVar(, False)</filename>. | ||
1910 | The datastore object is useful, for example, to find the original | ||
1911 | <filename>DISPLAY</filename> variable. | ||
1912 | Here is an example: | ||
1913 | <literallayout class='monospaced'> | ||
1914 | origenv = d.getVar("BB_ORIGENV", False) | ||
1915 | bar = origenv.getVar("BAR", False) | ||
1916 | </literallayout> | ||
1917 | The previous example returns <filename>BAR</filename> from the original | ||
1918 | execution environment. | ||
1919 | </para> | ||
1920 | </section> | ||
1921 | </section> | ||
1922 | |||
1923 | <section id='variable-flags'> | ||
1924 | <title>Variable Flags</title> | ||
1925 | |||
1926 | <para> | ||
1927 | Variable flags (varflags) help control a task's functionality | ||
1928 | and dependencies. | ||
1929 | BitBake reads and writes varflags to the datastore using the following | ||
1930 | command forms: | ||
1931 | <literallayout class='monospaced'> | ||
1932 | <replaceable>variable</replaceable> = d.getVarFlags("<replaceable>variable</replaceable>") | ||
1933 | self.d.setVarFlags("FOO", {"func": True}) | ||
1934 | </literallayout> | ||
1935 | </para> | ||
1936 | |||
1937 | <para> | ||
1938 | When working with varflags, the same syntax, with the exception of | ||
1939 | overrides, applies. | ||
1940 | In other words, you can set, append, and prepend varflags just like | ||
1941 | variables. | ||
1942 | See the | ||
1943 | "<link linkend='variable-flag-syntax'>Variable Flag Syntax</link>" | ||
1944 | section for details. | ||
1945 | </para> | ||
1946 | |||
1947 | <para> | ||
1948 | BitBake has a defined set of varflags available for recipes and | ||
1949 | classes. | ||
1950 | Tasks support a number of these flags which control various | ||
1951 | functionality of the task: | ||
1952 | <itemizedlist> | ||
1953 | <listitem><para><emphasis><filename>[cleandirs]</filename>:</emphasis> | ||
1954 | Empty directories that should be created before the | ||
1955 | task runs. | ||
1956 | Directories that already exist are removed and recreated | ||
1957 | to empty them. | ||
1958 | </para></listitem> | ||
1959 | <listitem><para><emphasis><filename>[depends]</filename>:</emphasis> | ||
1960 | Controls inter-task dependencies. | ||
1961 | See the | ||
1962 | <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> | ||
1963 | variable and the | ||
1964 | "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>" | ||
1965 | section for more information. | ||
1966 | </para></listitem> | ||
1967 | <listitem><para><emphasis><filename>[deptask]</filename>:</emphasis> | ||
1968 | Controls task build-time dependencies. | ||
1969 | See the | ||
1970 | <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> | ||
1971 | variable and the | ||
1972 | "<link linkend='build-dependencies'>Build Dependencies</link>" | ||
1973 | section for more information. | ||
1974 | </para></listitem> | ||
1975 | <listitem><para><emphasis><filename>[dirs]</filename>:</emphasis> | ||
1976 | Directories that should be created before the task runs. | ||
1977 | Directories that already exist are left as is. | ||
1978 | The last directory listed is used as the | ||
1979 | current working directory for the task. | ||
1980 | </para></listitem> | ||
1981 | <listitem><para><emphasis><filename>[lockfiles]</filename>:</emphasis> | ||
1982 | Specifies one or more lockfiles to lock while the task | ||
1983 | executes. | ||
1984 | Only one task may hold a lockfile, and any task that | ||
1985 | attempts to lock an already locked file will block until | ||
1986 | the lock is released. | ||
1987 | You can use this variable flag to accomplish mutual | ||
1988 | exclusion. | ||
1989 | </para></listitem> | ||
1990 | <listitem><para><emphasis><filename>[noexec]</filename>:</emphasis> | ||
1991 | When set to "1", marks the task as being empty, with | ||
1992 | no execution required. | ||
1993 | You can use the <filename>[noexec]</filename> flag to set up | ||
1994 | tasks as dependency placeholders, or to disable tasks defined | ||
1995 | elsewhere that are not needed in a particular recipe. | ||
1996 | </para></listitem> | ||
1997 | <listitem><para><emphasis><filename>[nostamp]</filename>:</emphasis> | ||
1998 | When set to "1", tells BitBake to not generate a stamp | ||
1999 | file for a task, which implies the task should always | ||
2000 | be executed. | ||
2001 | <note><title>Caution</title> | ||
2002 | Any task that depends (possibly indirectly) on a | ||
2003 | <filename>[nostamp]</filename> task will always be | ||
2004 | executed as well. | ||
2005 | This can cause unnecessary rebuilding if you are | ||
2006 | not careful. | ||
2007 | </note> | ||
2008 | </para></listitem> | ||
2009 | <listitem><para><emphasis><filename>[number_threads]</filename>:</emphasis> | ||
2010 | Limits tasks to a specific number of simultaneous threads | ||
2011 | during execution. | ||
2012 | This varflag is useful when your build host has a large number | ||
2013 | of cores but certain tasks need to be rate-limited due to various | ||
2014 | kinds of resource constraints (e.g. to avoid network throttling). | ||
2015 | <filename>number_threads</filename> works similarly to the | ||
2016 | <link linkend='var-bb-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> | ||
2017 | variable but is task-specific.</para> | ||
2018 | |||
2019 | <para>Set the value globally. | ||
2020 | For example, the following makes sure the | ||
2021 | <filename>do_fetch</filename> task uses no more than two | ||
2022 | simultaneous execution threads: | ||
2023 | <literallayout class='monospaced'> | ||
2024 | do_fetch[number_threads] = "2" | ||
2025 | </literallayout> | ||
2026 | <note><title>Warnings</title> | ||
2027 | <itemizedlist> | ||
2028 | <listitem><para> | ||
2029 | Setting the varflag in individual recipes rather | ||
2030 | than globally can result in unpredictable behavior. | ||
2031 | </para></listitem> | ||
2032 | <listitem><para> | ||
2033 | Setting the varflag to a value greater than the | ||
2034 | value used in the <filename>BB_NUMBER_THREADS</filename> | ||
2035 | variable causes <filename>number_threads</filename> | ||
2036 | to have no effect. | ||
2037 | </para></listitem> | ||
2038 | </itemizedlist> | ||
2039 | </note> | ||
2040 | </para></listitem> | ||
2041 | <listitem><para><emphasis><filename>[postfuncs]</filename>:</emphasis> | ||
2042 | List of functions to call after the completion of the task. | ||
2043 | </para></listitem> | ||
2044 | <listitem><para><emphasis><filename>[prefuncs]</filename>:</emphasis> | ||
2045 | List of functions to call before the task executes. | ||
2046 | </para></listitem> | ||
2047 | <listitem><para><emphasis><filename>[rdepends]</filename>:</emphasis> | ||
2048 | Controls inter-task runtime dependencies. | ||
2049 | See the | ||
2050 | <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link> | ||
2051 | variable, the | ||
2052 | <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> | ||
2053 | variable, and the | ||
2054 | "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>" | ||
2055 | section for more information. | ||
2056 | </para></listitem> | ||
2057 | <listitem><para><emphasis><filename>[rdeptask]</filename>:</emphasis> | ||
2058 | Controls task runtime dependencies. | ||
2059 | See the | ||
2060 | <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link> | ||
2061 | variable, the | ||
2062 | <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> | ||
2063 | variable, and the | ||
2064 | "<link linkend='runtime-dependencies'>Runtime Dependencies</link>" | ||
2065 | section for more information. | ||
2066 | </para></listitem> | ||
2067 | <listitem><para><emphasis><filename>[recideptask]</filename>:</emphasis> | ||
2068 | When set in conjunction with | ||
2069 | <filename>recrdeptask</filename>, specifies a task that | ||
2070 | should be inspected for additional dependencies. | ||
2071 | </para></listitem> | ||
2072 | <listitem><para><emphasis><filename>[recrdeptask]</filename>:</emphasis> | ||
2073 | Controls task recursive runtime dependencies. | ||
2074 | See the | ||
2075 | <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link> | ||
2076 | variable, the | ||
2077 | <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> | ||
2078 | variable, and the | ||
2079 | "<link linkend='recursive-dependencies'>Recursive Dependencies</link>" | ||
2080 | section for more information. | ||
2081 | </para></listitem> | ||
2082 | <listitem><para><emphasis><filename>[stamp-extra-info]</filename>:</emphasis> | ||
2083 | Extra stamp information to append to the task's stamp. | ||
2084 | As an example, OpenEmbedded uses this flag to allow | ||
2085 | machine-specific tasks. | ||
2086 | </para></listitem> | ||
2087 | <listitem><para><emphasis><filename>[umask]</filename>:</emphasis> | ||
2088 | The umask to run the task under. | ||
2089 | </para></listitem> | ||
2090 | </itemizedlist> | ||
2091 | </para> | ||
2092 | |||
2093 | <para> | ||
2094 | Several varflags are useful for controlling how signatures are | ||
2095 | calculated for variables. | ||
2096 | For more information on this process, see the | ||
2097 | "<link linkend='checksums'>Checksums (Signatures)</link>" | ||
2098 | section. | ||
2099 | <itemizedlist> | ||
2100 | <listitem><para><emphasis><filename>[vardeps]</filename>:</emphasis> | ||
2101 | Specifies a space-separated list of additional | ||
2102 | variables to add to a variable's dependencies | ||
2103 | for the purposes of calculating its signature. | ||
2104 | Adding variables to this list is useful, for example, when | ||
2105 | a function refers to a variable in a manner that | ||
2106 | does not allow BitBake to automatically determine | ||
2107 | that the variable is referred to. | ||
2108 | </para></listitem> | ||
2109 | <listitem><para><emphasis><filename>[vardepsexclude]</filename>:</emphasis> | ||
2110 | Specifies a space-separated list of variables | ||
2111 | that should be excluded from a variable's dependencies | ||
2112 | for the purposes of calculating its signature. | ||
2113 | </para></listitem> | ||
2114 | <listitem><para><emphasis><filename>[vardepvalue]</filename>:</emphasis> | ||
2115 | If set, instructs BitBake to ignore the actual | ||
2116 | value of the variable and instead use the specified | ||
2117 | value when calculating the variable's signature. | ||
2118 | </para></listitem> | ||
2119 | <listitem><para><emphasis><filename>[vardepvalueexclude]</filename>:</emphasis> | ||
2120 | Specifies a pipe-separated list of strings to exclude | ||
2121 | from the variable's value when calculating the | ||
2122 | variable's signature. | ||
2123 | </para></listitem> | ||
2124 | </itemizedlist> | ||
2125 | </para> | ||
2126 | </section> | ||
2127 | |||
2128 | <section id='events'> | ||
2129 | <title>Events</title> | ||
2130 | |||
2131 | <para> | ||
2132 | BitBake allows installation of event handlers within recipe | ||
2133 | and class files. | ||
2134 | Events are triggered at certain points during operation, such | ||
2135 | as the beginning of operation against a given recipe | ||
2136 | (i.e. <filename>*.bb</filename>), the start of a given task, | ||
2137 | a task failure, a task success, and so forth. | ||
2138 | The intent is to make it easy to do things like email | ||
2139 | notification on build failures. | ||
2140 | </para> | ||
2141 | |||
2142 | <para> | ||
2143 | Following is an example event handler that prints the name | ||
2144 | of the event and the content of the | ||
2145 | <filename>FILE</filename> variable: | ||
2146 | <literallayout class='monospaced'> | ||
2147 | addhandler myclass_eventhandler | ||
2148 | python myclass_eventhandler() { | ||
2149 | from bb.event import getName | ||
2150 | print("The name of the Event is %s" % getName(e)) | ||
2151 | print("The file we run for is %s" % d.getVar('FILE')) | ||
2152 | } | ||
2153 | myclass_eventhandler[eventmask] = "bb.event.BuildStarted bb.event.BuildCompleted" | ||
2154 | </literallayout> | ||
2155 | In the previous example, an eventmask has been set so that | ||
2156 | the handler only sees the "BuildStarted" and "BuildCompleted" | ||
2157 | events. | ||
2158 | This event handler gets called every time an event matching | ||
2159 | the eventmask is triggered. | ||
2160 | A global variable "e" is defined, which represents the current | ||
2161 | event. | ||
2162 | With the <filename>getName(e)</filename> method, you can get | ||
2163 | the name of the triggered event. | ||
2164 | The global datastore is available as "d". | ||
2165 | In legacy code, you might see "e.data" used to get the datastore. | ||
2166 | However, realize that "e.data" is deprecated and you should use | ||
2167 | "d" going forward. | ||
2168 | </para> | ||
2169 | |||
2170 | <para> | ||
2171 | The context of the datastore is appropriate to the event | ||
2172 | in question. | ||
2173 | For example, "BuildStarted" and "BuildCompleted" events run | ||
2174 | before any tasks are executed so would be in the global | ||
2175 | configuration datastore namespace. | ||
2176 | No recipe-specific metadata exists in that namespace. | ||
2177 | The "BuildStarted" and "BuildCompleted" events also run in | ||
2178 | the main cooker/server process rather than any worker context. | ||
2179 | Thus, any changes made to the datastore would be seen by other | ||
2180 | cooker/server events within the current build but not seen | ||
2181 | outside of that build or in any worker context. | ||
2182 | Task events run in the actual tasks in question consequently | ||
2183 | have recipe-specific and task-specific contents. | ||
2184 | These events run in the worker context and are discarded at | ||
2185 | the end of task execution. | ||
2186 | </para> | ||
2187 | |||
2188 | <para> | ||
2189 | During a standard build, the following common events might | ||
2190 | occur. | ||
2191 | The following events are the most common kinds of events that | ||
2192 | most metadata might have an interest in viewing: | ||
2193 | <itemizedlist> | ||
2194 | <listitem><para> | ||
2195 | <filename>bb.event.ConfigParsed()</filename>: | ||
2196 | Fired when the base configuration; which consists of | ||
2197 | <filename>bitbake.conf</filename>, | ||
2198 | <filename>base.bbclass</filename> and any global | ||
2199 | <filename>INHERIT</filename> statements; has been parsed. | ||
2200 | You can see multiple such events when each of the | ||
2201 | workers parse the base configuration or if the server | ||
2202 | changes configuration and reparses. | ||
2203 | Any given datastore only has one such event executed | ||
2204 | against it, however. | ||
2205 | If | ||
2206 | <link linkende='var-bb-BB_INVALIDCONF'><filename>BB_INVALIDCONF</filename></link> | ||
2207 | is set in the datastore by the event handler, the | ||
2208 | configuration is reparsed and a new event triggered, | ||
2209 | allowing the metadata to update configuration. | ||
2210 | </para></listitem> | ||
2211 | <listitem><para> | ||
2212 | <filename>bb.event.HeartbeatEvent()</filename>: | ||
2213 | Fires at regular time intervals of one second. | ||
2214 | You can configure the interval time using the | ||
2215 | <filename>BB_HEARTBEAT_EVENT</filename> variable. | ||
2216 | The event's "time" attribute is the | ||
2217 | <filename>time.time()</filename> value when the | ||
2218 | event is triggered. | ||
2219 | This event is useful for activities such as | ||
2220 | system state monitoring. | ||
2221 | </para></listitem> | ||
2222 | <listitem><para> | ||
2223 | <filename>bb.event.ParseStarted()</filename>: | ||
2224 | Fired when BitBake is about to start parsing recipes. | ||
2225 | This event's "total" attribute represents the number of | ||
2226 | recipes BitBake plans to parse. | ||
2227 | </para></listitem> | ||
2228 | <listitem><para> | ||
2229 | <filename>bb.event.ParseProgress()</filename>: | ||
2230 | Fired as parsing progresses. | ||
2231 | This event's "current" attribute is the number of | ||
2232 | recipes parsed as well as the "total" attribute. | ||
2233 | </para></listitem> | ||
2234 | <listitem><para> | ||
2235 | <filename>bb.event.ParseCompleted()</filename>: | ||
2236 | Fired when parsing is complete. | ||
2237 | This event's "cached", "parsed", "skipped", "virtuals", | ||
2238 | "masked", and "errors" attributes provide statistics | ||
2239 | for the parsing results. | ||
2240 | </para></listitem> | ||
2241 | <listitem><para> | ||
2242 | <filename>bb.event.BuildStarted()</filename>: | ||
2243 | Fired when a new build starts. | ||
2244 | BitBake fires multiple "BuildStarted" events (one per configuration) | ||
2245 | when multiple configuration (multiconfig) is enabled. | ||
2246 | </para></listitem> | ||
2247 | <listitem><para> | ||
2248 | <filename>bb.build.TaskStarted()</filename>: | ||
2249 | Fired when a task starts. | ||
2250 | This event's "taskfile" attribute points to the recipe | ||
2251 | from which the task originates. | ||
2252 | The "taskname" attribute, which is the task's name, | ||
2253 | includes the <filename>do_</filename> prefix, and the | ||
2254 | "logfile" attribute point to where the task's output is | ||
2255 | stored. | ||
2256 | Finally, the "time" attribute is the task's execution start | ||
2257 | time. | ||
2258 | </para></listitem> | ||
2259 | <listitem><para> | ||
2260 | <filename>bb.build.TaskInvalid()</filename>: | ||
2261 | Fired if BitBake tries to execute a task that does not exist. | ||
2262 | </para></listitem> | ||
2263 | <listitem><para> | ||
2264 | <filename>bb.build.TaskFailedSilent()</filename>: | ||
2265 | Fired for setscene tasks that fail and should not be | ||
2266 | presented to the user verbosely. | ||
2267 | </para></listitem> | ||
2268 | <listitem><para> | ||
2269 | <filename>bb.build.TaskFailed()</filename>: | ||
2270 | Fired for normal tasks that fail. | ||
2271 | </para></listitem> | ||
2272 | <listitem><para> | ||
2273 | <filename>bb.build.TaskSucceeded()</filename>: | ||
2274 | Fired when a task successfully completes. | ||
2275 | </para></listitem> | ||
2276 | <listitem><para> | ||
2277 | <filename>bb.event.BuildCompleted()</filename>: | ||
2278 | Fired when a build finishes. | ||
2279 | </para></listitem> | ||
2280 | <listitem><para> | ||
2281 | <filename>bb.cooker.CookerExit()</filename>: | ||
2282 | Fired when the BitBake server/cooker shuts down. | ||
2283 | This event is usually only seen by the UIs as a | ||
2284 | sign they should also shutdown. | ||
2285 | </para></listitem> | ||
2286 | </itemizedlist> | ||
2287 | </para> | ||
2288 | |||
2289 | <para> | ||
2290 | This next list of example events occur based on specific | ||
2291 | requests to the server. | ||
2292 | These events are often used to communicate larger pieces of | ||
2293 | information from the BitBake server to other parts of | ||
2294 | BitBake such as user interfaces: | ||
2295 | <itemizedlist> | ||
2296 | <listitem><para> | ||
2297 | <filename>bb.event.TreeDataPreparationStarted()</filename> | ||
2298 | </para></listitem> | ||
2299 | <listitem><para> | ||
2300 | <filename>bb.event.TreeDataPreparationProgress()</filename> | ||
2301 | </para></listitem> | ||
2302 | <listitem><para> | ||
2303 | <filename>bb.event.TreeDataPreparationCompleted()</filename> | ||
2304 | </para></listitem> | ||
2305 | <listitem><para> | ||
2306 | <filename>bb.event.DepTreeGenerated()</filename> | ||
2307 | </para></listitem> | ||
2308 | <listitem><para> | ||
2309 | <filename>bb.event.CoreBaseFilesFound()</filename> | ||
2310 | </para></listitem> | ||
2311 | <listitem><para> | ||
2312 | <filename>bb.event.ConfigFilePathFound()</filename> | ||
2313 | </para></listitem> | ||
2314 | <listitem><para> | ||
2315 | <filename>bb.event.FilesMatchingFound()</filename> | ||
2316 | </para></listitem> | ||
2317 | <listitem><para> | ||
2318 | <filename>bb.event.ConfigFilesFound()</filename> | ||
2319 | </para></listitem> | ||
2320 | <listitem><para> | ||
2321 | <filename>bb.event.TargetsTreeGenerated()</filename> | ||
2322 | </para></listitem> | ||
2323 | </itemizedlist> | ||
2324 | </para> | ||
2325 | </section> | ||
2326 | |||
2327 | <section id='variants-class-extension-mechanism'> | ||
2328 | <title>Variants - Class Extension Mechanism</title> | ||
2329 | |||
2330 | <para> | ||
2331 | BitBake supports two features that facilitate creating | ||
2332 | from a single recipe file multiple incarnations of that | ||
2333 | recipe file where all incarnations are buildable. | ||
2334 | These features are enabled through the | ||
2335 | <link linkend='var-bb-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> | ||
2336 | and | ||
2337 | <link linkend='var-bb-BBVERSIONS'><filename>BBVERSIONS</filename></link> | ||
2338 | variables. | ||
2339 | <note> | ||
2340 | The mechanism for this class extension is extremely | ||
2341 | specific to the implementation. | ||
2342 | Usually, the recipe's | ||
2343 | <link linkend='var-bb-PROVIDES'><filename>PROVIDES</filename></link>, | ||
2344 | <link linkend='var-bb-PN'><filename>PN</filename></link>, and | ||
2345 | <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> | ||
2346 | variables would need to be modified by the extension class. | ||
2347 | For specific examples, see the OE-Core | ||
2348 | <filename>native</filename>, <filename>nativesdk</filename>, | ||
2349 | and <filename>multilib</filename> classes. | ||
2350 | </note> | ||
2351 | <itemizedlist> | ||
2352 | <listitem><para><emphasis><filename>BBCLASSEXTEND</filename>:</emphasis> | ||
2353 | This variable is a space separated list of classes used to "extend" the | ||
2354 | recipe for each variant. | ||
2355 | Here is an example that results in a second incarnation of the current | ||
2356 | recipe being available. | ||
2357 | This second incarnation will have the "native" class inherited. | ||
2358 | <literallayout class='monospaced'> | ||
2359 | BBCLASSEXTEND = "native" | ||
2360 | </literallayout></para></listitem> | ||
2361 | <listitem><para><emphasis><filename>BBVERSIONS</filename>:</emphasis> | ||
2362 | This variable allows a single recipe to build multiple versions of a | ||
2363 | project from a single recipe file. | ||
2364 | You can also specify conditional metadata | ||
2365 | (using the | ||
2366 | <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link> | ||
2367 | mechanism) for a single version, or an optionally named range of versions. | ||
2368 | Here is an example: | ||
2369 | <literallayout class='monospaced'> | ||
2370 | BBVERSIONS = "1.0 2.0 git" | ||
2371 | SRC_URI_git = "git://someurl/somepath.git" | ||
2372 | |||
2373 | BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 1.0.[7-9]:1.0.7+" | ||
2374 | SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1" | ||
2375 | </literallayout> | ||
2376 | The name of the range defaults to the original version of the | ||
2377 | recipe. | ||
2378 | For example, in OpenEmbedded, the recipe file | ||
2379 | <filename>foo_1.0.0+.bb</filename> creates a default name range | ||
2380 | of <filename>1.0.0+</filename>. | ||
2381 | This is useful because the range name is not only placed | ||
2382 | into overrides, but it is also made available for the metadata to use | ||
2383 | in the variable that defines the base recipe versions for use in | ||
2384 | <filename>file://</filename> search paths | ||
2385 | (<link linkend='var-bb-FILESPATH'><filename>FILESPATH</filename></link>). | ||
2386 | </para></listitem> | ||
2387 | </itemizedlist> | ||
2388 | </para> | ||
2389 | </section> | ||
2390 | |||
2391 | <section id='dependencies'> | ||
2392 | <title>Dependencies</title> | ||
2393 | |||
2394 | <para> | ||
2395 | To allow for efficient parallel processing, BitBake handles | ||
2396 | dependencies at the task level. | ||
2397 | Dependencies can exist both between tasks within a single recipe | ||
2398 | and between tasks in different recipes. | ||
2399 | Following are examples of each: | ||
2400 | <itemizedlist> | ||
2401 | <listitem><para>For tasks within a single recipe, a | ||
2402 | recipe's <filename>do_configure</filename> | ||
2403 | task might need to complete before its | ||
2404 | <filename>do_compile</filename> task can run. | ||
2405 | </para></listitem> | ||
2406 | <listitem><para>For tasks in different recipes, one | ||
2407 | recipe's <filename>do_configure</filename> | ||
2408 | task might require another recipe's | ||
2409 | <filename>do_populate_sysroot</filename> | ||
2410 | task to finish first such that the libraries and headers | ||
2411 | provided by the other recipe are available. | ||
2412 | </para></listitem> | ||
2413 | </itemizedlist> | ||
2414 | </para> | ||
2415 | |||
2416 | <para> | ||
2417 | This section describes several ways to declare dependencies. | ||
2418 | Remember, even though dependencies are declared in different ways, they | ||
2419 | are all simply dependencies between tasks. | ||
2420 | </para> | ||
2421 | |||
2422 | <section id='dependencies-internal-to-the-bb-file'> | ||
2423 | <title>Dependencies Internal to the <filename>.bb</filename> File</title> | ||
2424 | |||
2425 | <para> | ||
2426 | BitBake uses the <filename>addtask</filename> directive | ||
2427 | to manage dependencies that are internal to a given recipe | ||
2428 | file. | ||
2429 | You can use the <filename>addtask</filename> directive to | ||
2430 | indicate when a task is dependent on other tasks or when | ||
2431 | other tasks depend on that recipe. | ||
2432 | Here is an example: | ||
2433 | <literallayout class='monospaced'> | ||
2434 | addtask printdate after do_fetch before do_build | ||
2435 | </literallayout> | ||
2436 | In this example, the <filename>do_printdate</filename> | ||
2437 | task depends on the completion of the | ||
2438 | <filename>do_fetch</filename> task, and the | ||
2439 | <filename>do_build</filename> task depends on the | ||
2440 | completion of the <filename>do_printdate</filename> | ||
2441 | task. | ||
2442 | <note><para> | ||
2443 | For a task to run, it must be a direct or indirect | ||
2444 | dependency of some other task that is scheduled to | ||
2445 | run.</para> | ||
2446 | |||
2447 | <para>For illustration, here are some examples: | ||
2448 | <itemizedlist> | ||
2449 | <listitem><para> | ||
2450 | The directive | ||
2451 | <filename>addtask mytask before do_configure</filename> | ||
2452 | causes <filename>do_mytask</filename> to run before | ||
2453 | <filename>do_configure</filename> runs. | ||
2454 | Be aware that <filename>do_mytask</filename> still only | ||
2455 | runs if its <link linkend='checksums'>input checksum</link> | ||
2456 | has changed since the last time it was run. | ||
2457 | Changes to the input checksum of | ||
2458 | <filename>do_mytask</filename> also indirectly cause | ||
2459 | <filename>do_configure</filename> to run. | ||
2460 | </para></listitem> | ||
2461 | <listitem><para> | ||
2462 | The directive | ||
2463 | <filename>addtask mytask after do_configure</filename> | ||
2464 | by itself never causes <filename>do_mytask</filename> | ||
2465 | to run. | ||
2466 | <filename>do_mytask</filename> can still be run manually | ||
2467 | as follows: | ||
2468 | <literallayout class='monospaced'> | ||
2469 | $ bitbake <replaceable>recipe</replaceable> -c mytask | ||
2470 | </literallayout> | ||
2471 | Declaring <filename>do_mytask</filename> as a dependency | ||
2472 | of some other task that is scheduled to run also causes | ||
2473 | it to run. | ||
2474 | Regardless, the task runs after | ||
2475 | <filename>do_configure</filename>. | ||
2476 | </para></listitem> | ||
2477 | </itemizedlist></para> | ||
2478 | </note> | ||
2479 | </para> | ||
2480 | </section> | ||
2481 | |||
2482 | <section id='build-dependencies'> | ||
2483 | <title>Build Dependencies</title> | ||
2484 | |||
2485 | <para> | ||
2486 | BitBake uses the | ||
2487 | <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> | ||
2488 | variable to manage build time dependencies. | ||
2489 | The <filename>[deptask]</filename> varflag for tasks | ||
2490 | signifies the task of each | ||
2491 | item listed in <filename>DEPENDS</filename> that must | ||
2492 | complete before that task can be executed. | ||
2493 | Here is an example: | ||
2494 | <literallayout class='monospaced'> | ||
2495 | do_configure[deptask] = "do_populate_sysroot" | ||
2496 | </literallayout> | ||
2497 | In this example, the <filename>do_populate_sysroot</filename> | ||
2498 | task of each item in <filename>DEPENDS</filename> must complete before | ||
2499 | <filename>do_configure</filename> can execute. | ||
2500 | </para> | ||
2501 | </section> | ||
2502 | |||
2503 | <section id='runtime-dependencies'> | ||
2504 | <title>Runtime Dependencies</title> | ||
2505 | |||
2506 | <para> | ||
2507 | BitBake uses the | ||
2508 | <link linkend='var-bb-PACKAGES'><filename>PACKAGES</filename></link>, | ||
2509 | <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link>, and | ||
2510 | <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> | ||
2511 | variables to manage runtime dependencies. | ||
2512 | </para> | ||
2513 | |||
2514 | <para> | ||
2515 | The <filename>PACKAGES</filename> variable lists runtime | ||
2516 | packages. | ||
2517 | Each of those packages can have <filename>RDEPENDS</filename> and | ||
2518 | <filename>RRECOMMENDS</filename> runtime dependencies. | ||
2519 | The <filename>[rdeptask]</filename> flag for tasks is used to | ||
2520 | signify the task of each | ||
2521 | item runtime dependency which must have completed before that | ||
2522 | task can be executed. | ||
2523 | <literallayout class='monospaced'> | ||
2524 | do_package_qa[rdeptask] = "do_packagedata" | ||
2525 | </literallayout> | ||
2526 | In the previous example, the <filename>do_packagedata</filename> | ||
2527 | task of each item in <filename>RDEPENDS</filename> must have | ||
2528 | completed before <filename>do_package_qa</filename> can execute. | ||
2529 | Although <filename>RDEPENDS</filename> contains entries from the | ||
2530 | runtime dependency namespace, BitBake knows how to map them back | ||
2531 | to the build-time dependency namespace, in which the tasks are defined. | ||
2532 | </para> | ||
2533 | </section> | ||
2534 | |||
2535 | <section id='recursive-dependencies'> | ||
2536 | <title>Recursive Dependencies</title> | ||
2537 | |||
2538 | <para> | ||
2539 | BitBake uses the <filename>[recrdeptask]</filename> flag to manage | ||
2540 | recursive task dependencies. | ||
2541 | BitBake looks through the build-time and runtime | ||
2542 | dependencies of the current recipe, looks through | ||
2543 | the task's inter-task | ||
2544 | dependencies, and then adds dependencies for the | ||
2545 | listed task. | ||
2546 | Once BitBake has accomplished this, it recursively works through | ||
2547 | the dependencies of those tasks. | ||
2548 | Iterative passes continue until all dependencies are discovered | ||
2549 | and added. | ||
2550 | </para> | ||
2551 | |||
2552 | <para> | ||
2553 | The <filename>[recrdeptask]</filename> flag is most commonly | ||
2554 | used in high-level | ||
2555 | recipes that need to wait for some task to finish "globally". | ||
2556 | For example, <filename>image.bbclass</filename> has the following: | ||
2557 | <literallayout class='monospaced'> | ||
2558 | do_rootfs[recrdeptask] += "do_packagedata" | ||
2559 | </literallayout> | ||
2560 | This statement says that the <filename>do_packagedata</filename> | ||
2561 | task of the current recipe and all recipes reachable | ||
2562 | (by way of dependencies) from the | ||
2563 | image recipe must run before the <filename>do_rootfs</filename> | ||
2564 | task can run. | ||
2565 | </para> | ||
2566 | |||
2567 | <para> | ||
2568 | BitBake allows a task to recursively depend on itself by | ||
2569 | referencing itself in the task list: | ||
2570 | <literallayout class='monospaced'> | ||
2571 | do_a[recrdeptask] = "do_a do_b" | ||
2572 | </literallayout> | ||
2573 | In the same way as before, this means that the <filename>do_a</filename> | ||
2574 | and <filename>do_b</filename> tasks of the current recipe and all | ||
2575 | recipes reachable (by way of dependencies) from the recipe | ||
2576 | must run before the <filename>do_a</filename> task can run. In this | ||
2577 | case BitBake will ignore the current recipe's <filename>do_a</filename> | ||
2578 | task circular dependency on itself. | ||
2579 | </para> | ||
2580 | </section> | ||
2581 | |||
2582 | <section id='inter-task-dependencies'> | ||
2583 | <title>Inter-Task Dependencies</title> | ||
2584 | |||
2585 | <para> | ||
2586 | BitBake uses the <filename>[depends]</filename> | ||
2587 | flag in a more generic form | ||
2588 | to manage inter-task dependencies. | ||
2589 | This more generic form allows for inter-dependency | ||
2590 | checks for specific tasks rather than checks for | ||
2591 | the data in <filename>DEPENDS</filename>. | ||
2592 | Here is an example: | ||
2593 | <literallayout class='monospaced'> | ||
2594 | do_patch[depends] = "quilt-native:do_populate_sysroot" | ||
2595 | </literallayout> | ||
2596 | In this example, the <filename>do_populate_sysroot</filename> | ||
2597 | task of the target <filename>quilt-native</filename> | ||
2598 | must have completed before the | ||
2599 | <filename>do_patch</filename> task can execute. | ||
2600 | </para> | ||
2601 | |||
2602 | <para> | ||
2603 | The <filename>[rdepends]</filename> flag works in a similar | ||
2604 | way but takes targets | ||
2605 | in the runtime namespace instead of the build-time dependency | ||
2606 | namespace. | ||
2607 | </para> | ||
2608 | </section> | ||
2609 | </section> | ||
2610 | |||
2611 | <section id='functions-you-can-call-from-within-python'> | ||
2612 | <title>Functions You Can Call From Within Python</title> | ||
2613 | |||
2614 | <para> | ||
2615 | BitBake provides many functions you can call from | ||
2616 | within Python functions. | ||
2617 | This section lists the most commonly used functions, | ||
2618 | and mentions where to find others. | ||
2619 | </para> | ||
2620 | |||
2621 | <section id='functions-for-accessing-datastore-variables'> | ||
2622 | <title>Functions for Accessing Datastore Variables</title> | ||
2623 | |||
2624 | <para> | ||
2625 | It is often necessary to access variables in the | ||
2626 | BitBake datastore using Python functions. | ||
2627 | The BitBake datastore has an API that allows you this | ||
2628 | access. | ||
2629 | Here is a list of available operations: | ||
2630 | </para> | ||
2631 | |||
2632 | <para> | ||
2633 | <informaltable frame='none'> | ||
2634 | <tgroup cols='2' align='left' colsep='1' rowsep='1'> | ||
2635 | <colspec colname='c1' colwidth='1*'/> | ||
2636 | <colspec colname='c2' colwidth='1*'/> | ||
2637 | <thead> | ||
2638 | <row> | ||
2639 | <entry align="left"><emphasis>Operation</emphasis></entry> | ||
2640 | <entry align="left"><emphasis>Description</emphasis></entry> | ||
2641 | </row> | ||
2642 | </thead> | ||
2643 | <tbody> | ||
2644 | <row> | ||
2645 | <entry align="left"><filename>d.getVar("X", expand)</filename></entry> | ||
2646 | <entry align="left">Returns the value of variable "X". | ||
2647 | Using "expand=True" expands the value. | ||
2648 | Returns "None" if the variable "X" does not exist.</entry> | ||
2649 | </row> | ||
2650 | <row> | ||
2651 | <entry align="left"><filename>d.setVar("X", "value")</filename></entry> | ||
2652 | <entry align="left">Sets the variable "X" to "value".</entry> | ||
2653 | </row> | ||
2654 | <row> | ||
2655 | <entry align="left"><filename>d.appendVar("X", "value")</filename></entry> | ||
2656 | <entry align="left">Adds "value" to the end of the variable "X". | ||
2657 | Acts like <filename>d.setVar("X", "value")</filename> | ||
2658 | if the variable "X" does not exist.</entry> | ||
2659 | </row> | ||
2660 | <row> | ||
2661 | <entry align="left"><filename>d.prependVar("X", "value")</filename></entry> | ||
2662 | <entry align="left">Adds "value" to the start of the variable "X". | ||
2663 | Acts like <filename>d.setVar("X", "value")</filename> | ||
2664 | if the variable "X" does not exist.</entry> | ||
2665 | </row> | ||
2666 | <row> | ||
2667 | <entry align="left"><filename>d.delVar("X")</filename></entry> | ||
2668 | <entry align="left">Deletes the variable "X" from the datastore. | ||
2669 | Does nothing if the variable "X" does not exist.</entry> | ||
2670 | </row> | ||
2671 | <row> | ||
2672 | <entry align="left"><filename>d.renameVar("X", "Y")</filename></entry> | ||
2673 | <entry align="left">Renames the variable "X" to "Y". | ||
2674 | Does nothing if the variable "X" does not exist.</entry> | ||
2675 | </row> | ||
2676 | <row> | ||
2677 | <entry align="left"><filename>d.getVarFlag("X", flag, expand)</filename></entry> | ||
2678 | <entry align="left">Returns the value of variable "X". | ||
2679 | Using "expand=True" expands the value. | ||
2680 | Returns "None" if either the variable "X" or the named flag | ||
2681 | does not exist.</entry> | ||
2682 | </row> | ||
2683 | <row> | ||
2684 | <entry align="left"><filename>d.setVarFlag("X", flag, "value")</filename></entry> | ||
2685 | <entry align="left">Sets the named flag for variable "X" to "value".</entry> | ||
2686 | </row> | ||
2687 | <row> | ||
2688 | <entry align="left"><filename>d.appendVarFlag("X", flag, "value")</filename></entry> | ||
2689 | <entry align="left">Appends "value" to the named flag on the | ||
2690 | variable "X". | ||
2691 | Acts like <filename>d.setVarFlag("X", flag, "value")</filename> | ||
2692 | if the named flag does not exist.</entry> | ||
2693 | </row> | ||
2694 | <row> | ||
2695 | <entry align="left"><filename>d.prependVarFlag("X", flag, "value")</filename></entry> | ||
2696 | <entry align="left">Prepends "value" to the named flag on | ||
2697 | the variable "X". | ||
2698 | Acts like <filename>d.setVarFlag("X", flag, "value")</filename> | ||
2699 | if the named flag does not exist.</entry> | ||
2700 | </row> | ||
2701 | <row> | ||
2702 | <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry> | ||
2703 | <entry align="left">Deletes the named flag on the variable | ||
2704 | "X" from the datastore.</entry> | ||
2705 | </row> | ||
2706 | <row> | ||
2707 | <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry> | ||
2708 | <entry align="left">Sets the flags specified in | ||
2709 | the <filename>flagsdict()</filename> parameter. | ||
2710 | <filename>setVarFlags</filename> does not clear previous flags. | ||
2711 | Think of this operation as <filename>addVarFlags</filename>.</entry> | ||
2712 | </row> | ||
2713 | <row> | ||
2714 | <entry align="left"><filename>d.getVarFlags("X")</filename></entry> | ||
2715 | <entry align="left">Returns a <filename>flagsdict</filename> | ||
2716 | of the flags for the variable "X". | ||
2717 | Returns "None" if the variable "X" does not exist.</entry> | ||
2718 | </row> | ||
2719 | <row> | ||
2720 | <entry align="left"><filename>d.delVarFlags("X")</filename></entry> | ||
2721 | <entry align="left">Deletes all the flags for the variable "X". | ||
2722 | Does nothing if the variable "X" does not exist.</entry> | ||
2723 | </row> | ||
2724 | <row> | ||
2725 | <entry align="left"><filename>d.expand(expression)</filename></entry> | ||
2726 | <entry align="left">Expands variable references in the specified | ||
2727 | string expression. | ||
2728 | References to variables that do not exist are left as is. | ||
2729 | For example, <filename>d.expand("foo ${X}")</filename> | ||
2730 | expands to the literal string "foo ${X}" if the | ||
2731 | variable "X" does not exist.</entry> | ||
2732 | </row> | ||
2733 | </tbody> | ||
2734 | </tgroup> | ||
2735 | </informaltable> | ||
2736 | </para> | ||
2737 | </section> | ||
2738 | |||
2739 | <section id='other-functions'> | ||
2740 | <title>Other Functions</title> | ||
2741 | |||
2742 | <para> | ||
2743 | You can find many other functions that can be called | ||
2744 | from Python by looking at the source code of the | ||
2745 | <filename>bb</filename> module, which is in | ||
2746 | <filename>bitbake/lib/bb</filename>. | ||
2747 | For example, | ||
2748 | <filename>bitbake/lib/bb/utils.py</filename> includes | ||
2749 | the commonly used functions | ||
2750 | <filename>bb.utils.contains()</filename> and | ||
2751 | <filename>bb.utils.mkdirhier()</filename>, which come | ||
2752 | with docstrings. | ||
2753 | </para> | ||
2754 | </section> | ||
2755 | </section> | ||
2756 | |||
2757 | <section id='task-checksums-and-setscene'> | ||
2758 | <title>Task Checksums and Setscene</title> | ||
2759 | |||
2760 | <para> | ||
2761 | BitBake uses checksums (or signatures) along with the setscene | ||
2762 | to determine if a task needs to be run. | ||
2763 | This section describes the process. | ||
2764 | To help understand how BitBake does this, the section assumes an | ||
2765 | OpenEmbedded metadata-based example. | ||
2766 | </para> | ||
2767 | |||
2768 | <para> | ||
2769 | These checksums are stored in | ||
2770 | <link linkend='var-bb-STAMP'><filename>STAMP</filename></link>. | ||
2771 | You can examine the checksums using the following BitBake command: | ||
2772 | <literallayout class='monospaced'> | ||
2773 | $ bitbake-dumpsigs | ||
2774 | </literallayout> | ||
2775 | This command returns the signature data in a readable format | ||
2776 | that allows you to examine the inputs used when the | ||
2777 | OpenEmbedded build system generates signatures. | ||
2778 | For example, using <filename>bitbake-dumpsigs</filename> | ||
2779 | allows you to examine the <filename>do_compile</filename> | ||
2780 | task's “sigdata” for a C application (e.g. | ||
2781 | <filename>bash</filename>). | ||
2782 | Running the command also reveals that the “CC” variable is part of | ||
2783 | the inputs that are hashed. | ||
2784 | Any changes to this variable would invalidate the stamp and | ||
2785 | cause the <filename>do_compile</filename> task to run. | ||
2786 | </para> | ||
2787 | |||
2788 | <para> | ||
2789 | The following list describes related variables: | ||
2790 | <itemizedlist> | ||
2791 | <listitem><para> | ||
2792 | <link linkend='var-bb-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></link>: | ||
2793 | Specifies the name of the function to call during | ||
2794 | the "setscene" part of the task's execution in order | ||
2795 | to validate the list of task hashes. | ||
2796 | </para></listitem> | ||
2797 | <listitem><para> | ||
2798 | <link linkend='var-bb-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></link>: | ||
2799 | Specifies a function BitBake calls that determines | ||
2800 | whether BitBake requires a setscene dependency to | ||
2801 | be met. | ||
2802 | </para></listitem> | ||
2803 | <listitem><para> | ||
2804 | <link linkend='var-bb-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></link>: | ||
2805 | Specifies a function to call that verifies the list of | ||
2806 | planned task execution before the main task execution | ||
2807 | happens. | ||
2808 | </para></listitem> | ||
2809 | <listitem><para> | ||
2810 | <link linkend='var-bb-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link>: | ||
2811 | Defines the mode for comparing timestamps of stamp files. | ||
2812 | </para></listitem> | ||
2813 | <listitem><para> | ||
2814 | <link linkend='var-bb-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link>: | ||
2815 | Lists stamp files that are looked at when the stamp policy | ||
2816 | is "whitelist". | ||
2817 | </para></listitem> | ||
2818 | <listitem><para> | ||
2819 | <link linkend='var-bb-BB_TASKHASH'><filename>BB_TASKHASH</filename></link>: | ||
2820 | Within an executing task, this variable holds the hash | ||
2821 | of the task as returned by the currently enabled | ||
2822 | signature generator. | ||
2823 | </para></listitem> | ||
2824 | <listitem><para> | ||
2825 | <link linkend='var-bb-STAMP'><filename>STAMP</filename></link>: | ||
2826 | The base path to create stamp files. | ||
2827 | </para></listitem> | ||
2828 | <listitem><para> | ||
2829 | <link linkend='var-bb-STAMPCLEAN'><filename>STAMPCLEAN</filename></link>: | ||
2830 | Again, the base path to create stamp files but can use wildcards | ||
2831 | for matching a range of files for clean operations. | ||
2832 | </para></listitem> | ||
2833 | </itemizedlist> | ||
2834 | </para> | ||
2835 | </section> | ||
2836 | |||
2837 | <section id='wildcard-support-in-variables'> | ||
2838 | <title>Wildcard Support in Variables</title> | ||
2839 | |||
2840 | <para> | ||
2841 | Support for wildcard use in variables varies depending on the | ||
2842 | context in which it is used. | ||
2843 | For example, some variables and file names allow limited use of | ||
2844 | wildcards through the "<filename>%</filename>" and | ||
2845 | "<filename>*</filename>" characters. | ||
2846 | Other variables or names support Python's | ||
2847 | <ulink url='https://docs.python.org/3/library/glob.html'><filename>glob</filename></ulink> | ||
2848 | syntax, | ||
2849 | <ulink url='https://docs.python.org/3/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink> | ||
2850 | syntax, or | ||
2851 | <ulink url='https://docs.python.org/3/library/re.html#re'><filename>Regular Expression (re)</filename></ulink> | ||
2852 | syntax. | ||
2853 | </para> | ||
2854 | |||
2855 | <para> | ||
2856 | For variables that have wildcard suport, the | ||
2857 | documentation describes which form of wildcard, its | ||
2858 | use, and its limitations. | ||
2859 | </para> | ||
2860 | </section> | ||
2861 | |||
2862 | </chapter> | ||