diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2014-06-26 15:13:13 +0300 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-07-03 13:58:56 +0100 |
commit | 00ade7ecd04946474aed9d26348bf2c9db4c3495 (patch) | |
tree | 5927548b0720829c07ebd3ba55a3b4127ef11240 | |
parent | 0736649c577d85bd689c73633f302d6b0928896c (diff) | |
download | openembedded-core-contrib-00ade7ecd04946474aed9d26348bf2c9db4c3495.tar.gz |
bitbake: bitbake-user-manual-execution.xml: Edits to "Providers and Preferences"
I split this section into two sections and tried to simplify what
was being said about PROVIDES.
(Bitbake rev: 394f64123d5ef1e9b4628d083488b9432eccbded)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml | 93 |
1 files changed, 55 insertions, 38 deletions
diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml index 8514f23f25..641c6e0af0 100644 --- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml +++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml @@ -331,38 +331,55 @@ </section> <section id='bb-bitbake-providers'> - <title>Preferences and Providers</title> + <title>Providers</title> <para> Assuming BitBake has been instructed to execute a target and that all the recipe files have been parsed, BitBake starts to figure out how to build the target. - BitBake starts by looking through the + BitBake looks through the <filename>PROVIDES</filename> list + for each of the recipes. + A <filename>PROVIDES</filename> list is the list of names by which + the recipe can be known. + Each recipe's <filename>PROVIDES</filename> list is created + implicitly through the recipe's + <link linkend='var-PN'><filename>PN</filename></link> variable + and explicitly through the recipe's <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link> - set in recipe files. - The default <filename>PROVIDES</filename> for a recipe is its name - (<link linkend='var-PN'><filename>PN</filename></link>), - however, a recipe can provide multiple things. + variable, which is optional. </para> <para> - As an example of adding an extra provider, suppose a recipe named - <filename>foo_1.0.bb</filename> contained the following: + When a recipe uses <filename>PROVIDES</filename>, that recipe's + functionality can be found under an alternative name or names other + than the implicit <filename>PN</filename> name. + As an example, suppose a recipe named <filename>keyboard_1.0.bb</filename> + contained the following: <literallayout class='monospaced'> - PROVIDES += "virtual/bar_1.0" + PROVIDES += "fullkeyboard" </literallayout> - The recipe now provides both "foo_1.0" and "virtual/bar_1.0". - The "virtual/" namespace is often used to denote cases where - multiple providers are expected with the user choosing between - them. - Kernels and toolchain components are common cases of this in - OpenEmbedded. + The <filename>PROVIDES</filename> list for this recipe becomes + "keyboard", which is implicit, and "fullkeyboard", which is explicit. + Consequently, the functionality found in + <filename>keyboard_1.0.bb</filename> can be found under two + different names. + </para> + </section> + + <section id='bb-bitbake-preferences'> + <title>Preferences</title> + + <para> + The <filename>PROVIDES</filename> list is only part of the solution + for figuring out a target's recipes. + Because targets might have multiple providers, BitBake needs + to prioritize providers by determining provider preferences. </para> <para> - Sometimes a target might have multiple providers. - A common example is "virtual/kernel", which is provided by each - kernel recipe. + A common example in which a target has multiple providers + is "virtual/kernel", which is on the + <filename>PROVIDES</filename> list for each kernel recipe. Each machine often selects the best kernel provider by using a line similar to the following in the machine configuration file: <literallayout class='monospaced'> @@ -377,7 +394,7 @@ <para> Understanding how providers are chosen is made complicated by the fact - that multiple versions might exist. + that multiple versions might exist for a given provider. BitBake defaults to the highest version of a provider. Version comparisons are made using the same method as Debian. You can use the @@ -386,13 +403,19 @@ You can influence the order by using the <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link> variable. + </para> + + <para> By default, files have a preference of "0". - Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the + Setting <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the recipe unlikely to be used unless it is explicitly referenced. - Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the recipe is used. - <filename>PREFERRED_VERSION</filename> overrides any <filename>DEFAULT_PREFERENCE</filename> setting. - <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental recipe - versions until they have undergone sufficient testing to be considered stable. + Setting <filename>DEFAULT_PREFERENCE</filename> to "1" makes it + likely the recipe is used. + <filename>PREFERRED_VERSION</filename> overrides any + <filename>DEFAULT_PREFERENCE</filename> setting. + <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer + and more experimental recipe versions until they have undergone + sufficient testing to be considered stable. </para> <para> @@ -401,18 +424,16 @@ version, unless otherwise specified. If the recipe in question has a <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link> - set lower than - the other recipes (default is 0), then it will not be - selected. + set lower than the other recipes (default is 0), then + it will not be selected. This allows the person or persons maintaining the repository of recipe files to specify their preference for the default selected version. - In addition, the user can specify their preferred version. + Additionally, the user can specify their preferred version. </para> <para> - If the first recipe is named <filename>a_1.1.bb</filename>, - then the + If the first recipe is named <filename>a_1.1.bb</filename>, then the <link linkend='var-PN'><filename>PN</filename></link> variable will be set to “a”, and the <link linkend='var-PV'><filename>PV</filename></link> @@ -420,19 +441,15 @@ </para> <para> - If we then have a recipe named <filename>a_1.2.bb</filename>, BitBake + Thus, if a recipe named <filename>a_1.2.bb</filename> exists, BitBake will choose 1.2 by default. - However, if we define the following variable in a - <filename>.conf</filename> file that BitBake parses, we - can change that. + However, if you define the following variable in a + <filename>.conf</filename> file that BitBake parses, you + can change that preference: <literallayout class='monospaced'> PREFERRED_VERSION_a = "1.1" </literallayout> </para> - - <para> - In summary, BitBake has created a list of providers, which is prioritized, for each target. - </para> </section> <section id='bb-bitbake-dependencies'> |