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