[gnome-continuous-yocto/gnomeostree-3.28-rocko: 2645/8267] sdk-manual: Updated SDK workflow

[Emmanuele Bassi <ebassi src gnome org>]

commit aba386b92cb1bd926a69f703587b133363374dee
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Tue Sep 13 18:05:31 2016 -0700

    sdk-manual: Updated SDK workflow
    
    A new command devtool finish has superceded the final commands
    in the SDK workflow.  I updated the two figures (add and modify)
    to reflect this new flow.  I also updated the ordered number list
    to match reality.
    
    (From yocto-docs rev: 0ba31e730cd748d06eab8d46b38764cda5c4e3bd)
    
    Signed-off-by: Scott Rifenbark <srifenbark gmail com>
    Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>

 .../sdk-manual/figures/sdk-devtool-add-flow.png    |  Bin 179361 -> 177945 bytes
 .../sdk-manual/figures/sdk-devtool-modify-flow.png |  Bin 146467 -> 164192 bytes
 .../sdk-manual/sdk-appendix-customizing.xml        |   13 +-
 documentation/sdk-manual/sdk-extensible.xml        |  156 +++++++++++---------
 4 files changed, 96 insertions(+), 73 deletions(-)
---
diff --git a/documentation/sdk-manual/figures/sdk-devtool-add-flow.png 
b/documentation/sdk-manual/figures/sdk-devtool-add-flow.png
index c09e60e..985ac33 100644
Binary files a/documentation/sdk-manual/figures/sdk-devtool-add-flow.png and 
b/documentation/sdk-manual/figures/sdk-devtool-add-flow.png differ
diff --git a/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png 
b/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png
index cd06c01..fd684ff 100644
Binary files a/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png and 
b/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png differ
diff --git a/documentation/sdk-manual/sdk-appendix-customizing.xml 
b/documentation/sdk-manual/sdk-appendix-customizing.xml
index 0695707..e8a8b8c 100644
--- a/documentation/sdk-manual/sdk-appendix-customizing.xml
+++ b/documentation/sdk-manual/sdk-appendix-customizing.xml
@@ -384,12 +384,15 @@
 
     <para>
         You can explicitly control whether or not to include the toolchain
-        when you build and SDK by setting the
+        when you build an SDK by setting the
         <ulink 
url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink>
-        variable.
-        When you set this variable to "1", you cause the toolchain to be
-        included even when <filename>SDK_EXT_TYPE</filename> is set to
-        "minimal".
+        variable to "1".
+        In particular, it is useful to include the toolchain when you
+        have set <filename>SDK_EXT_TYPE</filename> to
+        "minimal", which by default, excludes the toolchain.
+        Also, it is helpful if you are building a small SDK for use with
+        an IDE, such as Eclipse, or some other tool where you do not want
+        to take extra steps to install a toolchain.
     </para>
 </section>
 </appendix>
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index 9b78862..8f64745 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -343,42 +343,40 @@
                     However, <filename>devtool</filename> does not provide a
                     specific command that allows you to do this.
                     </para></listitem>
-                <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>:
-                    Once you are satisfied with the recipe, if you have made
-                    any changes to the source tree that you want to have
-                    applied by the recipe, you need to generate patches
-                    from those changes.
-                    You do this before moving the recipe
-                    to its final layer and cleaning up the workspace area
-                    <filename>devtool</filename> uses.
-                    This optional step is especially relevant if you are
-                    using or adding third-party software.</para>
-                    <para>To convert commits created using Git to patch files,
-                    use the <filename>devtool update-recipe</filename> command.
+                <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, moves the new recipe to a more permanent
+                    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></para>
+
+                    <para>Part of the <filename>devtool finish</filename>
+                    command converts commits created using Git to patch files.
                     <note>
                         Any changes you want to turn into patches must be
                         committed to the Git repository in the source tree.
+                    </note></para>
+
+                    <para>As mentioned, the <filename>devtool finish</filename>
+                    command moves the final recipe to its permanent layer.
+                    </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>
-                    <literallayout class='monospaced'>
-     $ devtool update-recipe <replaceable>recipe</replaceable>
-                    </literallayout>
-                    </para></listitem>
-                <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>:
-                    Before cleaning up the workspace, you need to move the
-                    final recipe to its permanent layer.
-                    You must do this before using the
-                    <filename>devtool reset</filename> command if you want to
-                    retain the recipe.
-                    </para></listitem>
-                <listitem><para><emphasis>Reset the Recipe</emphasis>:
-                    As a final step, you can restore the state such that
-                    standard layers and the upstream source is used to build
-                    the recipe rather than data in the workspace.
-                    To reset the recipe, use the <filename>devtool reset</filename>
-                    command:
-                    <literallayout class='monospaced'>
-     $ devtool reset <replaceable>recipe</replaceable>
-                    </literallayout>
                     </para></listitem>
             </orderedlist>
         </para>
@@ -569,42 +567,43 @@
                     However, <filename>devtool</filename> does not provide a
                     specific command that allows you to do this.
                     </para></listitem>
-                <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>:
-                    After you have debugged your changes, you can
-                    use <filename>devtool update-recipe</filename> to
-                    generate patch files for all the commits you have
-                    made.
-                    <note>
-                        Patch files are generated only for changes
-                        you have committed.
-                    </note>
+                <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 and then resets the recipe so that the
+                    recipe is built normally rather than from the workspace.
                     <literallayout class='monospaced'>
-     $ devtool update-recipe <replaceable>recipe</replaceable>
-                    </literallayout>
-                    By default, the
-                    <filename>devtool update-recipe</filename> command
-                    creates the patch files in a folder named the same
-                    as the recipe beneath the folder in which the recipe
-                    resides, and updates the recipe's
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
-                    statement to point to the generated patch files.
+     $ devtool finish <replaceable>recipe layer</replaceable>
+                    </literallayout></para>
+
+                    <para>Part of the <filename>devtool finish</filename>
+                    command converts commits created using Git to patch files.
+                    <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
-                        "--append <replaceable>LAYERDIR</replaceable>"
-                        option to cause the command to create append files
-                        in a specific layer rather than the default
-                        recipe layer.
+                        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>
-                <listitem><para><emphasis>Restore the Workspace</emphasis>:
-                    The <filename>devtool reset</filename> restores the
-                    state so that standard layers and upstream sources are
-                    used to build the recipe rather than what is in the
-                    workspace.
-                    <literallayout class='monospaced'>
-     $ devtool reset <replaceable>recipe</replaceable>
-                    </literallayout>
-                    </para></listitem>
             </orderedlist>
         </para>
     </section>
@@ -641,8 +640,7 @@
                 Binary package (i.e. "-b" option)
                 </para></listitem>
             <listitem><para>
-                Node.js module through
-                <filename>npm</filename>
+                Node.js module
                 </para></listitem>
             <listitem><para>
                 Python modules that use <filename>setuptools</filename>
@@ -921,8 +919,15 @@
         <title>Adding Node.js Modules</title>
 
         <para>
-            You can use the <filename>devtool add</filename> command in the
-            following form to add Node.js modules:
+            You can use the <filename>devtool add</filename> command two
+            different ways to add Node.js modules: 1) Through
+            <filename>npm</filename> and, 2) from a repository or local
+            source.
+        </para>
+
+        <para>
+            Use the following form to add Node.js modules through
+            <filename>npm</filename>:
             <literallayout class='monospaced'>
      $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
             </literallayout>
@@ -955,6 +960,21 @@
                 </itemizedlist>
             </note>
         </para>
+
+        <para>
+            As mentioned earlier, you can also add Node.js modules
+            directly from a repository or local source tree.
+            To add modules this way, use <filename>devtool add</filename> in
+            the following form:
+            <literallayout class='monospaced'>
+     $ devtool add https://github.com/diversario/node-ssdp
+            </literallayout>
+            In this example, <filename>devtool</filename> fetches the specified
+            Git repository, detects that the code is Node.js code, fetches
+            dependencies using <filename>npm</filename>, and sets
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+            accordingly.
+        </para>
     </section>
 </section>