diff options
authorJamie Lenehan <lenehan@twibble.org>2007-03-15 00:02:06 +0000
committerJamie Lenehan <lenehan@twibble.org>2007-03-15 00:02:06 +0000
commit7b153a75335a572a2ba78bee5bf4a4c60f0c8c82 (patch)
parent845b0062935f20e90551cace2520e70f1ca4e5f6 (diff)
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>
- <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>
@@ -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 id="recipes_initscripts" xreflabel="initscripts">
@@ -3418,4 +3449,4 @@ which find
+</chapter> \ No newline at end of file