dev-manual: Applied review edits to devtool section.

(From yocto-docs rev: 2b04710ccb1c63c4dafc2abbb79f5a7feddf43e9)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 108 insertions, 117 deletions

diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 9c549d7464..6e0ded2f17 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1721,44 +1721,17 @@
                     section.
                 </para>
             </footnote>
-            <note>
-                The workflow considers the entire build process for the
-                image and not just modification of the external source
-                code.
-            </note>
         </para>
 
-        <section id='establish-the-reference-image'>
-            <title>Establish the Reference Image</title>
-
-            <para>
-                The steps to clone the <filename>poky</filename> Git
-                repository, build out an image, and test it using QEMU
-                are well documented as follows:
-                <itemizedlist>
-                    <listitem><para>
-                        For information on how to set up a local copy of the
-                        <filename>poky</filename> repository and on how to
-                        build a Yocto Project image, see the
-                        "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
-                        section in the Yocto Project Quick Start.
-                        </para></listitem>
-                    <listitem><para>
-                        For information on how to test an image using QEMU, see
-                        the
-                        "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>"
-                        section.
-                        </para></listitem>
-                </itemizedlist>
-            </para>
-
-            <para>
-                Before you start making modifications to your project's
-                source code, you should be sure you have the appropriate
-                local repositories and have a base image built using
-                BitBake that you can run on QEMU.
-            </para>
-        </section>
+        <para>
+            The steps in this section assume 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.
+        </para>
 
         <section id='update-your-external-source'>
             <title>Update Your External Source</title>
@@ -1806,18 +1779,12 @@
                 <literallayout class='monospaced'>
      $ devtool add <replaceable>your-project-name</replaceable>&nbsp;<replaceable>path-to-source</replaceable>
                 </literallayout>
-                Running <filename>devtool add</filename> modifies the
-                <filename>bblayers.conf</filename> that the
-                OpenEmbedded build system uses to build an image.
-                For more information on the <filename>bblayers.conf</filename>,
-                see the
-                "<ulink url='&YOCTO_DOCS_REF_URL;#structure-build-conf-bblayers.conf'><filename>build/conf/bblayers.conf</filename></ulink>"
-                section in the Yocto Project Reference Manual.
             </para>
 
             <para>
-                Running <filename>devtool add</filename> adds a new workspace
-                layer to the <filename>bblayers.conf</filename> file that
+                Running <filename>devtool</filename> for the first time
+                creates a workspace layer through the
+                <filename>bblayers.conf</filename> file that
                 is based on your project's location:
                 <literallayout class='monospaced'>
      <replaceable>path-to-source</replaceable>/<replaceable>build-directory</replaceable>/<replaceable>workspace-layer</replaceable>
@@ -1918,6 +1885,7 @@
             </para>
         </section>
 
+<!--
         <section id='dev-build-the-image'>
             <title>Build the Image</title>
 
@@ -1946,6 +1914,7 @@
                 section.
             </para>
         </section>
+-->
     </section>
 
     <section id='devtool-quick-reference'>
@@ -2003,7 +1972,8 @@
                 name and using <filename>--help</filename>:
                 <literallayout class='monospaced'>
      $ devtool add --help
-     usage: devtool add [-h] [--same-dir] [--version VERSION] recipename srctree
+     usage: devtool add [-h] [--same-dir] [--fetch URI] [--version VERSION]
+                        recipename srctree
 
      Adds a new recipe
 
@@ -2013,9 +1983,11 @@
 
      optional arguments:
        -h, --help            show this help message and exit
-       --same-dir, -s        Build in same directory as source (default: False)
+       --same-dir, -s        Build in same directory as source
+       --fetch URI, -f URI   Fetch the specified URI and extract it to create the
+                             source tree
        --version VERSION, -V VERSION
-                             Version to use within recipe (PV) (default: None)
+                             Version to use within recipe (PV)
                 </literallayout>
             </para>
         </section>
@@ -2034,11 +2006,11 @@
 
             <para>
                 The following example creates and adds a new recipe named
-                <filename>jackson-2.0</filename> to the workspace layer.
+                <filename>jackson</filename> to the workspace layer.
                 The source code built by the recipes resides in
                 <filename>/home/scottrif/sources/jackson</filename>:
                 <literallayout class='monospaced'>
-     $ devtool add jackson-2.0 /home/scottrif/sources/jackson
+     $ devtool add jackson /home/scottrif/sources/jackson
                 </literallayout>
                 <note>
                     For complete syntax, use the
@@ -2082,44 +2054,8 @@
             </para>
         </section>
 
-        <section id='devtool-creating-the-workspace'>
-            <title>Creating the Workspace Layer</title>
-
-            <para>
-                Use the <filename>devtool create-workspace</filename> command to
-                create a new workspace layer in your
-                <link linkend='build-directory'>Build Directory</link>.
-                When you create a new workspace layer, it is populated with the
-                <filename>README</filename> file and the
-                <filename>conf</filename> directory only.
-            </para>
-
-            <para>
-                The following example creates a new workspace layer in your
-                current working and by default names the workspace layer
-                "workspace":
-                <literallayout class='monospaced'>
-     $ devtool create-workspace
-                </literallayout>
-                <note>
-                    For complete syntax, use the
-                    <filename>devtool create-workspace --help</filename> command.
-                </note>
-            </para>
-
-            <para>
-                You can create a workspace layer anywhere by supplying
-                a pathname with the command.
-                The following command creates a new workspace layer named
-                "new-workspace":
-                <literallayout class='monospaced'>
-     $ devtool create-workspace /home/scottrif/new-workspace
-                </literallayout>
-            </para>
-        </section>
-
         <section id='devtool-modifying-a-recipe'>
-            <title>Modifying a Recipe</title>
+            <title>Modifying an Existing Recipe</title>
 
             <para>
                 Use the <filename>devtool modify</filename> command to begin
@@ -2144,18 +2080,62 @@
                 </literallayout>
                 Using the above command form, the default development branch
                 would be "devtool".
+                <note>
+                    For complete syntax, use the
+                    <filename>devtool modify --help</filename> command.
+                </note>
             </para>
+        </section>
+
+        <section id='devtool-updating-a-recipe'>
+            <title>Updating a Recipe</title>
 
             <para>
-                If you want to name a development branch, use the
-                <filename>-b</filename> option with the
-                <filename>-x</filename> option:
+                Use the <filename>devtool update-recipe</filename> command to
+                update your recipe with patches that reflect changes you make
+                to the source files.
+                For example, if you know you are going to work on some
+                code, you could first use the
+                <link linkend='devtool-modifying-a-recipe'><filename>devtool modify</filename></link>
+                command to extract the code and set up the workspace.
+                After which, you could modify, compile, and test the code.
+            </para>
+
+            <para>
+                When you are satisfied with the results and you have committed
+                your changes to the Git repository, you can then
+                run the <filename>devtool update-recipe</filename> to create the
+                patches and update the recipe:
                 <literallayout class='monospaced'>
-     $ devtool modify -x -b <replaceable>branch</replaceable>&nbsp;<replaceable>recipe</replaceable>&nbsp;<replaceable>path-to-source</replaceable>
+     $ devtool update-recipe <replaceable>recipe</replaceable>
                 </literallayout>
+                If you run the <filename>devtool update-recipe</filename>
+                without committing your changes, the command ignores the
+                changes.
+             </para>
+
+             <para>
+                 Often, you might want to apply customizations made to your
+                 software in your own layer rather than apply them to the
+                 original recipe.
+                 If so, you can use the
+                 <filename>-a</filename> or <filename>--append</filename>
+                 option with the <filename>devtool update-recipe</filename>
+                 command.
+                 These options allow you to specify the layer into which to
+                 write an append file:
+                 <literallayout class='monospaced'>
+     $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable>
+                 </literallayout>
+                 The <filename>*.bbappend</filename> file is created at the
+                 appropriate path within the specified layer directory, which
+                 may or may not be in your <filename>bblayers.conf</filename>
+                 file.
+                 If an append file already exists, the command updates it
+                 appropriately.
                 <note>
                     For complete syntax, use the
-                    <filename>devtool modify --help</filename> command.
+                    <filename>devtool update-recipe --help</filename> command.
                 </note>
             </para>
         </section>
@@ -2188,31 +2168,6 @@
             </para>
         </section>
 
-        <section id='devtool-updating-a-recipe'>
-            <title>Updating a Recipe</title>
-
-            <para>
-                Use the <filename>devtool update-recipe</filename> command to
-                update your recipe with patches that reflect changes you make
-                to the source files.
-                For example, if you know you are going to work on some
-                code, you could first use the
-                <link linkend='devtool-modifying-a-recipe'><filename>devtool modify</filename></link>
-                command to extract the code and set up the workspace.
-                After which, you could modify, compile, and test the code.
-                When you are satisfied with the results you can then
-                run the <filename>devtool update-recipe</filename> to create the
-                patches and update the recipe:
-                <literallayout class='monospaced'>
-     $ devtool update-recipe <replaceable>recipe</replaceable>
-                </literallayout>
-                <note>
-                    For complete syntax, use the
-                    <filename>devtool update-recipe --help</filename> command.
-                </note>
-            </para>
-        </section>
-
         <section id='devtool-building-your-software'>
             <title>Building Your Software</title>
 
@@ -2295,6 +2250,42 @@
                 </note>
             </para>
         </section>
+
+        <section id='devtool-creating-the-workspace'>
+            <title>Creating the Workspace Layer in an Alternative Location</title>
+
+            <para>
+                Use the <filename>devtool create-workspace</filename> command to
+                create a new workspace layer in your
+                <link linkend='build-directory'>Build Directory</link>.
+                When you create a new workspace layer, it is populated with the
+                <filename>README</filename> file and the
+                <filename>conf</filename> directory only.
+            </para>
+
+            <para>
+                The following example creates a new workspace layer in your
+                current working and by default names the workspace layer
+                "workspace":
+                <literallayout class='monospaced'>
+     $ devtool create-workspace
+                </literallayout>
+                <note>
+                    For complete syntax, use the
+                    <filename>devtool create-workspace --help</filename> command.
+                </note>
+            </para>
+
+            <para>
+                You can create a workspace layer anywhere by supplying
+                a pathname with the command.
+                The following command creates a new workspace layer named
+                "new-workspace":
+                <literallayout class='monospaced'>
+     $ devtool create-workspace /home/scottrif/new-workspace
+                </literallayout>
+            </para>
+        </section>
     </section>
 
     <section id="using-a-quilt-workflow">