mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-09-19 09:49:33 +02:00
Code Issues Packages Projects Releases Wiki Activity

bitbake: user-manual-metadata.xml: Edits to "Conditional Syntax (Overrides)"

Browse Source 
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>
This commit is contained in:
Scott Rifenbark
2014-02-03 16:55:51 -06:00
committed by Richard Purdie
parent decc756e89
commit d110f55a94
1 changed files with 156 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

243
bitbake/doc/user-manual/user-manual-metadata.xml
View File

@@ -304,98 +304,64 @@
<section id='conditional-syntax-overrides'> <section id='conditional-syntax-overrides'>
<title>Conditional Syntax (Overrides)</title> <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'> <section id='conditional-metadata'>
<title>Conditional Metadata</title> <title>Conditional Metadata</title>
<para> <para>
<filename>OVERRIDES</filename> is a “:” separated variable containing You can use <filename>OVERRIDES</filename> to conditionally select
each item for which you want to satisfy conditions. a specific version of a variable and to conditionally
So, if you have a variable that is conditional on “arm”, and “arm” append or prepend the value of a variable.
is in <filename>OVERRIDES</filename>, then the “arm” specific <itemizedlist>
version of the variable is used rather than the non-conditional <listitem><para><emphasis>Selecting a Variable:</emphasis>
version. The <filename>OVERRIDES</filename> variable is
Here is an example: a colon-character-separated list that contains items
<literallayout class='monospaced'> 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" OVERRIDES = "architecture:os:machine"
TEST = "defaultvalue" TEST = "default"
TEST_os = "osspecificvalue" TEST_os = "osspecific"
TEST_condnotinoverrides = "othercondvalue" TEST_nooverride = "othercondvalue"
</literallayout> </literallayout>
In this example, <filename>TEST</filename> would be In this example, the <filename>OVERRIDES</filename>
<filename>osspecificvalue</filename>, due to the condition variable lists three overrides:
“os” being in <filename>OVERRIDES</filename>. "architecture", "os", and "machine".
</para> The variable <filename>TEST</filename> by itself has a default
</section> value of "default".
You select the os-specific version of the <filename>TEST</filename>
<section id='conditional-appending'> variable by appending the "os" override to the variable
<title>Conditional Appending</title> (i.e.<filename>TEST_os</filename>).
</para></listitem>
<para> <listitem><para><emphasis>Appending and Prepending:</emphasis>
BitBake also supports appending and prepending to variables based BitBake also supports append and prepend operations to
on whether something is in <filename>OVERRIDES</filename>. variable values based on whether a specific item is
Here is an example: listed in <filename>OVERRIDES</filename>.
<literallayout class='monospaced'> Here is an example:
<literallayout class='monospaced'>
DEPENDS = "glibc ncurses" DEPENDS = "glibc ncurses"
OVERRIDES = "machine:local" OVERRIDES = "machine:local"
DEPENDS_append_machine = "libmad" DEPENDS_append_machine = "libmad"
</literallayout> </literallayout>
In this example, <filename>DEPENDS</filename> is set to In this example, <filename>DEPENDS</filename> becomes
"glibc ncurses libmad". "glibc ncurses libmad".
</para> </para></listitem>
</section> </itemizedlist>
<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>
<para>
Following are some common scenarios where variables interact
that can confuse users.
</para>
<para>
There is often confusion about which order overrides and the
various "append" operators take effect:
<literallayout class='monospaced'>
OVERRIDES = "foo"
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>.
<literallayout class='monospaced'>
OVERRIDES = "foo"
A = "X"
A_append_foo = "Y"
</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).
<literallayout class='monospaced'>
OVERRIDES = "foo"
A_foo_append = "X"
A_foo_append += "Y"
</literallayout>
This behaves as per the first case above, but the value of
<filename>A</filename> would be "X Y" instead of just "X".
<literallayout class='monospaced'>
A = "1"
A_append = "2"
A_append = "3"
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> </para>
</section> </section>
@@ -403,14 +369,117 @@
<title>Key Expansion</title> <title>Key Expansion</title>
<para> <para>
Key expansion happens at the data store finalization Key expansion happens when the BitBake data store is finalized
time just before overrides are expanded. just before BitBake expands overrides.
To better understand this, consider the following example:
<literallayout class='monospaced'> <literallayout class='monospaced'>
A${B} = "X" A${B} = "X"
B = "2" B = "2"
A2 = "Y" A2 = "Y"
</literallayout> </literallayout>
So in this case <filename>A2</filename> would take the value of "X". 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>Examples</title>
<para>
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 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>
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 = "Z"
A_append_foo = "X"
</literallayout>
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 = "Y"
A_foo_append = "Z"
A_foo_append += "X"
</literallayout>
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"
A_append = "3"
A += "4"
A .= "5"
</literallayout>
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> </para>
</section> </section>
</section> </section>