diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2014-02-03 16:55:51 -0600 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-02-11 12:17:06 +0000 |
commit | d110f55a945399359a0ff0643e11a5283a84e337 (patch) | |
tree | cb3f9613949fe66e9ab63af95b0f09863b0f730f /bitbake/doc | |
parent | decc756e8990bfc5e0aa973320b2b81419a33518 (diff) | |
download | openembedded-core-contrib-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>
Diffstat (limited to 'bitbake/doc')
-rw-r--r-- | bitbake/doc/user-manual/user-manual-metadata.xml | 207 |
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 @@ <section id='conditional-syntax-overrides'> <title>Conditional Syntax (Overrides)</title> + <para> + BitBake uses + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> + to control what variables are overridden after BitBake + parses recipes and configuration files. + This section describes how you can use + <filename>OVERRIDES</filename> as conditional metadata, + talks about key expansion in relationship to + <filename>OVERRIDES</filename>, and provides some examples + to help with understanding. + </para> + <section id='conditional-metadata'> <title>Conditional Metadata</title> <para> - <filename>OVERRIDES</filename> 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 <filename>OVERRIDES</filename>, then the “arm” specific - version of the variable is used rather than the non-conditional - version. - Here is an example: - <literallayout class='monospaced'> + You can use <filename>OVERRIDES</filename> to conditionally select + a specific version of a variable and to conditionally + append or prepend the value of a variable. + <itemizedlist> + <listitem><para><emphasis>Selecting a Variable:</emphasis> + The <filename>OVERRIDES</filename> 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 <filename>OVERRIDES</filename>, then the “arm”-specific + version of the variable is used rather than the non-conditional + version. + Here is an example: + <literallayout class='monospaced'> OVERRIDES = "architecture:os:machine" - TEST = "defaultvalue" - TEST_os = "osspecificvalue" - TEST_condnotinoverrides = "othercondvalue" - </literallayout> - In this example, <filename>TEST</filename> would be - <filename>osspecificvalue</filename>, due to the condition - “os” being in <filename>OVERRIDES</filename>. + TEST = "default" + TEST_os = "osspecific" + TEST_nooverride = "othercondvalue" + </literallayout> + In this example, the <filename>OVERRIDES</filename> + variable lists three overrides: + "architecture", "os", and "machine". + The variable <filename>TEST</filename> by itself has a default + value of "default". + You select the os-specific version of the <filename>TEST</filename> + variable by appending the "os" override to the variable + (i.e.<filename>TEST_os</filename>). + </para></listitem> + <listitem><para><emphasis>Appending and Prepending:</emphasis> + BitBake also supports append and prepend operations to + variable values based on whether a specific item is + listed in <filename>OVERRIDES</filename>. + Here is an example: + <literallayout class='monospaced'> + DEPENDS = "glibc ncurses" + OVERRIDES = "machine:local" + DEPENDS_append_machine = "libmad" + </literallayout> + In this example, <filename>DEPENDS</filename> becomes + "glibc ncurses libmad". + </para></listitem> + </itemizedlist> </para> </section> - <section id='conditional-appending'> - <title>Conditional Appending</title> + <section id='key-expansion'> + <title>Key Expansion</title> <para> - BitBake also supports appending and prepending to variables based - on whether something is in <filename>OVERRIDES</filename>. - 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: <literallayout class='monospaced'> - DEPENDS = "glibc ncurses" - OVERRIDES = "machine:local" - DEPENDS_append_machine = "libmad" + A${B} = "X" + B = "2" + A2 = "Y" </literallayout> - In this example, <filename>DEPENDS</filename> is set to - "glibc ncurses libmad". + In this case, after all the parsing is complete, and + before any overrides are handled, BitBake expands + <filename>${B}</filename> into "2". + This expansion causes <filename>A2</filename>, which was + set to "Y" before the expansion, to become "X". </para> </section> <section id='variable-interaction-worked-examples'> - <title>Variable Interaction: Worked Examples</title> - - <para> - 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. - </para> + <title>Examples</title> <para> - 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. </para> <para> - 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: <literallayout class='monospaced'> OVERRIDES = "foo" + A = "Z" A_foo_append = "X" </literallayout> - In this case, <filename>X</filename> is unconditionally appended - to the variable <filename>A_foo</filename>. - Since foo is an override, <filename>A_foo</filename> would then replace - <filename>A</filename>. + For this case, <filename>A</filename> is + unconditionally set to "Z" and "X" is + unconditionally and immediately appended to the variable + <filename>A_foo</filename>. + Because overrides have not been applied yet, + <filename>A_foo</filename> is set to "X" due to the append + and <filename>A</filename> simply equals "Z". + </para> + + <para> + Applying overrides, however, changes things. + Since "foo" is listed in <filename>OVERRIDES</filename>, + the conditional variable <filename>A</filename> is replaced + with the "foo" version, which is equal to "X". + So effectively, <filename>A_foo</filename> replaces <filename>A</filename>. + </para> + + <para> + This next example changes the order of the override and + the append: <literallayout class='monospaced'> OVERRIDES = "foo" - A = "X" - A_append_foo = "Y" + A = "Z" + A_append_foo = "X" </literallayout> - In this case, only when <filename>foo</filename> is in - <filename>OVERRIDES</filename>, <filename>Y</filename> - is appended to the variable <filename>A</filename> - so the value of <filename>A</filename> would - become <filename>XY</filename> (NB: no spaces are appended). + For this case, before overrides are handled, + <filename>A</filename> is set to "Z" and <filename>A_append_foo</filename> + is set to "X". + Once the override for "foo" is applied, however, + <filename>A</filename> gets appended with "X". + Consequently, <filename>A</filename> becomes "ZX". + Notice that spaces are not appended. + </para> + + <para> + This next example has the order of the appends and overrides reversed + back as in the first example: <literallayout class='monospaced'> OVERRIDES = "foo" - A_foo_append = "X" - A_foo_append += "Y" + A = "Y" + A_foo_append = "Z" + A_foo_append += "X" </literallayout> - This behaves as per the first case above, but the value of - <filename>A</filename> would be "X Y" instead of just "X". + For this case, before any overrides are resolved, + <filename>A</filename> is set to "Y" using an immediate assignment. + After this immediate assignment, <filename>A_foo</filename> 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 <filename>A</filename> becoming "Z X" (i.e. + <filename>A</filename> is replaced with <filename>A_foo</filename>). + </para> + + <para> + This final example mixes in some varying operators: <literallayout class='monospaced'> A = "1" A_append = "2" @@ -393,24 +472,14 @@ A += "4" A .= "5" </literallayout> - Would ultimately result in <filename>A</filename> taking the value - "1 4523" since the "_append" operator executes at the - same time as the expansion of other overrides. - </para> - </section> - - <section id='key-expansion'> - <title>Key Expansion</title> - - <para> - Key expansion happens at the data store finalization - time just before overrides are expanded. - <literallayout class='monospaced'> - A${B} = "X" - B = "2" - A2 = "Y" - </literallayout> - So in this case <filename>A2</filename> 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, <filename>A</filename> is set to "1 45" because + of the three statements that use immediate operators. + After these assignments are made, BitBake applies the + <filename>_append</filename> operations. + Those operations result in <filename>A</filename> becoming "1 4523". </para> </section> </section> |