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,98 +304,64 @@
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. - -
- -
- Conditional Appending - - - BitBake also supports appending and prepending to variables based - on whether something is in OVERRIDES. - Here is an example: - + 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 is set to - "glibc ncurses libmad". - -
- -
- 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. - - - - Following are some common scenarios where variables interact - that can confuse users. - - - - There is often confusion about which order overrides and the - various "append" operators take effect: - - OVERRIDES = "foo" - 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. - - OVERRIDES = "foo" - A = "X" - A_append_foo = "Y" - - 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). - - OVERRIDES = "foo" - A_foo_append = "X" - A_foo_append += "Y" - - This behaves as per the first case above, but the value of - A would be "X Y" instead of just "X". - - A = "1" - A_append = "2" - A_append = "3" - 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. + + In this example, DEPENDS becomes + "glibc ncurses libmad". + +
@@ -403,14 +369,117 @@ Key Expansion - Key expansion happens at the data store finalization - time just before overrides are expanded. + Key expansion happens when the BitBake data store is finalized + just before BitBake expands overrides. + To better understand this, consider the following example: A${B} = "X" B = "2" A2 = "Y" - So in this case A2 would take the value of "X". + 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". + +
+ +
+ Examples + + + 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 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" + + 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 = "Z" + A_append_foo = "X" + + 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 = "Y" + A_foo_append = "Z" + A_foo_append += "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" + A_append = "3" + A += "4" + A .= "5" + + 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".