dev-manual: Added section for devtool modify flow

New figure and some writer notes for now

(From yocto-docs rev: 0a627626f5f353e514b0225b468b0bd0fa3ceef3)

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

1 files changed, 275 insertions, 0 deletions

diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index d3fadbd1f7..b07b6c96c9 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1952,6 +1952,281 @@
                 </orderedlist>
             </para>
         </section>
+
+        <section id='devtool-use-devtool-modify-to-enable-work-on-code-associated-with-an-existing-recipe'>
+            <title>Use <filename>devtool modify</filename> to Enable Work on Code Associated with an Existing Recipe</title>
+
+            <para>
+                The <filename>devtool modify</filename> command prepares the
+                way to work on existing code that already has a recipe in
+                place.
+                The command is flexible enough to allow you to extract code,
+                specify the existing recipe, and keep track of and gather any
+                patch files from other developers that are
+                associated with the code.
+            </para>
+
+            <para>
+                Depending on your particular scenario, the arguments and options
+                you use with <filename>devtool modify</filename> form different
+                combinations.
+                The following diagram shows common development flows
+                you would use with the <filename>devtool modify</filename>
+                command:
+            </para>
+
+            <para>
+                <imagedata fileref="figures/devtool-modify-flow.png" align="center" />
+            </para>
+
+            <para>
+                <orderedlist>
+                    <listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
+                        The top part of the flow shows three scenarios by which
+                        you could use <filename>devtool modify</filename> to
+                        prepare to work on source files.
+                        Each scenario assumes the following:
+                        <itemizedlist>
+                            <listitem><para>The recipe exists in some layer external
+                                to the <filename>devtool</filename> workspace.
+                                </para></listitem>
+                            <listitem><para>The source files exist in a Git
+                                structure either upstream in an un-extracted
+                                state or locally in a previously extracted
+                                state.
+                                </para></listitem>
+                        </itemizedlist>
+                        The typical situation is where another developer has
+                        created some layer for use with the Yocto Project and
+                        their recipe already resides in that layer.
+                        Furthermore, their source code is readily available
+                        either upstream or locally.
+                        <itemizedlist>
+                            <listitem><para><emphasis>Left</emphasis>:
+                                The left scenario represents a situation
+                                where the source tree (srctree) exists as a
+                                previously extracted Git structure outside of
+                                the <filename>devtool</filename> workspace.
+                                In this example, the recipe also exists
+                                elsewhere in its own layer
+                                (i.e. <filename>meta-</filename><replaceable>layername</replaceable>).
+                                </para>
+
+                                <para>The following command tells
+                                <filename>devtool</filename> the recipe
+                                with which to work and uses
+                                <replaceable>srctree</replaceable> to point to the
+                                previously extracted source files:
+                                <literallayout class='monospaced'>
+     $ devtool modify <replaceable>recipe srctree</replaceable>
+                                </literallayout>
+                                Because <filename>devtool</filename> uses the
+                                <filename>conf/bblayers.conf</filename> to
+                                identify layers in which to look for recipes,
+                                you do not have to provide anything beyond a
+                                recipe's name with the command.
+                                In other words, you do not have to provide a
+                                full recipe pathname or provide any file naming
+                                extensions for <replaceable>recipe</replaceable>.
+                                </para>
+
+                                <para>Once the command finishes, it creates only
+                                an append file for the recipe in the workspace.
+                                The recipe and the source code remain in their
+                                original locations.
+                                </para></listitem>
+                            <listitem><para><emphasis>Middle</emphasis>:
+                                The middle scenario represents a situation where
+                                the source code does not exist locally.
+                                In this case, the code is in an upstream Git
+                                repository and needs to be extracted to some
+                                local area.
+                                The recipe, in this scenario, is again in its own
+                                layer outside the workspace.</para>
+
+                                <para>The following command tells
+                                <filename>devtool</filename> what recipe with
+                                which to work and also uses the "-x" option to
+                                instruct <filename>devtool</filename> to locate and
+                                extract the source code:
+                                <literallayout class='monospaced'>
+     $ devtool modify -x <replaceable>recipe srctree</replaceable>
+                                </literallayout>
+                                With the help of the
+                                <filename>conf/bblayers.conf</filename> file,
+                                <filename>devtool</filename>locates the recipe.
+                                Inside the recipe, the
+                                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                                variable points to where the source code and
+                                any local patch files from other developers are
+                                located.
+                                <note>
+                                    You cannot provide an URL for
+                                    <replaceable>srctree</replaceable> when using the
+                                    <filename>devtool modify</filename> command.
+                                </note>
+                                Once the files are located, the command extracts
+                                them to the location specified by
+                                <replaceable>srctree</replaceable>.</para>
+
+                                <para>Within workspace, <filename>devtool</filename>
+                                creates an append file for the recipe.
+                                The recipe remains in its original location but
+                                the source files are extracted to the location you
+                                provided with <replaceable>srctree</replaceable>.
+                                </para></listitem>
+                            <listitem><para><emphasis>Right</emphasis>:
+                                The right scenario represents another situation
+                                where the source code does not exist locally
+                                and again needs to be extracted.
+                                However, in this situation, you want to extract the
+                                source into the workspace.
+                                The recipe, in this scenario, is again in its own
+                                layer outside the workspace.</para>
+
+                                <para>The following command identifies the recipe
+                                and instructs <filename>devtool</filename> to
+                                extract the source files using the "-x" option:
+                                <literallayout class='monospaced'>
+     $ devtool modify -x <replaceable>recipe</replaceable>
+                                </literallayout>
+                                As with the previous example, the
+                                <filename>conf/bblayers.conf</filename> file
+                                helps locate the recipe.
+                                And, as with all extractions, the command uses
+                                the recipe's <filename>SRC_URI</filename> to locate the
+                                source files.
+                                With this scenario, however, since no
+                                <replaceable>srctree</replaceable> argument exists, the
+                                <filename>devtool modify</filename> command extracts the
+                                source files to a Git structure using the default
+                                location within the workspace.
+                                The result is that the command set up both the source
+                                code and an append file within the workspace with the
+                                recipe remaining in its original location.
+                                </para></listitem>
+                            </itemizedlist>
+                        </para></listitem>
+                    <listitem><para><emphasis>Edit the Source</emphasis>:
+                        Once you have used the <filename>devtool modify</filename>
+                        command, you are free to make changes to the source
+                        files.
+                        You can use any editor you like to make and save
+                        your source code modifications.
+                        </para></listitem>
+                    <listitem><para><emphasis>Build the Recipe</emphasis>:
+                        Once you have updated the source files, you can build
+                        the recipe.
+                        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>Test Your Changes</emphasis>:
+                        Once your code is built, you can test it for
+                        correct operation.
+                        If you have actual hardware, you can use the
+                        <filename>devtool deploy-target</filename> command
+                        to put the build output on the target.
+                        If you do not have target hardware, you can deploy
+                        the output to QEMU where it can emulate the hardware:
+                        <literallayout class='monospaced'>
+     $ devtool deploy-target <replaceable>recipe target</replaceable>
+                        </literallayout>
+                        Regardless of where you are deploying the build
+                        output, the <replaceable>target</replaceable> must
+                        be running an SSH server.
+                        For example, to run the <filename>dropbear</filename>
+                        SSH server in an image you are going to be running on
+                        QEMU, be sure this statement is in your
+                        <filename>conf/local.conf</filename> file:
+                        <literallayout class='monospaced'>
+     EXTRA_IMAGE_FEATURES += "ssh-server-dropbear"
+                        </literallayout>
+                        Here is a <filename>devtool deploy-target</filename>
+                        command example that uses the
+                        <filename>busybox</filename> recipe and QEMU as
+                        the target:
+                        <literallayout class='monospaced'>
+     $ devtool deploy-target busybox root@192.168.7.2
+                        </literallayout>
+                        <note>
+                            It is worth mentioning that you can load an image
+                            onto your <replaceable>target</replaceable> and
+                            while it is running, deploy your package build
+                            output to the target as the image is running.
+                            You can also rebuild your image using
+                            <filename>bitbake</filename> and it will pick up
+                            your new package output.
+                            From there, you could re-run the image on QEMU
+                            to see the effects of your
+                            <filename>devtool build</filename> output.
+                        </note>
+                        You can continue to change, build, and test your
+                        changes until you are satisfied with the code's
+                        behavior.
+                        </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>
+                        <literallayout class='monospaced'>
+     $ devtool update-recipe <replaceable>recipe</replaceable>
+                        </literallayout>
+                        By default, <filename>devtool</filename> updates
+                        the recipe's <filename>SRC_URI</filename> statement
+                        to include the location for the patch files it
+                        generates.
+                        <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.
+                        </note>
+                        The command also creates a <replaceable>recipe</replaceable>
+                        folder beneath the folder in which the recipe resides
+                        that contains the actual <filename>*.patch</filename>
+                        files.
+                        </para></listitem>
+                    <listitem><para><emphasis>Make Sure the Recipe is in the Final Layer</emphasis>:
+                        Strictly speaking, this step is not necessary if
+                        you begin this workflow with the recipe in its own
+                        proper layer outside of the <filename>devtool</filename>
+                        workspace.
+                        However, it is included here so that when you do the
+                        final step following this you do not lose the recipe
+                        should it be in the workspace, which is possible
+                        (e.g. starting with <filename>devtool add</filename> to
+                        create a recipe in the workspace).</para>
+
+                        <para>You should be sure that the recipe is located
+                        outside of the workspace before using the
+                        <filename>devtool reset</filename> command described in
+                        the next step.
+                        </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.
+                        Restoring the workspace removes all traces of the
+                        <replaceable>recipe</replaceable>.
+                        <literallayout class='monospaced'>
+     $ devtool reset <replaceable>recipe</replaceable>
+                        </literallayout>
+                        Once the workspace is restored, you can use it again for
+                        working on different code.
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
     </section>
 
     <section id='devtool-quick-reference'>