sdk-manual: Added the devtool upgrade command flow to the manual.

I needed a new figure and a new section.

(From yocto-docs rev: d413ca7b9b946450af7c2c15ab0e68e9181517e9)

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

2 files changed, 164 insertions, 0 deletions

diff --git a/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png b/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png
new file mode 100644
index 0000000000..65474dad02
--- /dev/null
+++ b/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index bb51683a44..67df1b0975 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -604,6 +604,170 @@
             </orderedlist>
         </para>
     </section>
+
+    <section id='sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>
+        <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
+
+        <para>
+            The <filename>devtool upgrade</filename> command updates
+            an existing recipe so that you can build it for an updated
+            set of source files.
+            The command is flexible enough to allow you to specify
+            source code revision and versioning schemes, extract code into
+            or out of the <filename>devtool</filename> workspace, and
+            work with any source file forms that the fetchers support.
+        </para>
+
+        <para>
+            Depending on your particular scenario, the arguments and options
+            you use with <filename>devtool upgrade</filename> form different
+            combinations.
+            The following diagram shows a common development flow
+            you would use with the <filename>devtool modify</filename>
+            command:
+        </para>
+
+        <para>
+            <imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" />
+        </para>
+
+        <para>
+            <orderedlist>
+                <listitem><para><emphasis>Initiate the Upgrade</emphasis>:
+                    The top part of the flow shows a typical scenario by which
+                    you could use <filename>devtool upgrade</filename>.
+                    The following conditions exist:
+                    <itemizedlist>
+                        <listitem><para>The recipe exists in some layer external
+                            to the <filename>devtool</filename> workspace.
+                            </para></listitem>
+                        <listitem><para>The source files for the new release
+                            exist adjacent to the same location pointed to by
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                            in the recipe (e.g. a tarball with the new version
+                            number in the name, or as a different revision in
+                            the upstream Git repository).
+                            </para></listitem>
+                    </itemizedlist>
+                    A common situation is where third-party software has
+                    undergone a revision so that it has been upgraded.
+                    The recipe you have access to is likely in your own layer.
+                    Thus, you need to upgrade the recipe to use the
+                    newer version of the software:
+                    <literallayout class='monospaced'>
+     $ devtool upgrade -V <replaceable>version recipe</replaceable>
+                    </literallayout>
+                    By default, the <filename>devtool upgrade</filename> command
+                    extracts source code into the <filename>sources</filename>
+                    directory in the workspace.
+                    If you want the code extracted to any other location, you
+                    need to provide the <replaceable>srctree</replaceable>
+                    positional argument with the command as follows:
+                    <literallayout class='monospaced'>
+     $ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
+                    </literallayout>
+                    Also, in this example, the "-V" option is used to specify
+                    the new version.
+                    If the source files pointed to by the
+                    <filename>SRC_URI</filename> statement in the recipe are
+                    in a Git repository, you must provide the "-S" option and
+                    specify a revision for the software.</para>
+
+                    <para>Once <filename>devtool</filename> locates the recipe,
+                    it uses the <filename>SRC_URI</filename> variable to locate
+                    the source code and any local patch files from other
+                    developers are located.
+                    The result is that the command sets up the source
+                    code, the new version of the recipe, and an append file
+                    all within the workspace.
+                    </para></listitem>
+                <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
+                    At this point, there could be some conflicts due to the
+                    software being upgraded to a new version.
+                    This would occur if your recipe specifies some patch files in
+                    <filename>SRC_URI</filename> that conflict with changes
+                    made in the new version of the software.
+                    If this is the case, you need to resolve the conflicts
+                    by editing the source and following the normal
+                    <filename>git rebase</filename> conflict resolution
+                    process.</para>
+                    <para>Before moving onto the next step, be sure to resolve any
+                    such conflicts created through use of a newer or different
+                    version of the software.
+                    </para></listitem>
+                <listitem><para><emphasis>Build the Recipe</emphasis>:
+                    Once you have your recipe in order, you can build it.
+                    You can either use <filename>devtool build</filename> or
+                    <filename>bitbake</filename>.
+                    Either method produces build output that is stored
+                    in
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
+                    </para></listitem>
+                <listitem><para><emphasis>Deploy the Build Output</emphasis>:
+                    When you use the <filename>devtool build</filename>
+                    command or <filename>bitbake</filename> to build out your
+                    recipe, you probably want to see if the resulting build
+                    output works as expected on target hardware.
+                    <note>
+                        This step assumes you have a previously built
+                        image that is already either running in QEMU or
+                        running on actual hardware.
+                        Also, it is assumed that for deployment of the image
+                        to the target, SSH is installed in the image and if
+                        the image is running on real hardware that you have
+                        network access to and from your development machine.
+                    </note>
+                    You can deploy your build output to that target hardware by
+                    using the <filename>devtool deploy-target</filename> command:
+                    <literallayout class='monospaced'>
+     $ devtool deploy-target <replaceable>recipe target</replaceable>
+                    </literallayout>
+                    The <replaceable>target</replaceable> is a live target machine
+                    running as an SSH server.</para>
+                    <para>You can, of course, also deploy the image you build
+                    using the <filename>devtool build-image</filename> command
+                    to actual hardware.
+                    However, <filename>devtool</filename> does not provide a
+                    specific command that allows you to do this.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Finish Your Work With the Recipe</emphasis>:
+                    The <filename>devtool finish</filename> command creates
+                    any patches corresponding to commits in the local
+                    Git repository, updates the recipe to point to them
+                    (or creates a <filename>.bbappend</filename> file to do
+                    so, depending on the specified destination layer), and
+                    then resets the recipe so that the recipe is built normally
+                    rather than from the workspace.
+                    <literallayout class='monospaced'>
+     $ devtool finish <replaceable>recipe layer</replaceable>
+                    </literallayout>
+                    <note>
+                        Any changes you want to turn into patches must be
+                        committed to the Git repository in the source tree.
+                    </note></para>
+                    <para>Because there is no need to move the recipe,
+                    <filename>devtool finish</filename> either updates the
+                    original recipe in the original layer or the command
+                    creates a <filename>.bbappend</filename> in a different
+                    layer as provided by <replaceable>layer</replaceable>.
+                    </para>
+                    <para>As a final process of the
+                    <filename>devtool finish</filename> command, the state
+                    of the standard layers and the upstream source is
+                    restored so that you can build the recipe from those
+                    areas rather than the workspace.
+                    <note>
+                        You can use the <filename>devtool reset</filename>
+                        command to put things back should you decide you
+                        do not want to proceed with your work.
+                        If you do use this command, realize that the source
+                        tree is preserved.
+                    </note>
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
 </section>
 
 <section id='sdk-a-closer-look-at-devtool-add'>