toaster-manual: New section on PREFERRED_VERSION

Added a new section in the interface use area that describes
how to build a version of a recipe that is not the default
version.  Four new figures were added to support the
description.

(From yocto-docs rev: 232a875fb8fff97ce0578cf50b2a102bdaed1758)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

documentation/toaster-manual/toaster-manual-setup-and-use.xml

@@ -867,6 +867,12 @@
                     CPU usage, and disk I/O.
                     </para></listitem>
             </itemizedlist>
+        </para>
+
+        <section id='web-interface-videos'>
+            <title>Toaster Web Interface Videos</title>
+
+            <para>
                 Following are several videos that show how to use the Toaster GUI:
                 <itemizedlist>
                     <listitem><para><emphasis>Build Configuration:</emphasis>
@@ -921,6 +927,55 @@
             </para>
         </section>
 
+        <section id='toaster-web-interface-preferred-version'>
+            <title>Building a Specific Recipe Given Multiple Versions</title>
+
+            <para>
+                Occasionally, a layer might provide more than one version of
+                the same recipe.
+                For example, the <filename>openembedded-core</filename> layer
+                provides two versions of the <filename>bash</filename> recipe
+                (i.e. 3.2.48 and 4.3.30-r0) and two versions of the
+                <filename>which</filename> recipe (i.e. 2.21 and 2.18).
+                The following figure shows this exact scenario:
+                <imagedata fileref="figures/bash-oecore.png" align="center" width="9in" depth="6in" />
+            </para>
+
+            <para>
+                By default, the OpenEmbedded build system builds one of the
+                two recipes.
+                For the <filename>bash</filename> case, version 4.3.30-r0 is
+                built by default.
+                Unfortunately, Toaster as it exists, is not able to override
+                the default recipe version.
+                If you would like to build bash 3.2.48, you need to set the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
+                variable.
+                You can do so from Toaster, using the "Add variable" form,
+                which is available in the "BitBake variables" page of the
+                project configuration section as shown in the following screen:
+                <imagedata fileref="figures/add-variable.png" align="center" width="9in" depth="6in" />
+            </para>
+
+            <para>
+                To specify <filename>bash</filename> 3.2.48 as the version to build,
+                enter "PREFERRED_VERSION_bash" in the "Variable" field, and "3.2.48"
+                in the "Value" field.
+                Next, click the "Add variable" button:
+                <imagedata fileref="figures/set-variable.png" align="center" width="9in" depth="6in" />
+            </para>
+
+            <para>
+                After clicking the "Add variable" button, the settings for
+                <filename>PREFERRED_VERSION</filename> are added to the bottom
+                of the BitBake variables list.
+                With these settings, the OpenEmbedded build system builds the
+                desired version of the recipe rather than the default version:
+                <imagedata fileref="figures/variable-added.png" align="center" width="9in" depth="6in" />
+            </para>
+        </section>
+    </section>
+
 <!--
         <section id='toaster-gui-vids-1'>
             <title>Toaster Homepage and Table Controls</title>