ref-manual: Rewrite of "Image Generation" and devtool text.

Rewrite of devtool reference section. This was a separate commit
but got squashed wrong so it ended up with this commit.

The changes to "Image Generation" section reflect the new, more
detailed image generation figure

(From yocto-docs rev: 827c6872b88c17d2d0c8d44b1024fff19076e505)

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

2 files changed, 250 insertions, 38 deletions

diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index ec11824a56..f82a489fac 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -2113,6 +2113,55 @@
             </para>
         </section>
 
+        <section id='devtool-extracting-the-source-for-an-existing-recipe'>
+            <title>Extracting the Source for an Existing Recipe</title>
+
+            <para>
+                Use the <filename>devtool extract</filename> command to
+                extract the source for an existing recipe.
+                When you use this command, you must supply the root name
+                of the recipe (i.e. no version, paths, or extensions), and
+                you must supply the directory to which you want the source
+                extracted.
+            </para>
+
+            <para>
+                Additional command options let you control the name of a
+                development branch into which you can checkout the source
+                and whether or not to keep a temporary directory, which is
+                useful for debugging.
+                <note>
+                    For complete syntax, use the
+                    <filename>devtool extract --help</filename> command.
+                </note>
+            </para>
+        </section>
+
+        <section id='devtool-synchronizing-a-recipes-extracted-source-tree'>
+            <title>Synchronizing a Recipe's Extracted Source Tree</title>
+
+            <para>
+                Use the <filename>devtool sync</filename> command to
+                synchronize a previously extracted source tree for an
+                existing recipe.
+                When you use this command, you must supply the root name
+                of the recipe (i.e. no version, paths, or extensions), and
+                you must supply the directory to which you want the source
+                extracted.
+            </para>
+
+            <para>
+                Additional command options let you control the name of a
+                development branch into which you can checkout the source
+                and whether or not to keep a temporary directory, which is
+                useful for debugging.
+                <note>
+                    For complete syntax, use the
+                    <filename>devtool sync --help</filename> command.
+                </note>
+            </para>
+        </section>
+
         <section id='devtool-modifying-a-recipe'>
             <title>Modifying an Existing Recipe</title>
 
@@ -2146,6 +2195,33 @@
             </para>
         </section>
 
+        <section id='devtool-edit-an-existing-recipe'>
+            <title>Edit an Existing Recipe</title>
+
+            <para>
+                Use the <filename>devtool edit-recipe</filename> command
+                to run the default editor, which is identified using the
+                <filename>EDITOR</filename> variable, on the specified recipe.
+            </para>
+
+            <para>
+                When you use the <filename>devtool edit-recipe</filename>
+                command, you must supply the root name of the recipe
+                (i.e. no version, paths, or extensions).
+                Also, the recipe file itself must reside in the workspace
+                as a result of the <filename>devtool add</filename> or
+                <filename>devtool upgrade</filename> commands.
+                However, you can override that requirement by using the
+                "-a" or "--any-recipe" option.
+                Using either of these options allows you to edit any recipe
+                regardless of its location.
+                <note>
+                    For complete syntax, use the
+                    <filename>devtool edit-recipe --help</filename> command.
+                </note>
+            </para>
+        </section>
+
         <section id='devtool-updating-a-recipe'>
             <title>Updating a Recipe</title>
 
@@ -2199,6 +2275,36 @@
             </para>
         </section>
 
+        <section id='devtool-upgrading-a-recipe'>
+            <title>Upgrading a Recipe</title>
+
+            <para>
+                Use the <filename>devtool upgrade</filename> command
+                to upgrade an existing recipe to a new upstream version.
+                The command puts the upgraded recipe file into the
+                workspace along with any associated files, and extracts
+                the source tree to a specified location should patches
+                need rebased or added to as a result of the upgrade.
+            </para>
+
+            <para>
+                When you use the <filename>devtool upgrade</filename> command,
+                you must supply the root name of the recipe (i.e. no version,
+                paths, or extensions), and you must supply the directory
+                to which you want the source extracted.
+                Additional command options let you control things such as
+                the version number to which you want to upgrade (i.e. the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>),
+                the source revision to which you want to upgrade (i.e. the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>,
+                whether or not to apply patches, and so forth.
+                <note>
+                    For complete syntax, use the
+                    <filename>devtool upgrade --help</filename> command.
+                </note>
+            </para>
+        </section>
+
         <section id='devtool-resetting-a-recipe'>
             <title>Resetting a Recipe</title>
 
@@ -2227,15 +2333,22 @@
             </para>
         </section>
 
-        <section id='devtool-building-your-software'>
-            <title>Building Your Software</title>
+        <section id='devtool-building-your-recipe'>
+            <title>Building Your Recipe</title>
 
             <para>
                 Use the <filename>devtool build</filename> command to cause the
-                OpenEmbedded build system to build your software based
-                on the recipe file.
+                OpenEmbedded build system to build your recipe.
                 The <filename>devtool build</filename> command is equivalent to
                 <filename>bitbake -c populate_sysroot</filename>.
+            </para>
+
+            <para>
+                When you use the <filename>devtool build</filename> command,
+                you must supply the root name of the recipe (i.e. no version,
+                paths, or extensions).
+                You can use either the "-s" or the "--disable-parallel-make"
+                option to disable parallel makes during the build.
                 Here is an example:
                 <literallayout class='monospaced'>
      $ devtool build <replaceable>recipe</replaceable>
@@ -2244,8 +2357,25 @@
                     For complete syntax, use the
                     <filename>devtool build --help</filename> command.
                 </note>
-                Building your software using <filename>devtool build</filename>
-                is identical to using BitBake to build the software.
+            </para>
+        </section>
+
+        <section id='devtool-building-your-image'>
+            <title>Building Your Image</title>
+
+            <para>
+                Use the <filename>devtool build-image</filename> command
+                to build an image, extending it to include packages from
+                recipes in the workspace.
+            </para>
+
+            <para>
+                When you use the <filename>devtool build-image</filename>
+                command, you must supply the name of the image.
+                This command has no command line options:
+                <literallayout class='monospaced'>
+     $ devtool build-image <replaceable>image</replaceable>
+                </literallayout>
             </para>
         </section>
 
@@ -2345,6 +2475,49 @@
                 </literallayout>
             </para>
         </section>
+
+        <section id='devtool-get-the-status-of-the-recipes-in-your-workspace'>
+            <title>Get the Status of the Recipes in Your Workspace</title>
+
+            <para>
+                Use the <filename>devtool status</filename> command to
+                list the recipes currently in your workspace.
+                Information includes the paths to their respective
+                external source trees.
+            </para>
+
+            <para>
+                The <filename>devtool status</filename> command has no
+                command-line options:
+                <literallayout class='monospaced'>
+     devtool status
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='devtool-search-for-available-target-recipes'>
+            <title>Search for Available Target Recipes</title>
+
+            <para>
+                Use the <filename>devtool search</filename> command to
+                search for available target recipes.
+                The command matches the recipe name, package name,
+                description, and installed files.
+                The command displays the recipe name as a result of a
+                match.
+            </para>
+
+            <para>
+                When you use the <filename>devtool search</filename> command,
+                you must supply a <replaceable>keyword</replaceable>.
+                The command uses the <replaceable>keyword</replaceable> when
+                searching for a match.
+                <note>
+                    For complete syntax, use the
+                    <filename>devtool search --help</filename> command.
+                </note>
+            </para>
+        </section>
     </section>
 
     <section id="using-a-quilt-workflow">
diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index bb7624c9e8..c05972e9ec 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@@ -993,11 +993,13 @@
 
             <para>
                 The image generation process consists of several stages and
-                depends on many variables.
+                depends on several tasks and variables.
                 The
                 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
-                task uses these key variables
-                to help create the list of packages to actually install:
+                task creates the root filesystem (file and directory structure)
+                for an image.
+                This task uses several key variables to help create the list
+                of packages to actually install:
                 <itemizedlist>
                     <listitem><para><link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>:
                         Lists out the base set of packages to install from
@@ -1017,23 +1019,34 @@
                         Determines the language(s) for which additional
                         language support packages are installed.
                         </para></listitem>
+                    <listitem><para><link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>:
+                        The final list of packages passed to the package manager
+                        for installation into the image.
+                        </para></listitem>
                 </itemizedlist>
             </para>
 
             <para>
+                With
+                <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
+                pointing to the location of the filesystem under construction and
+                the <filename>PACKAGE_INSTALL</filename> variable providing the
+                final list of packages to install, the root file system is
+                created.
+            </para>
+
+            <para>
                 Package installation is under control of the package manager
                 (e.g. smart/rpm, opkg, or apt/dpkg) regardless of whether or
                 not package management is enabled for the target.
                 At the end of the process, if package management is not
                 enabled for the target, the package manager's data files
                 are deleted from the root filesystem.
-            </para>
-
-            <para>
-                During image generation, the build system attempts to run
-                all post-installation scripts.
-                Any that fail to run on the build host are run on the
-                target when the target system is first booted.
+                As part of the final stage of package installation, postinstall
+                scripts that are part of the packages are run.
+                Any scripts that fail to run
+                on the build host are run on the target when the target system
+                is first booted.
                 If you are using a
                 <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>,
                 all the post installation scripts must succeed during the
@@ -1042,24 +1055,17 @@
             </para>
 
             <para>
-                During Optimization, optimizing processes are run across
-                the image.
-                These processes include <filename>mklibs</filename> and
-                <filename>prelink</filename>.
-                The <filename>mklibs</filename> process optimizes the size
-                of the libraries.
-                A <filename>prelink</filename> process optimizes the dynamic
-                linking of shared libraries to reduce start up time of
-                executables.
+                The final stages of the <filename>do_rootfs</filename> task
+                handle post processing.
+                Post processing includes creation of a manifest file and
+                optimizations.
             </para>
 
             <para>
-                Along with writing out the root filesystem image, the
-                <filename>do_rootfs</filename> task creates a manifest file
-                (<filename>.manifest</filename>) in the same directory as
-                the root filesystem image that lists out, line-by-line, the
-                installed packages.
-                This manifest file is useful for the
+                The manifest file (<filename>.manifest</filename>) resides
+                in the same directory as the root filesystem image.
+                This file lists out, line-by-line, the installed packages.
+                The manifest file is useful for the
                 <link linkend='ref-classes-testimage*'><filename>testimage</filename></link>
                 class, for example, to determine whether or not to run
                 specific tests.
@@ -1069,21 +1075,54 @@
             </para>
 
             <para>
-                Part of the image generation process includes compressing the
-                root filesystem image.
-                Compression is accomplished through several optimization
-                routines designed to reduce the overall size of the image.
+                Optimizing processes run across the image include
+                <filename>mklibs</filename>, <filename>prelink</filename>,
+                and any other post-processing commands as defined by the
+                <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>
+                variable.
+                The <filename>mklibs</filename> process optimizes the size
+                of the libraries, while the
+                <filename>prelink</filename> process optimizes the dynamic
+                linking of shared libraries to reduce start up time of
+                executables.
+            </para>
+
+            <para>
+                After the root filesystem is built, processing begins on
+                the image through the <filename>do_image</filename> task.
+                The build system runs any pre-processing commands as defined
+                by the
+                <link linkend='var-IMAGE_PREPROCESS_COMMAND'><filename>IMAGE_PREPROCESS_COMMAND</filename></link>
+                variable.
+                This variable specifies a list of functions to call before
+                the OpenEmbedded build system creates the final image output
+                files.
             </para>
 
             <para>
-                After the root filesystem has been constructed, the image
-                generation process turns everything into an image file or
-                a set of image files.
+                The <filename>do_image</filename> task dynamically creates
+                other <filename>do_image_*</filename> tasks as needed, which
+                include compressing the root filesystem image to reduce the
+                overall size of the image.
+                The process turns everything into an image file or a set of
+                image files.
                 The formats used for the root filesystem depend on the
                 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
                 variable.
             </para>
 
+            <para>
+                The final task involved in image creation is the
+                <filename>do_image_complete</filename> task.
+                This task completes the image by applying any image
+                post processing as defined through the
+                <link linkend='var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></link>
+                variable.
+                The variable specifies a list of functions to call once the
+                OpenEmbedded build system has created the final image output
+                files.
+            </para>
+
             <note>
                 The entire image generation process is run under Pseudo.
                 Running under Pseudo ensures that the files in the root