diff options
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.rst | 591 |
1 files changed, 343 insertions, 248 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 7ea68ade72..58975f4c88 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst | |||
@@ -26,7 +26,7 @@ assignment. :: | |||
26 | VARIABLE = "value" | 26 | VARIABLE = "value" |
27 | 27 | ||
28 | As expected, if you include leading or | 28 | As expected, if you include leading or |
29 | trailing spaces as part of an assignment, the spaces are retained: :: | 29 | trailing spaces as part of an assignment, the spaces are retained:: |
30 | 30 | ||
31 | VARIABLE = " value" | 31 | VARIABLE = " value" |
32 | VARIABLE = "value " | 32 | VARIABLE = "value " |
@@ -40,7 +40,7 @@ blank space (i.e. these are not the same values). :: | |||
40 | 40 | ||
41 | You can use single quotes instead of double quotes when setting a | 41 | You can use single quotes instead of double quotes when setting a |
42 | variable's value. Doing so allows you to use values that contain the | 42 | variable's value. Doing so allows you to use values that contain the |
43 | double quote character: :: | 43 | double quote character:: |
44 | 44 | ||
45 | VARIABLE = 'I have a " in my value' | 45 | VARIABLE = 'I have a " in my value' |
46 | 46 | ||
@@ -77,7 +77,7 @@ occurs, you can use BitBake to check the actual value of the suspect | |||
77 | variable. You can make these checks for both configuration and recipe | 77 | variable. You can make these checks for both configuration and recipe |
78 | level changes: | 78 | level changes: |
79 | 79 | ||
80 | - For configuration changes, use the following: :: | 80 | - For configuration changes, use the following:: |
81 | 81 | ||
82 | $ bitbake -e | 82 | $ bitbake -e |
83 | 83 | ||
@@ -91,9 +91,10 @@ level changes: | |||
91 | Variables that are exported to the environment are preceded by the | 91 | Variables that are exported to the environment are preceded by the |
92 | string "export" in the command's output. | 92 | string "export" in the command's output. |
93 | 93 | ||
94 | - For recipe changes, use the following: :: | 94 | - To find changes to a given variable in a specific recipe, use the |
95 | following:: | ||
95 | 96 | ||
96 | $ bitbake recipe -e \| grep VARIABLE=" | 97 | $ bitbake recipename -e | grep VARIABLENAME=\" |
97 | 98 | ||
98 | This command checks to see if the variable actually makes | 99 | This command checks to see if the variable actually makes |
99 | it into a specific recipe. | 100 | it into a specific recipe. |
@@ -103,20 +104,20 @@ Line Joining | |||
103 | 104 | ||
104 | Outside of :ref:`functions <bitbake-user-manual/bitbake-user-manual-metadata:functions>`, | 105 | Outside of :ref:`functions <bitbake-user-manual/bitbake-user-manual-metadata:functions>`, |
105 | BitBake joins any line ending in | 106 | BitBake joins any line ending in |
106 | a backslash character ("\") with the following line before parsing | 107 | a backslash character ("\\") with the following line before parsing |
107 | statements. The most common use for the "\" character is to split | 108 | statements. The most common use for the "\\" character is to split |
108 | variable assignments over multiple lines, as in the following example: :: | 109 | variable assignments over multiple lines, as in the following example:: |
109 | 110 | ||
110 | FOO = "bar \ | 111 | FOO = "bar \ |
111 | baz \ | 112 | baz \ |
112 | qaz" | 113 | qaz" |
113 | 114 | ||
114 | Both the "\" character and the newline | 115 | Both the "\\" character and the newline |
115 | character that follow it are removed when joining lines. Thus, no | 116 | character that follow it are removed when joining lines. Thus, no |
116 | newline characters end up in the value of ``FOO``. | 117 | newline characters end up in the value of ``FOO``. |
117 | 118 | ||
118 | Consider this additional example where the two assignments both assign | 119 | Consider this additional example where the two assignments both assign |
119 | "barbaz" to ``FOO``: :: | 120 | "barbaz" to ``FOO``:: |
120 | 121 | ||
121 | FOO = "barbaz" | 122 | FOO = "barbaz" |
122 | FOO = "bar\ | 123 | FOO = "bar\ |
@@ -124,7 +125,7 @@ Consider this additional example where the two assignments both assign | |||
124 | 125 | ||
125 | .. note:: | 126 | .. note:: |
126 | 127 | ||
127 | BitBake does not interpret escape sequences like "\n" in variable | 128 | BitBake does not interpret escape sequences like "\\n" in variable |
128 | values. For these to have an effect, the value must be passed to some | 129 | values. For these to have an effect, the value must be passed to some |
129 | utility that interprets escape sequences, such as | 130 | utility that interprets escape sequences, such as |
130 | ``printf`` or ``echo -n``. | 131 | ``printf`` or ``echo -n``. |
@@ -149,7 +150,7 @@ The "=" operator does not immediately expand variable references in the | |||
149 | right-hand side. Instead, expansion is deferred until the variable | 150 | right-hand side. Instead, expansion is deferred until the variable |
150 | assigned to is actually used. The result depends on the current values | 151 | assigned to is actually used. The result depends on the current values |
151 | of the referenced variables. The following example should clarify this | 152 | of the referenced variables. The following example should clarify this |
152 | behavior: :: | 153 | behavior:: |
153 | 154 | ||
154 | A = "${B} baz" | 155 | A = "${B} baz" |
155 | B = "${C} bar" | 156 | B = "${C} bar" |
@@ -158,7 +159,7 @@ behavior: :: | |||
158 | C = "qux" | 159 | C = "qux" |
159 | *At this point, ${A} equals "qux bar baz"* | 160 | *At this point, ${A} equals "qux bar baz"* |
160 | B = "norf" | 161 | B = "norf" |
161 | *At this point, ${A} equals "norf baz"\* | 162 | *At this point, ${A} equals "norf baz"* |
162 | 163 | ||
163 | Contrast this behavior with the | 164 | Contrast this behavior with the |
164 | :ref:`bitbake-user-manual/bitbake-user-manual-metadata:immediate variable | 165 | :ref:`bitbake-user-manual/bitbake-user-manual-metadata:immediate variable |
@@ -177,7 +178,7 @@ Setting a default value (?=) | |||
177 | You can use the "?=" operator to achieve a "softer" assignment for a | 178 | You can use the "?=" operator to achieve a "softer" assignment for a |
178 | variable. This type of assignment allows you to define a variable if it | 179 | variable. This type of assignment allows you to define a variable if it |
179 | is undefined when the statement is parsed, but to leave the value alone | 180 | is undefined when the statement is parsed, but to leave the value alone |
180 | if the variable has a value. Here is an example: :: | 181 | if the variable has a value. Here is an example:: |
181 | 182 | ||
182 | A ?= "aval" | 183 | A ?= "aval" |
183 | 184 | ||
@@ -194,28 +195,51 @@ value. However, if ``A`` is not set, the variable is set to "aval". | |||
194 | Setting a weak default value (??=) | 195 | Setting a weak default value (??=) |
195 | ---------------------------------- | 196 | ---------------------------------- |
196 | 197 | ||
197 | It is possible to use a "weaker" assignment than in the previous section | 198 | The weak default value of a variable is the value which that variable |
198 | by using the "??=" operator. This assignment behaves identical to "?=" | 199 | will expand to if no value has been assigned to it via any of the other |
199 | except that the assignment is made at the end of the parsing process | 200 | assignment operators. The "??=" operator takes effect immediately, replacing |
200 | rather than immediately. Consequently, when multiple "??=" assignments | 201 | any previously defined weak default value. Here is an example:: |
201 | exist, the last one is used. Also, any "=" or "?=" assignment will | ||
202 | override the value set with "??=". Here is an example: :: | ||
203 | 202 | ||
204 | A ??= "somevalue" | 203 | W ??= "x" |
205 | A ??= "someothervalue" | 204 | A := "${W}" # Immediate variable expansion |
205 | W ??= "y" | ||
206 | B := "${W}" # Immediate variable expansion | ||
207 | W ??= "z" | ||
208 | C = "${W}" | ||
209 | W ?= "i" | ||
206 | 210 | ||
207 | If ``A`` is set before the above statements are | 211 | After parsing we will have:: |
208 | parsed, the variable retains its value. If ``A`` is not set, the | ||
209 | variable is set to "someothervalue". | ||
210 | 212 | ||
211 | Again, this assignment is a "lazy" or "weak" assignment because it does | 213 | A = "x" |
212 | not occur until the end of the parsing process. | 214 | B = "y" |
215 | C = "i" | ||
216 | W = "i" | ||
217 | |||
218 | Appending and prepending non-override style will not substitute the weak | ||
219 | default value, which means that after parsing:: | ||
220 | |||
221 | W ??= "x" | ||
222 | W += "y" | ||
223 | |||
224 | we will have:: | ||
225 | |||
226 | W = " y" | ||
227 | |||
228 | On the other hand, override-style appends/prepends/removes are applied after | ||
229 | any active weak default value has been substituted:: | ||
230 | |||
231 | W ??= "x" | ||
232 | W:append = "y" | ||
233 | |||
234 | After parsing we will have:: | ||
235 | |||
236 | W = "xy" | ||
213 | 237 | ||
214 | Immediate variable expansion (:=) | 238 | Immediate variable expansion (:=) |
215 | --------------------------------- | 239 | --------------------------------- |
216 | 240 | ||
217 | The ":=" operator results in a variable's contents being expanded | 241 | The ":=" operator results in a variable's contents being expanded |
218 | immediately, rather than when the variable is actually used: :: | 242 | immediately, rather than when the variable is actually used:: |
219 | 243 | ||
220 | T = "123" | 244 | T = "123" |
221 | A := "test ${T}" | 245 | A := "test ${T}" |
@@ -225,7 +249,7 @@ immediately, rather than when the variable is actually used: :: | |||
225 | C := "${C}append" | 249 | C := "${C}append" |
226 | 250 | ||
227 | In this example, ``A`` contains "test 123", even though the final value | 251 | In this example, ``A`` contains "test 123", even though the final value |
228 | of ``T`` is "456". The variable ``B`` will end up containing "456 | 252 | of :term:`T` is "456". The variable :term:`B` will end up containing "456 |
229 | cvalappend". This is because references to undefined variables are | 253 | cvalappend". This is because references to undefined variables are |
230 | preserved as is during (immediate)expansion. This is in contrast to GNU | 254 | preserved as is during (immediate)expansion. This is in contrast to GNU |
231 | Make, where undefined variables expand to nothing. The variable ``C`` | 255 | Make, where undefined variables expand to nothing. The variable ``C`` |
@@ -241,14 +265,14 @@ the "+=" and "=+" operators. These operators insert a space between the | |||
241 | current value and prepended or appended value. | 265 | current value and prepended or appended value. |
242 | 266 | ||
243 | These operators take immediate effect during parsing. Here are some | 267 | These operators take immediate effect during parsing. Here are some |
244 | examples: :: | 268 | examples:: |
245 | 269 | ||
246 | B = "bval" | 270 | B = "bval" |
247 | B += "additionaldata" | 271 | B += "additionaldata" |
248 | C = "cval" | 272 | C = "cval" |
249 | C =+ "test" | 273 | C =+ "test" |
250 | 274 | ||
251 | The variable ``B`` contains "bval additionaldata" and ``C`` contains "test | 275 | The variable :term:`B` contains "bval additionaldata" and ``C`` contains "test |
252 | cval". | 276 | cval". |
253 | 277 | ||
254 | .. _appending-and-prepending-without-spaces: | 278 | .. _appending-and-prepending-without-spaces: |
@@ -260,14 +284,14 @@ If you want to append or prepend values without an inserted space, use | |||
260 | the ".=" and "=." operators. | 284 | the ".=" and "=." operators. |
261 | 285 | ||
262 | These operators take immediate effect during parsing. Here are some | 286 | These operators take immediate effect during parsing. Here are some |
263 | examples: :: | 287 | examples:: |
264 | 288 | ||
265 | B = "bval" | 289 | B = "bval" |
266 | B .= "additionaldata" | 290 | B .= "additionaldata" |
267 | C = "cval" | 291 | C = "cval" |
268 | C =. "test" | 292 | C =. "test" |
269 | 293 | ||
270 | The variable ``B`` contains "bvaladditionaldata" and ``C`` contains | 294 | The variable :term:`B` contains "bvaladditionaldata" and ``C`` contains |
271 | "testcval". | 295 | "testcval". |
272 | 296 | ||
273 | Appending and Prepending (Override Style Syntax) | 297 | Appending and Prepending (Override Style Syntax) |
@@ -278,16 +302,16 @@ style syntax. When you use this syntax, no spaces are inserted. | |||
278 | 302 | ||
279 | These operators differ from the ":=", ".=", "=.", "+=", and "=+" | 303 | These operators differ from the ":=", ".=", "=.", "+=", and "=+" |
280 | operators in that their effects are applied at variable expansion time | 304 | operators in that their effects are applied at variable expansion time |
281 | rather than being immediately applied. Here are some examples: :: | 305 | rather than being immediately applied. Here are some examples:: |
282 | 306 | ||
283 | B = "bval" | 307 | B = "bval" |
284 | B_append = " additional data" | 308 | B:append = " additional data" |
285 | C = "cval" | 309 | C = "cval" |
286 | C_prepend = "additional data " | 310 | C:prepend = "additional data " |
287 | D = "dval" | 311 | D = "dval" |
288 | D_append = "additional data" | 312 | D:append = "additional data" |
289 | 313 | ||
290 | The variable ``B`` | 314 | The variable :term:`B` |
291 | becomes "bval additional data" and ``C`` becomes "additional data cval". | 315 | becomes "bval additional data" and ``C`` becomes "additional data cval". |
292 | The variable ``D`` becomes "dvaladditional data". | 316 | The variable ``D`` becomes "dvaladditional data". |
293 | 317 | ||
@@ -295,6 +319,10 @@ The variable ``D`` becomes "dvaladditional data". | |||
295 | 319 | ||
296 | You must control all spacing when you use the override syntax. | 320 | You must control all spacing when you use the override syntax. |
297 | 321 | ||
322 | .. note:: | ||
323 | |||
324 | The overrides are applied in this order, ":append", ":prepend", ":remove". | ||
325 | |||
298 | It is also possible to append and prepend to shell functions and | 326 | It is also possible to append and prepend to shell functions and |
299 | BitBake-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`" | 327 | BitBake-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`" |
300 | sections for examples. | 328 | sections for examples. |
@@ -306,16 +334,17 @@ Removal (Override Style Syntax) | |||
306 | 334 | ||
307 | You can remove values from lists using the removal override style | 335 | You can remove values from lists using the removal override style |
308 | syntax. Specifying a value for removal causes all occurrences of that | 336 | syntax. Specifying a value for removal causes all occurrences of that |
309 | value to be removed from the variable. | 337 | value to be removed from the variable. Unlike ":append" and ":prepend", |
338 | there is no need to add a leading or trailing space to the value. | ||
310 | 339 | ||
311 | When you use this syntax, BitBake expects one or more strings. | 340 | When you use this syntax, BitBake expects one or more strings. |
312 | Surrounding spaces and spacing are preserved. Here is an example: :: | 341 | Surrounding spaces and spacing are preserved. Here is an example:: |
313 | 342 | ||
314 | FOO = "123 456 789 123456 123 456 123 456" | 343 | FOO = "123 456 789 123456 123 456 123 456" |
315 | FOO_remove = "123" | 344 | FOO:remove = "123" |
316 | FOO_remove = "456" | 345 | FOO:remove = "456" |
317 | FOO2 = " abc def ghi abcdef abc def abc def def" | 346 | FOO2 = " abc def ghi abcdef abc def abc def def" |
318 | FOO2_remove = "\ | 347 | FOO2:remove = "\ |
319 | def \ | 348 | def \ |
320 | abc \ | 349 | abc \ |
321 | ghi \ | 350 | ghi \ |
@@ -324,40 +353,62 @@ Surrounding spaces and spacing are preserved. Here is an example: :: | |||
324 | The variable ``FOO`` becomes | 353 | The variable ``FOO`` becomes |
325 | " 789 123456 " and ``FOO2`` becomes " abcdef ". | 354 | " 789 123456 " and ``FOO2`` becomes " abcdef ". |
326 | 355 | ||
327 | Like "_append" and "_prepend", "_remove" is applied at variable | 356 | Like ":append" and ":prepend", ":remove" is applied at variable |
328 | expansion time. | 357 | expansion time. |
329 | 358 | ||
359 | .. note:: | ||
360 | |||
361 | The overrides are applied in this order, ":append", ":prepend", ":remove". | ||
362 | This implies it is not possible to re-append previously removed strings. | ||
363 | However, one can undo a ":remove" by using an intermediate variable whose | ||
364 | content is passed to the ":remove" so that modifying the intermediate | ||
365 | variable equals to keeping the string in:: | ||
366 | |||
367 | FOOREMOVE = "123 456 789" | ||
368 | FOO:remove = "${FOOREMOVE}" | ||
369 | ... | ||
370 | FOOREMOVE = "123 789" | ||
371 | |||
372 | This expands to ``FOO:remove = "123 789"``. | ||
373 | |||
374 | .. note:: | ||
375 | |||
376 | Override application order may not match variable parse history, i.e. | ||
377 | the output of ``bitbake -e`` may contain ":remove" before ":append", | ||
378 | but the result will be removed string, because ":remove" is handled | ||
379 | last. | ||
380 | |||
330 | Override Style Operation Advantages | 381 | Override Style Operation Advantages |
331 | ----------------------------------- | 382 | ----------------------------------- |
332 | 383 | ||
333 | An advantage of the override style operations "_append", "_prepend", and | 384 | An advantage of the override style operations ":append", ":prepend", and |
334 | "_remove" as compared to the "+=" and "=+" operators is that the | 385 | ":remove" as compared to the "+=" and "=+" operators is that the |
335 | override style operators provide guaranteed operations. For example, | 386 | override style operators provide guaranteed operations. For example, |
336 | consider a class ``foo.bbclass`` that needs to add the value "val" to | 387 | consider a class ``foo.bbclass`` that needs to add the value "val" to |
337 | the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows: :: | 388 | the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows:: |
338 | 389 | ||
339 | inherit foo | 390 | inherit foo |
340 | FOO = "initial" | 391 | FOO = "initial" |
341 | 392 | ||
342 | If ``foo.bbclass`` uses the "+=" operator, | 393 | If ``foo.bbclass`` uses the "+=" operator, |
343 | as follows, then the final value of ``FOO`` will be "initial", which is | 394 | as follows, then the final value of ``FOO`` will be "initial", which is |
344 | not what is desired: :: | 395 | not what is desired:: |
345 | 396 | ||
346 | FOO += "val" | 397 | FOO += "val" |
347 | 398 | ||
348 | If, on the other hand, ``foo.bbclass`` | 399 | If, on the other hand, ``foo.bbclass`` |
349 | uses the "_append" operator, then the final value of ``FOO`` will be | 400 | uses the ":append" operator, then the final value of ``FOO`` will be |
350 | "initial val", as intended: :: | 401 | "initial val", as intended:: |
351 | 402 | ||
352 | FOO_append = " val" | 403 | FOO:append = " val" |
353 | 404 | ||
354 | .. note:: | 405 | .. note:: |
355 | 406 | ||
356 | It is never necessary to use "+=" together with "_append". The following | 407 | It is never necessary to use "+=" together with ":append". The following |
357 | sequence of assignments appends "barbaz" to FOO: :: | 408 | sequence of assignments appends "barbaz" to FOO:: |
358 | 409 | ||
359 | FOO_append = "bar" | 410 | FOO:append = "bar" |
360 | FOO_append = "baz" | 411 | FOO:append = "baz" |
361 | 412 | ||
362 | 413 | ||
363 | The only effect of changing the second assignment in the previous | 414 | The only effect of changing the second assignment in the previous |
@@ -378,10 +429,10 @@ You can find more out about variable flags in general in the | |||
378 | 429 | ||
379 | You can define, append, and prepend values to variable flags. All the | 430 | You can define, append, and prepend values to variable flags. All the |
380 | standard syntax operations previously mentioned work for variable flags | 431 | standard syntax operations previously mentioned work for variable flags |
381 | except for override style syntax (i.e. "_prepend", "_append", and | 432 | except for override style syntax (i.e. ":prepend", ":append", and |
382 | "_remove"). | 433 | ":remove"). |
383 | 434 | ||
384 | Here are some examples showing how to set variable flags: :: | 435 | Here are some examples showing how to set variable flags:: |
385 | 436 | ||
386 | FOO[a] = "abc" | 437 | FOO[a] = "abc" |
387 | FOO[b] = "123" | 438 | FOO[b] = "123" |
@@ -393,15 +444,21 @@ respectively. The ``[a]`` flag becomes "abc 456". | |||
393 | 444 | ||
394 | No need exists to pre-define variable flags. You can simply start using | 445 | No need exists to pre-define variable flags. You can simply start using |
395 | them. One extremely common application is to attach some brief | 446 | them. One extremely common application is to attach some brief |
396 | documentation to a BitBake variable as follows: :: | 447 | documentation to a BitBake variable as follows:: |
397 | 448 | ||
398 | CACHE[doc] = "The directory holding the cache of the metadata." | 449 | CACHE[doc] = "The directory holding the cache of the metadata." |
399 | 450 | ||
451 | .. note:: | ||
452 | |||
453 | Variable flag names starting with an underscore (``_``) character | ||
454 | are allowed but are ignored by ``d.getVarFlags("VAR")`` | ||
455 | in Python code. Such flag names are used internally by BitBake. | ||
456 | |||
400 | Inline Python Variable Expansion | 457 | Inline Python Variable Expansion |
401 | -------------------------------- | 458 | -------------------------------- |
402 | 459 | ||
403 | You can use inline Python variable expansion to set variables. Here is | 460 | You can use inline Python variable expansion to set variables. Here is |
404 | an example: :: | 461 | an example:: |
405 | 462 | ||
406 | DATE = "${@time.strftime('%Y%m%d',time.gmtime())}" | 463 | DATE = "${@time.strftime('%Y%m%d',time.gmtime())}" |
407 | 464 | ||
@@ -410,21 +467,21 @@ This example results in the ``DATE`` variable being set to the current date. | |||
410 | Probably the most common use of this feature is to extract the value of | 467 | Probably the most common use of this feature is to extract the value of |
411 | variables from BitBake's internal data dictionary, ``d``. The following | 468 | variables from BitBake's internal data dictionary, ``d``. The following |
412 | lines select the values of a package name and its version number, | 469 | lines select the values of a package name and its version number, |
413 | respectively: :: | 470 | respectively:: |
414 | 471 | ||
415 | PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" | 472 | PN = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" |
416 | PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" | 473 | PV = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" |
417 | 474 | ||
418 | .. note:: | 475 | .. note:: |
419 | 476 | ||
420 | Inline Python expressions work just like variable expansions insofar as the | 477 | Inline Python expressions work just like variable expansions insofar as the |
421 | "=" and ":=" operators are concerned. Given the following assignment, foo() | 478 | "=" and ":=" operators are concerned. Given the following assignment, foo() |
422 | is called each time FOO is expanded: :: | 479 | is called each time FOO is expanded:: |
423 | 480 | ||
424 | FOO = "${@foo()}" | 481 | FOO = "${@foo()}" |
425 | 482 | ||
426 | Contrast this with the following immediate assignment, where foo() is only | 483 | Contrast this with the following immediate assignment, where foo() is only |
427 | called once, while the assignment is parsed: :: | 484 | called once, while the assignment is parsed:: |
428 | 485 | ||
429 | FOO := "${@foo()}" | 486 | FOO := "${@foo()}" |
430 | 487 | ||
@@ -437,7 +494,7 @@ Unsetting variables | |||
437 | 494 | ||
438 | It is possible to completely remove a variable or a variable flag from | 495 | It is possible to completely remove a variable or a variable flag from |
439 | BitBake's internal data dictionary by using the "unset" keyword. Here is | 496 | BitBake's internal data dictionary by using the "unset" keyword. Here is |
440 | an example: :: | 497 | an example:: |
441 | 498 | ||
442 | unset DATE | 499 | unset DATE |
443 | unset do_fetch[noexec] | 500 | unset do_fetch[noexec] |
@@ -452,7 +509,7 @@ When specifying pathnames for use with BitBake, do not use the tilde | |||
452 | cause BitBake to not recognize the path since BitBake does not expand | 509 | cause BitBake to not recognize the path since BitBake does not expand |
453 | this character in the same way a shell would. | 510 | this character in the same way a shell would. |
454 | 511 | ||
455 | Instead, provide a fuller path as the following example illustrates: :: | 512 | Instead, provide a fuller path as the following example illustrates:: |
456 | 513 | ||
457 | BBLAYERS ?= " \ | 514 | BBLAYERS ?= " \ |
458 | /home/scott-lenovo/LayerA \ | 515 | /home/scott-lenovo/LayerA \ |
@@ -463,7 +520,7 @@ Exporting Variables to the Environment | |||
463 | 520 | ||
464 | You can export variables to the environment of running tasks by using | 521 | You can export variables to the environment of running tasks by using |
465 | the ``export`` keyword. For example, in the following example, the | 522 | the ``export`` keyword. For example, in the following example, the |
466 | ``do_foo`` task prints "value from the environment" when run: :: | 523 | ``do_foo`` task prints "value from the environment" when run:: |
467 | 524 | ||
468 | export ENV_VARIABLE | 525 | export ENV_VARIABLE |
469 | ENV_VARIABLE = "value from the environment" | 526 | ENV_VARIABLE = "value from the environment" |
@@ -481,7 +538,7 @@ It does not matter whether ``export ENV_VARIABLE`` appears before or | |||
481 | after assignments to ``ENV_VARIABLE``. | 538 | after assignments to ``ENV_VARIABLE``. |
482 | 539 | ||
483 | It is also possible to combine ``export`` with setting a value for the | 540 | It is also possible to combine ``export`` with setting a value for the |
484 | variable. Here is an example: :: | 541 | variable. Here is an example:: |
485 | 542 | ||
486 | export ENV_VARIABLE = "variable-value" | 543 | export ENV_VARIABLE = "variable-value" |
487 | 544 | ||
@@ -496,78 +553,78 @@ Conditional Syntax (Overrides) | |||
496 | 553 | ||
497 | BitBake uses :term:`OVERRIDES` to control what | 554 | BitBake uses :term:`OVERRIDES` to control what |
498 | variables are overridden after BitBake parses recipes and configuration | 555 | variables are overridden after BitBake parses recipes and configuration |
499 | files. This section describes how you can use ``OVERRIDES`` as | 556 | files. This section describes how you can use :term:`OVERRIDES` as |
500 | conditional metadata, talks about key expansion in relationship to | 557 | conditional metadata, talks about key expansion in relationship to |
501 | ``OVERRIDES``, and provides some examples to help with understanding. | 558 | :term:`OVERRIDES`, and provides some examples to help with understanding. |
502 | 559 | ||
503 | Conditional Metadata | 560 | Conditional Metadata |
504 | -------------------- | 561 | -------------------- |
505 | 562 | ||
506 | You can use ``OVERRIDES`` to conditionally select a specific version of | 563 | You can use :term:`OVERRIDES` to conditionally select a specific version of |
507 | a variable and to conditionally append or prepend the value of a | 564 | a variable and to conditionally append or prepend the value of a |
508 | variable. | 565 | variable. |
509 | 566 | ||
510 | .. note:: | 567 | .. note:: |
511 | 568 | ||
512 | Overrides can only use lower-case characters. Additionally, | 569 | Overrides can only use lower-case characters, digits and dashes. |
513 | underscores are not permitted in override names as they are used to | 570 | In particular, colons are not permitted in override names as they are used to |
514 | separate overrides from each other and from the variable name. | 571 | separate overrides from each other and from the variable name. |
515 | 572 | ||
516 | - *Selecting a Variable:* The ``OVERRIDES`` variable is a | 573 | - *Selecting a Variable:* The :term:`OVERRIDES` variable is a |
517 | colon-character-separated list that contains items for which you want | 574 | colon-character-separated list that contains items for which you want |
518 | to satisfy conditions. Thus, if you have a variable that is | 575 | to satisfy conditions. Thus, if you have a variable that is |
519 | conditional on "arm", and "arm" is in ``OVERRIDES``, then the | 576 | conditional on "arm", and "arm" is in :term:`OVERRIDES`, then the |
520 | "arm"-specific version of the variable is used rather than the | 577 | "arm"-specific version of the variable is used rather than the |
521 | non-conditional version. Here is an example: :: | 578 | non-conditional version. Here is an example:: |
522 | 579 | ||
523 | OVERRIDES = "architecture:os:machine" | 580 | OVERRIDES = "architecture:os:machine" |
524 | TEST = "default" | 581 | TEST = "default" |
525 | TEST_os = "osspecific" | 582 | TEST:os = "osspecific" |
526 | TEST_nooverride = "othercondvalue" | 583 | TEST:nooverride = "othercondvalue" |
527 | 584 | ||
528 | In this example, the ``OVERRIDES`` | 585 | In this example, the :term:`OVERRIDES` |
529 | variable lists three overrides: "architecture", "os", and "machine". | 586 | variable lists three overrides: "architecture", "os", and "machine". |
530 | The variable ``TEST`` by itself has a default value of "default". You | 587 | The variable ``TEST`` by itself has a default value of "default". You |
531 | select the os-specific version of the ``TEST`` variable by appending | 588 | select the os-specific version of the ``TEST`` variable by appending |
532 | the "os" override to the variable (i.e. ``TEST_os``). | 589 | the "os" override to the variable (i.e. ``TEST:os``). |
533 | 590 | ||
534 | To better understand this, consider a practical example that assumes | 591 | To better understand this, consider a practical example that assumes |
535 | an OpenEmbedded metadata-based Linux kernel recipe file. The | 592 | an OpenEmbedded metadata-based Linux kernel recipe file. The |
536 | following lines from the recipe file first set the kernel branch | 593 | following lines from the recipe file first set the kernel branch |
537 | variable ``KBRANCH`` to a default value, then conditionally override | 594 | variable ``KBRANCH`` to a default value, then conditionally override |
538 | that value based on the architecture of the build: :: | 595 | that value based on the architecture of the build:: |
539 | 596 | ||
540 | KBRANCH = "standard/base" | 597 | KBRANCH = "standard/base" |
541 | KBRANCH_qemuarm = "standard/arm-versatile-926ejs" | 598 | KBRANCH:qemuarm = "standard/arm-versatile-926ejs" |
542 | KBRANCH_qemumips = "standard/mti-malta32" | 599 | KBRANCH:qemumips = "standard/mti-malta32" |
543 | KBRANCH_qemuppc = "standard/qemuppc" | 600 | KBRANCH:qemuppc = "standard/qemuppc" |
544 | KBRANCH_qemux86 = "standard/common-pc/base" | 601 | KBRANCH:qemux86 = "standard/common-pc/base" |
545 | KBRANCH_qemux86-64 = "standard/common-pc-64/base" | 602 | KBRANCH:qemux86-64 = "standard/common-pc-64/base" |
546 | KBRANCH_qemumips64 = "standard/mti-malta64" | 603 | KBRANCH:qemumips64 = "standard/mti-malta64" |
547 | 604 | ||
548 | - *Appending and Prepending:* BitBake also supports append and prepend | 605 | - *Appending and Prepending:* BitBake also supports append and prepend |
549 | operations to variable values based on whether a specific item is | 606 | operations to variable values based on whether a specific item is |
550 | listed in ``OVERRIDES``. Here is an example: :: | 607 | listed in :term:`OVERRIDES`. Here is an example:: |
551 | 608 | ||
552 | DEPENDS = "glibc ncurses" | 609 | DEPENDS = "glibc ncurses" |
553 | OVERRIDES = "machine:local" | 610 | OVERRIDES = "machine:local" |
554 | DEPENDS_append_machine = "libmad" | 611 | DEPENDS:append:machine = "libmad" |
555 | 612 | ||
556 | In this example, ``DEPENDS`` becomes "glibc ncurses libmad". | 613 | In this example, :term:`DEPENDS` becomes "glibc ncurses libmad". |
557 | 614 | ||
558 | Again, using an OpenEmbedded metadata-based kernel recipe file as an | 615 | Again, using an OpenEmbedded metadata-based kernel recipe file as an |
559 | example, the following lines will conditionally append to the | 616 | example, the following lines will conditionally append to the |
560 | ``KERNEL_FEATURES`` variable based on the architecture: :: | 617 | ``KERNEL_FEATURES`` variable based on the architecture:: |
561 | 618 | ||
562 | KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}" | 619 | KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}" |
563 | KERNEL_FEATURES_append_qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc" | 620 | KERNEL_FEATURES:append:qemux86=" cfg/sound.scc cfg/paravirt_kvm.scc" |
564 | KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc" | 621 | KERNEL_FEATURES:append:qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc" |
565 | 622 | ||
566 | - *Setting a Variable for a Single Task:* BitBake supports setting a | 623 | - *Setting a Variable for a Single Task:* BitBake supports setting a |
567 | variable just for the duration of a single task. Here is an example: :: | 624 | variable just for the duration of a single task. Here is an example:: |
568 | 625 | ||
569 | FOO_task-configure = "val 1" | 626 | FOO:task-configure = "val 1" |
570 | FOO_task-compile = "val 2" | 627 | FOO:task-compile = "val 2" |
571 | 628 | ||
572 | In the | 629 | In the |
573 | previous example, ``FOO`` has the value "val 1" while the | 630 | previous example, ``FOO`` has the value "val 1" while the |
@@ -580,15 +637,25 @@ variable. | |||
580 | ``do_compile`` task. | 637 | ``do_compile`` task. |
581 | 638 | ||
582 | You can also use this syntax with other combinations (e.g. | 639 | You can also use this syntax with other combinations (e.g. |
583 | "``_prepend``") as shown in the following example: :: | 640 | "``:prepend``") as shown in the following example:: |
584 | 641 | ||
585 | EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} " | 642 | EXTRA_OEMAKE:prepend:task-compile = "${PARALLEL_MAKE} " |
643 | |||
644 | .. note:: | ||
645 | |||
646 | Before BitBake 1.52 (Honister 3.4), the syntax for :term:`OVERRIDES` | ||
647 | used ``_`` instead of ``:``, so you will still find a lot of documentation | ||
648 | using ``_append``, ``_prepend``, and ``_remove``, for example. | ||
649 | |||
650 | For details, see the | ||
651 | :yocto_docs:`Overrides Syntax Changes </migration-guides/migration-3.4.html#override-syntax-changes>` | ||
652 | section in the Yocto Project manual migration notes. | ||
586 | 653 | ||
587 | Key Expansion | 654 | Key Expansion |
588 | ------------- | 655 | ------------- |
589 | 656 | ||
590 | Key expansion happens when the BitBake datastore is finalized. To better | 657 | Key expansion happens when the BitBake datastore is finalized. To better |
591 | understand this, consider the following example: :: | 658 | understand this, consider the following example:: |
592 | 659 | ||
593 | A${B} = "X" | 660 | A${B} = "X" |
594 | B = "2" | 661 | B = "2" |
@@ -612,57 +679,57 @@ users. | |||
612 | 679 | ||
613 | There is often confusion concerning the order in which overrides and | 680 | There is often confusion concerning the order in which overrides and |
614 | various "append" operators take effect. Recall that an append or prepend | 681 | various "append" operators take effect. Recall that an append or prepend |
615 | operation using "_append" and "_prepend" does not result in an immediate | 682 | operation using ":append" and ":prepend" does not result in an immediate |
616 | assignment as would "+=", ".=", "=+", or "=.". Consider the following | 683 | assignment as would "+=", ".=", "=+", or "=.". Consider the following |
617 | example: :: | 684 | example:: |
618 | 685 | ||
619 | OVERRIDES = "foo" | 686 | OVERRIDES = "foo" |
620 | A = "Z" | 687 | A = "Z" |
621 | A_foo_append = "X" | 688 | A:foo:append = "X" |
622 | 689 | ||
623 | For this case, | 690 | For this case, |
624 | ``A`` is unconditionally set to "Z" and "X" is unconditionally and | 691 | ``A`` is unconditionally set to "Z" and "X" is unconditionally and |
625 | immediately appended to the variable ``A_foo``. Because overrides have | 692 | immediately appended to the variable ``A:foo``. Because overrides have |
626 | not been applied yet, ``A_foo`` is set to "X" due to the append and | 693 | not been applied yet, ``A:foo`` is set to "X" due to the append and |
627 | ``A`` simply equals "Z". | 694 | ``A`` simply equals "Z". |
628 | 695 | ||
629 | Applying overrides, however, changes things. Since "foo" is listed in | 696 | Applying overrides, however, changes things. Since "foo" is listed in |
630 | ``OVERRIDES``, the conditional variable ``A`` is replaced with the "foo" | 697 | :term:`OVERRIDES`, the conditional variable ``A`` is replaced with the "foo" |
631 | version, which is equal to "X". So effectively, ``A_foo`` replaces | 698 | version, which is equal to "X". So effectively, ``A:foo`` replaces |
632 | ``A``. | 699 | ``A``. |
633 | 700 | ||
634 | This next example changes the order of the override and the append: :: | 701 | This next example changes the order of the override and the append:: |
635 | 702 | ||
636 | OVERRIDES = "foo" | 703 | OVERRIDES = "foo" |
637 | A = "Z" | 704 | A = "Z" |
638 | A_append_foo = "X" | 705 | A:append:foo = "X" |
639 | 706 | ||
640 | For this case, before | 707 | For this case, before |
641 | overrides are handled, ``A`` is set to "Z" and ``A_append_foo`` is set | 708 | overrides are handled, ``A`` is set to "Z" and ``A:append:foo`` is set |
642 | to "X". Once the override for "foo" is applied, however, ``A`` gets | 709 | to "X". Once the override for "foo" is applied, however, ``A`` gets |
643 | appended with "X". Consequently, ``A`` becomes "ZX". Notice that spaces | 710 | appended with "X". Consequently, ``A`` becomes "ZX". Notice that spaces |
644 | are not appended. | 711 | are not appended. |
645 | 712 | ||
646 | This next example has the order of the appends and overrides reversed | 713 | This next example has the order of the appends and overrides reversed |
647 | back as in the first example: :: | 714 | back as in the first example:: |
648 | 715 | ||
649 | OVERRIDES = "foo" | 716 | OVERRIDES = "foo" |
650 | A = "Y" | 717 | A = "Y" |
651 | A_foo_append = "Z" | 718 | A:foo:append = "Z" |
652 | A_foo_append = "X" | 719 | A:foo:append = "X" |
653 | 720 | ||
654 | For this case, before any overrides are resolved, | 721 | For this case, before any overrides are resolved, |
655 | ``A`` is set to "Y" using an immediate assignment. After this immediate | 722 | ``A`` is set to "Y" using an immediate assignment. After this immediate |
656 | assignment, ``A_foo`` is set to "Z", and then further appended with "X" | 723 | assignment, ``A:foo`` is set to "Z", and then further appended with "X" |
657 | leaving the variable set to "ZX". Finally, applying the override for | 724 | leaving the variable set to "ZX". Finally, applying the override for |
658 | "foo" results in the conditional variable ``A`` becoming "ZX" (i.e. | 725 | "foo" results in the conditional variable ``A`` becoming "ZX" (i.e. |
659 | ``A`` is replaced with ``A_foo``). | 726 | ``A`` is replaced with ``A:foo``). |
660 | 727 | ||
661 | This final example mixes in some varying operators: :: | 728 | This final example mixes in some varying operators:: |
662 | 729 | ||
663 | A = "1" | 730 | A = "1" |
664 | A_append = "2" | 731 | A:append = "2" |
665 | A_append = "3" | 732 | A:append = "3" |
666 | A += "4" | 733 | A += "4" |
667 | A .= "5" | 734 | A .= "5" |
668 | 735 | ||
@@ -670,7 +737,7 @@ For this case, the type of append | |||
670 | operators are affecting the order of assignments as BitBake passes | 737 | operators are affecting the order of assignments as BitBake passes |
671 | through the code multiple times. Initially, ``A`` is set to "1 45" | 738 | through the code multiple times. Initially, ``A`` is set to "1 45" |
672 | because of the three statements that use immediate operators. After | 739 | because of the three statements that use immediate operators. After |
673 | these assignments are made, BitBake applies the "_append" operations. | 740 | these assignments are made, BitBake applies the ":append" operations. |
674 | Those operations result in ``A`` becoming "1 4523". | 741 | Those operations result in ``A`` becoming "1 4523". |
675 | 742 | ||
676 | Sharing Functionality | 743 | Sharing Functionality |
@@ -686,7 +753,7 @@ share the task. | |||
686 | 753 | ||
687 | This section presents the mechanisms BitBake provides to allow you to | 754 | This section presents the mechanisms BitBake provides to allow you to |
688 | share functionality between recipes. Specifically, the mechanisms | 755 | share functionality between recipes. Specifically, the mechanisms |
689 | include ``include``, ``inherit``, ``INHERIT``, and ``require`` | 756 | include ``include``, ``inherit``, :term:`INHERIT`, and ``require`` |
690 | directives. | 757 | directives. |
691 | 758 | ||
692 | Locating Include and Class Files | 759 | Locating Include and Class Files |
@@ -702,7 +769,7 @@ current directory for ``include`` and ``require`` directives. | |||
702 | 769 | ||
703 | In order for include and class files to be found by BitBake, they need | 770 | In order for include and class files to be found by BitBake, they need |
704 | to be located in a "classes" subdirectory that can be found in | 771 | to be located in a "classes" subdirectory that can be found in |
705 | ``BBPATH``. | 772 | :term:`BBPATH`. |
706 | 773 | ||
707 | ``inherit`` Directive | 774 | ``inherit`` Directive |
708 | --------------------- | 775 | --------------------- |
@@ -720,12 +787,12 @@ file and then have your recipe inherit that class file. | |||
720 | 787 | ||
721 | As an example, your recipes could use the following directive to inherit | 788 | As an example, your recipes could use the following directive to inherit |
722 | an ``autotools.bbclass`` file. The class file would contain common | 789 | an ``autotools.bbclass`` file. The class file would contain common |
723 | functionality for using Autotools that could be shared across recipes: :: | 790 | functionality for using Autotools that could be shared across recipes:: |
724 | 791 | ||
725 | inherit autotools | 792 | inherit autotools |
726 | 793 | ||
727 | In this case, BitBake would search for the directory | 794 | In this case, BitBake would search for the directory |
728 | ``classes/autotools.bbclass`` in ``BBPATH``. | 795 | ``classes/autotools.bbclass`` in :term:`BBPATH`. |
729 | 796 | ||
730 | .. note:: | 797 | .. note:: |
731 | 798 | ||
@@ -734,7 +801,7 @@ In this case, BitBake would search for the directory | |||
734 | 801 | ||
735 | If you want to use the directive to inherit multiple classes, separate | 802 | If you want to use the directive to inherit multiple classes, separate |
736 | them with spaces. The following example shows how to inherit both the | 803 | them with spaces. The following example shows how to inherit both the |
737 | ``buildhistory`` and ``rm_work`` classes: :: | 804 | ``buildhistory`` and ``rm_work`` classes:: |
738 | 805 | ||
739 | inherit buildhistory rm_work | 806 | inherit buildhistory rm_work |
740 | 807 | ||
@@ -742,19 +809,19 @@ An advantage with the inherit directive as compared to both the | |||
742 | :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>` and :ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` | 809 | :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>` and :ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` |
743 | directives is that you can inherit class files conditionally. You can | 810 | directives is that you can inherit class files conditionally. You can |
744 | accomplish this by using a variable expression after the ``inherit`` | 811 | accomplish this by using a variable expression after the ``inherit`` |
745 | statement. Here is an example: :: | 812 | statement. Here is an example:: |
746 | 813 | ||
747 | inherit ${VARNAME} | 814 | inherit ${VARNAME} |
748 | 815 | ||
749 | If ``VARNAME`` is | 816 | If ``VARNAME`` is |
750 | going to be set, it needs to be set before the ``inherit`` statement is | 817 | going to be set, it needs to be set before the ``inherit`` statement is |
751 | parsed. One way to achieve a conditional inherit in this case is to use | 818 | parsed. One way to achieve a conditional inherit in this case is to use |
752 | overrides: :: | 819 | overrides:: |
753 | 820 | ||
754 | VARIABLE = "" | 821 | VARIABLE = "" |
755 | VARIABLE_someoverride = "myclass" | 822 | VARIABLE:someoverride = "myclass" |
756 | 823 | ||
757 | Another method is by using anonymous Python. Here is an example: :: | 824 | Another method is by using anonymous Python. Here is an example:: |
758 | 825 | ||
759 | python () { | 826 | python () { |
760 | if condition == value: | 827 | if condition == value: |
@@ -764,7 +831,7 @@ Another method is by using anonymous Python. Here is an example: :: | |||
764 | } | 831 | } |
765 | 832 | ||
766 | Alternatively, you could use an in-line Python expression in the | 833 | Alternatively, you could use an in-line Python expression in the |
767 | following form: :: | 834 | following form:: |
768 | 835 | ||
769 | inherit ${@'classname' if condition else ''} | 836 | inherit ${@'classname' if condition else ''} |
770 | inherit ${@functionname(params)} | 837 | inherit ${@functionname(params)} |
@@ -780,7 +847,7 @@ BitBake understands the ``include`` directive. This directive causes | |||
780 | BitBake to parse whatever file you specify, and to insert that file at | 847 | BitBake to parse whatever file you specify, and to insert that file at |
781 | that location. The directive is much like its equivalent in Make except | 848 | that location. The directive is much like its equivalent in Make except |
782 | that if the path specified on the include line is a relative path, | 849 | that if the path specified on the include line is a relative path, |
783 | BitBake locates the first file it can find within ``BBPATH``. | 850 | BitBake locates the first file it can find within :term:`BBPATH`. |
784 | 851 | ||
785 | The include directive is a more generic method of including | 852 | The include directive is a more generic method of including |
786 | functionality as compared to the :ref:`inherit <bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` directive>` | 853 | functionality as compared to the :ref:`inherit <bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` directive>` |
@@ -790,7 +857,7 @@ encapsulated functionality or configuration that does not suit a | |||
790 | ``.bbclass`` file. | 857 | ``.bbclass`` file. |
791 | 858 | ||
792 | As an example, suppose you needed a recipe to include some self-test | 859 | As an example, suppose you needed a recipe to include some self-test |
793 | definitions: :: | 860 | definitions:: |
794 | 861 | ||
795 | include test_defs.inc | 862 | include test_defs.inc |
796 | 863 | ||
@@ -822,7 +889,7 @@ does not suit a ``.bbclass`` file. | |||
822 | 889 | ||
823 | Similar to how BitBake handles :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>`, if | 890 | Similar to how BitBake handles :ref:`include <bitbake-user-manual/bitbake-user-manual-metadata:\`\`include\`\` directive>`, if |
824 | the path specified on the require line is a relative path, BitBake | 891 | the path specified on the require line is a relative path, BitBake |
825 | locates the first file it can find within ``BBPATH``. | 892 | locates the first file it can find within :term:`BBPATH`. |
826 | 893 | ||
827 | As an example, suppose you have two versions of a recipe (e.g. | 894 | As an example, suppose you have two versions of a recipe (e.g. |
828 | ``foo_1.2.2.bb`` and ``foo_2.0.0.bb``) where each version contains some | 895 | ``foo_1.2.2.bb`` and ``foo_2.0.0.bb``) where each version contains some |
@@ -831,7 +898,7 @@ include file named ``foo.inc`` that contains the common definitions | |||
831 | needed to build "foo". You need to be sure ``foo.inc`` is located in the | 898 | needed to build "foo". You need to be sure ``foo.inc`` is located in the |
832 | same directory as your two recipe files as well. Once these conditions | 899 | same directory as your two recipe files as well. Once these conditions |
833 | are set up, you can share the functionality using a ``require`` | 900 | are set up, you can share the functionality using a ``require`` |
834 | directive from within each recipe: :: | 901 | directive from within each recipe:: |
835 | 902 | ||
836 | require foo.inc | 903 | require foo.inc |
837 | 904 | ||
@@ -844,14 +911,14 @@ class. BitBake only supports this directive when used within a | |||
844 | configuration file. | 911 | configuration file. |
845 | 912 | ||
846 | As an example, suppose you needed to inherit a class file called | 913 | As an example, suppose you needed to inherit a class file called |
847 | ``abc.bbclass`` from a configuration file as follows: :: | 914 | ``abc.bbclass`` from a configuration file as follows:: |
848 | 915 | ||
849 | INHERIT += "abc" | 916 | INHERIT += "abc" |
850 | 917 | ||
851 | This configuration directive causes the named class to be inherited at | 918 | This configuration directive causes the named class to be inherited at |
852 | the point of the directive during parsing. As with the ``inherit`` | 919 | the point of the directive during parsing. As with the ``inherit`` |
853 | directive, the ``.bbclass`` file must be located in a "classes" | 920 | directive, the ``.bbclass`` file must be located in a "classes" |
854 | subdirectory in one of the directories specified in ``BBPATH``. | 921 | subdirectory in one of the directories specified in :term:`BBPATH`. |
855 | 922 | ||
856 | .. note:: | 923 | .. note:: |
857 | 924 | ||
@@ -862,7 +929,7 @@ subdirectory in one of the directories specified in ``BBPATH``. | |||
862 | If you want to use the directive to inherit multiple classes, you can | 929 | If you want to use the directive to inherit multiple classes, you can |
863 | provide them on the same line in the ``local.conf`` file. Use spaces to | 930 | provide them on the same line in the ``local.conf`` file. Use spaces to |
864 | separate the classes. The following example shows how to inherit both | 931 | separate the classes. The following example shows how to inherit both |
865 | the ``autotools`` and ``pkgconfig`` classes: :: | 932 | the ``autotools`` and ``pkgconfig`` classes:: |
866 | 933 | ||
867 | INHERIT += "autotools pkgconfig" | 934 | INHERIT += "autotools pkgconfig" |
868 | 935 | ||
@@ -893,9 +960,9 @@ Regardless of the type of function, you can only define them in class | |||
893 | Shell Functions | 960 | Shell Functions |
894 | --------------- | 961 | --------------- |
895 | 962 | ||
896 | Functions written in shell script and executed either directly as | 963 | Functions written in shell script are executed either directly as |
897 | functions, tasks, or both. They can also be called by other shell | 964 | functions, tasks, or both. They can also be called by other shell |
898 | functions. Here is an example shell function definition: :: | 965 | functions. Here is an example shell function definition:: |
899 | 966 | ||
900 | some_function () { | 967 | some_function () { |
901 | echo "Hello World" | 968 | echo "Hello World" |
@@ -907,19 +974,19 @@ rules. The scripts are executed by ``/bin/sh``, which may not be a bash | |||
907 | shell but might be something such as ``dash``. You should not use | 974 | shell but might be something such as ``dash``. You should not use |
908 | Bash-specific script (bashisms). | 975 | Bash-specific script (bashisms). |
909 | 976 | ||
910 | Overrides and override-style operators like ``_append`` and ``_prepend`` | 977 | Overrides and override-style operators like ``:append`` and ``:prepend`` |
911 | can also be applied to shell functions. Most commonly, this application | 978 | can also be applied to shell functions. Most commonly, this application |
912 | would be used in a ``.bbappend`` file to modify functions in the main | 979 | would be used in a ``.bbappend`` file to modify functions in the main |
913 | recipe. It can also be used to modify functions inherited from classes. | 980 | recipe. It can also be used to modify functions inherited from classes. |
914 | 981 | ||
915 | As an example, consider the following: :: | 982 | As an example, consider the following:: |
916 | 983 | ||
917 | do_foo() { | 984 | do_foo() { |
918 | bbplain first | 985 | bbplain first |
919 | fn | 986 | fn |
920 | } | 987 | } |
921 | 988 | ||
922 | fn_prepend() { | 989 | fn:prepend() { |
923 | bbplain second | 990 | bbplain second |
924 | } | 991 | } |
925 | 992 | ||
@@ -927,11 +994,11 @@ As an example, consider the following: :: | |||
927 | bbplain third | 994 | bbplain third |
928 | } | 995 | } |
929 | 996 | ||
930 | do_foo_append() { | 997 | do_foo:append() { |
931 | bbplain fourth | 998 | bbplain fourth |
932 | } | 999 | } |
933 | 1000 | ||
934 | Running ``do_foo`` prints the following: :: | 1001 | Running ``do_foo`` prints the following:: |
935 | 1002 | ||
936 | recipename do_foo: first | 1003 | recipename do_foo: first |
937 | recipename do_foo: second | 1004 | recipename do_foo: second |
@@ -943,7 +1010,7 @@ Running ``do_foo`` prints the following: :: | |||
943 | Overrides and override-style operators can be applied to any shell | 1010 | Overrides and override-style operators can be applied to any shell |
944 | function, not just :ref:`tasks <bitbake-user-manual/bitbake-user-manual-metadata:tasks>`. | 1011 | function, not just :ref:`tasks <bitbake-user-manual/bitbake-user-manual-metadata:tasks>`. |
945 | 1012 | ||
946 | You can use the ``bitbake -e`` recipename command to view the final | 1013 | You can use the ``bitbake -e recipename`` command to view the final |
947 | assembled function after all overrides have been applied. | 1014 | assembled function after all overrides have been applied. |
948 | 1015 | ||
949 | BitBake-Style Python Functions | 1016 | BitBake-Style Python Functions |
@@ -952,7 +1019,7 @@ BitBake-Style Python Functions | |||
952 | These functions are written in Python and executed by BitBake or other | 1019 | These functions are written in Python and executed by BitBake or other |
953 | Python functions using ``bb.build.exec_func()``. | 1020 | Python functions using ``bb.build.exec_func()``. |
954 | 1021 | ||
955 | An example BitBake function is: :: | 1022 | An example BitBake function is:: |
956 | 1023 | ||
957 | python some_python_function () { | 1024 | python some_python_function () { |
958 | d.setVar("TEXT", "Hello World") | 1025 | d.setVar("TEXT", "Hello World") |
@@ -975,9 +1042,9 @@ import these modules. Also in these types of functions, the datastore | |||
975 | Similar to shell functions, you can also apply overrides and | 1042 | Similar to shell functions, you can also apply overrides and |
976 | override-style operators to BitBake-style Python functions. | 1043 | override-style operators to BitBake-style Python functions. |
977 | 1044 | ||
978 | As an example, consider the following: :: | 1045 | As an example, consider the following:: |
979 | 1046 | ||
980 | python do_foo_prepend() { | 1047 | python do_foo:prepend() { |
981 | bb.plain("first") | 1048 | bb.plain("first") |
982 | } | 1049 | } |
983 | 1050 | ||
@@ -985,17 +1052,17 @@ As an example, consider the following: :: | |||
985 | bb.plain("second") | 1052 | bb.plain("second") |
986 | } | 1053 | } |
987 | 1054 | ||
988 | python do_foo_append() { | 1055 | python do_foo:append() { |
989 | bb.plain("third") | 1056 | bb.plain("third") |
990 | } | 1057 | } |
991 | 1058 | ||
992 | Running ``do_foo`` prints the following: :: | 1059 | Running ``do_foo`` prints the following:: |
993 | 1060 | ||
994 | recipename do_foo: first | 1061 | recipename do_foo: first |
995 | recipename do_foo: second | 1062 | recipename do_foo: second |
996 | recipename do_foo: third | 1063 | recipename do_foo: third |
997 | 1064 | ||
998 | You can use the ``bitbake -e`` recipename command to view | 1065 | You can use the ``bitbake -e recipename`` command to view |
999 | the final assembled function after all overrides have been applied. | 1066 | the final assembled function after all overrides have been applied. |
1000 | 1067 | ||
1001 | Python Functions | 1068 | Python Functions |
@@ -1004,7 +1071,7 @@ Python Functions | |||
1004 | These functions are written in Python and are executed by other Python | 1071 | These functions are written in Python and are executed by other Python |
1005 | code. Examples of Python functions are utility functions that you intend | 1072 | code. Examples of Python functions are utility functions that you intend |
1006 | to call from in-line Python or from within other Python functions. Here | 1073 | to call from in-line Python or from within other Python functions. Here |
1007 | is an example: :: | 1074 | is an example:: |
1008 | 1075 | ||
1009 | def get_depends(d): | 1076 | def get_depends(d): |
1010 | if d.getVar('SOMECONDITION'): | 1077 | if d.getVar('SOMECONDITION'): |
@@ -1015,7 +1082,7 @@ is an example: :: | |||
1015 | SOMECONDITION = "1" | 1082 | SOMECONDITION = "1" |
1016 | DEPENDS = "${@get_depends(d)}" | 1083 | DEPENDS = "${@get_depends(d)}" |
1017 | 1084 | ||
1018 | This would result in ``DEPENDS`` containing ``dependencywithcond``. | 1085 | This would result in :term:`DEPENDS` containing ``dependencywithcond``. |
1019 | 1086 | ||
1020 | Here are some things to know about Python functions: | 1087 | Here are some things to know about Python functions: |
1021 | 1088 | ||
@@ -1056,7 +1123,7 @@ functions and regular Python functions defined with "def": | |||
1056 | - Regular Python functions are called with the usual Python syntax. | 1123 | - Regular Python functions are called with the usual Python syntax. |
1057 | BitBake-style Python functions are usually tasks and are called | 1124 | BitBake-style Python functions are usually tasks and are called |
1058 | directly by BitBake, but can also be called manually from Python code | 1125 | directly by BitBake, but can also be called manually from Python code |
1059 | by using the ``bb.build.exec_func()`` function. Here is an example: :: | 1126 | by using the ``bb.build.exec_func()`` function. Here is an example:: |
1060 | 1127 | ||
1061 | bb.build.exec_func("my_bitbake_style_function", d) | 1128 | bb.build.exec_func("my_bitbake_style_function", d) |
1062 | 1129 | ||
@@ -1094,7 +1161,7 @@ Sometimes it is useful to set variables or perform other operations | |||
1094 | programmatically during parsing. To do this, you can define special | 1161 | programmatically during parsing. To do this, you can define special |
1095 | Python functions, called anonymous Python functions, that run at the end | 1162 | Python functions, called anonymous Python functions, that run at the end |
1096 | of parsing. For example, the following conditionally sets a variable | 1163 | of parsing. For example, the following conditionally sets a variable |
1097 | based on the value of another variable: :: | 1164 | based on the value of another variable:: |
1098 | 1165 | ||
1099 | python () { | 1166 | python () { |
1100 | if d.getVar('SOMEVAR') == 'value': | 1167 | if d.getVar('SOMEVAR') == 'value': |
@@ -1107,7 +1174,7 @@ the name "__anonymous", rather than no name. | |||
1107 | Anonymous Python functions always run at the end of parsing, regardless | 1174 | Anonymous Python functions always run at the end of parsing, regardless |
1108 | of where they are defined. If a recipe contains many anonymous | 1175 | of where they are defined. If a recipe contains many anonymous |
1109 | functions, they run in the same order as they are defined within the | 1176 | functions, they run in the same order as they are defined within the |
1110 | recipe. As an example, consider the following snippet: :: | 1177 | recipe. As an example, consider the following snippet:: |
1111 | 1178 | ||
1112 | python () { | 1179 | python () { |
1113 | d.setVar('FOO', 'foo 2') | 1180 | d.setVar('FOO', 'foo 2') |
@@ -1122,7 +1189,7 @@ recipe. As an example, consider the following snippet: :: | |||
1122 | BAR = "bar 1" | 1189 | BAR = "bar 1" |
1123 | 1190 | ||
1124 | The previous example is conceptually | 1191 | The previous example is conceptually |
1125 | equivalent to the following snippet: :: | 1192 | equivalent to the following snippet:: |
1126 | 1193 | ||
1127 | FOO = "foo 1" | 1194 | FOO = "foo 1" |
1128 | BAR = "bar 1" | 1195 | BAR = "bar 1" |
@@ -1134,12 +1201,12 @@ equivalent to the following snippet: :: | |||
1134 | values set for the variables within the anonymous functions become | 1201 | values set for the variables within the anonymous functions become |
1135 | available to tasks, which always run after parsing. | 1202 | available to tasks, which always run after parsing. |
1136 | 1203 | ||
1137 | Overrides and override-style operators such as "``_append``" are applied | 1204 | Overrides and override-style operators such as "``:append``" are applied |
1138 | before anonymous functions run. In the following example, ``FOO`` ends | 1205 | before anonymous functions run. In the following example, ``FOO`` ends |
1139 | up with the value "foo from anonymous": :: | 1206 | up with the value "foo from anonymous":: |
1140 | 1207 | ||
1141 | FOO = "foo" | 1208 | FOO = "foo" |
1142 | FOO_append = " from outside" | 1209 | FOO:append = " from outside" |
1143 | 1210 | ||
1144 | python () { | 1211 | python () { |
1145 | d.setVar("FOO", "foo from anonymous") | 1212 | d.setVar("FOO", "foo from anonymous") |
@@ -1164,7 +1231,7 @@ To understand the benefits of this feature, consider the basic scenario | |||
1164 | where a class defines a task function and your recipe inherits the | 1231 | where a class defines a task function and your recipe inherits the |
1165 | class. In this basic scenario, your recipe inherits the task function as | 1232 | class. In this basic scenario, your recipe inherits the task function as |
1166 | defined in the class. If desired, your recipe can add to the start and | 1233 | defined in the class. If desired, your recipe can add to the start and |
1167 | end of the function by using the "_prepend" or "_append" operations | 1234 | end of the function by using the ":prepend" or ":append" operations |
1168 | respectively, or it can redefine the function completely. However, if it | 1235 | respectively, or it can redefine the function completely. However, if it |
1169 | redefines the function, there is no means for it to call the class | 1236 | redefines the function, there is no means for it to call the class |
1170 | version of the function. ``EXPORT_FUNCTIONS`` provides a mechanism that | 1237 | version of the function. ``EXPORT_FUNCTIONS`` provides a mechanism that |
@@ -1173,24 +1240,24 @@ version of the function. | |||
1173 | 1240 | ||
1174 | To make use of this technique, you need the following things in place: | 1241 | To make use of this technique, you need the following things in place: |
1175 | 1242 | ||
1176 | - The class needs to define the function as follows: :: | 1243 | - The class needs to define the function as follows:: |
1177 | 1244 | ||
1178 | classname_functionname | 1245 | classname_functionname |
1179 | 1246 | ||
1180 | For example, if you have a class file | 1247 | For example, if you have a class file |
1181 | ``bar.bbclass`` and a function named ``do_foo``, the class must | 1248 | ``bar.bbclass`` and a function named ``do_foo``, the class must |
1182 | define the function as follows: :: | 1249 | define the function as follows:: |
1183 | 1250 | ||
1184 | bar_do_foo | 1251 | bar_do_foo |
1185 | 1252 | ||
1186 | - The class needs to contain the ``EXPORT_FUNCTIONS`` statement as | 1253 | - The class needs to contain the ``EXPORT_FUNCTIONS`` statement as |
1187 | follows: :: | 1254 | follows:: |
1188 | 1255 | ||
1189 | EXPORT_FUNCTIONS functionname | 1256 | EXPORT_FUNCTIONS functionname |
1190 | 1257 | ||
1191 | For example, continuing with | 1258 | For example, continuing with |
1192 | the same example, the statement in the ``bar.bbclass`` would be as | 1259 | the same example, the statement in the ``bar.bbclass`` would be as |
1193 | follows: :: | 1260 | follows:: |
1194 | 1261 | ||
1195 | EXPORT_FUNCTIONS do_foo | 1262 | EXPORT_FUNCTIONS do_foo |
1196 | 1263 | ||
@@ -1199,7 +1266,7 @@ To make use of this technique, you need the following things in place: | |||
1199 | class version of the function, it should call ``bar_do_foo``. | 1266 | class version of the function, it should call ``bar_do_foo``. |
1200 | Assuming ``do_foo`` was a shell function and ``EXPORT_FUNCTIONS`` was | 1267 | Assuming ``do_foo`` was a shell function and ``EXPORT_FUNCTIONS`` was |
1201 | used as above, the recipe's function could conditionally call the | 1268 | used as above, the recipe's function could conditionally call the |
1202 | class version of the function as follows: :: | 1269 | class version of the function as follows:: |
1203 | 1270 | ||
1204 | do_foo() { | 1271 | do_foo() { |
1205 | if [ somecondition ] ; then | 1272 | if [ somecondition ] ; then |
@@ -1233,7 +1300,7 @@ Tasks are either :ref:`shell functions <bitbake-user-manual/bitbake-user-manual- | |||
1233 | that have been promoted to tasks by using the ``addtask`` command. The | 1300 | that have been promoted to tasks by using the ``addtask`` command. The |
1234 | ``addtask`` command can also optionally describe dependencies between | 1301 | ``addtask`` command can also optionally describe dependencies between |
1235 | the task and other tasks. Here is an example that shows how to define a | 1302 | the task and other tasks. Here is an example that shows how to define a |
1236 | task and declare some dependencies: :: | 1303 | task and declare some dependencies:: |
1237 | 1304 | ||
1238 | python do_printdate () { | 1305 | python do_printdate () { |
1239 | import time | 1306 | import time |
@@ -1264,12 +1331,12 @@ Additionally, the ``do_printdate`` task becomes dependent upon the | |||
1264 | rerun for experimentation purposes, you can make BitBake always | 1331 | rerun for experimentation purposes, you can make BitBake always |
1265 | consider the task "out-of-date" by using the | 1332 | consider the task "out-of-date" by using the |
1266 | :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>` | 1333 | :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>` |
1267 | variable flag, as follows: :: | 1334 | variable flag, as follows:: |
1268 | 1335 | ||
1269 | do_printdate[nostamp] = "1" | 1336 | do_printdate[nostamp] = "1" |
1270 | 1337 | ||
1271 | You can also explicitly run the task and provide the | 1338 | You can also explicitly run the task and provide the |
1272 | -f option as follows: :: | 1339 | -f option as follows:: |
1273 | 1340 | ||
1274 | $ bitbake recipe -c printdate -f | 1341 | $ bitbake recipe -c printdate -f |
1275 | 1342 | ||
@@ -1278,7 +1345,7 @@ Additionally, the ``do_printdate`` task becomes dependent upon the | |||
1278 | name. | 1345 | name. |
1279 | 1346 | ||
1280 | You might wonder about the practical effects of using ``addtask`` | 1347 | You might wonder about the practical effects of using ``addtask`` |
1281 | without specifying any dependencies as is done in the following example: :: | 1348 | without specifying any dependencies as is done in the following example:: |
1282 | 1349 | ||
1283 | addtask printdate | 1350 | addtask printdate |
1284 | 1351 | ||
@@ -1286,7 +1353,7 @@ In this example, assuming dependencies have not been | |||
1286 | added through some other means, the only way to run the task is by | 1353 | added through some other means, the only way to run the task is by |
1287 | explicitly selecting it with ``bitbake`` recipe ``-c printdate``. You | 1354 | explicitly selecting it with ``bitbake`` recipe ``-c printdate``. You |
1288 | can use the ``do_listtasks`` task to list all tasks defined in a recipe | 1355 | can use the ``do_listtasks`` task to list all tasks defined in a recipe |
1289 | as shown in the following example: :: | 1356 | as shown in the following example:: |
1290 | 1357 | ||
1291 | $ bitbake recipe -c listtasks | 1358 | $ bitbake recipe -c listtasks |
1292 | 1359 | ||
@@ -1296,12 +1363,23 @@ For more information on task dependencies, see the | |||
1296 | See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section for information | 1363 | See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section for information |
1297 | on variable flags you can use with tasks. | 1364 | on variable flags you can use with tasks. |
1298 | 1365 | ||
1366 | .. note:: | ||
1367 | |||
1368 | While it's infrequent, it's possible to define multiple tasks as | ||
1369 | dependencies when calling ``addtask``. For example, here's a snippet | ||
1370 | from the OpenEmbedded class file ``package_tar.bbclass``:: | ||
1371 | |||
1372 | addtask package_write_tar before do_build after do_packagedata do_package | ||
1373 | |||
1374 | Note how the ``package_write_tar`` task has to wait until both of | ||
1375 | ``do_packagedata`` and ``do_package`` complete. | ||
1376 | |||
1299 | Deleting a Task | 1377 | Deleting a Task |
1300 | --------------- | 1378 | --------------- |
1301 | 1379 | ||
1302 | As well as being able to add tasks, you can delete them. Simply use the | 1380 | As well as being able to add tasks, you can delete them. Simply use the |
1303 | ``deltask`` command to delete a task. For example, to delete the example | 1381 | ``deltask`` command to delete a task. For example, to delete the example |
1304 | task used in the previous sections, you would use: :: | 1382 | task used in the previous sections, you would use:: |
1305 | 1383 | ||
1306 | deltask printdate | 1384 | deltask printdate |
1307 | 1385 | ||
@@ -1317,7 +1395,7 @@ to run before ``do_a``. | |||
1317 | 1395 | ||
1318 | If you want dependencies such as these to remain intact, use the | 1396 | If you want dependencies such as these to remain intact, use the |
1319 | ``[noexec]`` varflag to disable the task instead of using the | 1397 | ``[noexec]`` varflag to disable the task instead of using the |
1320 | ``deltask`` command to delete it: :: | 1398 | ``deltask`` command to delete it:: |
1321 | 1399 | ||
1322 | do_b[noexec] = "1" | 1400 | do_b[noexec] = "1" |
1323 | 1401 | ||
@@ -1331,8 +1409,8 @@ the build machine cannot influence the build. | |||
1331 | .. note:: | 1409 | .. note:: |
1332 | 1410 | ||
1333 | By default, BitBake cleans the environment to include only those | 1411 | By default, BitBake cleans the environment to include only those |
1334 | things exported or listed in its whitelist to ensure that the build | 1412 | things exported or listed in its passthrough list to ensure that the |
1335 | environment is reproducible and consistent. You can prevent this | 1413 | build environment is reproducible and consistent. You can prevent this |
1336 | "cleaning" by setting the :term:`BB_PRESERVE_ENV` variable. | 1414 | "cleaning" by setting the :term:`BB_PRESERVE_ENV` variable. |
1337 | 1415 | ||
1338 | Consequently, if you do want something to get passed into the build task | 1416 | Consequently, if you do want something to get passed into the build task |
@@ -1340,14 +1418,14 @@ environment, you must take these two steps: | |||
1340 | 1418 | ||
1341 | #. Tell BitBake to load what you want from the environment into the | 1419 | #. Tell BitBake to load what you want from the environment into the |
1342 | datastore. You can do so through the | 1420 | datastore. You can do so through the |
1343 | :term:`BB_ENV_WHITELIST` and | 1421 | :term:`BB_ENV_PASSTHROUGH` and |
1344 | :term:`BB_ENV_EXTRAWHITE` variables. For | 1422 | :term:`BB_ENV_PASSTHROUGH_ADDITIONS` variables. For |
1345 | example, assume you want to prevent the build system from accessing | 1423 | example, assume you want to prevent the build system from accessing |
1346 | your ``$HOME/.ccache`` directory. The following command "whitelists" | 1424 | your ``$HOME/.ccache`` directory. The following command adds the |
1347 | the environment variable ``CCACHE_DIR`` causing BitBake to allow that | 1425 | the environment variable ``CCACHE_DIR`` to BitBake's passthrough |
1348 | variable into the datastore: :: | 1426 | list to allow that variable into the datastore:: |
1349 | 1427 | ||
1350 | export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" | 1428 | export BB_ENV_PASSTHROUGH_ADDITIONS="$BB_ENV_PASSTHROUGH_ADDITIONS CCACHE_DIR" |
1351 | 1429 | ||
1352 | #. Tell BitBake to export what you have loaded into the datastore to the | 1430 | #. Tell BitBake to export what you have loaded into the datastore to the |
1353 | task environment of every running task. Loading something from the | 1431 | task environment of every running task. Loading something from the |
@@ -1355,7 +1433,7 @@ environment, you must take these two steps: | |||
1355 | available in the datastore. To export it to the task environment of | 1433 | available in the datastore. To export it to the task environment of |
1356 | every running task, use a command similar to the following in your | 1434 | every running task, use a command similar to the following in your |
1357 | local configuration file ``local.conf`` or your distribution | 1435 | local configuration file ``local.conf`` or your distribution |
1358 | configuration file: :: | 1436 | configuration file:: |
1359 | 1437 | ||
1360 | export CCACHE_DIR | 1438 | export CCACHE_DIR |
1361 | 1439 | ||
@@ -1364,17 +1442,17 @@ environment, you must take these two steps: | |||
1364 | A side effect of the previous steps is that BitBake records the | 1442 | A side effect of the previous steps is that BitBake records the |
1365 | variable as a dependency of the build process in things like the | 1443 | variable as a dependency of the build process in things like the |
1366 | setscene checksums. If doing so results in unnecessary rebuilds of | 1444 | setscene checksums. If doing so results in unnecessary rebuilds of |
1367 | tasks, you can whitelist the variable so that the setscene code | 1445 | tasks, you can also flag the variable so that the setscene code |
1368 | ignores the dependency when it creates checksums. | 1446 | ignores the dependency when it creates checksums. |
1369 | 1447 | ||
1370 | Sometimes, it is useful to be able to obtain information from the | 1448 | Sometimes, it is useful to be able to obtain information from the |
1371 | original execution environment. BitBake saves a copy of the original | 1449 | original execution environment. BitBake saves a copy of the original |
1372 | environment into a special variable named :term:`BB_ORIGENV`. | 1450 | environment into a special variable named :term:`BB_ORIGENV`. |
1373 | 1451 | ||
1374 | The ``BB_ORIGENV`` variable returns a datastore object that can be | 1452 | The :term:`BB_ORIGENV` variable returns a datastore object that can be |
1375 | queried using the standard datastore operators such as | 1453 | queried using the standard datastore operators such as |
1376 | ``getVar(, False)``. The datastore object is useful, for example, to | 1454 | ``getVar(, False)``. The datastore object is useful, for example, to |
1377 | find the original ``DISPLAY`` variable. Here is an example: :: | 1455 | find the original ``DISPLAY`` variable. Here is an example:: |
1378 | 1456 | ||
1379 | origenv = d.getVar("BB_ORIGENV", False) | 1457 | origenv = d.getVar("BB_ORIGENV", False) |
1380 | bar = origenv.getVar("BAR", False) | 1458 | bar = origenv.getVar("BAR", False) |
@@ -1387,7 +1465,7 @@ Variable Flags | |||
1387 | 1465 | ||
1388 | Variable flags (varflags) help control a task's functionality and | 1466 | Variable flags (varflags) help control a task's functionality and |
1389 | dependencies. BitBake reads and writes varflags to the datastore using | 1467 | dependencies. BitBake reads and writes varflags to the datastore using |
1390 | the following command forms: :: | 1468 | the following command forms:: |
1391 | 1469 | ||
1392 | variable = d.getVarFlags("variable") | 1470 | variable = d.getVarFlags("variable") |
1393 | self.d.setVarFlags("FOO", {"func": True}) | 1471 | self.d.setVarFlags("FOO", {"func": True}) |
@@ -1418,12 +1496,35 @@ functionality of the task: | |||
1418 | directory listed is used as the current working directory for the | 1496 | directory listed is used as the current working directory for the |
1419 | task. | 1497 | task. |
1420 | 1498 | ||
1499 | - ``[file-checksums]``: Controls the file dependencies for a task. The | ||
1500 | baseline file list is the set of files associated with | ||
1501 | :term:`SRC_URI`. May be used to set additional dependencies on | ||
1502 | files not associated with :term:`SRC_URI`. | ||
1503 | |||
1504 | The value set to the list is a file-boolean pair where the first | ||
1505 | value is the file name and the second is whether or not it | ||
1506 | physically exists on the filesystem. :: | ||
1507 | |||
1508 | do_configure[file-checksums] += "${MY_DIRPATH}/my-file.txt:True" | ||
1509 | |||
1510 | It is important to record any paths which the task looked at and | ||
1511 | which didn't exist. This means that if these do exist at a later | ||
1512 | time, the task can be rerun with the new additional files. The | ||
1513 | "exists" True or False value after the path allows this to be | ||
1514 | handled. | ||
1515 | |||
1421 | - ``[lockfiles]``: Specifies one or more lockfiles to lock while the | 1516 | - ``[lockfiles]``: Specifies one or more lockfiles to lock while the |
1422 | task executes. Only one task may hold a lockfile, and any task that | 1517 | task executes. Only one task may hold a lockfile, and any task that |
1423 | attempts to lock an already locked file will block until the lock is | 1518 | attempts to lock an already locked file will block until the lock is |
1424 | released. You can use this variable flag to accomplish mutual | 1519 | released. You can use this variable flag to accomplish mutual |
1425 | exclusion. | 1520 | exclusion. |
1426 | 1521 | ||
1522 | - ``[network]``: When set to "1", allows a task to access the network. By | ||
1523 | default, only the ``do_fetch`` task is granted network access. Recipes | ||
1524 | shouldn't access the network outside of ``do_fetch`` as it usually | ||
1525 | undermines fetcher source mirroring, image and licence manifests, software | ||
1526 | auditing and supply chain security. | ||
1527 | |||
1427 | - ``[noexec]``: When set to "1", marks the task as being empty, with | 1528 | - ``[noexec]``: When set to "1", marks the task as being empty, with |
1428 | no execution required. You can use the ``[noexec]`` flag to set up | 1529 | no execution required. You can use the ``[noexec]`` flag to set up |
1429 | tasks as dependency placeholders, or to disable tasks defined | 1530 | tasks as dependency placeholders, or to disable tasks defined |
@@ -1456,7 +1557,7 @@ functionality of the task: | |||
1456 | can result in unpredictable behavior. | 1557 | can result in unpredictable behavior. |
1457 | 1558 | ||
1458 | - Setting the varflag to a value greater than the value used in | 1559 | - Setting the varflag to a value greater than the value used in |
1459 | the ``BB_NUMBER_THREADS`` variable causes ``number_threads`` to | 1560 | the :term:`BB_NUMBER_THREADS` variable causes ``number_threads`` to |
1460 | have no effect. | 1561 | have no effect. |
1461 | 1562 | ||
1462 | - ``[postfuncs]``: List of functions to call after the completion of | 1563 | - ``[postfuncs]``: List of functions to call after the completion of |
@@ -1526,7 +1627,7 @@ intent is to make it easy to do things like email notification on build | |||
1526 | failures. | 1627 | failures. |
1527 | 1628 | ||
1528 | Following is an example event handler that prints the name of the event | 1629 | Following is an example event handler that prints the name of the event |
1529 | and the content of the ``FILE`` variable: :: | 1630 | and the content of the :term:`FILE` variable:: |
1530 | 1631 | ||
1531 | addhandler myclass_eventhandler | 1632 | addhandler myclass_eventhandler |
1532 | python myclass_eventhandler() { | 1633 | python myclass_eventhandler() { |
@@ -1565,11 +1666,11 @@ might have an interest in viewing: | |||
1565 | 1666 | ||
1566 | - ``bb.event.ConfigParsed()``: Fired when the base configuration; which | 1667 | - ``bb.event.ConfigParsed()``: Fired when the base configuration; which |
1567 | consists of ``bitbake.conf``, ``base.bbclass`` and any global | 1668 | consists of ``bitbake.conf``, ``base.bbclass`` and any global |
1568 | ``INHERIT`` statements; has been parsed. You can see multiple such | 1669 | :term:`INHERIT` statements; has been parsed. You can see multiple such |
1569 | events when each of the workers parse the base configuration or if | 1670 | events when each of the workers parse the base configuration or if |
1570 | the server changes configuration and reparses. Any given datastore | 1671 | the server changes configuration and reparses. Any given datastore |
1571 | only has one such event executed against it, however. If | 1672 | only has one such event executed against it, however. If |
1572 | ```BB_INVALIDCONF`` <#>`__ is set in the datastore by the event | 1673 | :term:`BB_INVALIDCONF` is set in the datastore by the event |
1573 | handler, the configuration is reparsed and a new event triggered, | 1674 | handler, the configuration is reparsed and a new event triggered, |
1574 | allowing the metadata to update configuration. | 1675 | allowing the metadata to update configuration. |
1575 | 1676 | ||
@@ -1636,13 +1737,18 @@ user interfaces: | |||
1636 | 1737 | ||
1637 | .. _variants-class-extension-mechanism: | 1738 | .. _variants-class-extension-mechanism: |
1638 | 1739 | ||
1639 | Variants - Class Extension Mechanism | 1740 | Variants --- Class Extension Mechanism |
1640 | ==================================== | 1741 | ====================================== |
1641 | 1742 | ||
1642 | BitBake supports two features that facilitate creating from a single | 1743 | BitBake supports multiple incarnations of a recipe file via the |
1643 | recipe file multiple incarnations of that recipe file where all | 1744 | :term:`BBCLASSEXTEND` variable. |
1644 | incarnations are buildable. These features are enabled through the | 1745 | |
1645 | :term:`BBCLASSEXTEND` and :term:`BBVERSIONS` variables. | 1746 | The :term:`BBCLASSEXTEND` variable is a space separated list of classes used |
1747 | to "extend" the recipe for each variant. Here is an example that results in a | ||
1748 | second incarnation of the current recipe being available. This second | ||
1749 | incarnation will have the "native" class inherited. :: | ||
1750 | |||
1751 | BBCLASSEXTEND = "native" | ||
1646 | 1752 | ||
1647 | .. note:: | 1753 | .. note:: |
1648 | 1754 | ||
@@ -1652,34 +1758,6 @@ incarnations are buildable. These features are enabled through the | |||
1652 | class. For specific examples, see the OE-Core native , nativesdk , and | 1758 | class. For specific examples, see the OE-Core native , nativesdk , and |
1653 | multilib classes. | 1759 | multilib classes. |
1654 | 1760 | ||
1655 | - ``BBCLASSEXTEND``: This variable is a space separated list of | ||
1656 | classes used to "extend" the recipe for each variant. Here is an | ||
1657 | example that results in a second incarnation of the current recipe | ||
1658 | being available. This second incarnation will have the "native" class | ||
1659 | inherited. :: | ||
1660 | |||
1661 | BBCLASSEXTEND = "native" | ||
1662 | |||
1663 | - ``BBVERSIONS``: This variable allows a single recipe to build | ||
1664 | multiple versions of a project from a single recipe file. You can | ||
1665 | also specify conditional metadata (using the | ||
1666 | :term:`OVERRIDES` mechanism) for a single | ||
1667 | version, or an optionally named range of versions. Here is an | ||
1668 | example: :: | ||
1669 | |||
1670 | BBVERSIONS = "1.0 2.0 git" | ||
1671 | SRC_URI_git = "git://someurl/somepath.git" | ||
1672 | |||
1673 | BBVERSIONS = "1.0.[0-6]:1.0.0+ 1.0.[7-9]:1.0.7+" | ||
1674 | SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1" | ||
1675 | |||
1676 | The name of the range defaults to the original version of the recipe. For | ||
1677 | example, in OpenEmbedded, the recipe file ``foo_1.0.0+.bb`` creates a default | ||
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`). | ||
1682 | |||
1683 | Dependencies | 1761 | Dependencies |
1684 | ============ | 1762 | ============ |
1685 | 1763 | ||
@@ -1708,7 +1786,7 @@ Dependencies Internal to the ``.bb`` File | |||
1708 | BitBake uses the ``addtask`` directive to manage dependencies that are | 1786 | BitBake uses the ``addtask`` directive to manage dependencies that are |
1709 | internal to a given recipe file. You can use the ``addtask`` directive | 1787 | internal to a given recipe file. You can use the ``addtask`` directive |
1710 | to indicate when a task is dependent on other tasks or when other tasks | 1788 | to indicate when a task is dependent on other tasks or when other tasks |
1711 | depend on that recipe. Here is an example: :: | 1789 | depend on that recipe. Here is an example:: |
1712 | 1790 | ||
1713 | addtask printdate after do_fetch before do_build | 1791 | addtask printdate after do_fetch before do_build |
1714 | 1792 | ||
@@ -1732,7 +1810,7 @@ task depends on the completion of the ``do_printdate`` task. | |||
1732 | 1810 | ||
1733 | - The directive ``addtask mytask after do_configure`` by itself | 1811 | - The directive ``addtask mytask after do_configure`` by itself |
1734 | never causes ``do_mytask`` to run. ``do_mytask`` can still be run | 1812 | never causes ``do_mytask`` to run. ``do_mytask`` can still be run |
1735 | manually as follows: :: | 1813 | manually as follows:: |
1736 | 1814 | ||
1737 | $ bitbake recipe -c mytask | 1815 | $ bitbake recipe -c mytask |
1738 | 1816 | ||
@@ -1745,13 +1823,13 @@ Build Dependencies | |||
1745 | 1823 | ||
1746 | BitBake uses the :term:`DEPENDS` variable to manage | 1824 | BitBake uses the :term:`DEPENDS` variable to manage |
1747 | build time dependencies. The ``[deptask]`` varflag for tasks signifies | 1825 | build time dependencies. The ``[deptask]`` varflag for tasks signifies |
1748 | the task of each item listed in ``DEPENDS`` that must complete before | 1826 | the task of each item listed in :term:`DEPENDS` that must complete before |
1749 | that task can be executed. Here is an example: :: | 1827 | that task can be executed. Here is an example:: |
1750 | 1828 | ||
1751 | do_configure[deptask] = "do_populate_sysroot" | 1829 | do_configure[deptask] = "do_populate_sysroot" |
1752 | 1830 | ||
1753 | In this example, the ``do_populate_sysroot`` task | 1831 | In this example, the ``do_populate_sysroot`` task |
1754 | of each item in ``DEPENDS`` must complete before ``do_configure`` can | 1832 | of each item in :term:`DEPENDS` must complete before ``do_configure`` can |
1755 | execute. | 1833 | execute. |
1756 | 1834 | ||
1757 | Runtime Dependencies | 1835 | Runtime Dependencies |
@@ -1760,8 +1838,8 @@ Runtime Dependencies | |||
1760 | BitBake uses the :term:`PACKAGES`, :term:`RDEPENDS`, and :term:`RRECOMMENDS` | 1838 | BitBake uses the :term:`PACKAGES`, :term:`RDEPENDS`, and :term:`RRECOMMENDS` |
1761 | variables to manage runtime dependencies. | 1839 | variables to manage runtime dependencies. |
1762 | 1840 | ||
1763 | The ``PACKAGES`` variable lists runtime packages. Each of those packages | 1841 | The :term:`PACKAGES` variable lists runtime packages. Each of those packages |
1764 | can have ``RDEPENDS`` and ``RRECOMMENDS`` runtime dependencies. The | 1842 | can have :term:`RDEPENDS` and :term:`RRECOMMENDS` runtime dependencies. The |
1765 | ``[rdeptask]`` flag for tasks is used to signify the task of each item | 1843 | ``[rdeptask]`` flag for tasks is used to signify the task of each item |
1766 | runtime dependency which must have completed before that task can be | 1844 | runtime dependency which must have completed before that task can be |
1767 | executed. :: | 1845 | executed. :: |
@@ -1769,9 +1847,9 @@ executed. :: | |||
1769 | do_package_qa[rdeptask] = "do_packagedata" | 1847 | do_package_qa[rdeptask] = "do_packagedata" |
1770 | 1848 | ||
1771 | In the previous | 1849 | In the previous |
1772 | example, the ``do_packagedata`` task of each item in ``RDEPENDS`` must | 1850 | example, the ``do_packagedata`` task of each item in :term:`RDEPENDS` must |
1773 | have completed before ``do_package_qa`` can execute. | 1851 | have completed before ``do_package_qa`` can execute. |
1774 | Although ``RDEPENDS`` contains entries from the | 1852 | Although :term:`RDEPENDS` contains entries from the |
1775 | runtime dependency namespace, BitBake knows how to map them back | 1853 | runtime dependency namespace, BitBake knows how to map them back |
1776 | to the build-time dependency namespace, in which the tasks are defined. | 1854 | to the build-time dependency namespace, in which the tasks are defined. |
1777 | 1855 | ||
@@ -1788,7 +1866,7 @@ dependencies are discovered and added. | |||
1788 | 1866 | ||
1789 | The ``[recrdeptask]`` flag is most commonly used in high-level recipes | 1867 | The ``[recrdeptask]`` flag is most commonly used in high-level recipes |
1790 | that need to wait for some task to finish "globally". For example, | 1868 | that need to wait for some task to finish "globally". For example, |
1791 | ``image.bbclass`` has the following: :: | 1869 | ``image.bbclass`` has the following:: |
1792 | 1870 | ||
1793 | do_rootfs[recrdeptask] += "do_packagedata" | 1871 | do_rootfs[recrdeptask] += "do_packagedata" |
1794 | 1872 | ||
@@ -1797,7 +1875,7 @@ the current recipe and all recipes reachable (by way of dependencies) | |||
1797 | from the image recipe must run before the ``do_rootfs`` task can run. | 1875 | from the image recipe must run before the ``do_rootfs`` task can run. |
1798 | 1876 | ||
1799 | BitBake allows a task to recursively depend on itself by | 1877 | BitBake allows a task to recursively depend on itself by |
1800 | referencing itself in the task list: :: | 1878 | referencing itself in the task list:: |
1801 | 1879 | ||
1802 | do_a[recrdeptask] = "do_a do_b" | 1880 | do_a[recrdeptask] = "do_a do_b" |
1803 | 1881 | ||
@@ -1814,7 +1892,7 @@ Inter-Task Dependencies | |||
1814 | BitBake uses the ``[depends]`` flag in a more generic form to manage | 1892 | BitBake uses the ``[depends]`` flag in a more generic form to manage |
1815 | inter-task dependencies. This more generic form allows for | 1893 | inter-task dependencies. This more generic form allows for |
1816 | inter-dependency checks for specific tasks rather than checks for the | 1894 | inter-dependency checks for specific tasks rather than checks for the |
1817 | data in ``DEPENDS``. Here is an example: :: | 1895 | data in :term:`DEPENDS`. Here is an example:: |
1818 | 1896 | ||
1819 | do_patch[depends] = "quilt-native:do_populate_sysroot" | 1897 | do_patch[depends] = "quilt-native:do_populate_sysroot" |
1820 | 1898 | ||
@@ -1900,6 +1978,33 @@ looking at the source code of the ``bb`` module, which is in | |||
1900 | the commonly used functions ``bb.utils.contains()`` and | 1978 | the commonly used functions ``bb.utils.contains()`` and |
1901 | ``bb.utils.mkdirhier()``, which come with docstrings. | 1979 | ``bb.utils.mkdirhier()``, which come with docstrings. |
1902 | 1980 | ||
1981 | Extending Python Library Code | ||
1982 | ----------------------------- | ||
1983 | |||
1984 | If you wish to add your own Python library code (e.g. to provide | ||
1985 | functions/classes you can use from Python functions in the metadata) | ||
1986 | you can do so from any layer using the ``addpylib`` directive. | ||
1987 | This directive is typically added to your layer configuration ( | ||
1988 | ``conf/layer.conf``) although it will be handled in any ``.conf`` file. | ||
1989 | |||
1990 | Usage is of the form:: | ||
1991 | |||
1992 | addpylib <directory> <namespace> | ||
1993 | |||
1994 | Where <directory> specifies the directory to add to the library path. | ||
1995 | The specified <namespace> is imported automatically, and if the imported | ||
1996 | module specifies an attribute named ``BBIMPORTS``, that list of | ||
1997 | sub-modules is iterated and imported too. | ||
1998 | |||
1999 | Testing and Debugging BitBake Python code | ||
2000 | ----------------------------------------- | ||
2001 | |||
2002 | The OpenEmbedded build system implements a convenient ``pydevshell`` target which | ||
2003 | you can use to access the BitBake datastore and experiment with your own Python | ||
2004 | code. See :yocto_docs:`Using a Python Development Shell | ||
2005 | </dev-manual/python-development-shell.html#using-a-python-development-shell>` in the Yocto | ||
2006 | Project manual for details. | ||
2007 | |||
1903 | Task Checksums and Setscene | 2008 | Task Checksums and Setscene |
1904 | =========================== | 2009 | =========================== |
1905 | 2010 | ||
@@ -1909,7 +2014,7 @@ To help understand how BitBake does this, the section assumes an | |||
1909 | OpenEmbedded metadata-based example. | 2014 | OpenEmbedded metadata-based example. |
1910 | 2015 | ||
1911 | These checksums are stored in :term:`STAMP`. You can | 2016 | These checksums are stored in :term:`STAMP`. You can |
1912 | examine the checksums using the following BitBake command: :: | 2017 | examine the checksums using the following BitBake command:: |
1913 | 2018 | ||
1914 | $ bitbake-dumpsigs | 2019 | $ bitbake-dumpsigs |
1915 | 2020 | ||
@@ -1932,16 +2037,6 @@ The following list describes related variables: | |||
1932 | Specifies a function BitBake calls that determines whether BitBake | 2037 | Specifies a function BitBake calls that determines whether BitBake |
1933 | requires a setscene dependency to be met. | 2038 | requires a setscene dependency to be met. |
1934 | 2039 | ||
1935 | - :term:`BB_SETSCENE_VERIFY_FUNCTION2`: | ||
1936 | Specifies a function to call that verifies the list of planned task | ||
1937 | execution before the main task execution happens. | ||
1938 | |||
1939 | - :term:`BB_STAMP_POLICY`: Defines the mode | ||
1940 | for comparing timestamps of stamp files. | ||
1941 | |||
1942 | - :term:`BB_STAMP_WHITELIST`: Lists stamp | ||
1943 | files that are looked at when the stamp policy is "whitelist". | ||
1944 | |||
1945 | - :term:`BB_TASKHASH`: Within an executing task, | 2040 | - :term:`BB_TASKHASH`: Within an executing task, |
1946 | this variable holds the hash of the task as returned by the currently | 2041 | this variable holds the hash of the task as returned by the currently |
1947 | enabled signature generator. | 2042 | enabled signature generator. |
@@ -1956,7 +2051,7 @@ Wildcard Support in Variables | |||
1956 | ============================= | 2051 | ============================= |
1957 | 2052 | ||
1958 | Support for wildcard use in variables varies depending on the context in | 2053 | Support for wildcard use in variables varies depending on the context in |
1959 | which it is used. For example, some variables and file names allow | 2054 | which it is used. For example, some variables and filenames allow |
1960 | limited use of wildcards through the "``%``" and "``*``" characters. | 2055 | limited use of wildcards through the "``%``" and "``*``" characters. |
1961 | Other variables or names support Python's | 2056 | Other variables or names support Python's |
1962 | `glob <https://docs.python.org/3/library/glob.html>`_ syntax, | 2057 | `glob <https://docs.python.org/3/library/glob.html>`_ syntax, |