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 @@
- Preferences and Providers
+ Providers
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 PROVIDES list
+ for each of the recipes.
+ A PROVIDES list is the list of names by which
+ the recipe can be known.
+ Each recipe's PROVIDES list is created
+ implicitly through the recipe's
+ PN variable
+ and explicitly through the recipe's
PROVIDES
- set in recipe files.
- The default PROVIDES for a recipe is its name
- (PN),
- however, a recipe can provide multiple things.
+ variable, which is optional.
- As an example of adding an extra provider, suppose a recipe named
- foo_1.0.bb contained the following:
+ When a recipe uses PROVIDES, that recipe's
+ functionality can be found under an alternative name or names other
+ than the implicit PN name.
+ As an example, suppose a recipe named keyboard_1.0.bb
+ contained the following:
- PROVIDES += "virtual/bar_1.0"
+ PROVIDES += "fullkeyboard"
- 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 PROVIDES list for this recipe becomes
+ "keyboard", which is implicit, and "fullkeyboard", which is explicit.
+ Consequently, the functionality found in
+ keyboard_1.0.bb can be found under two
+ different names.
+
+
+
+
+ Preferences
+
+
+ The PROVIDES 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.
- 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
+ PROVIDES 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:
@@ -377,7 +394,7 @@
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
DEFAULT_PREFERENCE
variable.
+
+
+
By default, files have a preference of "0".
- Setting the DEFAULT_PREFERENCE to "-1" makes the
+ Setting DEFAULT_PREFERENCE to "-1" makes the
recipe unlikely to be used unless it is explicitly referenced.
- Setting the DEFAULT_PREFERENCE to "1" makes it likely the recipe is used.
- PREFERRED_VERSION overrides any DEFAULT_PREFERENCE setting.
- DEFAULT_PREFERENCE is often used to mark newer and more experimental recipe
- versions until they have undergone sufficient testing to be considered stable.
+ Setting DEFAULT_PREFERENCE to "1" makes it
+ likely the recipe is used.
+ PREFERRED_VERSION overrides any
+ DEFAULT_PREFERENCE setting.
+ DEFAULT_PREFERENCE is often used to mark newer
+ and more experimental recipe versions until they have undergone
+ sufficient testing to be considered stable.
@@ -401,18 +424,16 @@
version, unless otherwise specified.
If the recipe in question has a
DEFAULT_PREFERENCE
- 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.
- If the first recipe is named a_1.1.bb,
- then the
+ If the first recipe is named a_1.1.bb, then the
PN variable
will be set to “a”, and the
PV
@@ -420,19 +441,15 @@
- If we then have a recipe named a_1.2.bb, BitBake
+ Thus, if a recipe named a_1.2.bb exists, BitBake
will choose 1.2 by default.
- However, if we define the following variable in a
- .conf file that BitBake parses, we
- can change that.
+ However, if you define the following variable in a
+ .conf file that BitBake parses, you
+ can change that preference:
PREFERRED_VERSION_a = "1.1"
-
-
- In summary, BitBake has created a list of providers, which is prioritized, for each target.
-