summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-02-03 16:55:51 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-02-11 12:17:06 +0000
commitd110f55a945399359a0ff0643e11a5283a84e337 (patch)
treecb3f9613949fe66e9ab63af95b0f09863b0f730f
parentdecc756e8990bfc5e0aa973320b2b81419a33518 (diff)
downloadpoky-d110f55a945399359a0ff0643e11a5283a84e337.tar.gz
bitbake: user-manual-metadata.xml: Edits to "Conditional Syntax (Overrides)"
Re-wrote this section to use clearer more described examples. (Bitbake rev: 6eea23c4783c591c2d2c7f0b2a98e7a0cc8aa3c3) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--bitbake/doc/user-manual/user-manual-metadata.xml207
1 files changed, 138 insertions, 69 deletions
diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index 05cb9850c6..9708bbb12f 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -304,88 +304,167 @@
304 <section id='conditional-syntax-overrides'> 304 <section id='conditional-syntax-overrides'>
305 <title>Conditional Syntax (Overrides)</title> 305 <title>Conditional Syntax (Overrides)</title>
306 306
307 <para>
308 BitBake uses
309 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
310 to control what variables are overridden after BitBake
311 parses recipes and configuration files.
312 This section describes how you can use
313 <filename>OVERRIDES</filename> as conditional metadata,
314 talks about key expansion in relationship to
315 <filename>OVERRIDES</filename>, and provides some examples
316 to help with understanding.
317 </para>
318
307 <section id='conditional-metadata'> 319 <section id='conditional-metadata'>
308 <title>Conditional Metadata</title> 320 <title>Conditional Metadata</title>
309 321
310 <para> 322 <para>
311 <filename>OVERRIDES</filename> is a “:” separated variable containing 323 You can use <filename>OVERRIDES</filename> to conditionally select
312 each item for which you want to satisfy conditions. 324 a specific version of a variable and to conditionally
313 So, if you have a variable that is conditional on “arm”, and “arm” 325 append or prepend the value of a variable.
314 is in <filename>OVERRIDES</filename>, then the “arm” specific 326 <itemizedlist>
315 version of the variable is used rather than the non-conditional 327 <listitem><para><emphasis>Selecting a Variable:</emphasis>
316 version. 328 The <filename>OVERRIDES</filename> variable is
317 Here is an example: 329 a colon-character-separated list that contains items
318 <literallayout class='monospaced'> 330 for which you want to satisfy conditions.
331 Thus, if you have a variable that is conditional on “arm”, and “arm”
332 is in <filename>OVERRIDES</filename>, then the “arm”-specific
333 version of the variable is used rather than the non-conditional
334 version.
335 Here is an example:
336 <literallayout class='monospaced'>
319 OVERRIDES = "architecture:os:machine" 337 OVERRIDES = "architecture:os:machine"
320 TEST = "defaultvalue" 338 TEST = "default"
321 TEST_os = "osspecificvalue" 339 TEST_os = "osspecific"
322 TEST_condnotinoverrides = "othercondvalue" 340 TEST_nooverride = "othercondvalue"
323 </literallayout> 341 </literallayout>
324 In this example, <filename>TEST</filename> would be 342 In this example, the <filename>OVERRIDES</filename>
325 <filename>osspecificvalue</filename>, due to the condition 343 variable lists three overrides:
326 “os” being in <filename>OVERRIDES</filename>. 344 "architecture", "os", and "machine".
345 The variable <filename>TEST</filename> by itself has a default
346 value of "default".
347 You select the os-specific version of the <filename>TEST</filename>
348 variable by appending the "os" override to the variable
349 (i.e.<filename>TEST_os</filename>).
350 </para></listitem>
351 <listitem><para><emphasis>Appending and Prepending:</emphasis>
352 BitBake also supports append and prepend operations to
353 variable values based on whether a specific item is
354 listed in <filename>OVERRIDES</filename>.
355 Here is an example:
356 <literallayout class='monospaced'>
357 DEPENDS = "glibc ncurses"
358 OVERRIDES = "machine:local"
359 DEPENDS_append_machine = "libmad"
360 </literallayout>
361 In this example, <filename>DEPENDS</filename> becomes
362 "glibc ncurses libmad".
363 </para></listitem>
364 </itemizedlist>
327 </para> 365 </para>
328 </section> 366 </section>
329 367
330 <section id='conditional-appending'> 368 <section id='key-expansion'>
331 <title>Conditional Appending</title> 369 <title>Key Expansion</title>
332 370
333 <para> 371 <para>
334 BitBake also supports appending and prepending to variables based 372 Key expansion happens when the BitBake data store is finalized
335 on whether something is in <filename>OVERRIDES</filename>. 373 just before BitBake expands overrides.
336 Here is an example: 374 To better understand this, consider the following example:
337 <literallayout class='monospaced'> 375 <literallayout class='monospaced'>
338 DEPENDS = "glibc ncurses" 376 A${B} = "X"
339 OVERRIDES = "machine:local" 377 B = "2"
340 DEPENDS_append_machine = "libmad" 378 A2 = "Y"
341 </literallayout> 379 </literallayout>
342 In this example, <filename>DEPENDS</filename> is set to 380 In this case, after all the parsing is complete, and
343 "glibc ncurses libmad". 381 before any overrides are handled, BitBake expands
382 <filename>${B}</filename> into "2".
383 This expansion causes <filename>A2</filename>, which was
384 set to "Y" before the expansion, to become "X".
344 </para> 385 </para>
345 </section> 386 </section>
346 387
347 <section id='variable-interaction-worked-examples'> 388 <section id='variable-interaction-worked-examples'>
348 <title>Variable Interaction: Worked Examples</title> 389 <title>Examples</title>
349
350 <para>
351 Despite the documentation of the different forms of
352 variable definition above, it can be hard to work
353 out what happens when variable operators are combined.
354 </para>
355 390
356 <para> 391 <para>
357 Following are some common scenarios where variables interact 392 Despite the previous explanations that show the different forms of
358 that can confuse users. 393 variable definitions, it can be hard to work
394 out exactly what happens when variable operators, conditional
395 overrides, and unconditional overrides are combined.
396 This section presents some common scenarios along
397 with explanations for variable interactions that
398 typically confuse users.
359 </para> 399 </para>
360 400
361 <para> 401 <para>
362 There is often confusion about which order overrides and the 402 There is often confusion concerning the order in which
363 various "append" operators take effect: 403 overrides and various "append" operators take effect.
404 Recall that an append or prepend operation using "_append"
405 and "_prepend" does not result in an immediate assignment
406 as would "+=", ".=", "=+", or "=.".
407 Consider the following example:
364 <literallayout class='monospaced'> 408 <literallayout class='monospaced'>
365 OVERRIDES = "foo" 409 OVERRIDES = "foo"
410 A = "Z"
366 A_foo_append = "X" 411 A_foo_append = "X"
367 </literallayout> 412 </literallayout>
368 In this case, <filename>X</filename> is unconditionally appended 413 For this case, <filename>A</filename> is
369 to the variable <filename>A_foo</filename>. 414 unconditionally set to "Z" and "X" is
370 Since foo is an override, <filename>A_foo</filename> would then replace 415 unconditionally and immediately appended to the variable
371 <filename>A</filename>. 416 <filename>A_foo</filename>.
417 Because overrides have not been applied yet,
418 <filename>A_foo</filename> is set to "X" due to the append
419 and <filename>A</filename> simply equals "Z".
420 </para>
421
422 <para>
423 Applying overrides, however, changes things.
424 Since "foo" is listed in <filename>OVERRIDES</filename>,
425 the conditional variable <filename>A</filename> is replaced
426 with the "foo" version, which is equal to "X".
427 So effectively, <filename>A_foo</filename> replaces <filename>A</filename>.
428 </para>
429
430 <para>
431 This next example changes the order of the override and
432 the append:
372 <literallayout class='monospaced'> 433 <literallayout class='monospaced'>
373 OVERRIDES = "foo" 434 OVERRIDES = "foo"
374 A = "X" 435 A = "Z"
375 A_append_foo = "Y" 436 A_append_foo = "X"
376 </literallayout> 437 </literallayout>
377 In this case, only when <filename>foo</filename> is in 438 For this case, before overrides are handled,
378 <filename>OVERRIDES</filename>, <filename>Y</filename> 439 <filename>A</filename> is set to "Z" and <filename>A_append_foo</filename>
379 is appended to the variable <filename>A</filename> 440 is set to "X".
380 so the value of <filename>A</filename> would 441 Once the override for "foo" is applied, however,
381 become <filename>XY</filename> (NB: no spaces are appended). 442 <filename>A</filename> gets appended with "X".
443 Consequently, <filename>A</filename> becomes "ZX".
444 Notice that spaces are not appended.
445 </para>
446
447 <para>
448 This next example has the order of the appends and overrides reversed
449 back as in the first example:
382 <literallayout class='monospaced'> 450 <literallayout class='monospaced'>
383 OVERRIDES = "foo" 451 OVERRIDES = "foo"
384 A_foo_append = "X" 452 A = "Y"
385 A_foo_append += "Y" 453 A_foo_append = "Z"
454 A_foo_append += "X"
386 </literallayout> 455 </literallayout>
387 This behaves as per the first case above, but the value of 456 For this case, before any overrides are resolved,
388 <filename>A</filename> would be "X Y" instead of just "X". 457 <filename>A</filename> is set to "Y" using an immediate assignment.
458 After this immediate assignment, <filename>A_foo</filename> is set
459 to "Z", and then further appended with
460 "X" leaving the variable set to "Z X".
461 Finally, applying the override for "foo" results in the conditional
462 variable <filename>A</filename> becoming "Z X" (i.e.
463 <filename>A</filename> is replaced with <filename>A_foo</filename>).
464 </para>
465
466 <para>
467 This final example mixes in some varying operators:
389 <literallayout class='monospaced'> 468 <literallayout class='monospaced'>
390 A = "1" 469 A = "1"
391 A_append = "2" 470 A_append = "2"
@@ -393,24 +472,14 @@
393 A += "4" 472 A += "4"
394 A .= "5" 473 A .= "5"
395 </literallayout> 474 </literallayout>
396 Would ultimately result in <filename>A</filename> taking the value 475 For this case, the type of append operators are affecting the
397 "1 4523" since the "_append" operator executes at the 476 order of assignments as BitBake passes through the code
398 same time as the expansion of other overrides. 477 multiple times.
399 </para> 478 Initially, <filename>A</filename> is set to "1 45" because
400 </section> 479 of the three statements that use immediate operators.
401 480 After these assignments are made, BitBake applies the
402 <section id='key-expansion'> 481 <filename>_append</filename> operations.
403 <title>Key Expansion</title> 482 Those operations result in <filename>A</filename> becoming "1 4523".
404
405 <para>
406 Key expansion happens at the data store finalization
407 time just before overrides are expanded.
408 <literallayout class='monospaced'>
409 A${B} = "X"
410 B = "2"
411 A2 = "Y"
412 </literallayout>
413 So in this case <filename>A2</filename> would take the value of "X".
414 </para> 483 </para>
415 </section> 484 </section>
416 </section> 485 </section>