From d110f55a945399359a0ff0643e11a5283a84e337 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 3 Feb 2014 16:55:51 -0600 Subject: 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 Signed-off-by: Richard Purdie --- bitbake/doc/user-manual/user-manual-metadata.xml | 207 +++++++++++++++-------- 1 file changed, 138 insertions(+), 69 deletions(-) (limited to 'bitbake/doc') 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 @@
Conditional Syntax (Overrides) + + BitBake uses + OVERRIDES + to control what variables are overridden after BitBake + parses recipes and configuration files. + This section describes how you can use + OVERRIDES as conditional metadata, + talks about key expansion in relationship to + OVERRIDES, and provides some examples + to help with understanding. + +
Conditional Metadata - OVERRIDES is a “:” separated variable containing - each item for which you want to satisfy conditions. - So, if you have a variable that is conditional on “arm”, and “arm” - is in OVERRIDES, then the “arm” specific - version of the variable is used rather than the non-conditional - version. - Here is an example: - + You can use OVERRIDES to conditionally select + a specific version of a variable and to conditionally + append or prepend the value of a variable. + + Selecting a Variable: + The OVERRIDES variable is + a colon-character-separated list that contains items + for which you want to satisfy conditions. + Thus, if you have a variable that is conditional on “arm”, and “arm” + is in OVERRIDES, then the “arm”-specific + version of the variable is used rather than the non-conditional + version. + Here is an example: + OVERRIDES = "architecture:os:machine" - TEST = "defaultvalue" - TEST_os = "osspecificvalue" - TEST_condnotinoverrides = "othercondvalue" - - In this example, TEST would be - osspecificvalue, due to the condition - “os” being in OVERRIDES. + TEST = "default" + TEST_os = "osspecific" + TEST_nooverride = "othercondvalue" + + In this example, the OVERRIDES + variable lists three overrides: + "architecture", "os", and "machine". + The variable TEST by itself has a default + value of "default". + You select the os-specific version of the TEST + variable by appending the "os" override to the variable + (i.e.TEST_os). + + Appending and Prepending: + BitBake also supports append and prepend operations to + variable values based on whether a specific item is + listed in OVERRIDES. + Here is an example: + + DEPENDS = "glibc ncurses" + OVERRIDES = "machine:local" + DEPENDS_append_machine = "libmad" + + In this example, DEPENDS becomes + "glibc ncurses libmad". + +
-
- Conditional Appending +
+ Key Expansion - BitBake also supports appending and prepending to variables based - on whether something is in OVERRIDES. - Here is an example: + Key expansion happens when the BitBake data store is finalized + just before BitBake expands overrides. + To better understand this, consider the following example: - DEPENDS = "glibc ncurses" - OVERRIDES = "machine:local" - DEPENDS_append_machine = "libmad" + A${B} = "X" + B = "2" + A2 = "Y" - In this example, DEPENDS is set to - "glibc ncurses libmad". + In this case, after all the parsing is complete, and + before any overrides are handled, BitBake expands + ${B} into "2". + This expansion causes A2, which was + set to "Y" before the expansion, to become "X".
- Variable Interaction: Worked Examples - - - Despite the documentation of the different forms of - variable definition above, it can be hard to work - out what happens when variable operators are combined. - + Examples - Following are some common scenarios where variables interact - that can confuse users. + Despite the previous explanations that show the different forms of + variable definitions, it can be hard to work + out exactly what happens when variable operators, conditional + overrides, and unconditional overrides are combined. + This section presents some common scenarios along + with explanations for variable interactions that + typically confuse users. - There is often confusion about which order overrides and the - various "append" operators take effect: + There is often confusion concerning the order in which + overrides and various "append" operators take effect. + Recall that an append or prepend operation using "_append" + and "_prepend" does not result in an immediate assignment + as would "+=", ".=", "=+", or "=.". + Consider the following example: OVERRIDES = "foo" + A = "Z" A_foo_append = "X" - In this case, X is unconditionally appended - to the variable A_foo. - Since foo is an override, A_foo would then replace - A. + For this case, A is + unconditionally set to "Z" and "X" is + unconditionally and immediately appended to the variable + A_foo. + Because overrides have not been applied yet, + A_foo is set to "X" due to the append + and A simply equals "Z". + + + + Applying overrides, however, changes things. + Since "foo" is listed in OVERRIDES, + the conditional variable A is replaced + with the "foo" version, which is equal to "X". + So effectively, A_foo replaces A. + + + + This next example changes the order of the override and + the append: OVERRIDES = "foo" - A = "X" - A_append_foo = "Y" + A = "Z" + A_append_foo = "X" - In this case, only when foo is in - OVERRIDES, Y - is appended to the variable A - so the value of A would - become XY (NB: no spaces are appended). + For this case, before overrides are handled, + A is set to "Z" and A_append_foo + is set to "X". + Once the override for "foo" is applied, however, + A gets appended with "X". + Consequently, A becomes "ZX". + Notice that spaces are not appended. + + + + This next example has the order of the appends and overrides reversed + back as in the first example: OVERRIDES = "foo" - A_foo_append = "X" - A_foo_append += "Y" + A = "Y" + A_foo_append = "Z" + A_foo_append += "X" - This behaves as per the first case above, but the value of - A would be "X Y" instead of just "X". + For this case, before any overrides are resolved, + A is set to "Y" using an immediate assignment. + After this immediate assignment, A_foo is set + to "Z", and then further appended with + "X" leaving the variable set to "Z X". + Finally, applying the override for "foo" results in the conditional + variable A becoming "Z X" (i.e. + A is replaced with A_foo). + + + + This final example mixes in some varying operators: A = "1" A_append = "2" @@ -393,24 +472,14 @@ A += "4" A .= "5" - Would ultimately result in A taking the value - "1 4523" since the "_append" operator executes at the - same time as the expansion of other overrides. - -
- -
- Key Expansion - - - Key expansion happens at the data store finalization - time just before overrides are expanded. - - A${B} = "X" - B = "2" - A2 = "Y" - - So in this case A2 would take the value of "X". + For this case, the type of append operators are affecting the + order of assignments as BitBake passes through the code + multiple times. + Initially, A is set to "1 45" because + of the three statements that use immediate operators. + After these assignments are made, BitBake applies the + _append operations. + Those operations result in A becoming "1 4523".
-- cgit v1.2.3-54-g00ecf