summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-07-31 10:00:02 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-16 18:14:08 +0100
commite3b76c8fc370833a623791cec6e805158d35e9d1 (patch)
tree9ad3df8166ed0a79dee3a454dcba53281f375f2f /bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
parent4324c6e0716915c4d375805ce695a9eedb0fa010 (diff)
downloadpoky-e3b76c8fc370833a623791cec6e805158d35e9d1.tar.gz
bitbake: sphinx: last manual round of fixes/improvements
Review all pages, and fix up for formatting which was not covered by pandoc, such as some links and code block sections. (Bitbake rev: d99760cc687cc9c24d6d9a1c49fa094574476e0c) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst')
-rw-r--r--bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst1233
1 files changed, 737 insertions, 496 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
index 4de70e8e1d..12491c5947 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst
@@ -21,16 +21,28 @@ Basic Variable Setting
21 21
22The following example sets ``VARIABLE`` to "value". This assignment 22The following example sets ``VARIABLE`` to "value". This assignment
23occurs immediately as the statement is parsed. It is a "hard" 23occurs immediately as the statement is parsed. It is a "hard"
24assignment. VARIABLE = "value" As expected, if you include leading or 24assignment. ::
25trailing spaces as part of an assignment, the spaces are retained: 25
26VARIABLE = " value" VARIABLE = "value " Setting ``VARIABLE`` to "" sets 26 VARIABLE = "value"
27
28As expected, if you include leading or
29trailing spaces as part of an assignment, the spaces are retained: ::
30
31 VARIABLE = " value"
32 VARIABLE = "value "
33
34Setting ``VARIABLE`` to "" sets
27it to an empty string, while setting the variable to " " sets it to a 35it to an empty string, while setting the variable to " " sets it to a
28blank space (i.e. these are not the same values). VARIABLE = "" VARIABLE 36blank space (i.e. these are not the same values). ::
29= " " 37
38 VARIABLE = ""
39 VARIABLE = " "
30 40
31You can use single quotes instead of double quotes when setting a 41You can use single quotes instead of double quotes when setting a
32variable's value. Doing so allows you to use values that contain the 42variable's value. Doing so allows you to use values that contain the
33double quote character: VARIABLE = 'I have a " in my value' 43double quote character: ::
44
45 VARIABLE = 'I have a " in my value'
34 46
35.. note:: 47.. note::
36 48
@@ -65,7 +77,11 @@ occurs, you can use BitBake to check the actual value of the suspect
65variable. You can make these checks for both configuration and recipe 77variable. You can make these checks for both configuration and recipe
66level changes: 78level changes:
67 79
68- For configuration changes, use the following: $ bitbake -e This 80- For configuration changes, use the following: ::
81
82 $ bitbake -e
83
84 This
69 command displays variable values after the configuration files (i.e. 85 command displays variable values after the configuration files (i.e.
70 ``local.conf``, ``bblayers.conf``, ``bitbake.conf`` and so forth) 86 ``local.conf``, ``bblayers.conf``, ``bitbake.conf`` and so forth)
71 have been parsed. 87 have been parsed.
@@ -75,33 +91,43 @@ level changes:
75 Variables that are exported to the environment are preceded by the 91 Variables that are exported to the environment are preceded by the
76 string "export" in the command's output. 92 string "export" in the command's output.
77 93
78- For recipe changes, use the following: $ bitbake recipe -e \| grep 94- For recipe changes, use the following: ::
79 VARIABLE=" This command checks to see if the variable actually makes 95
96 $ bitbake recipe -e \| grep VARIABLE="
97
98 This command checks to see if the variable actually makes
80 it into a specific recipe. 99 it into a specific recipe.
81 100
82Line Joining 101Line Joining
83------------ 102------------
84 103
85Outside of `functions <#functions>`__, BitBake joins any line ending in 104Outside of :ref:`functions <bitbake-user-manual/bitbake-user-manual-metadata:functions>`,
105BitBake joins any line ending in
86a backslash character ("\") with the following line before parsing 106a backslash character ("\") with the following line before parsing
87statements. The most common use for the "\" character is to split 107statements. The most common use for the "\" character is to split
88variable assignments over multiple lines, as in the following example: 108variable assignments over multiple lines, as in the following example: ::
89FOO = "bar \\ baz \\ qaz" Both the "\" character and the newline 109
110 FOO = "bar \
111 baz \
112 qaz"
113
114Both the "\" character and the newline
90character that follow it are removed when joining lines. Thus, no 115character that follow it are removed when joining lines. Thus, no
91newline characters end up in the value of ``FOO``. 116newline characters end up in the value of ``FOO``.
92 117
93Consider this additional example where the two assignments both assign 118Consider this additional example where the two assignments both assign
94"barbaz" to ``FOO``: FOO = "barbaz" FOO = "bar\\ baz" 119"barbaz" to ``FOO``: ::
120
121 FOO = "barbaz"
122 FOO = "bar\
123 baz"
95 124
96.. note:: 125.. note::
97 126
98 BitBake does not interpret escape sequences like "\n" in variable 127 BitBake does not interpret escape sequences like "\n" in variable
99 values. For these to have an effect, the value must be passed to some 128 values. For these to have an effect, the value must be passed to some
100 utility that interprets escape sequences, such as 129 utility that interprets escape sequences, such as
101 printf 130 ``printf`` or ``echo -n``.
102 or
103 echo -n
104 .
105 131
106Variable Expansion 132Variable Expansion
107------------------ 133------------------
@@ -109,32 +135,41 @@ Variable Expansion
109Variables can reference the contents of other variables using a syntax 135Variables can reference the contents of other variables using a syntax
110that is similar to variable expansion in Bourne shells. The following 136that is similar to variable expansion in Bourne shells. The following
111assignments result in A containing "aval" and B evaluating to 137assignments result in A containing "aval" and B evaluating to
112"preavalpost". A = "aval" B = "pre${A}post" 138"preavalpost". ::
139
140 A = "aval"
141 B = "pre${A}post"
113 142
114.. note:: 143.. note::
115 144
116 Unlike in Bourne shells, the curly braces are mandatory: Only 145 Unlike in Bourne shells, the curly braces are mandatory: Only ``${FOO}`` and not
117 ${FOO} 146 ``$FOO`` is recognized as an expansion of ``FOO``.
118 and not
119 $FOO
120 is recognized as an expansion of
121 FOO
122 .
123 147
124The "=" operator does not immediately expand variable references in the 148The "=" operator does not immediately expand variable references in the
125right-hand side. Instead, expansion is deferred until the variable 149right-hand side. Instead, expansion is deferred until the variable
126assigned to is actually used. The result depends on the current values 150assigned to is actually used. The result depends on the current values
127of the referenced variables. The following example should clarify this 151of the referenced variables. The following example should clarify this
128behavior: A = "${B} baz" B = "${C} bar" C = "foo" \*At this point, ${A} 152behavior: ::
129equals "foo bar baz"\* C = "qux" \*At this point, ${A} equals "qux bar 153
130baz"\* B = "norf" \*At this point, ${A} equals "norf baz"\* Contrast 154 A = "${B} baz"
131this behavior with the `immediate variable 155 B = "${C} bar"
132expansion <#immediate-variable-expansion>`__ operator (i.e. ":="). 156 C = "foo"
157 *At this point, ${A} equals "foo bar baz"*
158 C = "qux"
159 *At this point, ${A} equals "qux bar baz"*
160 B = "norf"
161 *At this point, ${A} equals "norf baz"\*
162
163Contrast this behavior with the
164:ref:`bitbake-user-manual/bitbake-user-manual-metadata:immediate variable
165expansion (:=)` operator.
133 166
134If the variable expansion syntax is used on a variable that does not 167If the variable expansion syntax is used on a variable that does not
135exist, the string is kept as is. For example, given the following 168exist, the string is kept as is. For example, given the following
136assignment, ``BAR`` expands to the literal string "${FOO}" as long as 169assignment, ``BAR`` expands to the literal string "${FOO}" as long as
137``FOO`` does not exist. BAR = "${FOO}" 170``FOO`` does not exist. ::
171
172 BAR = "${FOO}"
138 173
139Setting a default value (?=) 174Setting a default value (?=)
140---------------------------- 175----------------------------
@@ -142,7 +177,11 @@ Setting a default value (?=)
142You can use the "?=" operator to achieve a "softer" assignment for a 177You can use the "?=" operator to achieve a "softer" assignment for a
143variable. This type of assignment allows you to define a variable if it 178variable. This type of assignment allows you to define a variable if it
144is undefined when the statement is parsed, but to leave the value alone 179is undefined when the statement is parsed, but to leave the value alone
145if the variable has a value. Here is an example: A ?= "aval" If ``A`` is 180if the variable has a value. Here is an example: ::
181
182 A ?= "aval"
183
184If ``A`` is
146set at the time this statement is parsed, the variable retains its 185set at the time this statement is parsed, the variable retains its
147value. However, if ``A`` is not set, the variable is set to "aval". 186value. However, if ``A`` is not set, the variable is set to "aval".
148 187
@@ -160,8 +199,12 @@ by using the "??=" operator. This assignment behaves identical to "?="
160except that the assignment is made at the end of the parsing process 199except that the assignment is made at the end of the parsing process
161rather than immediately. Consequently, when multiple "??=" assignments 200rather than immediately. Consequently, when multiple "??=" assignments
162exist, the last one is used. Also, any "=" or "?=" assignment will 201exist, the last one is used. Also, any "=" or "?=" assignment will
163override the value set with "??=". Here is an example: A ??= "somevalue" 202override the value set with "??=". Here is an example: ::
164A ??= "someothervalue" If ``A`` is set before the above statements are 203
204 A ??= "somevalue"
205 A ??= "someothervalue"
206
207If ``A`` is set before the above statements are
165parsed, the variable retains its value. If ``A`` is not set, the 208parsed, the variable retains its value. If ``A`` is not set, the
166variable is set to "someothervalue". 209variable is set to "someothervalue".
167 210
@@ -172,8 +215,15 @@ Immediate variable expansion (:=)
172--------------------------------- 215---------------------------------
173 216
174The ":=" operator results in a variable's contents being expanded 217The ":=" operator results in a variable's contents being expanded
175immediately, rather than when the variable is actually used: T = "123" A 218immediately, rather than when the variable is actually used: ::
176:= "test ${T}" T = "456" B := "${T} ${C}" C = "cval" C := "${C}append" 219
220 T = "123"
221 A := "test ${T}"
222 T = "456"
223 B := "${T} ${C}"
224 C = "cval"
225 C := "${C}append"
226
177In this example, ``A`` contains "test 123", even though the final value 227In this example, ``A`` contains "test 123", even though the final value
178of ``T`` is "456". The variable ``B`` will end up containing "456 228of ``T`` is "456". The variable ``B`` will end up containing "456
179cvalappend". This is because references to undefined variables are 229cvalappend". This is because references to undefined variables are
@@ -191,8 +241,14 @@ the "+=" and "=+" operators. These operators insert a space between the
191current value and prepended or appended value. 241current value and prepended or appended value.
192 242
193These operators take immediate effect during parsing. Here are some 243These operators take immediate effect during parsing. Here are some
194examples: B = "bval" B += "additionaldata" C = "cval" C =+ "test" The 244examples: ::
195variable ``B`` contains "bval additionaldata" and ``C`` contains "test 245
246 B = "bval"
247 B += "additionaldata"
248 C = "cval"
249 C =+ "test"
250
251The variable ``B`` contains "bval additionaldata" and ``C`` contains "test
196cval". 252cval".
197 253
198.. _appending-and-prepending-without-spaces: 254.. _appending-and-prepending-without-spaces:
@@ -204,8 +260,14 @@ If you want to append or prepend values without an inserted space, use
204the ".=" and "=." operators. 260the ".=" and "=." operators.
205 261
206These operators take immediate effect during parsing. Here are some 262These operators take immediate effect during parsing. Here are some
207examples: B = "bval" B .= "additionaldata" C = "cval" C =. "test" The 263examples: ::
208variable ``B`` contains "bvaladditionaldata" and ``C`` contains 264
265 B = "bval"
266 B .= "additionaldata"
267 C = "cval"
268 C =. "test"
269
270The variable ``B`` contains "bvaladditionaldata" and ``C`` contains
209"testcval". 271"testcval".
210 272
211Appending and Prepending (Override Style Syntax) 273Appending and Prepending (Override Style Syntax)
@@ -216,9 +278,16 @@ style syntax. When you use this syntax, no spaces are inserted.
216 278
217These operators differ from the ":=", ".=", "=.", "+=", and "=+" 279These operators differ from the ":=", ".=", "=.", "+=", and "=+"
218operators in that their effects are applied at variable expansion time 280operators in that their effects are applied at variable expansion time
219rather than being immediately applied. Here are some examples: B = 281rather than being immediately applied. Here are some examples: ::
220"bval" B_append = " additional data" C = "cval" C_prepend = "additional 282
221data " D = "dval" D_append = "additional data" The variable ``B`` 283 B = "bval"
284 B_append = " additional data"
285 C = "cval"
286 C_prepend = "additional data "
287 D = "dval"
288 D_append = "additional data"
289
290The variable ``B``
222becomes "bval additional data" and ``C`` becomes "additional data cval". 291becomes "bval additional data" and ``C`` becomes "additional data cval".
223The variable ``D`` becomes "dvaladditional data". 292The variable ``D`` becomes "dvaladditional data".
224 293
@@ -227,9 +296,8 @@ The variable ``D`` becomes "dvaladditional data".
227 You must control all spacing when you use the override syntax. 296 You must control all spacing when you use the override syntax.
228 297
229It is also possible to append and prepend to shell functions and 298It is also possible to append and prepend to shell functions and
230BitBake-style Python functions. See the "`Shell 299BitBake-style Python functions. See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:shell functions`" and ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:bitbake-style python functions`"
231Functions <#shell-functions>`__" and "`BitBake-Style Python 300sections for examples.
232Functions <#bitbake-style-python-functions>`__ sections for examples.
233 301
234.. _removing-override-style-syntax: 302.. _removing-override-style-syntax:
235 303
@@ -241,11 +309,20 @@ syntax. Specifying a value for removal causes all occurrences of that
241value to be removed from the variable. 309value to be removed from the variable.
242 310
243When you use this syntax, BitBake expects one or more strings. 311When you use this syntax, BitBake expects one or more strings.
244Surrounding spaces and spacing are preserved. Here is an example: FOO = 312Surrounding spaces and spacing are preserved. Here is an example: ::
245"123 456 789 123456 123 456 123 456" FOO_remove = "123" FOO_remove = 313
246"456" FOO2 = " abc def ghi abcdef abc def abc def def" FOO2_remove = " 314 FOO = "123 456 789 123456 123 456 123 456"
247\\ def \\ abc \\ ghi \\ " The variable ``FOO`` becomes 315 FOO_remove = "123"
248"  789 123456    " and ``FOO2`` becomes "     abcdef      ". 316 FOO_remove = "456"
317 FOO2 = " abc def ghi abcdef abc def abc def def"
318 FOO2_remove = "\
319 def \
320 abc \
321 ghi \
322 "
323
324The variable ``FOO`` becomes
325" 789 123456 " and ``FOO2`` becomes " abcdef ".
249 326
250Like "_append" and "_prepend", "_remove" is applied at variable 327Like "_append" and "_prepend", "_remove" is applied at variable
251expansion time. 328expansion time.
@@ -257,105 +334,115 @@ An advantage of the override style operations "_append", "_prepend", and
257"_remove" as compared to the "+=" and "=+" operators is that the 334"_remove" as compared to the "+=" and "=+" operators is that the
258override style operators provide guaranteed operations. For example, 335override style operators provide guaranteed operations. For example,
259consider a class ``foo.bbclass`` that needs to add the value "val" to 336consider a class ``foo.bbclass`` that needs to add the value "val" to
260the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows: 337the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows: ::
261inherit foo FOO = "initial" If ``foo.bbclass`` uses the "+=" operator, 338
339 inherit foo
340 FOO = "initial"
341
342If ``foo.bbclass`` uses the "+=" operator,
262as follows, then the final value of ``FOO`` will be "initial", which is 343as follows, then the final value of ``FOO`` will be "initial", which is
263not what is desired: FOO += "val" If, on the other hand, ``foo.bbclass`` 344not what is desired: ::
345
346 FOO += "val"
347
348If, on the other hand, ``foo.bbclass``
264uses the "_append" operator, then the final value of ``FOO`` will be 349uses the "_append" operator, then the final value of ``FOO`` will be
265"initial val", as intended: FOO_append = " val" 350"initial val", as intended: ::
351
352 FOO_append = " val"
266 353
267.. note:: 354.. note::
268 355
269 It is never necessary to use "+=" together with "_append". The 356 It is never necessary to use "+=" together with "_append". The following
270 following sequence of assignments appends "barbaz" to 357 sequence of assignments appends "barbaz" to FOO: ::
271 FOO 358
272 : 359 FOO_append = "bar"
273 :: 360 FOO_append = "baz"
274 361
275 FOO_append = "bar"
276 FOO_append = "baz"
277
278 362
279 The only effect of changing the second assignment in the previous 363 The only effect of changing the second assignment in the previous
280 example to use "+=" would be to add a space before "baz" in the 364 example to use "+=" would be to add a space before "baz" in the
281 appended value (due to how the "+=" operator works). 365 appended value (due to how the "+=" operator works).
282 366
283Another advantage of the override style operations is that you can 367Another advantage of the override style operations is that you can
284combine them with other overrides as described in the "`Conditional 368combine them with other overrides as described in the
285Syntax (Overrides) <#conditional-syntax-overrides>`__" section. 369":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" section.
286 370
287Variable Flag Syntax 371Variable Flag Syntax
288-------------------- 372--------------------
289 373
290Variable flags are BitBake's implementation of variable properties or 374Variable flags are BitBake's implementation of variable properties or
291attributes. It is a way of tagging extra information onto a variable. 375attributes. It is a way of tagging extra information onto a variable.
292You can find more out about variable flags in general in the "`Variable 376You can find more out about variable flags in general in the
293Flags <#variable-flags>`__" section. 377":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section.
294 378
295You can define, append, and prepend values to variable flags. All the 379You can define, append, and prepend values to variable flags. All the
296standard syntax operations previously mentioned work for variable flags 380standard syntax operations previously mentioned work for variable flags
297except for override style syntax (i.e. "_prepend", "_append", and 381except for override style syntax (i.e. "_prepend", "_append", and
298"_remove"). 382"_remove").
299 383
300Here are some examples showing how to set variable flags: FOO[a] = "abc" 384Here are some examples showing how to set variable flags: ::
301FOO[b] = "123" FOO[a] += "456" The variable ``FOO`` has two flags: 385
386 FOO[a] = "abc"
387 FOO[b] = "123"
388 FOO[a] += "456"
389
390The variable ``FOO`` has two flags:
302``[a]`` and ``[b]``. The flags are immediately set to "abc" and "123", 391``[a]`` and ``[b]``. The flags are immediately set to "abc" and "123",
303respectively. The ``[a]`` flag becomes "abc 456". 392respectively. The ``[a]`` flag becomes "abc 456".
304 393
305No need exists to pre-define variable flags. You can simply start using 394No need exists to pre-define variable flags. You can simply start using
306them. One extremely common application is to attach some brief 395them. One extremely common application is to attach some brief
307documentation to a BitBake variable as follows: CACHE[doc] = "The 396documentation to a BitBake variable as follows: ::
308directory holding the cache of the metadata." 397
398 CACHE[doc] = "The directory holding the cache of the metadata."
309 399
310Inline Python Variable Expansion 400Inline Python Variable Expansion
311-------------------------------- 401--------------------------------
312 402
313You can use inline Python variable expansion to set variables. Here is 403You can use inline Python variable expansion to set variables. Here is
314an example: DATE = "${@time.strftime('%Y%m%d',time.gmtime())}" This 404an example: ::
315example results in the ``DATE`` variable being set to the current date. 405
406 DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
407
408This example results in the ``DATE`` variable being set to the current date.
316 409
317Probably the most common use of this feature is to extract the value of 410Probably the most common use of this feature is to extract the value of
318variables from BitBake's internal data dictionary, ``d``. The following 411variables from BitBake's internal data dictionary, ``d``. The following
319lines select the values of a package name and its version number, 412lines select the values of a package name and its version number,
320respectively: PN = 413respectively: ::
321"${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 414
322'defaultpkgname'}" PV = 415 PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}"
323"${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or 416 PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}"
324'1.0'}"
325 417
326.. note:: 418.. note::
327 419
328 Inline Python expressions work just like variable expansions insofar 420 Inline Python expressions work just like variable expansions insofar as the
329 as the "=" and ":=" operators are concerned. Given the following 421 "=" and ":=" operators are concerned. Given the following assignment, foo()
330 assignment, 422 is called each time FOO is expanded: ::
331 foo()
332 is called each time
333 FOO
334 is expanded:
335 ::
336 423
337 FOO = "${@foo()}" 424 FOO = "${@foo()}"
338
339 425
340 Contrast this with the following immediate assignment, where 426 Contrast this with the following immediate assignment, where foo() is only
341 foo() 427 called once, while the assignment is parsed: ::
342 is only called once, while the assignment is parsed:
343 ::
344 428
345 FOO := "${@foo()}" 429 FOO := "${@foo()}"
346
347 430
348For a different way to set variables with Python code during parsing, 431For a different way to set variables with Python code during parsing,
349see the "`Anonymous Python Functions <#anonymous-python-functions>`__" 432see the
350section. 433":ref:`bitbake-user-manual/bitbake-user-manual-metadata:anonymous python functions`" section.
351 434
352Unsetting variables 435Unsetting variables
353------------------- 436-------------------
354 437
355It is possible to completely remove a variable or a variable flag from 438It is possible to completely remove a variable or a variable flag from
356BitBake's internal data dictionary by using the "unset" keyword. Here is 439BitBake's internal data dictionary by using the "unset" keyword. Here is
357an example: unset DATE unset do_fetch[noexec] These two statements 440an example: ::
358remove the ``DATE`` and the ``do_fetch[noexec]`` flag. 441
442 unset DATE
443 unset do_fetch[noexec]
444
445These two statements remove the ``DATE`` and the ``do_fetch[noexec]`` flag.
359 446
360Providing Pathnames 447Providing Pathnames
361------------------- 448-------------------
@@ -365,34 +452,40 @@ When specifying pathnames for use with BitBake, do not use the tilde
365cause BitBake to not recognize the path since BitBake does not expand 452cause BitBake to not recognize the path since BitBake does not expand
366this character in the same way a shell would. 453this character in the same way a shell would.
367 454
368Instead, provide a fuller path as the following example illustrates: 455Instead, provide a fuller path as the following example illustrates: ::
369BBLAYERS ?= " \\ /home/scott-lenovo/LayerA \\ " 456
457 BBLAYERS ?= " \
458 /home/scott-lenovo/LayerA \
459 "
370 460
371Exporting Variables to the Environment 461Exporting Variables to the Environment
372====================================== 462======================================
373 463
374You can export variables to the environment of running tasks by using 464You can export variables to the environment of running tasks by using
375the ``export`` keyword. For example, in the following example, the 465the ``export`` keyword. For example, in the following example, the
376``do_foo`` task prints "value from the environment" when run: export 466``do_foo`` task prints "value from the environment" when run: ::
377ENV_VARIABLE ENV_VARIABLE = "value from the environment" do_foo() { 467
378bbplain "$ENV_VARIABLE" } 468 export ENV_VARIABLE
469 ENV_VARIABLE = "value from the environment"
470
471 do_foo() {
472 bbplain "$ENV_VARIABLE"
473 }
379 474
380.. note:: 475.. note::
381 476
382 BitBake does not expand 477 BitBake does not expand ``$ENV_VARIABLE`` in this case because it lacks the
383 $ENV_VARIABLE 478 obligatory ``{}`` . Rather, ``$ENV_VARIABLE`` is expanded by the shell.
384 in this case because it lacks the obligatory
385 {}
386 . Rather,
387 $ENV_VARIABLE
388 is expanded by the shell.
389 479
390It does not matter whether ``export ENV_VARIABLE`` appears before or 480It does not matter whether ``export ENV_VARIABLE`` appears before or
391after assignments to ``ENV_VARIABLE``. 481after assignments to ``ENV_VARIABLE``.
392 482
393It is also possible to combine ``export`` with setting a value for the 483It is also possible to combine ``export`` with setting a value for the
394variable. Here is an example: export ENV_VARIABLE = "variable-value" In 484variable. Here is an example: ::
395the output of ``bitbake -e``, variables that are exported to the 485
486 export ENV_VARIABLE = "variable-value"
487
488In the output of ``bitbake -e``, variables that are exported to the
396environment are preceded by "export". 489environment are preceded by "export".
397 490
398Among the variables commonly exported to the environment are ``CC`` and 491Among the variables commonly exported to the environment are ``CC`` and
@@ -425,42 +518,58 @@ variable.
425 to satisfy conditions. Thus, if you have a variable that is 518 to satisfy conditions. Thus, if you have a variable that is
426 conditional on “arm”, and “arm” is in ``OVERRIDES``, then the 519 conditional on “arm”, and “arm” is in ``OVERRIDES``, then the
427 “arm”-specific version of the variable is used rather than the 520 “arm”-specific version of the variable is used rather than the
428 non-conditional version. Here is an example: OVERRIDES = 521 non-conditional version. Here is an example: ::
429 "architecture:os:machine" TEST = "default" TEST_os = "osspecific" 522
430 TEST_nooverride = "othercondvalue" In this example, the ``OVERRIDES`` 523 OVERRIDES = "architecture:os:machine"
524 TEST = "default"
525 TEST_os = "osspecific"
526 TEST_nooverride = "othercondvalue"
527
528 In this example, the ``OVERRIDES``
431 variable lists three overrides: "architecture", "os", and "machine". 529 variable lists three overrides: "architecture", "os", and "machine".
432 The variable ``TEST`` by itself has a default value of "default". You 530 The variable ``TEST`` by itself has a default value of "default". You
433 select the os-specific version of the ``TEST`` variable by appending 531 select the os-specific version of the ``TEST`` variable by appending
434 the "os" override to the variable (i.e.\ ``TEST_os``). 532 the "os" override to the variable (i.e. ``TEST_os``).
435 533
436 To better understand this, consider a practical example that assumes 534 To better understand this, consider a practical example that assumes
437 an OpenEmbedded metadata-based Linux kernel recipe file. The 535 an OpenEmbedded metadata-based Linux kernel recipe file. The
438 following lines from the recipe file first set the kernel branch 536 following lines from the recipe file first set the kernel branch
439 variable ``KBRANCH`` to a default value, then conditionally override 537 variable ``KBRANCH`` to a default value, then conditionally override
440 that value based on the architecture of the build: KBRANCH = 538 that value based on the architecture of the build: ::
441 "standard/base" KBRANCH_qemuarm = "standard/arm-versatile-926ejs" 539
442 KBRANCH_qemumips = "standard/mti-malta32" KBRANCH_qemuppc = 540 KBRANCH = "standard/base"
443 "standard/qemuppc" KBRANCH_qemux86 = "standard/common-pc/base" 541 KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
444 KBRANCH_qemux86-64 = "standard/common-pc-64/base" KBRANCH_qemumips64 542 KBRANCH_qemumips = "standard/mti-malta32"
445 = "standard/mti-malta64" 543 KBRANCH_qemuppc = "standard/qemuppc"
544 KBRANCH_qemux86 = "standard/common-pc/base"
545 KBRANCH_qemux86-64 = "standard/common-pc-64/base"
546 KBRANCH_qemumips64 = "standard/mti-malta64"
446 547
447- *Appending and Prepending:* BitBake also supports append and prepend 548- *Appending and Prepending:* BitBake also supports append and prepend
448 operations to variable values based on whether a specific item is 549 operations to variable values based on whether a specific item is
449 listed in ``OVERRIDES``. Here is an example: DEPENDS = "glibc 550 listed in ``OVERRIDES``. Here is an example: ::
450 ncurses" OVERRIDES = "machine:local" DEPENDS_append_machine = " 551
451 libmad" In this example, ``DEPENDS`` becomes "glibc ncurses libmad". 552 DEPENDS = "glibc ncurses"
553 OVERRIDES = "machine:local"
554 DEPENDS_append_machine = "libmad"
555
556 In this example, ``DEPENDS`` becomes "glibc ncurses libmad".
452 557
453 Again, using an OpenEmbedded metadata-based kernel recipe file as an 558 Again, using an OpenEmbedded metadata-based kernel recipe file as an
454 example, the following lines will conditionally append to the 559 example, the following lines will conditionally append to the
455 ``KERNEL_FEATURES`` variable based on the architecture: 560 ``KERNEL_FEATURES`` variable based on the architecture: ::
456 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}" 561
457 KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc" 562 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
458 KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc 563 KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc"
459 cfg/paravirt_kvm.scc" 564 KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc"
460 565
461- *Setting a Variable for a Single Task:* BitBake supports setting a 566- *Setting a Variable for a Single Task:* BitBake supports setting a
462 variable just for the duration of a single task. Here is an example: 567 variable just for the duration of a single task. Here is an example: ::
463 FOO_task-configure = "val 1" FOO_task-compile = "val 2" In the 568
569 FOO_task-configure = "val 1"
570 FOO_task-compile = "val 2"
571
572 In the
464 previous example, ``FOO`` has the value "val 1" while the 573 previous example, ``FOO`` has the value "val 1" while the
465 ``do_configure`` task is executed, and the value "val 2" while the 574 ``do_configure`` task is executed, and the value "val 2" while the
466 ``do_compile`` task is executed. 575 ``do_compile`` task is executed.
@@ -471,15 +580,21 @@ variable.
471 ``do_compile`` task. 580 ``do_compile`` task.
472 581
473 You can also use this syntax with other combinations (e.g. 582 You can also use this syntax with other combinations (e.g.
474 "``_prepend``") as shown in the following example: 583 "``_prepend``") as shown in the following example: ::
475 EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} " 584
585 EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} "
476 586
477Key Expansion 587Key Expansion
478------------- 588-------------
479 589
480Key expansion happens when the BitBake datastore is finalized. To better 590Key expansion happens when the BitBake datastore is finalized. To better
481understand this, consider the following example: A${B} = "X" B = "2" A2 591understand this, consider the following example: ::
482= "Y" In this case, after all the parsing is complete, BitBake expands 592
593 A${B} = "X"
594 B = "2"
595 A2 = "Y"
596
597In this case, after all the parsing is complete, BitBake expands
483``${B}`` into "2". This expansion causes ``A2``, which was set to "Y" 598``${B}`` into "2". This expansion causes ``A2``, which was set to "Y"
484before the expansion, to become "X". 599before the expansion, to become "X".
485 600
@@ -499,7 +614,13 @@ There is often confusion concerning the order in which overrides and
499various "append" operators take effect. Recall that an append or prepend 614various "append" operators take effect. Recall that an append or prepend
500operation using "_append" and "_prepend" does not result in an immediate 615operation using "_append" and "_prepend" does not result in an immediate
501assignment as would "+=", ".=", "=+", or "=.". Consider the following 616assignment as would "+=", ".=", "=+", or "=.". Consider the following
502example: OVERRIDES = "foo" A = "Z" A_foo_append = "X" For this case, 617example: ::
618
619 OVERRIDES = "foo"
620 A = "Z"
621 A_foo_append = "X"
622
623For this case,
503``A`` is unconditionally set to "Z" and "X" is unconditionally and 624``A`` is unconditionally set to "Z" and "X" is unconditionally and
504immediately appended to the variable ``A_foo``. Because overrides have 625immediately appended to the variable ``A_foo``. Because overrides have
505not been applied yet, ``A_foo`` is set to "X" due to the append and 626not been applied yet, ``A_foo`` is set to "X" due to the append and
@@ -510,24 +631,42 @@ Applying overrides, however, changes things. Since "foo" is listed in
510version, which is equal to "X". So effectively, ``A_foo`` replaces 631version, which is equal to "X". So effectively, ``A_foo`` replaces
511``A``. 632``A``.
512 633
513This next example changes the order of the override and the append: 634This next example changes the order of the override and the append: ::
514OVERRIDES = "foo" A = "Z" A_append_foo = "X" For this case, before 635
636 OVERRIDES = "foo"
637 A = "Z"
638 A_append_foo = "X"
639
640For this case, before
515overrides are handled, ``A`` is set to "Z" and ``A_append_foo`` is set 641overrides are handled, ``A`` is set to "Z" and ``A_append_foo`` is set
516to "X". Once the override for "foo" is applied, however, ``A`` gets 642to "X". Once the override for "foo" is applied, however, ``A`` gets
517appended with "X". Consequently, ``A`` becomes "ZX". Notice that spaces 643appended with "X". Consequently, ``A`` becomes "ZX". Notice that spaces
518are not appended. 644are not appended.
519 645
520This next example has the order of the appends and overrides reversed 646This next example has the order of the appends and overrides reversed
521back as in the first example: OVERRIDES = "foo" A = "Y" A_foo_append = 647back as in the first example: ::
522"Z" A_foo_append = "X" For this case, before any overrides are resolved, 648
649 OVERRIDES = "foo"
650 A = "Y"
651 A_foo_append = "Z"
652 A_foo_append = "X"
653
654For this case, before any overrides are resolved,
523``A`` is set to "Y" using an immediate assignment. After this immediate 655``A`` is set to "Y" using an immediate assignment. After this immediate
524assignment, ``A_foo`` is set to "Z", and then further appended with "X" 656assignment, ``A_foo`` is set to "Z", and then further appended with "X"
525leaving the variable set to "ZX". Finally, applying the override for 657leaving the variable set to "ZX". Finally, applying the override for
526"foo" results in the conditional variable ``A`` becoming "ZX" (i.e. 658"foo" results in the conditional variable ``A`` becoming "ZX" (i.e.
527``A`` is replaced with ``A_foo``). 659``A`` is replaced with ``A_foo``).
528 660
529This final example mixes in some varying operators: A = "1" A_append = 661This final example mixes in some varying operators: ::
530"2" A_append = "3" A += "4" A .= "5" For this case, the type of append 662
663 A = "1"
664 A_append = "2"
665 A_append = "3"
666 A += "4"
667 A .= "5"
668
669For this case, the type of append
531operators are affecting the order of assignments as BitBake passes 670operators are affecting the order of assignments as BitBake passes
532through the code multiple times. Initially, ``A`` is set to "1 45" 671through the code multiple times. Initially, ``A`` is set to "1 45"
533because of the three statements that use immediate operators. After 672because of the three statements that use immediate operators. After
@@ -559,11 +698,7 @@ current directory for ``include`` and ``require`` directives.
559 698
560.. note:: 699.. note::
561 700
562 The 701 The BBPATH variable is analogous to the environment variable PATH .
563 BBPATH
564 variable is analogous to the environment variable
565 PATH
566 .
567 702
568In order for include and class files to be found by BitBake, they need 703In order for include and class files to be found by BitBake, they need
569to be located in a "classes" subdirectory that can be found in 704to be located in a "classes" subdirectory that can be found in
@@ -585,8 +720,11 @@ file and then have your recipe inherit that class file.
585 720
586As an example, your recipes could use the following directive to inherit 721As an example, your recipes could use the following directive to inherit
587an ``autotools.bbclass`` file. The class file would contain common 722an ``autotools.bbclass`` file. The class file would contain common
588functionality for using Autotools that could be shared across recipes: 723functionality for using Autotools that could be shared across recipes: ::
589inherit autotools In this case, BitBake would search for the directory 724
725 inherit autotools
726
727In this case, BitBake would search for the directory
590``classes/autotools.bbclass`` in ``BBPATH``. 728``classes/autotools.bbclass`` in ``BBPATH``.
591 729
592.. note:: 730.. note::
@@ -596,24 +734,42 @@ inherit autotools In this case, BitBake would search for the directory
596 734
597If you want to use the directive to inherit multiple classes, separate 735If you want to use the directive to inherit multiple classes, separate
598them with spaces. The following example shows how to inherit both the 736them with spaces. The following example shows how to inherit both the
599``buildhistory`` and ``rm_work`` classes: inherit buildhistory rm_work 737``buildhistory`` and ``rm_work`` classes: ::
738
739 inherit buildhistory rm_work
600 740
601An advantage with the inherit directive as compared to both the 741An advantage with the inherit directive as compared to both the
602`include <#include-directive>`__ and `require <#require-inclusion>`__ 742:ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>` and :ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>`
603directives is that you can inherit class files conditionally. You can 743directives is that you can inherit class files conditionally. You can
604accomplish this by using a variable expression after the ``inherit`` 744accomplish this by using a variable expression after the ``inherit``
605statement. Here is an example: inherit ${VARNAME} If ``VARNAME`` is 745statement. Here is an example: ::
746
747 inherit ${VARNAME}
748
749If ``VARNAME`` is
606going to be set, it needs to be set before the ``inherit`` statement is 750going to be set, it needs to be set before the ``inherit`` statement is
607parsed. One way to achieve a conditional inherit in this case is to use 751parsed. One way to achieve a conditional inherit in this case is to use
608overrides: VARIABLE = "" VARIABLE_someoverride = "myclass" 752overrides: ::
753
754 VARIABLE = ""
755 VARIABLE_someoverride = "myclass"
756
757Another method is by using anonymous Python. Here is an example: ::
609 758
610Another method is by using anonymous Python. Here is an example: python 759 python () {
611() { if condition == value: d.setVar('VARIABLE', 'myclass') else: 760 if condition == value:
612d.setVar('VARIABLE', '') } 761 d.setVar('VARIABLE', 'myclass')
762 else:
763 d.setVar('VARIABLE', '')
764 }
613 765
614Alternatively, you could use an in-line Python expression in the 766Alternatively, you could use an in-line Python expression in the
615following form: inherit ${@'classname' if condition else ''} inherit 767following form: ::
616${@functionname(params)} In all cases, if the expression evaluates to an 768
769 inherit ${@'classname' if condition else ''}
770 inherit ${@functionname(params)}
771
772In all cases, if the expression evaluates to an
617empty string, the statement does not trigger a syntax error because it 773empty string, the statement does not trigger a syntax error because it
618becomes a no-op. 774becomes a no-op.
619 775
@@ -627,27 +783,24 @@ that if the path specified on the include line is a relative path,
627BitBake locates the first file it can find within ``BBPATH``. 783BitBake locates the first file it can find within ``BBPATH``.
628 784
629The include directive is a more generic method of including 785The include directive is a more generic method of including
630functionality as compared to the `inherit <#inherit-directive>`__ 786functionality as compared to the :ref:`inherit <bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` directive>`
631directive, which is restricted to class (i.e. ``.bbclass``) files. The 787directive, which is restricted to class (i.e. ``.bbclass``) files. The
632include directive is applicable for any other kind of shared or 788include directive is applicable for any other kind of shared or
633encapsulated functionality or configuration that does not suit a 789encapsulated functionality or configuration that does not suit a
634``.bbclass`` file. 790``.bbclass`` file.
635 791
636As an example, suppose you needed a recipe to include some self-test 792As an example, suppose you needed a recipe to include some self-test
637definitions: include test_defs.inc 793definitions: ::
794
795 include test_defs.inc
638 796
639.. note:: 797.. note::
640 798
641 The 799 The include directive does not produce an error when the file cannot be
642 include 800 found. Consequently, it is recommended that if the file you are including is
643 directive does not produce an error when the file cannot be found. 801 expected to exist, you should use :ref:`require <require-inclusion>` instead
644 Consequently, it is recommended that if the file you are including is 802 of include . Doing so makes sure that an error is produced if the file cannot
645 expected to exist, you should use 803 be found.
646 :ref:`require <require-inclusion>`
647 instead of
648 include
649 . Doing so makes sure that an error is produced if the file cannot be
650 found.
651 804
652.. _require-inclusion: 805.. _require-inclusion:
653 806
@@ -662,12 +815,12 @@ the location of the directive.
662 815
663The require directive, like the include directive previously described, 816The require directive, like the include directive previously described,
664is a more generic method of including functionality as compared to the 817is a more generic method of including functionality as compared to the
665`inherit <#inherit-directive>`__ directive, which is restricted to class 818:ref:`inherit <bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` directive>` directive, which is restricted to class
666(i.e. ``.bbclass``) files. The require directive is applicable for any 819(i.e. ``.bbclass``) files. The require directive is applicable for any
667other kind of shared or encapsulated functionality or configuration that 820other kind of shared or encapsulated functionality or configuration that
668does not suit a ``.bbclass`` file. 821does not suit a ``.bbclass`` file.
669 822
670Similar to how BitBake handles ```include`` <#include-directive>`__, if 823Similar to how BitBake handles :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>`, if
671the path specified on the require line is a relative path, BitBake 824the path specified on the require line is a relative path, BitBake
672locates the first file it can find within ``BBPATH``. 825locates the first file it can find within ``BBPATH``.
673 826
@@ -678,7 +831,9 @@ include file named ``foo.inc`` that contains the common definitions
678needed to build "foo". You need to be sure ``foo.inc`` is located in the 831needed to build "foo". You need to be sure ``foo.inc`` is located in the
679same directory as your two recipe files as well. Once these conditions 832same directory as your two recipe files as well. Once these conditions
680are set up, you can share the functionality using a ``require`` 833are set up, you can share the functionality using a ``require``
681directive from within each recipe: require foo.inc 834directive from within each recipe: ::
835
836 require foo.inc
682 837
683``INHERIT`` Configuration Directive 838``INHERIT`` Configuration Directive
684----------------------------------- 839-----------------------------------
@@ -689,7 +844,10 @@ class. BitBake only supports this directive when used within a
689configuration file. 844configuration file.
690 845
691As an example, suppose you needed to inherit a class file called 846As an example, suppose you needed to inherit a class file called
692``abc.bbclass`` from a configuration file as follows: INHERIT += "abc" 847``abc.bbclass`` from a configuration file as follows: ::
848
849 INHERIT += "abc"
850
693This configuration directive causes the named class to be inherited at 851This configuration directive causes the named class to be inherited at
694the point of the directive during parsing. As with the ``inherit`` 852the point of the directive during parsing. As with the ``inherit``
695directive, the ``.bbclass`` file must be located in a "classes" 853directive, the ``.bbclass`` file must be located in a "classes"
@@ -697,18 +855,16 @@ subdirectory in one of the directories specified in ``BBPATH``.
697 855
698.. note:: 856.. note::
699 857
700 Because 858 Because .conf files are parsed first during BitBake's execution, using
701 .conf 859 INHERIT to inherit a class effectively inherits the class globally (i.e. for
702 files are parsed first during BitBake's execution, using
703 INHERIT
704 to inherit a class effectively inherits the class globally (i.e. for
705 all recipes). 860 all recipes).
706 861
707If you want to use the directive to inherit multiple classes, you can 862If you want to use the directive to inherit multiple classes, you can
708provide them on the same line in the ``local.conf`` file. Use spaces to 863provide them on the same line in the ``local.conf`` file. Use spaces to
709separate the classes. The following example shows how to inherit both 864separate the classes. The following example shows how to inherit both
710the ``autotools`` and ``pkgconfig`` classes: INHERIT += "autotools 865the ``autotools`` and ``pkgconfig`` classes: ::
711pkgconfig" 866
867 INHERIT += "autotools pkgconfig"
712 868
713Functions 869Functions
714========= 870=========
@@ -739,8 +895,13 @@ Shell Functions
739 895
740Functions written in shell script and executed either directly as 896Functions written in shell script and executed either directly as
741functions, tasks, or both. They can also be called by other shell 897functions, tasks, or both. They can also be called by other shell
742functions. Here is an example shell function definition: some_function 898functions. Here is an example shell function definition: ::
743() { echo "Hello World" } When you create these types of functions in 899
900 some_function () {
901 echo "Hello World"
902 }
903
904When you create these types of functions in
744your recipe or class files, you need to follow the shell programming 905your recipe or class files, you need to follow the shell programming
745rules. The scripts are executed by ``/bin/sh``, which may not be a bash 906rules. The scripts are executed by ``/bin/sh``, which may not be a bash
746shell but might be something such as ``dash``. You should not use 907shell but might be something such as ``dash``. You should not use
@@ -751,16 +912,36 @@ can also be applied to shell functions. Most commonly, this application
751would be used in a ``.bbappend`` file to modify functions in the main 912would be used in a ``.bbappend`` file to modify functions in the main
752recipe. It can also be used to modify functions inherited from classes. 913recipe. It can also be used to modify functions inherited from classes.
753 914
754As an example, consider the following: do_foo() { bbplain first fn } 915As an example, consider the following: ::
755fn_prepend() { bbplain second } fn() { bbplain third } do_foo_append() { 916
756bbplain fourth } Running ``do_foo`` prints the following: recipename 917 do_foo() {
757do_foo: first recipename do_foo: second recipename do_foo: third 918 bbplain first
758recipename do_foo: fourth 919 fn
920 }
921
922 fn_prepend() {
923 bbplain second
924 }
925
926 fn() {
927 bbplain third
928 }
929
930 do_foo_append() {
931 bbplain fourth
932 }
933
934Running ``do_foo`` prints the following: ::
935
936 recipename do_foo: first
937 recipename do_foo: second
938 recipename do_foo: third
939 recipename do_foo: fourth
759 940
760.. note:: 941.. note::
761 942
762 Overrides and override-style operators can be applied to any shell 943 Overrides and override-style operators can be applied to any shell
763 function, not just :ref:`tasks <bitbake-user-manual/bitbake-user-manual-metadata:Tasks>`. 944 function, not just :ref:`tasks <bitbake-user-manual/bitbake-user-manual-metadata:tasks>`.
764 945
765You can use the ``bitbake -e`` recipename command to view the final 946You can use the ``bitbake -e`` recipename command to view the final
766assembled function after all overrides have been applied. 947assembled function after all overrides have been applied.
@@ -771,33 +952,50 @@ BitBake-Style Python Functions
771These functions are written in Python and executed by BitBake or other 952These functions are written in Python and executed by BitBake or other
772Python functions using ``bb.build.exec_func()``. 953Python functions using ``bb.build.exec_func()``.
773 954
774An example BitBake function is: python some_python_function () { 955An example BitBake function is: ::
775d.setVar("TEXT", "Hello World") print d.getVar("TEXT") } Because the 956
957 python some_python_function () {
958 d.setVar("TEXT", "Hello World")
959 print d.getVar("TEXT")
960 }
961
962Because the
776Python "bb" and "os" modules are already imported, you do not need to 963Python "bb" and "os" modules are already imported, you do not need to
777import these modules. Also in these types of functions, the datastore 964import these modules. Also in these types of functions, the datastore
778("d") is a global variable and is always automatically available. 965("d") is a global variable and is always automatically available.
779 966
780.. note:: 967.. note::
781 968
782 Variable expressions (e.g. 969 Variable expressions (e.g. ``${X}`` ) are no longer expanded within Python
783 ${X} 970 functions. This behavior is intentional in order to allow you to freely set
784 ) are no longer expanded within Python functions. This behavior is 971 variable values to expandable expressions without having them expanded
785 intentional in order to allow you to freely set variable values to 972 prematurely. If you do wish to expand a variable within a Python function,
786 expandable expressions without having them expanded prematurely. If 973 use ``d.getVar("X")`` . Or, for more complicated expressions, use ``d.expand()``.
787 you do wish to expand a variable within a Python function, use
788 d.getVar("X")
789 . Or, for more complicated expressions, use
790 d.expand()
791 .
792 974
793Similar to shell functions, you can also apply overrides and 975Similar to shell functions, you can also apply overrides and
794override-style operators to BitBake-style Python functions. 976override-style operators to BitBake-style Python functions.
795 977
796As an example, consider the following: python do_foo_prepend() { 978As an example, consider the following: ::
797bb.plain("first") } python do_foo() { bb.plain("second") } python 979
798do_foo_append() { bb.plain("third") } Running ``do_foo`` prints the 980 python do_foo_prepend() {
799following: recipename do_foo: first recipename do_foo: second recipename 981 bb.plain("first")
800do_foo: third You can use the ``bitbake -e`` recipename command to view 982 }
983
984 python do_foo() {
985 bb.plain("second")
986 }
987
988 python do_foo_append() {
989 bb.plain("third")
990 }
991
992Running ``do_foo`` prints the following: ::
993
994 recipename do_foo: first
995 recipename do_foo: second
996 recipename do_foo: third
997
998You can use the ``bitbake -e`` recipename command to view
801the final assembled function after all overrides have been applied. 999the final assembled function after all overrides have been applied.
802 1000
803Python Functions 1001Python Functions
@@ -806,10 +1004,18 @@ Python Functions
806These functions are written in Python and are executed by other Python 1004These functions are written in Python and are executed by other Python
807code. Examples of Python functions are utility functions that you intend 1005code. Examples of Python functions are utility functions that you intend
808to call from in-line Python or from within other Python functions. Here 1006to call from in-line Python or from within other Python functions. Here
809is an example: def get_depends(d): if d.getVar('SOMECONDITION'): return 1007is an example: ::
810"dependencywithcond" else: return "dependency" SOMECONDITION = "1" 1008
811DEPENDS = "${@get_depends(d)}" This would result in ``DEPENDS`` 1009 def get_depends(d):
812containing ``dependencywithcond``. 1010 if d.getVar('SOMECONDITION'):
1011 return "dependencywithcond"
1012 else:
1013 return "dependency"
1014
1015 SOMECONDITION = "1"
1016 DEPENDS = "${@get_depends(d)}"
1017
1018This would result in ``DEPENDS`` containing ``dependencywithcond``.
813 1019
814Here are some things to know about Python functions: 1020Here are some things to know about Python functions:
815 1021
@@ -827,15 +1033,15 @@ BitBake-Style Python Functions Versus Python Functions
827Following are some important differences between BitBake-style Python 1033Following are some important differences between BitBake-style Python
828functions and regular Python functions defined with "def": 1034functions and regular Python functions defined with "def":
829 1035
830- Only BitBake-style Python functions can be `tasks <#tasks>`__. 1036- Only BitBake-style Python functions can be :ref:`tasks <bitbake-user-manual/bitbake-user-manual-metadata:tasks>`.
831 1037
832- Overrides and override-style operators can only be applied to 1038- Overrides and override-style operators can only be applied to
833 BitBake-style Python functions. 1039 BitBake-style Python functions.
834 1040
835- Only regular Python functions can take arguments and return values. 1041- Only regular Python functions can take arguments and return values.
836 1042
837- `Variable flags <#variable-flags>`__ such as ``[dirs]``, 1043- :ref:`Variable flags <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>` such as
838 ``[cleandirs]``, and ``[lockfiles]`` can be used on BitBake-style 1044 ``[dirs]``, ``[cleandirs]``, and ``[lockfiles]`` can be used on BitBake-style
839 Python functions, but not on regular Python functions. 1045 Python functions, but not on regular Python functions.
840 1046
841- BitBake-style Python functions generate a separate 1047- BitBake-style Python functions generate a separate
@@ -850,18 +1056,17 @@ functions and regular Python functions defined with "def":
850- Regular Python functions are called with the usual Python syntax. 1056- Regular Python functions are called with the usual Python syntax.
851 BitBake-style Python functions are usually tasks and are called 1057 BitBake-style Python functions are usually tasks and are called
852 directly by BitBake, but can also be called manually from Python code 1058 directly by BitBake, but can also be called manually from Python code
853 by using the ``bb.build.exec_func()`` function. Here is an example: 1059 by using the ``bb.build.exec_func()`` function. Here is an example: ::
854 bb.build.exec_func("my_bitbake_style_function", d) 1060
1061 bb.build.exec_func("my_bitbake_style_function", d)
855 1062
856 .. note:: 1063 .. note::
857 1064
858 bb.build.exec_func() 1065 ``bb.build.exec_func()`` can also be used to run shell functions from Python
859 can also be used to run shell functions from Python code. If you 1066 code. If you want to run a shell function before a Python function within
860 want to run a shell function before a Python function within the 1067 the same task, then you can use a parent helper Python function that
861 same task, then you can use a parent helper Python function that 1068 starts by running the shell function with ``bb.build.exec_func()`` and then
862 starts by running the shell function with 1069 runs the Python code.
863 bb.build.exec_func()
864 and then runs the Python code.
865 1070
866 To detect errors from functions executed with 1071 To detect errors from functions executed with
867 ``bb.build.exec_func()``, you can catch the ``bb.build.FuncFailed`` 1072 ``bb.build.exec_func()``, you can catch the ``bb.build.FuncFailed``
@@ -869,20 +1074,12 @@ functions and regular Python functions defined with "def":
869 1074
870 .. note:: 1075 .. note::
871 1076
872 Functions in metadata (recipes and classes) should not themselves 1077 Functions in metadata (recipes and classes) should not themselves raise
873 raise 1078 ``bb.build.FuncFailed``. Rather, ``bb.build.FuncFailed`` should be viewed as a
874 bb.build.FuncFailed 1079 general indicator that the called function failed by raising an
875 . Rather, 1080 exception. For example, an exception raised by ``bb.fatal()`` will be caught
876 bb.build.FuncFailed 1081 inside ``bb.build.exec_func()``, and a ``bb.build.FuncFailed`` will be raised in
877 should be viewed as a general indicator that the called function 1082 response.
878 failed by raising an exception. For example, an exception raised
879 by
880 bb.fatal()
881 will be caught inside
882 bb.build.exec_func()
883 , and a
884 bb.build.FuncFailed
885 will be raised in response.
886 1083
887Due to their simplicity, you should prefer regular Python functions over 1084Due to their simplicity, you should prefer regular Python functions over
888BitBake-style Python functions unless you need a feature specific to 1085BitBake-style Python functions unless you need a feature specific to
@@ -897,32 +1094,62 @@ Sometimes it is useful to set variables or perform other operations
897programmatically during parsing. To do this, you can define special 1094programmatically during parsing. To do this, you can define special
898Python functions, called anonymous Python functions, that run at the end 1095Python functions, called anonymous Python functions, that run at the end
899of parsing. For example, the following conditionally sets a variable 1096of parsing. For example, the following conditionally sets a variable
900based on the value of another variable: python () { if 1097based on the value of another variable: ::
901d.getVar('SOMEVAR') == 'value': d.setVar('ANOTHERVAR', 'value2') } An 1098
902equivalent way to mark a function as an anonymous function is to give it 1099 python () {
1100 if d.getVar('SOMEVAR') == 'value':
1101 d.setVar('ANOTHERVAR', 'value2')
1102 }
1103
1104An equivalent way to mark a function as an anonymous function is to give it
903the name "__anonymous", rather than no name. 1105the name "__anonymous", rather than no name.
904 1106
905Anonymous Python functions always run at the end of parsing, regardless 1107Anonymous Python functions always run at the end of parsing, regardless
906of where they are defined. If a recipe contains many anonymous 1108of where they are defined. If a recipe contains many anonymous
907functions, they run in the same order as they are defined within the 1109functions, they run in the same order as they are defined within the
908recipe. As an example, consider the following snippet: python () { 1110recipe. As an example, consider the following snippet: ::
909d.setVar('FOO', 'foo 2') } FOO = "foo 1" python () { d.appendVar('BAR', 1111
910' bar 2') } BAR = "bar 1" The previous example is conceptually 1112 python () {
911equivalent to the following snippet: FOO = "foo 1" BAR = "bar 1" FOO = 1113 d.setVar('FOO', 'foo 2')
912"foo 2" BAR += "bar 2" ``FOO`` ends up with the value "foo 2", and 1114 }
1115
1116 FOO = "foo 1"
1117
1118 python () {
1119 d.appendVar('BAR',' bar 2')
1120 }
1121
1122 BAR = "bar 1"
1123
1124The previous example is conceptually
1125equivalent to the following snippet: ::
1126
1127 FOO = "foo 1"
1128 BAR = "bar 1"
1129 FOO = "foo 2"
1130 BAR += "bar 2"
1131
1132``FOO`` ends up with the value "foo 2", and
913``BAR`` with the value "bar 1 bar 2". Just as in the second snippet, the 1133``BAR`` with the value "bar 1 bar 2". Just as in the second snippet, the
914values set for the variables within the anonymous functions become 1134values set for the variables within the anonymous functions become
915available to tasks, which always run after parsing. 1135available to tasks, which always run after parsing.
916 1136
917Overrides and override-style operators such as "``_append``" are applied 1137Overrides and override-style operators such as "``_append``" are applied
918before anonymous functions run. In the following example, ``FOO`` ends 1138before anonymous functions run. In the following example, ``FOO`` ends
919up with the value "foo from anonymous": FOO = "foo" FOO_append = " from 1139up with the value "foo from anonymous": ::
920outside" python () { d.setVar("FOO", "foo from anonymous") } For methods 1140
921you can use with anonymous Python functions, see the "`Functions You Can 1141 FOO = "foo"
922Call From Within Python <#functions-you-can-call-from-within-python>`__" 1142 FOO_append = " from outside"
1143
1144 python () {
1145 d.setVar("FOO", "foo from anonymous")
1146 }
1147
1148For methods
1149you can use with anonymous Python functions, see the
1150":ref:`bitbake-user-manual/bitbake-user-manual-metadata:functions you can call from within python`"
923section. For a different method to run Python code during parsing, see 1151section. For a different method to run Python code during parsing, see
924the "`Inline Python Variable 1152the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:inline python variable expansion`" section.
925Expansion <#inline-python-variable-expansion>`__" section.
926 1153
927Flexible Inheritance for Class Functions 1154Flexible Inheritance for Class Functions
928---------------------------------------- 1155----------------------------------------
@@ -946,24 +1173,43 @@ version of the function.
946 1173
947To make use of this technique, you need the following things in place: 1174To make use of this technique, you need the following things in place:
948 1175
949- The class needs to define the function as follows: 1176- The class needs to define the function as follows: ::
950 classname\ ``_``\ functionname For example, if you have a class file 1177
1178 classname_functionname
1179
1180 For example, if you have a class file
951 ``bar.bbclass`` and a function named ``do_foo``, the class must 1181 ``bar.bbclass`` and a function named ``do_foo``, the class must
952 define the function as follows: bar_do_foo 1182 define the function as follows: ::
1183
1184 bar_do_foo
953 1185
954- The class needs to contain the ``EXPORT_FUNCTIONS`` statement as 1186- The class needs to contain the ``EXPORT_FUNCTIONS`` statement as
955 follows: EXPORT_FUNCTIONS functionname For example, continuing with 1187 follows: ::
1188
1189 EXPORT_FUNCTIONS functionname
1190
1191 For example, continuing with
956 the same example, the statement in the ``bar.bbclass`` would be as 1192 the same example, the statement in the ``bar.bbclass`` would be as
957 follows: EXPORT_FUNCTIONS do_foo 1193 follows: ::
1194
1195 EXPORT_FUNCTIONS do_foo
958 1196
959- You need to call the function appropriately from within your recipe. 1197- You need to call the function appropriately from within your recipe.
960 Continuing with the same example, if your recipe needs to call the 1198 Continuing with the same example, if your recipe needs to call the
961 class version of the function, it should call ``bar_do_foo``. 1199 class version of the function, it should call ``bar_do_foo``.
962 Assuming ``do_foo`` was a shell function and ``EXPORT_FUNCTIONS`` was 1200 Assuming ``do_foo`` was a shell function and ``EXPORT_FUNCTIONS`` was
963 used as above, the recipe's function could conditionally call the 1201 used as above, the recipe's function could conditionally call the
964 class version of the function as follows: do_foo() { if [ 1202 class version of the function as follows: ::
965 somecondition ] ; then bar_do_foo else # Do something else fi } To 1203
966 call your modified version of the function as defined in your recipe, 1204 do_foo() {
1205 if [ somecondition ] ; then
1206 bar_do_foo
1207 else
1208 # Do something else
1209 fi
1210 }
1211
1212 To call your modified version of the function as defined in your recipe,
967 call it as ``do_foo``. 1213 call it as ``do_foo``.
968 1214
969With these conditions met, your single recipe can freely choose between 1215With these conditions met, your single recipe can freely choose between
@@ -982,14 +1228,20 @@ classes (i.e. in ``.bb`` files and files included or inherited from
982Promoting a Function to a Task 1228Promoting a Function to a Task
983------------------------------ 1229------------------------------
984 1230
985Tasks are either `shell functions <#shell-functions>`__ or 1231Tasks are either :ref:`shell functions <bitbake-user-manual/bitbake-user-manual-metadata:shell functions>` or
986`BitBake-style Python functions <#bitbake-style-python-functions>`__ 1232:ref:`BitBake-style Python functions <bitbake-user-manual/bitbake-user-manual-metadata:bitbake-style python functions>`
987that have been promoted to tasks by using the ``addtask`` command. The 1233that have been promoted to tasks by using the ``addtask`` command. The
988``addtask`` command can also optionally describe dependencies between 1234``addtask`` command can also optionally describe dependencies between
989the task and other tasks. Here is an example that shows how to define a 1235the task and other tasks. Here is an example that shows how to define a
990task and declare some dependencies: python do_printdate () { import time 1236task and declare some dependencies: ::
991print time.strftime('%Y%m%d', time.gmtime()) } addtask printdate after 1237
992do_fetch before do_build The first argument to ``addtask`` is the name 1238 python do_printdate () {
1239 import time
1240 print time.strftime('%Y%m%d', time.gmtime())
1241 }
1242 addtask printdate after do_fetch before do_build
1243
1244The first argument to ``addtask`` is the name
993of the function to promote to a task. If the name does not start with 1245of the function to promote to a task. If the name does not start with
994"do\_", "do\_" is implicitly added, which enforces the convention that all 1246"do\_", "do\_" is implicitly added, which enforces the convention that all
995task names start with "do\_". 1247task names start with "do\_".
@@ -1004,49 +1256,44 @@ Additionally, the ``do_printdate`` task becomes dependent upon the
1004.. note:: 1256.. note::
1005 1257
1006 If you try out the previous example, you might see that the 1258 If you try out the previous example, you might see that the
1007 do_printdate 1259 ``do_printdate``
1008 task is only run the first time you build the recipe with the 1260 task is only run the first time you build the recipe with the
1009 bitbake 1261 ``bitbake``
1010 command. This is because BitBake considers the task "up-to-date" 1262 command. This is because BitBake considers the task "up-to-date"
1011 after that initial run. If you want to force the task to always be 1263 after that initial run. If you want to force the task to always be
1012 rerun for experimentation purposes, you can make BitBake always 1264 rerun for experimentation purposes, you can make BitBake always
1013 consider the task "out-of-date" by using the 1265 consider the task "out-of-date" by using the
1014 :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>` 1266 :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>`
1015 variable flag, as follows: 1267 variable flag, as follows: ::
1016 ::
1017 1268
1018 do_printdate[nostamp] = "1" 1269 do_printdate[nostamp] = "1"
1019
1020 1270
1021 You can also explicitly run the task and provide the 1271 You can also explicitly run the task and provide the
1022 -f 1272 -f option as follows: ::
1023 option as follows: 1273
1024 :: 1274 $ bitbake recipe -c printdate -f
1025 1275
1026 $ bitbake recipe -c printdate -f 1276 When manually selecting a task to run with the bitbake ``recipe
1027 1277 -c task`` command, you can omit the "do\_" prefix as part of the task
1028 1278 name.
1029 When manually selecting a task to run with the
1030 bitbake
1031 NBSP
1032 recipe
1033 NBSP
1034 -c
1035 NBSP
1036 task
1037 command, you can omit the "do\_" prefix as part of the task name.
1038 1279
1039You might wonder about the practical effects of using ``addtask`` 1280You might wonder about the practical effects of using ``addtask``
1040without specifying any dependencies as is done in the following example: 1281without specifying any dependencies as is done in the following example: ::
1041addtask printdate In this example, assuming dependencies have not been 1282
1283 addtask printdate
1284
1285In this example, assuming dependencies have not been
1042added through some other means, the only way to run the task is by 1286added through some other means, the only way to run the task is by
1043explicitly selecting it with ``bitbake`` recipe ``-c printdate``. You 1287explicitly selecting it with ``bitbake`` recipe ``-c printdate``. You
1044can use the ``do_listtasks`` task to list all tasks defined in a recipe 1288can use the ``do_listtasks`` task to list all tasks defined in a recipe
1045as shown in the following example: $ bitbake recipe -c listtasks For 1289as shown in the following example: ::
1046more information on task dependencies, see the
1047"`Dependencies <#dependencies>`__" section.
1048 1290
1049See the "`Variable Flags <#variable-flags>`__" section for information 1291 $ bitbake recipe -c listtasks
1292
1293For more information on task dependencies, see the
1294":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" section.
1295
1296See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section for information
1050on variable flags you can use with tasks. 1297on variable flags you can use with tasks.
1051 1298
1052Deleting a Task 1299Deleting a Task
@@ -1054,8 +1301,11 @@ Deleting a Task
1054 1301
1055As well as being able to add tasks, you can delete them. Simply use the 1302As well as being able to add tasks, you can delete them. Simply use the
1056``deltask`` command to delete a task. For example, to delete the example 1303``deltask`` command to delete a task. For example, to delete the example
1057task used in the previous sections, you would use: deltask printdate If 1304task used in the previous sections, you would use: ::
1058you delete a task using the ``deltask`` command and the task has 1305
1306 deltask printdate
1307
1308If you delete a task using the ``deltask`` command and the task has
1059dependencies, the dependencies are not reconnected. For example, suppose 1309dependencies, the dependencies are not reconnected. For example, suppose
1060you have three tasks named ``do_a``, ``do_b``, and ``do_c``. 1310you have three tasks named ``do_a``, ``do_b``, and ``do_c``.
1061Furthermore, ``do_c`` is dependent on ``do_b``, which in turn is 1311Furthermore, ``do_c`` is dependent on ``do_b``, which in turn is
@@ -1067,7 +1317,9 @@ to run before ``do_a``.
1067 1317
1068If you want dependencies such as these to remain intact, use the 1318If you want dependencies such as these to remain intact, use the
1069``[noexec]`` varflag to disable the task instead of using the 1319``[noexec]`` varflag to disable the task instead of using the
1070``deltask`` command to delete it: do_b[noexec] = "1" 1320``deltask`` command to delete it: ::
1321
1322 do_b[noexec] = "1"
1071 1323
1072Passing Information Into the Build Task Environment 1324Passing Information Into the Build Task Environment
1073--------------------------------------------------- 1325---------------------------------------------------
@@ -1081,30 +1333,31 @@ the build machine cannot influence the build.
1081 By default, BitBake cleans the environment to include only those 1333 By default, BitBake cleans the environment to include only those
1082 things exported or listed in its whitelist to ensure that the build 1334 things exported or listed in its whitelist to ensure that the build
1083 environment is reproducible and consistent. You can prevent this 1335 environment is reproducible and consistent. You can prevent this
1084 "cleaning" by setting the 1336 "cleaning" by setting the :term:`BB_PRESERVE_ENV` variable.
1085 :term:`BB_PRESERVE_ENV`
1086 variable.
1087 1337
1088Consequently, if you do want something to get passed into the build task 1338Consequently, if you do want something to get passed into the build task
1089environment, you must take these two steps: 1339environment, you must take these two steps:
1090 1340
10911. Tell BitBake to load what you want from the environment into the 1341#. Tell BitBake to load what you want from the environment into the
1092 datastore. You can do so through the 1342 datastore. You can do so through the
1093 :term:`BB_ENV_WHITELIST` and 1343 :term:`BB_ENV_WHITELIST` and
1094 :term:`BB_ENV_EXTRAWHITE` variables. For 1344 :term:`BB_ENV_EXTRAWHITE` variables. For
1095 example, assume you want to prevent the build system from accessing 1345 example, assume you want to prevent the build system from accessing
1096 your ``$HOME/.ccache`` directory. The following command "whitelists" 1346 your ``$HOME/.ccache`` directory. The following command "whitelists"
1097 the environment variable ``CCACHE_DIR`` causing BitBake to allow that 1347 the environment variable ``CCACHE_DIR`` causing BitBake to allow that
1098 variable into the datastore: export 1348 variable into the datastore: ::
1099 BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" 1349
1350 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
1100 1351
11012. Tell BitBake to export what you have loaded into the datastore to the 1352#. Tell BitBake to export what you have loaded into the datastore to the
1102 task environment of every running task. Loading something from the 1353 task environment of every running task. Loading something from the
1103 environment into the datastore (previous step) only makes it 1354 environment into the datastore (previous step) only makes it
1104 available in the datastore. To export it to the task environment of 1355 available in the datastore. To export it to the task environment of
1105 every running task, use a command similar to the following in your 1356 every running task, use a command similar to the following in your
1106 local configuration file ``local.conf`` or your distribution 1357 local configuration file ``local.conf`` or your distribution
1107 configuration file: export CCACHE_DIR 1358 configuration file: ::
1359
1360 export CCACHE_DIR
1108 1361
1109 .. note:: 1362 .. note::
1110 1363
@@ -1116,15 +1369,17 @@ environment, you must take these two steps:
1116 1369
1117Sometimes, it is useful to be able to obtain information from the 1370Sometimes, it is useful to be able to obtain information from the
1118original execution environment. BitBake saves a copy of the original 1371original execution environment. BitBake saves a copy of the original
1119environment into a special variable named 1372environment into a special variable named :term:`BB_ORIGENV`.
1120:term:`BB_ORIGENV`.
1121 1373
1122The ``BB_ORIGENV`` variable returns a datastore object that can be 1374The ``BB_ORIGENV`` variable returns a datastore object that can be
1123queried using the standard datastore operators such as 1375queried using the standard datastore operators such as
1124``getVar(, False)``. The datastore object is useful, for example, to 1376``getVar(, False)``. The datastore object is useful, for example, to
1125find the original ``DISPLAY`` variable. Here is an example: origenv = 1377find the original ``DISPLAY`` variable. Here is an example: ::
1126d.getVar("BB_ORIGENV", False) bar = origenv.getVar("BAR", False) The 1378
1127previous example returns ``BAR`` from the original execution 1379 origenv = d.getVar("BB_ORIGENV", False)
1380 bar = origenv.getVar("BAR", False)
1381
1382The previous example returns ``BAR`` from the original execution
1128environment. 1383environment.
1129 1384
1130Variable Flags 1385Variable Flags
@@ -1132,71 +1387,70 @@ Variable Flags
1132 1387
1133Variable flags (varflags) help control a task's functionality and 1388Variable flags (varflags) help control a task's functionality and
1134dependencies. BitBake reads and writes varflags to the datastore using 1389dependencies. BitBake reads and writes varflags to the datastore using
1135the following command forms: variable = d.getVarFlags("variable") 1390the following command forms: ::
1136self.d.setVarFlags("FOO", {"func": True}) 1391
1392 variable = d.getVarFlags("variable")
1393 self.d.setVarFlags("FOO", {"func": True})
1137 1394
1138When working with varflags, the same syntax, with the exception of 1395When working with varflags, the same syntax, with the exception of
1139overrides, applies. In other words, you can set, append, and prepend 1396overrides, applies. In other words, you can set, append, and prepend
1140varflags just like variables. See the "`Variable Flag 1397varflags just like variables. See the
1141Syntax <#variable-flag-syntax>`__" section for details. 1398":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flag syntax`" section for details.
1142 1399
1143BitBake has a defined set of varflags available for recipes and classes. 1400BitBake has a defined set of varflags available for recipes and classes.
1144Tasks support a number of these flags which control various 1401Tasks support a number of these flags which control various
1145functionality of the task: 1402functionality of the task:
1146 1403
1147- *``[cleandirs]``:* Empty directories that should be created before 1404- ``[cleandirs]``: Empty directories that should be created before
1148 the task runs. Directories that already exist are removed and 1405 the task runs. Directories that already exist are removed and
1149 recreated to empty them. 1406 recreated to empty them.
1150 1407
1151- *``[depends]``:* Controls inter-task dependencies. See the 1408- ``[depends]``: Controls inter-task dependencies. See the
1152 :term:`DEPENDS` variable and the "`Inter-Task 1409 :term:`DEPENDS` variable and the
1153 Dependencies <#inter-task-dependencies>`__" section for more 1410 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:inter-task
1154 information. 1411 dependencies`" section for more information.
1155 1412
1156- *``[deptask]``:* Controls task build-time dependencies. See the 1413- ``[deptask]``: Controls task build-time dependencies. See the
1157 :term:`DEPENDS` variable and the "`Build 1414 :term:`DEPENDS` variable and the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:build dependencies`" section for more information.
1158 Dependencies <#build-dependencies>`__" section for more information.
1159 1415
1160- *``[dirs]``:* Directories that should be created before the task 1416- ``[dirs]``: Directories that should be created before the task
1161 runs. Directories that already exist are left as is. The last 1417 runs. Directories that already exist are left as is. The last
1162 directory listed is used as the current working directory for the 1418 directory listed is used as the current working directory for the
1163 task. 1419 task.
1164 1420
1165- *``[lockfiles]``:* Specifies one or more lockfiles to lock while the 1421- ``[lockfiles]``: Specifies one or more lockfiles to lock while the
1166 task executes. Only one task may hold a lockfile, and any task that 1422 task executes. Only one task may hold a lockfile, and any task that
1167 attempts to lock an already locked file will block until the lock is 1423 attempts to lock an already locked file will block until the lock is
1168 released. You can use this variable flag to accomplish mutual 1424 released. You can use this variable flag to accomplish mutual
1169 exclusion. 1425 exclusion.
1170 1426
1171- *``[noexec]``:* When set to "1", marks the task as being empty, with 1427- ``[noexec]``: When set to "1", marks the task as being empty, with
1172 no execution required. You can use the ``[noexec]`` flag to set up 1428 no execution required. You can use the ``[noexec]`` flag to set up
1173 tasks as dependency placeholders, or to disable tasks defined 1429 tasks as dependency placeholders, or to disable tasks defined
1174 elsewhere that are not needed in a particular recipe. 1430 elsewhere that are not needed in a particular recipe.
1175 1431
1176- *``[nostamp]``:* When set to "1", tells BitBake to not generate a 1432- ``[nostamp]``: When set to "1", tells BitBake to not generate a
1177 stamp file for a task, which implies the task should always be 1433 stamp file for a task, which implies the task should always be
1178 executed. 1434 executed.
1179 1435
1180 .. note:: 1436 .. caution::
1181 1437
1182 Any task that depends (possibly indirectly) on a 1438 Any task that depends (possibly indirectly) on a ``[nostamp]`` task will
1183 [nostamp] 1439 always be executed as well. This can cause unnecessary rebuilding if you
1184 task will always be executed as well. This can cause unnecessary 1440 are not careful.
1185 rebuilding if you are not careful.
1186 1441
1187- *``[number_threads]``:* Limits tasks to a specific number of 1442- ``[number_threads]``: Limits tasks to a specific number of
1188 simultaneous threads during execution. This varflag is useful when 1443 simultaneous threads during execution. This varflag is useful when
1189 your build host has a large number of cores but certain tasks need to 1444 your build host has a large number of cores but certain tasks need to
1190 be rate-limited due to various kinds of resource constraints (e.g. to 1445 be rate-limited due to various kinds of resource constraints (e.g. to
1191 avoid network throttling). ``number_threads`` works similarly to the 1446 avoid network throttling). ``number_threads`` works similarly to the
1192 :term:`BB_NUMBER_THREADS` variable but is 1447 :term:`BB_NUMBER_THREADS` variable but is task-specific.
1193 task-specific.
1194 1448
1195 Set the value globally. For example, the following makes sure the 1449 Set the value globally. For example, the following makes sure the
1196 ``do_fetch`` task uses no more than two simultaneous execution 1450 ``do_fetch`` task uses no more than two simultaneous execution
1197 threads: do_fetch[number_threads] = "2" 1451 threads: do_fetch[number_threads] = "2"
1198 1452
1199 .. note:: 1453 .. warning::
1200 1454
1201 - Setting the varflag in individual recipes rather than globally 1455 - Setting the varflag in individual recipes rather than globally
1202 can result in unpredictable behavior. 1456 can result in unpredictable behavior.
@@ -1205,59 +1459,59 @@ functionality of the task:
1205 the ``BB_NUMBER_THREADS`` variable causes ``number_threads`` to 1459 the ``BB_NUMBER_THREADS`` variable causes ``number_threads`` to
1206 have no effect. 1460 have no effect.
1207 1461
1208- *``[postfuncs]``:* List of functions to call after the completion of 1462- ``[postfuncs]``: List of functions to call after the completion of
1209 the task. 1463 the task.
1210 1464
1211- *``[prefuncs]``:* List of functions to call before the task executes. 1465- ``[prefuncs]``: List of functions to call before the task executes.
1212 1466
1213- *``[rdepends]``:* Controls inter-task runtime dependencies. See the 1467- ``[rdepends]``: Controls inter-task runtime dependencies. See the
1214 :term:`RDEPENDS` variable, the 1468 :term:`RDEPENDS` variable, the
1215 :term:`RRECOMMENDS` variable, and the 1469 :term:`RRECOMMENDS` variable, and the
1216 "`Inter-Task Dependencies <#inter-task-dependencies>`__" section for 1470 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:inter-task dependencies`" section for
1217 more information. 1471 more information.
1218 1472
1219- *``[rdeptask]``:* Controls task runtime dependencies. See the 1473- ``[rdeptask]``: Controls task runtime dependencies. See the
1220 :term:`RDEPENDS` variable, the 1474 :term:`RDEPENDS` variable, the
1221 :term:`RRECOMMENDS` variable, and the "`Runtime 1475 :term:`RRECOMMENDS` variable, and the
1222 Dependencies <#runtime-dependencies>`__" section for more 1476 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:runtime dependencies`" section for more
1223 information. 1477 information.
1224 1478
1225- *``[recideptask]``:* When set in conjunction with ``recrdeptask``, 1479- ``[recideptask]``: When set in conjunction with ``recrdeptask``,
1226 specifies a task that should be inspected for additional 1480 specifies a task that should be inspected for additional
1227 dependencies. 1481 dependencies.
1228 1482
1229- *``[recrdeptask]``:* Controls task recursive runtime dependencies. 1483- ``[recrdeptask]``: Controls task recursive runtime dependencies.
1230 See the :term:`RDEPENDS` variable, the 1484 See the :term:`RDEPENDS` variable, the
1231 :term:`RRECOMMENDS` variable, and the 1485 :term:`RRECOMMENDS` variable, and the
1232 "`Recursive Dependencies <#recursive-dependencies>`__" section for 1486 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:recursive dependencies`" section for
1233 more information. 1487 more information.
1234 1488
1235- *``[stamp-extra-info]``:* Extra stamp information to append to the 1489- ``[stamp-extra-info]``: Extra stamp information to append to the
1236 task's stamp. As an example, OpenEmbedded uses this flag to allow 1490 task's stamp. As an example, OpenEmbedded uses this flag to allow
1237 machine-specific tasks. 1491 machine-specific tasks.
1238 1492
1239- *``[umask]``:* The umask to run the task under. 1493- ``[umask]``: The umask to run the task under.
1240 1494
1241Several varflags are useful for controlling how signatures are 1495Several varflags are useful for controlling how signatures are
1242calculated for variables. For more information on this process, see the 1496calculated for variables. For more information on this process, see the
1243"`Checksums (Signatures) <#checksums>`__" section. 1497":ref:`bitbake-user-manual/bitbake-user-manual-execution:checksums (signatures)`" section.
1244 1498
1245- *``[vardeps]``:* Specifies a space-separated list of additional 1499- ``[vardeps]``: Specifies a space-separated list of additional
1246 variables to add to a variable's dependencies for the purposes of 1500 variables to add to a variable's dependencies for the purposes of
1247 calculating its signature. Adding variables to this list is useful, 1501 calculating its signature. Adding variables to this list is useful,
1248 for example, when a function refers to a variable in a manner that 1502 for example, when a function refers to a variable in a manner that
1249 does not allow BitBake to automatically determine that the variable 1503 does not allow BitBake to automatically determine that the variable
1250 is referred to. 1504 is referred to.
1251 1505
1252- *``[vardepsexclude]``:* Specifies a space-separated list of variables 1506- ``[vardepsexclude]``: Specifies a space-separated list of variables
1253 that should be excluded from a variable's dependencies for the 1507 that should be excluded from a variable's dependencies for the
1254 purposes of calculating its signature. 1508 purposes of calculating its signature.
1255 1509
1256- *``[vardepvalue]``:* If set, instructs BitBake to ignore the actual 1510- ``[vardepvalue]``: If set, instructs BitBake to ignore the actual
1257 value of the variable and instead use the specified value when 1511 value of the variable and instead use the specified value when
1258 calculating the variable's signature. 1512 calculating the variable's signature.
1259 1513
1260- *``[vardepvalueexclude]``:* Specifies a pipe-separated list of 1514- ``[vardepvalueexclude]``: Specifies a pipe-separated list of
1261 strings to exclude from the variable's value when calculating the 1515 strings to exclude from the variable's value when calculating the
1262 variable's signature. 1516 variable's signature.
1263 1517
@@ -1272,12 +1526,18 @@ intent is to make it easy to do things like email notification on build
1272failures. 1526failures.
1273 1527
1274Following is an example event handler that prints the name of the event 1528Following is an example event handler that prints the name of the event
1275and the content of the ``FILE`` variable: addhandler 1529and the content of the ``FILE`` variable: ::
1276myclass_eventhandler python myclass_eventhandler() { from bb.event 1530
1277import getName print("The name of the Event is %s" % getName(e)) 1531 addhandler myclass_eventhandler
1278print("The file we run for is %s" % d.getVar('FILE')) } 1532 python myclass_eventhandler() {
1279myclass_eventhandler[eventmask] = "bb.event.BuildStarted 1533 from bb.event import getName
1280bb.event.BuildCompleted" In the previous example, an eventmask has been 1534 print("The name of the Event is %s" % getName(e))
1535 print("The file we run for is %s" % d.getVar('FILE'))
1536 }
1537 myclass_eventhandler[eventmask] = "bb.event.BuildStarted
1538 bb.event.BuildCompleted"
1539
1540In the previous example, an eventmask has been
1281set so that the handler only sees the "BuildStarted" and 1541set so that the handler only sees the "BuildStarted" and
1282"BuildCompleted" events. This event handler gets called every time an 1542"BuildCompleted" events. This event handler gets called every time an
1283event matching the eventmask is triggered. A global variable "e" is 1543event matching the eventmask is triggered. A global variable "e" is
@@ -1365,21 +1625,13 @@ information from the BitBake server to other parts of BitBake such as
1365user interfaces: 1625user interfaces:
1366 1626
1367- ``bb.event.TreeDataPreparationStarted()`` 1627- ``bb.event.TreeDataPreparationStarted()``
1368
1369- ``bb.event.TreeDataPreparationProgress()`` 1628- ``bb.event.TreeDataPreparationProgress()``
1370
1371- ``bb.event.TreeDataPreparationCompleted()`` 1629- ``bb.event.TreeDataPreparationCompleted()``
1372
1373- ``bb.event.DepTreeGenerated()`` 1630- ``bb.event.DepTreeGenerated()``
1374
1375- ``bb.event.CoreBaseFilesFound()`` 1631- ``bb.event.CoreBaseFilesFound()``
1376
1377- ``bb.event.ConfigFilePathFound()`` 1632- ``bb.event.ConfigFilePathFound()``
1378
1379- ``bb.event.FilesMatchingFound()`` 1633- ``bb.event.FilesMatchingFound()``
1380
1381- ``bb.event.ConfigFilesFound()`` 1634- ``bb.event.ConfigFilesFound()``
1382
1383- ``bb.event.TargetsTreeGenerated()`` 1635- ``bb.event.TargetsTreeGenerated()``
1384 1636
1385.. _variants-class-extension-mechanism: 1637.. _variants-class-extension-mechanism:
@@ -1390,49 +1642,43 @@ Variants - Class Extension Mechanism
1390BitBake supports two features that facilitate creating from a single 1642BitBake supports two features that facilitate creating from a single
1391recipe file multiple incarnations of that recipe file where all 1643recipe file multiple incarnations of that recipe file where all
1392incarnations are buildable. These features are enabled through the 1644incarnations are buildable. These features are enabled through the
1393:term:`BBCLASSEXTEND` and 1645:term:`BBCLASSEXTEND` and :term:`BBVERSIONS` variables.
1394:term:`BBVERSIONS` variables.
1395 1646
1396.. note:: 1647.. note::
1397 1648
1398 The mechanism for this class extension is extremely specific to the 1649 The mechanism for this class extension is extremely specific to the
1399 implementation. Usually, the recipe's 1650 implementation. Usually, the recipe's :term:`PROVIDES` , :term:`PN` , and
1400 :term:`PROVIDES` 1651 :term:`DEPENDS` variables would need to be modified by the extension
1401 , 1652 class. For specific examples, see the OE-Core native , nativesdk , and
1402 :term:`PN` 1653 multilib classes.
1403 , and 1654
1404 :term:`DEPENDS` 1655- ``BBCLASSEXTEND``: This variable is a space separated list of
1405 variables would need to be modified by the extension class. For
1406 specific examples, see the OE-Core
1407 native
1408 ,
1409 nativesdk
1410 , and
1411 multilib
1412 classes.
1413
1414- *``BBCLASSEXTEND``:* This variable is a space separated list of
1415 classes used to "extend" the recipe for each variant. Here is an 1656 classes used to "extend" the recipe for each variant. Here is an
1416 example that results in a second incarnation of the current recipe 1657 example that results in a second incarnation of the current recipe
1417 being available. This second incarnation will have the "native" class 1658 being available. This second incarnation will have the "native" class
1418 inherited. BBCLASSEXTEND = "native" 1659 inherited. ::
1660
1661 BBCLASSEXTEND = "native"
1419 1662
1420- *``BBVERSIONS``:* This variable allows a single recipe to build 1663- ``BBVERSIONS``: This variable allows a single recipe to build
1421 multiple versions of a project from a single recipe file. You can 1664 multiple versions of a project from a single recipe file. You can
1422 also specify conditional metadata (using the 1665 also specify conditional metadata (using the
1423 :term:`OVERRIDES` mechanism) for a single 1666 :term:`OVERRIDES` mechanism) for a single
1424 version, or an optionally named range of versions. Here is an 1667 version, or an optionally named range of versions. Here is an
1425 example: BBVERSIONS = "1.0 2.0 git" SRC_URI_git = 1668 example: ::
1426 "git://someurl/somepath.git" BBVERSIONS = "1.0.[0-6]:1.0.0+ \\ 1669
1427 1.0.[7-9]:1.0.7+" SRC_URI_append_1.0.7+ = 1670 BBVERSIONS = "1.0 2.0 git"
1428 "file://some_patch_which_the_new_versions_need.patch;patch=1" The 1671 SRC_URI_git = "git://someurl/somepath.git"
1429 name of the range defaults to the original version of the recipe. For 1672
1430 example, in OpenEmbedded, the recipe file ``foo_1.0.0+.bb`` creates a 1673 BBVERSIONS = "1.0.[0-6]:1.0.0+ 1.0.[7-9]:1.0.7+"
1431 default name range of ``1.0.0+``. This is useful because the range 1674 SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1"
1432 name is not only placed into overrides, but it is also made available 1675
1433 for the metadata to use in the variable that defines the base recipe 1676 The name of the range defaults to the original version of the recipe. For
1434 versions for use in ``file://`` search paths 1677 example, in OpenEmbedded, the recipe file ``foo_1.0.0+.bb`` creates a default
1435 (:term:`FILESPATH`). 1678 name range of ``1.0.0+``. This is useful because the range name is not only
1679 placed into overrides, but it is also made available for the metadata to use
1680 in the variable that defines the base recipe versions for use in ``file://``
1681 search paths (:term:`FILESPATH`).
1436 1682
1437Dependencies 1683Dependencies
1438============ 1684============
@@ -1462,8 +1708,11 @@ Dependencies Internal to the ``.bb`` File
1462BitBake uses the ``addtask`` directive to manage dependencies that are 1708BitBake uses the ``addtask`` directive to manage dependencies that are
1463internal to a given recipe file. You can use the ``addtask`` directive 1709internal to a given recipe file. You can use the ``addtask`` directive
1464to indicate when a task is dependent on other tasks or when other tasks 1710to indicate when a task is dependent on other tasks or when other tasks
1465depend on that recipe. Here is an example: addtask printdate after 1711depend on that recipe. Here is an example: ::
1466do_fetch before do_build In this example, the ``do_printdate`` task 1712
1713 addtask printdate after do_fetch before do_build
1714
1715In this example, the ``do_printdate`` task
1467depends on the completion of the ``do_fetch`` task, and the ``do_build`` 1716depends on the completion of the ``do_fetch`` task, and the ``do_build``
1468task depends on the completion of the ``do_printdate`` task. 1717task depends on the completion of the ``do_printdate`` task.
1469 1718
@@ -1476,16 +1725,19 @@ task depends on the completion of the ``do_printdate`` task.
1476 1725
1477 - The directive ``addtask mytask before do_configure`` causes 1726 - The directive ``addtask mytask before do_configure`` causes
1478 ``do_mytask`` to run before ``do_configure`` runs. Be aware that 1727 ``do_mytask`` to run before ``do_configure`` runs. Be aware that
1479 ``do_mytask`` still only runs if its `input 1728 ``do_mytask`` still only runs if its :ref:`input
1480 checksum <#checksums>`__ has changed since the last time it was 1729 checksum <bitbake-user-manual/bitbake-user-manual-execution:checksums (signatures)>` has changed since the last time it was
1481 run. Changes to the input checksum of ``do_mytask`` also 1730 run. Changes to the input checksum of ``do_mytask`` also
1482 indirectly cause ``do_configure`` to run. 1731 indirectly cause ``do_configure`` to run.
1483 1732
1484 - The directive ``addtask mytask after do_configure`` by itself 1733 - The directive ``addtask mytask after do_configure`` by itself
1485 never causes ``do_mytask`` to run. ``do_mytask`` can still be run 1734 never causes ``do_mytask`` to run. ``do_mytask`` can still be run
1486 manually as follows: $ bitbake recipe -c mytask Declaring 1735 manually as follows: ::
1487 ``do_mytask`` as a dependency of some other task that is scheduled 1736
1488 to run also causes it to run. Regardless, the task runs after 1737 $ bitbake recipe -c mytask
1738
1739 Declaring ``do_mytask`` as a dependency of some other task that is
1740 scheduled to run also causes it to run. Regardless, the task runs after
1489 ``do_configure``. 1741 ``do_configure``.
1490 1742
1491Build Dependencies 1743Build Dependencies
@@ -1494,24 +1746,29 @@ Build Dependencies
1494BitBake uses the :term:`DEPENDS` variable to manage 1746BitBake uses the :term:`DEPENDS` variable to manage
1495build time dependencies. The ``[deptask]`` varflag for tasks signifies 1747build time dependencies. The ``[deptask]`` varflag for tasks signifies
1496the task of each item listed in ``DEPENDS`` that must complete before 1748the task of each item listed in ``DEPENDS`` that must complete before
1497that task can be executed. Here is an example: do_configure[deptask] = 1749that task can be executed. Here is an example: ::
1498"do_populate_sysroot" In this example, the ``do_populate_sysroot`` task 1750
1751 do_configure[deptask] = "do_populate_sysroot"
1752
1753In this example, the ``do_populate_sysroot`` task
1499of each item in ``DEPENDS`` must complete before ``do_configure`` can 1754of each item in ``DEPENDS`` must complete before ``do_configure`` can
1500execute. 1755execute.
1501 1756
1502Runtime Dependencies 1757Runtime Dependencies
1503-------------------- 1758--------------------
1504 1759
1505BitBake uses the :term:`PACKAGES`, 1760BitBake uses the :term:`PACKAGES`, :term:`RDEPENDS`, and :term:`RRECOMMENDS`
1506:term:`RDEPENDS`, and 1761variables to manage runtime dependencies.
1507:term:`RRECOMMENDS` variables to manage runtime
1508dependencies.
1509 1762
1510The ``PACKAGES`` variable lists runtime packages. Each of those packages 1763The ``PACKAGES`` variable lists runtime packages. Each of those packages
1511can have ``RDEPENDS`` and ``RRECOMMENDS`` runtime dependencies. The 1764can have ``RDEPENDS`` and ``RRECOMMENDS`` runtime dependencies. The
1512``[rdeptask]`` flag for tasks is used to signify the task of each item 1765``[rdeptask]`` flag for tasks is used to signify the task of each item
1513runtime dependency which must have completed before that task can be 1766runtime dependency which must have completed before that task can be
1514executed. do_package_qa[rdeptask] = "do_packagedata" In the previous 1767executed. ::
1768
1769 do_package_qa[rdeptask] = "do_packagedata"
1770
1771In the previous
1515example, the ``do_packagedata`` task of each item in ``RDEPENDS`` must 1772example, the ``do_packagedata`` task of each item in ``RDEPENDS`` must
1516have completed before ``do_package_qa`` can execute. 1773have completed before ``do_package_qa`` can execute.
1517Although ``RDEPENDS`` contains entries from the 1774Although ``RDEPENDS`` contains entries from the
@@ -1531,14 +1788,18 @@ dependencies are discovered and added.
1531 1788
1532The ``[recrdeptask]`` flag is most commonly used in high-level recipes 1789The ``[recrdeptask]`` flag is most commonly used in high-level recipes
1533that need to wait for some task to finish "globally". For example, 1790that need to wait for some task to finish "globally". For example,
1534``image.bbclass`` has the following: do_rootfs[recrdeptask] += 1791``image.bbclass`` has the following: ::
1535"do_packagedata" This statement says that the ``do_packagedata`` task of 1792
1793 do_rootfs[recrdeptask] += "do_packagedata"
1794
1795This statement says that the ``do_packagedata`` task of
1536the current recipe and all recipes reachable (by way of dependencies) 1796the current recipe and all recipes reachable (by way of dependencies)
1537from the image recipe must run before the ``do_rootfs`` task can run. 1797from the image recipe must run before the ``do_rootfs`` task can run.
1538 1798
1539BitBake allows a task to recursively depend on itself by 1799BitBake allows a task to recursively depend on itself by
1540referencing itself in the task list: 1800referencing itself in the task list: ::
1541do_a[recrdeptask] = "do_a do_b" 1801
1802 do_a[recrdeptask] = "do_a do_b"
1542 1803
1543In the same way as before, this means that the ``do_a`` 1804In the same way as before, this means that the ``do_a``
1544and ``do_b`` tasks of the current recipe and all 1805and ``do_b`` tasks of the current recipe and all
@@ -1553,10 +1814,12 @@ Inter-Task Dependencies
1553BitBake uses the ``[depends]`` flag in a more generic form to manage 1814BitBake uses the ``[depends]`` flag in a more generic form to manage
1554inter-task dependencies. This more generic form allows for 1815inter-task dependencies. This more generic form allows for
1555inter-dependency checks for specific tasks rather than checks for the 1816inter-dependency checks for specific tasks rather than checks for the
1556data in ``DEPENDS``. Here is an example: do_patch[depends] = 1817data in ``DEPENDS``. Here is an example: ::
1557"quilt-native:do_populate_sysroot" In this example, the 1818
1558``do_populate_sysroot`` task of the target ``quilt-native`` must have 1819 do_patch[depends] = "quilt-native:do_populate_sysroot"
1559completed before the ``do_patch`` task can execute. 1820
1821In this example, the ``do_populate_sysroot`` task of the target ``quilt-native``
1822must have completed before the ``do_patch`` task can execute.
1560 1823
1561The ``[rdepends]`` flag works in a similar way but takes targets in the 1824The ``[rdepends]`` flag works in a similar way but takes targets in the
1562runtime namespace instead of the build-time dependency namespace. 1825runtime namespace instead of the build-time dependency namespace.
@@ -1575,83 +1838,58 @@ It is often necessary to access variables in the BitBake datastore using
1575Python functions. The BitBake datastore has an API that allows you this 1838Python functions. The BitBake datastore has an API that allows you this
1576access. Here is a list of available operations: 1839access. Here is a list of available operations:
1577 1840
1578+-----------------------------------+-----------------------------------+ 1841.. list-table::
1579| *Operation* | *Description* | 1842 :widths: auto
1580+===================================+===================================+ 1843 :header-rows: 1
1581| ``d.getVar("X", expand)`` | Returns the value of variable | 1844
1582| | "X". Using "expand=True" expands | 1845 * - *Operation*
1583| | the value. Returns "None" if the | 1846 - *Description*
1584| | variable "X" does not exist. | 1847 * - ``d.getVar("X", expand)``
1585+-----------------------------------+-----------------------------------+ 1848 - Returns the value of variable "X". Using "expand=True" expands the
1586| ``d.setVar("X", "value")`` | Sets the variable "X" to "value". | 1849 value. Returns "None" if the variable "X" does not exist.
1587+-----------------------------------+-----------------------------------+ 1850 * - ``d.setVar("X", "value")``
1588| ``d.appendVar("X", "value")`` | Adds "value" to the end of the | 1851 - Sets the variable "X" to "value"
1589| | variable "X". Acts like | 1852 * - ``d.appendVar("X", "value")``
1590| | ``d.setVar("X", "value")`` if the | 1853 - Adds "value" to the end of the variable "X". Acts like ``d.setVar("X",
1591| | variable "X" does not exist. | 1854 "value")`` if the variable "X" does not exist.
1592+-----------------------------------+-----------------------------------+ 1855 * - ``d.prependVar("X", "value")``
1593| ``d.prependVar("X", "value")`` | Adds "value" to the start of the | 1856 - Adds "value" to the start of the variable "X". Acts like
1594| | variable "X". Acts like | 1857 ``d.setVar("X","value")`` if the variable "X" does not exist.
1595| | ``d.setVar("X", "value")`` if the | 1858 * - ``d.delVar("X")``
1596| | variable "X" does not exist. | 1859 - Deletes the variable "X" from the datastore. Does nothing if the variable
1597+-----------------------------------+-----------------------------------+ 1860 "X" does not exist.
1598| ``d.delVar("X")`` | Deletes the variable "X" from the | 1861 * - ``d.renameVar("X", "Y")``
1599| | datastore. Does nothing if the | 1862 - Renames the variable "X" to "Y". Does nothing if the variable "X" does
1600| | variable "X" does not exist. | 1863 not exist.
1601+-----------------------------------+-----------------------------------+ 1864 * - ``d.getVarFlag("X", flag, expand)``
1602| ``d.renameVar("X", "Y")`` | Renames the variable "X" to "Y". | 1865 - Returns the value of variable "X". Using "expand=True" expands the
1603| | Does nothing if the variable "X" | 1866 value. Returns "None" if either the variable "X" or the named flag does
1604| | does not exist. | 1867 not exist.
1605+-----------------------------------+-----------------------------------+ 1868 * - ``d.setVarFlag("X", flag, "value")``
1606| `` | Returns the value of variable | 1869 - Sets the named flag for variable "X" to "value".
1607| d.getVarFlag("X", flag, expand)`` | "X". Using "expand=True" expands | 1870 * - ``d.appendVarFlag("X", flag, "value")``
1608| | the value. Returns "None" if | 1871 - Appends "value" to the named flag on the variable "X". Acts like
1609| | either the variable "X" or the | 1872 ``d.setVarFlag("X", flag, "value")`` if the named flag does not exist.
1610| | named flag does not exist. | 1873 * - ``d.prependVarFlag("X", flag, "value")``
1611+-----------------------------------+-----------------------------------+ 1874 - Prepends "value" to the named flag on the variable "X". Acts like
1612| ``d | Sets the named flag for variable | 1875 ``d.setVarFlag("X", flag, "value")`` if the named flag does not exist.
1613| .setVarFlag("X", flag, "value")`` | "X" to "value". | 1876 * - ``d.delVarFlag("X", flag)``
1614+-----------------------------------+-----------------------------------+ 1877 - Deletes the named flag on the variable "X" from the datastore.
1615| ``d.ap | Appends "value" to the named flag | 1878 * - ``d.setVarFlags("X", flagsdict)``
1616| pendVarFlag("X", flag, "value")`` | on the variable "X". Acts like | 1879 - Sets the flags specified in the ``flagsdict()``
1617| | ``d | 1880 parameter. ``setVarFlags`` does not clear previous flags. Think of this
1618| | .setVarFlag("X", flag, "value")`` | 1881 operation as ``addVarFlags``.
1619| | if the named flag does not exist. | 1882 * - ``d.getVarFlags("X")``
1620+-----------------------------------+-----------------------------------+ 1883 - Returns a ``flagsdict`` of the flags for the variable "X". Returns "None"
1621| ``d.pre | Prepends "value" to the named | 1884 if the variable "X" does not exist.
1622| pendVarFlag("X", flag, "value")`` | flag on the variable "X". Acts | 1885 * - ``d.delVarFlags("X")``
1623| | like | 1886 - Deletes all the flags for the variable "X". Does nothing if the variable
1624| | ``d | 1887 "X" does not exist.
1625| | .setVarFlag("X", flag, "value")`` | 1888 * - ``d.expand(expression)``
1626| | if the named flag does not exist. | 1889 - Expands variable references in the specified string
1627+-----------------------------------+-----------------------------------+ 1890 expression. References to variables that do not exist are left as is. For
1628| ``d.delVarFlag("X", flag)`` | Deletes the named flag on the | 1891 example, ``d.expand("foo ${X}")`` expands to the literal string "foo
1629| | variable "X" from the datastore. | 1892 ${X}" if the variable "X" does not exist.
1630+-----------------------------------+-----------------------------------+
1631| ``d.setVarFlags("X", flagsdict)`` | Sets the flags specified in the |
1632| | ``flagsdict()`` parameter. |
1633| | ``setVarFlags`` does not clear |
1634| | previous flags. Think of this |
1635| | operation as ``addVarFlags``. |
1636+-----------------------------------+-----------------------------------+
1637| ``d.getVarFlags("X")`` | Returns a ``flagsdict`` of the |
1638| | flags for the variable "X". |
1639| | Returns "None" if the variable |
1640| | "X" does not exist. |
1641+-----------------------------------+-----------------------------------+
1642| ``d.delVarFlags("X")`` | Deletes all the flags for the |
1643| | variable "X". Does nothing if the |
1644| | variable "X" does not exist. |
1645+-----------------------------------+-----------------------------------+
1646| ``d.expand(expression)`` | Expands variable references in |
1647| | the specified string expression. |
1648| | References to variables that do |
1649| | not exist are left as is. For |
1650| | example, ``d.expand("foo ${X}")`` |
1651| | expands to the literal string |
1652| | "foo ${X}" if the variable "X" |
1653| | does not exist. |
1654+-----------------------------------+-----------------------------------+
1655 1893
1656Other Functions 1894Other Functions
1657--------------- 1895---------------
@@ -1671,8 +1909,11 @@ To help understand how BitBake does this, the section assumes an
1671OpenEmbedded metadata-based example. 1909OpenEmbedded metadata-based example.
1672 1910
1673These checksums are stored in :term:`STAMP`. You can 1911These checksums are stored in :term:`STAMP`. You can
1674examine the checksums using the following BitBake command: $ 1912examine the checksums using the following BitBake command: ::
1675bitbake-dumpsigs This command returns the signature data in a readable 1913
1914 $ bitbake-dumpsigs
1915
1916This command returns the signature data in a readable
1676format that allows you to examine the inputs used when the OpenEmbedded 1917format that allows you to examine the inputs used when the OpenEmbedded
1677build system generates signatures. For example, using 1918build system generates signatures. For example, using
1678``bitbake-dumpsigs`` allows you to examine the ``do_compile`` task's 1919``bitbake-dumpsigs`` allows you to examine the ``do_compile`` task's