recipes: Fill out the section on DEFAULT_PREFERENCE.

1 files changed, 49 insertions, 18 deletions

diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml
index 83c3f39279..786b80540c 100644
--- a/usermanual/chapters/recipes.xml
+++ b/usermanual/chapters/recipes.xml
@@ -2001,7 +2001,8 @@ NOTE: package helloworld-0.1-r0: task do_package_write: completed</screen>We
       matched via wildcards. Consider the case where we have three binaries in
       the /usr/bin directory and we want the test program in a separate
       package:<screen>/usr/bin/programa /usr/bin/programb /usr/bin/test</screen>So
-      we define a new package and instruct bitbake to /usr/bin/test in it.</para>
+      we define a new package and instruct bitbake to /usr/bin/test in
+      it.</para>
 
       <screen>FILES-${PN}-test = "${bindir}/test"
 PACKAGES += "FILES-${PN}-test"</screen>
@@ -2019,7 +2020,8 @@ PACKAGES += "FILES-${PN}-test"</screen>
       processing of the <emphasis role="bold">${PN}-test</emphasis>
       package.</para>
 
-      <para>To achieve what we are trying to accomplish we have two options:</para>
+      <para>To achieve what we are trying to accomplish we have two
+      options:</para>
 
       <orderedlist>
         <listitem>
@@ -3103,21 +3105,50 @@ do_configure() {
   <section id="recipes_defaultpreference" xreflabel="default preference">
     <title>Preferences: How to disable packages</title>
 
-    <para>This section is to be completed.</para>
-
-    <itemizedlist>
-      <listitem>
-        <para>what DEFAULT_PREFERENCE does</para>
-      </listitem>
-
-      <listitem>
-        <para>why you would want to use it</para>
-      </listitem>
-
-      <listitem>
-        <para>using it with overrides</para>
-      </listitem>
-    </itemizedlist>
+    <para>When bitbake is asked to build a package and multiple version of
+    that package are available it will normally select the version with the
+    highest version number (where the version is defined via the
+    <command>PV</command> variable). </para>
+
+    <para>For example if we were to ask bitbake to build procps and the
+    following packages are available:<screen>~/oe%&gt; ls packages/procps 
+procps-3.1.15/    procps-3.2.1/    procps-3.2.5/    procps-3.2.7/    procps.inc
+procps_3.1.15.bb  procps_3.2.1.bb  procps_3.2.5.bb  procps_3.2.7.bb
+~/oe%&gt;</screen>then we would expect that version <command>3.2.7</command>
+    (the highest version number) would be built.</para>
+
+    <para>Sometimes this is not what you actually want to happen though.
+    Perhaps you have added a new version does not yet work or maybe the new
+    version has no support for your target yet. Help is at hand since bitbake
+    is not only looking at the version to decided which version to build but
+    is also looking at the preference for the versions, as defined via a
+    <command>DEFAULT_PREFERENCE</command> variable contained without the
+    recipes.</para>
+
+    <para>By default <command>DEFAULT_PREFERENCE</command> is set to zero.
+    Bitbake will find the highest preference that is available and then for
+    all the packages at the preference level it will select the package with
+    the highest version. In general this means that adding a positive
+    <command>DEFAULT_PREFERENCE</command> will cause the package to be
+    preferred over other versions and a negative
+    <command>DEFAULT_PREFERENCE</command> will cause all other packages to be
+    preferred.</para>
+
+    <para>Imagine that you are adding procps version 4.0.0, but that it does
+    not yet work. You could delete it to make procps build so you can build a
+    working image, but what you really want it just for version 4.0.0 to be
+    ignored until it works. By adding:<screen>DEFAULT_PREFERENCE = "-1"</screen>to
+    the recipe it'll cause it to be ignored by bitbake (since all the existing
+    versions have a preference of 0). Note that you can still call bitbake
+    directly on the recipe:<screen>bitbake -b packages/procps/procps_4.0.0.bb</screen>This
+    enables you to test, and fix the package manually without having bitbake
+    automatically select normally.</para>
+
+    <para>By using this in conjunction with overrides you can also disable (or
+    select) specific version for a specific architecture. The following
+    example from glibc shows that this version has been disabled for the sh3
+    architecture because it doesn't support sh3. This will force bitbake to
+    try and select one of the other versions instead:<screen>packages/glibc/glibc_2.3.2+cvs20040726.bb:DEFAULT_PREFERENCE_sh3 = "-99"</screen></para>
   </section>
 
   <section id="recipes_initscripts" xreflabel="initscripts">
@@ -3418,4 +3449,4 @@ which find
 
     <para></para>
   </section>
-</chapter>
+</chapter>
\ No newline at end of file