sdk-manual: WIP on the book.

(From yocto-docs rev: 140577dd1f91c096152354e711709efe64bbcd0e)

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

3 files changed, 998 insertions, 121 deletions

diff --git a/documentation/sdk-manual/sdk-appendix-obtain.xml b/documentation/sdk-manual/sdk-appendix-obtain.xml
index eada4cc8ed..8b245615c9 100644
--- a/documentation/sdk-manual/sdk-appendix-obtain.xml
+++ b/documentation/sdk-manual/sdk-appendix-obtain.xml
@@ -6,26 +6,210 @@
 
 <title>Obtaining the SDK</title>
 
-<section id='sdk-appendix-obtain-manual-development-notes'>
-    <title>Manual Development Notes for Scott and Paul</title>
+<section id='sdk-locating-pre-built-sdk-installers'>
+    <title>Locating Pre-Built SDK Installers</title>
 
-    <para role='writernotes'>
-        This chapter is going to cover details about the installed SDK and perhaps
-        stuff on locating it (e.g. the naming scheme used to identify the
-        <filename>.sh</filename> installation script.
+    <para>
+        You can use existing, pre-built toolchains by locating and running
+        an SDK installer script that ships with the Yocto Project.
+        Using this method, you select and download an architecture-specific
+        toolchain installer and then run the script to hand-install the
+        toolchain.
+    </para>
+
+    <para>
+        You can find SDK installers here:
+        <itemizedlist>
+            <listitem><para><emphasis>Standard SDK Installers</emphasis>
+                Go to <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>
+                and find the folder that matches your host development system
+                (i.e. <filename>i686</filename> for 32-bit machines or
+                <filename>x86_64</filename> for 64-bit machines).</para>
+
+                <para>Go into that folder and download the toolchain installer
+                whose name includes the appropriate target architecture.
+                The toolchains provided by the Yocto Project are based off of
+                the <filename>core-image-sato</filename> image and contain
+                libraries appropriate for developing against that image.
+                For example, if your host development system is a 64-bit x86
+                system and you are going to use your cross-toolchain for a
+                32-bit x86 target, go into the <filename>x86_64</filename>
+                folder and download the following installer:
+                <literallayout class='monospaced'>
+     poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
+                </literallayout>
+                </para></listitem>
+            <listitem><para><emphasis>Extensible SDK Installers</emphasis>
+                Installers for the extensible SDK are in
+                <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='sdk-optionally-building-a-toolchain-installer'>
+    <title>Optionally Building a Toolchain Installer</title>
+
+    <para>
+        As an alternative to locating and downloading a toolchain installer,
+        you can build the toolchain installer if you have a
+        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+        <note>
+            Although not the preferred method, it is also possible to use
+            <filename>bitbake meta-toolchain</filename> to build the toolchain
+            installer.
+            If you do use this method, you must separately install and extract
+            the target sysroot.
+            For information on how to install the sysroot, see the
+            "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"
+            section.
+        </note>
+    </para>
+
+    <para>
+        To build the toolchain installer for a standard SDK and populate
+        the SDK image, use the following command:
+        <literallayout class='monospaced'>
+     $ bitbake <replaceable>image</replaceable> -c populate_sdk
+        </literallayout>
+        You can do the same for the extensible SDK using this command:
+        <literallayout class='monospaced'>
+     $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext
+        </literallayout>
+        These commands result in a toolchain installer that contains the sysroot
+        that matches your target root filesystem.
+    </para>
+
+    <para>
+        Another powerful feature is that the toolchain is completely
+        self-contained.
+        The binaries are linked against their own copy of
+        <filename>libc</filename>, which results in no dependencies
+        on the target system.
+        To achieve this, the pointer to the dynamic loader is
+        configured at install time since that path cannot be dynamically
+        altered.
+        This is the reason for a wrapper around the
+        <filename>populate_sdk</filename> and
+        <filename>populate_sdk_ext</filename> archives.
     </para>
 
-    <para role='writernotes'>
-        The idea here is to gather all the current information in the regular
-        YP doc set that describes how to locate, download, or build out the SDK.
+    <para>
+        Another feature is that only one set of cross-canadian toolchain
+        binaries are produced per architecture.
+        This feature takes advantage of the fact that the target hardware can
+        be passed to <filename>gcc</filename> as a set of compiler options.
+        Those options are set up by the environment script and contained in
+        variables such as
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink>
+        and
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>.
+        This reduces the space needed for the tools.
+        Understand, however, that a sysroot is still needed for every target
+        since those binaries are target-specific.
+    </para>
+
+    <para>
+         Remember, before using any BitBake command, you
+         must source the build environment setup script
+         (i.e.
+         <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+         or
+         <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
+         located in the Source Directory and you must make sure your
+         <filename>conf/local.conf</filename> variables are correct.
+         In particular, you need to be sure the
+         <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+         variable matches the architecture for which you are building and that
+         the
+         <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
+         variable is correctly set if you are building a toolchain designed to
+         run on an architecture that differs from your current development host
+         machine (i.e. the build machine).
     </para>
 
-    <para role='writernotes'>
-        One thing that needs discussed is any differences between getting the
-        standard SDK as compared to the extended SDK.
-        Do we have pre-build extensible SDKs laying around?
-        Where do we get any pre-built SDKs from?
-        Show the methods by which the user builds out the SDK?
+    <para>
+        When the <filename>bitbake</filename> command completes, the toolchain
+        installer will be in
+        <filename>tmp/deploy/sdk</filename> in the Build Directory.
+        <note>
+            By default, this toolchain does not build static binaries.
+            If you want to use the toolchain to build these types of libraries,
+            you need to be sure your image has the appropriate static
+            development libraries.
+            Use the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
+            variable inside your <filename>local.conf</filename> file to
+            install the appropriate library packages.
+            Following is an example using <filename>glibc</filename> static
+            development libraries:
+            <literallayout class='monospaced'>
+     IMAGE_INSTALL_append = " glibc-staticdev"
+            </literallayout>
+        </note>
+    </para>
+</section>
+
+<section id='sdk-extracting-the-root-filesystem'>
+    <title>Extracting the Root Filesystem</title>
+
+    <para>
+        After installing the toolchain or building it using BitBake,
+        you need a root filesystem, which you need to separately extract.
+    </para>
+
+    <para>
+        Here are some cases where you need to extract the root filesystem:
+        <itemizedlist>
+            <listitem><para>You want to boot the image using NFS.
+                </para></listitem>
+            <listitem><para>You want to use the root filesystem as the
+                target sysroot.
+                For example, the Eclipse IDE environment with the Eclipse
+                Yocto Plug-in installed allows you to use QEMU to boot
+                under NFS.</para></listitem>
+            <listitem><para>You want to develop your target application
+                using the root filesystem as the target sysroot.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        To extract the root filesystem, first <filename>source</filename>
+        the cross-development environment setup script to establish
+        necessary environment variables.
+        If you built the toolchain in the Build Directory, you will find
+        the toolchain environment script in the
+        <filename>tmp</filename> directory.
+        If you installed the toolchain by hand, the environment setup
+        script is located in <filename>/opt/poky/&DISTRO;</filename>.
+    </para>
+
+    <para>
+        After sourcing the environment script, use the
+        <filename>runqemu-extract-sdk</filename> command and provide the
+        filesystem image.
+    </para>
+
+    <para>
+        Following is an example.
+        The second command sets up the environment.
+        In this case, the setup script is located in the
+        <filename>/opt/poky/&DISTRO;</filename> directory.
+        The third command extracts the root filesystem from a previously
+        built filesystem that is located in the
+        <filename>~/Downloads</filename> directory.
+        Furthermore, this command extracts the root filesystem into the
+        <filename>qemux86-sato</filename> directory:
+        <literallayout class='monospaced'>
+     $ cd ~
+     $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+     $ runqemu-extract-sdk \
+        ~/Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \
+        $HOME/qemux86-sato
+        </literallayout>
+        You could now point to the target sysroot at
+        <filename>qemux86-sato</filename>.
     </para>
 </section>
 
@@ -70,6 +254,48 @@
     </para>
 </section>
 
+<section id='sdk-installed-extensible-sdk-directory-structure'>
+    <title>Installed Extensible SDK Directory Structure</title>
+
+    <para>
+        The following figure shows the resulting directory structure after
+        you install the Extensible SDK by running the <filename>.sh</filename>
+        SDK installation script:
+    </para>
+
+    <para>
+        <imagedata fileref="figures/sdk-installed-extensible-sdk-directory.png" scale="60" align="center" />
+    </para>
+
+    <para>
+        The installed directory structure for the extensible SDK is quite
+        different than the installed structure for the standard SDK.
+        The extensible SDK does not separate host and target parts in the
+        same manner as does the standard SDK.
+        The extensible SDK uses an embedded copy of the build system, which
+        has its own sysroots.
+    </para>
+
+    <para>
+        Of note in the directory structure are an environment setup script
+        for the SDK, a configuration file for the target, a version file for
+        the target, and a log file for the build system preparation script run
+        by the installer.
+    </para>
+
+    <para>
+        Within the figure, italicized text is used to indicate replaceable
+        portions of the file or directory name.
+        For example,
+        <replaceable>install_dir</replaceable> is the directory where the SDK
+        is installed, which is <filename>poky_sdk</filename> by default.
+        <replaceable>target</replaceable> represents the target
+        architecture (e.g. <filename>i586</filename>) and
+        <replaceable>host</replaceable> represents the development system's
+        architecture (e.g. <filename>x86_64</filename>).
+    </para>
+</section>
+
 </appendix>
 <!--
 vim: expandtab tw=80 ts=4
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index c238dee382..bc9ccd28d3 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -6,69 +6,537 @@
 
 <title>Using the Extensible SDK</title>
 
-<para role='writernotes'>
-    This chapter describes what you need on your machine in order to use
-    an extensible SDK.
-    The chapter does not repeat information that also applies to using the
-    standard SDK.
-    The chapter also includes procedures of tasks you can perform using
-    an extensible SDK.
-    <note>
-        The tasks you can perform using a standard SDK are also available
-        using an extensible SDK.
-        For information on using the standard SDK, see the
-        "<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>"
-        chapter.
-    </note>
+<para>
+    This chapter describes the extensible SDK and how to use it.
+    The extensible SDK makes it easy to add new applications and libraries
+    to an image, modify the source for an existing component, test
+    changes on the target hardware, and ease integration into the rest
+    of the build system.
 </para>
 
+<para>
+    Information in this chapter covers features that are not part of the
+    standard SDK.
+    In other words, the chapter presents information unique to the
+    extensible SDK only.
+    For information on how to use the standard SDK, see the
+    "<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>"
+    chapter.
+</para>
 
 <section id='sdk-setting-up-to-use-the-extensible-sdk'>
     <title>Setting Up to Use the Extensible SDK</title>
 
-    <para role='writernotes'>
-        Here is a list of items I think need addressed in this section:
+    <para>
+        Getting set up to use the extensible SDK is identical to getting set
+        up to use the standard SDK.
+        You still need to locate and run the installer and then run the
+        environment setup script.
+        See the
+        "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
+        and the
+        "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>"
+        sections for general information.
+        The following items highlight the only differences between getting
+        set up to use the extensible SDK as compared to the standard SDK:
         <itemizedlist>
-            <listitem><para role='writernotes'><emphasis>Cover differences in the development
-                that might be impacted because they are using an extensible
-                SDK</emphasis></para>
-                <para role='writernotes'>Presumably, the various development scenarios are
-                covered regarding setup in the previous chapter.
-                Are these impacted because the developer is going to now be
-                using an extensible SDK?
-                If so, what are the implications?
+            <listitem><para><emphasis>Default Installation Directory:</emphasis>
+                By default, the extensible SDK installs into the
+                <filename>poky_sdk</filename> folder of your home directory.
+                As with the standard SDK, you can choose to install the
+                extensible SDK in any location when you run the installer.
                 </para></listitem>
-            <listitem><para role='writernotes'><emphasis>What new recommendations exist now that
-                the developer is going to be using an extensible SDK?</emphasis></para>
-                <para role='writernotes'>We should cover the most common development scenarios
-                that apply when using an extensible SDK.
-                Is there a recommended development flow we want to present
-                when using an extensible SDK?
-                What conditions in a development scenario warrant use of
-                the extensible SDK as compared to the standard SDK?
-                </para></listitem>
-            <listitem><para role='writernotes'><emphasis>What procedures do we want to cover to set
-                up the extensible SDK?</emphasis></para>
-                <para role='writernotes'>Is it just a matter of building out the SDK using
-                <filename>bitbake -c populate_sdk_ext</filename>?
-                Is there a pre-built extensible SDK laying around they can
-                find and download if they are using a machine that does not
-                have YP installed, which would prevent them from building their
-                own SDK?
+            <listitem><para><emphasis>Build Tools and Build System:</emphasis>
+                The extensible SDK installer performs additional tasks as
+                compared to the standard SDK installer.
+                The extensible SDK installer extracts build tools specific
+                to the SDK and the installer also prepares the build system.
+                Here is example output for running the extensible SDK
+                installer:
+                <literallayout class='monospaced'>
+     $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.1+snapshot.sh
+     Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.1+snapshot
+     ===================================================================================
+     Enter target directory for SDK (default: ~/poky_sdk):
+     You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
+     Extracting SDK......................................................................done
+     Setting it up...
+     Extracting buildtools...
+     Preparing build system...
+     done
+     SDK has been successfully set up and is ready to be used.
+     Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
+      $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
+                </literallayout>
                 </para></listitem>
         </itemizedlist>
     </para>
+
+    <para>
+        After installing the SDK, you need to run the SDK environment setup
+        script.
+        Here is the output:
+        <literallayout class='monospaced'>
+     $ source environment-setup-core2-64-poky-linux
+     SDK environment now set up; additionally you may now run devtool to perform development tasks.
+     Run devtool --help for further details.
+        </literallayout>
+        Once you run the environment setup script, you have
+        <filename>devtool</filename> available.
+    </para>
 </section>
 
-<section id='sdk-using-the-extensible-sdk-to-task-1'>
-    <title>Using the Extensible SDK to <replaceable>item 1</replaceable></title>
+<section id='sdk-use-devtool-to-add-an-application'>
+    <title>Use <filename>devtool add</filename> to Add an Application</title>
 
-    <para role='writernotes'>
-        Describe the specific task you are going to accomplish with the
-        extensible SDK.
-        Provide a diagram showing the rough flow of the task.
-        Provide specific steps using a real example that works through the
-        task.
+    <para>
+        The <filename>devtool add</filename> command generates
+        a new recipe based on existing source code.
+        This command takes advantage of the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
+        layer that many <filename>devtool</filename> commands
+        use.
+        The command is flexible enough to allow you to extract source
+        code into both the workspace or a separate local Git repository
+        and to use existing code that does not need to be extracted.
+    </para>
+
+    <para>
+        Depending on your particular scenario, the arguments and options
+        you use with <filename>devtool add</filename> form different
+        combinations.
+        The following diagram shows common development flows
+        you would use with the <filename>devtool add</filename>
+        command:
+    </para>
+
+    <para>
+        <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" />
+    </para>
+
+    <para>
+        <orderedlist>
+            <listitem><para><emphasis>Generating the New Recipe</emphasis>:
+                The top part of the flow shows three scenarios by which
+                you could use <filename>devtool add</filename> to
+                generate a recipe based on existing source code.</para>
+
+                <para>In a shared development environment, it is
+                typical where other developers are responsible for
+                various areas of source code.
+                As a developer, you are probably interested in using
+                that source code as part of your development using
+                the Yocto Project.
+                All you need is access to the code, a recipe, and a
+                controlled area in which to do your work.</para>
+
+                <para>Within the diagram, three possible scenarios
+                feed into the <filename>devtool add</filename> workflow:
+                <itemizedlist>
+                    <listitem><para><emphasis>Left</emphasis>:
+                        The left scenario represents a common situation
+                        where the source code does not exist locally
+                        and needs to be extracted.
+                        In this situation, you just let it get
+                        extracted to the default workspace - you do not
+                        want it in some specific location outside of the
+                        workspace.
+                        Thus, everything you need will be located in the
+                        workspace:
+                        <literallayout class='monospaced'>
+     $ devtool add <replaceable>recipe fetchuri</replaceable>
+                        </literallayout>
+                        With this command, <filename>devtool</filename>
+                        creates a recipe and an append file in the
+                        workspace as well as extracts the upstream
+                        source files into a local Git repository also
+                        within the <filename>sources</filename> folder.
+                        </para></listitem>
+                    <listitem><para><emphasis>Middle</emphasis>:
+                        The middle scenario also represents a situation where
+                        the source code does not exist locally.
+                        In this case, the code is again upstream
+                        and needs to be extracted to some
+                        local area - this time outside of the default
+                        workspace.
+                        As always, if required <filename>devtool</filename> creates
+                        a Git repository locally during the extraction.
+                        Furthermore, the first positional argument
+                        <replaceable>srctree</replaceable> in this case
+                        identifies where the
+                        <filename>devtool add</filename> command
+                        will locate the extracted code outside of the
+                        workspace:
+                        <literallayout class='monospaced'>
+     $ devtool add <replaceable>recipe srctree fetchuri</replaceable>
+                        </literallayout>
+                        In summary, the source code is pulled from
+                        <replaceable>fetchuri</replaceable> and extracted
+                        into the location defined by
+                        <replaceable>srctree</replaceable> as a local
+                        Git repository.</para>
+
+                        <para>Within workspace, <filename>devtool</filename>
+                        creates both the recipe and an append file
+                        for the recipe.
+                        </para></listitem>
+                    <listitem><para><emphasis>Right</emphasis>:
+                        The right scenario represents a situation
+                        where the source tree (srctree) has been
+                        previously prepared outside of the
+                        <filename>devtool</filename> workspace.
+                        </para>
+
+                        <para>The following command names the recipe
+                        and identifies where the existing source tree
+                        is located:
+                        <literallayout class='monospaced'>
+     $ devtool add <replaceable>recipe srctree</replaceable>
+                        </literallayout>
+                        The command examines the source code and creates
+                        a recipe for it placing the recipe into the
+                        workspace.</para>
+
+                        <para>Because the extracted source code already exists,
+                        <filename>devtool</filename> does not try to
+                        relocate it into the workspace - just the new
+                        the recipe is placed in the workspace.</para>
+
+                        <para>Aside from a recipe folder, the command
+                        also creates an append folder and places an initial
+                        <filename>*.bbappend</filename> within.
+                        </para></listitem>
+                </itemizedlist>
+                </para></listitem>
+            <listitem><para><emphasis>Edit the Recipe</emphasis>:
+                At this point, you can use <filename>devtool edit-recipe</filename>
+                to open up the editor as defined by the
+                <filename>$EDITOR</filename> environment variable
+                and modify the file:
+                <literallayout class='monospaced'>
+     $ devtool edit-recipe <replaceable>recipe</replaceable>
+                </literallayout>
+                From within the editor, you can make modifications to the
+                recipe that take affect when you build it later.
+                </para></listitem>
+            <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>:
+                At this point in the flow, the next step you
+                take depends on what you are going to do with
+                the new code.</para>
+                <para>If you need to take the build output and eventually
+                move it to the target hardware, you would use
+                <filename>devtool build</filename>:
+                <note>
+                    You could use <filename>bitbake</filename> to build
+                    the recipe as well.
+                </note>
+                <literallayout class='monospaced'>
+     $ devtool build <replaceable>recipe</replaceable>
+                </literallayout></para>
+                <para>On the other hand, if you want an image to
+                contain the recipe's packages for immediate deployment
+                onto a device (e.g. for testing purposes), you can use
+                the <filename>devtool build-image</filename> command:
+                <literallayout class='monospaced'>
+     $ devtool build-image <replaceable>image</replaceable>
+                </literallayout>
+                </para></listitem>
+            <listitem><para><emphasis>Deploy the Build Output</emphasis>:
+                When you use the <filename>devtool build</filename>
+                command 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>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.
+                <note>
+                    Any changes you want to turn into patches must be
+                    committed to the Git repository in the source tree.
+                </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>
+</section>
+
+<section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'>
+    <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</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/sdk-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 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 common situation
+                        where the source code does not exist locally
+                        and needs to be extracted.
+                        In this situation, the source is extracted
+                        into the default workspace location.
+                        The recipe, in this scenario, is in its own
+                        layer outside the workspace
+                        (i.e.
+                        <filename>meta-</filename><replaceable>layername</replaceable>).
+                        </para>
+
+                        <para>The following command identifies the recipe
+                        and by default extracts the source files:
+                        <literallayout class='monospaced'>
+     $ devtool modify <replaceable>recipe</replaceable>
+                        </literallayout>
+                        Once <filename>devtool</filename>locates the recipe,
+                        it uses the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                        variable to locate 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>
+                        With this scenario, however, since no
+                        <replaceable>srctree</replaceable> argument exists, the
+                        <filename>devtool modify</filename> command by default
+                        extracts the source files to a Git structure.
+                        Furthermore, the location for the extracted source is the
+                        default area within the workspace.
+                        The result is that the command sets up both the source
+                        code and an append file within the workspace with the
+                        recipe remaining in its original location.
+                        </para></listitem>
+                    <listitem><para><emphasis>Middle</emphasis>:
+                        The middle scenario represents a situation where
+                        the source code also does not exist locally.
+                        In this case, the code is again upstream
+                        and needs to be extracted to some
+                        local area as a Git repository.
+                        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, in this case, identifies a local
+                        area for the extracted source files that is outside
+                        of the default workspace:
+                        <literallayout class='monospaced'>
+     $ devtool modify <replaceable>recipe srctree</replaceable>
+                        </literallayout>
+                        As with all extractions, the command uses
+                        the recipe's <filename>SRC_URI</filename> to locate the
+                        source files.
+                        Once the files are located, the command by default
+                        extracts them.
+                        Providing the <replaceable>srctree</replaceable>
+                        argument instructs <filename>devtool</filename> where
+                        place the extracted source.</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 a situation
+                        where the source tree
+                        (<replaceable>srctree</replaceable>) 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.
+                        </para>
+
+                        <para>The following command tells
+                        <filename>devtool</filename> the recipe
+                        with which to work, uses the "-n" option to indicate
+                        source does not need to be extracted, and uses
+                        <replaceable>srctree</replaceable> to point to the
+                        previously extracted source files:
+                        <literallayout class='monospaced'>
+     $ devtool modify -n <replaceable>recipe srctree</replaceable>
+                        </literallayout>
+                        </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>
+                    </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>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>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, 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.
+                <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>
+                </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>
 
diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml
index 66f2c0ed9d..f2acaa7fc4 100644
--- a/documentation/sdk-manual/sdk-using.xml
+++ b/documentation/sdk-manual/sdk-using.xml
@@ -23,8 +23,9 @@
 <section id='sdk-standard-sdk-intro'>
     <title>Why use the Standard SDK and What is in It?</title>
 
-    <para role='writernotes'>
-        <emphasis>MANUAL DEVELOPMENT NOTES:</emphasis>
+    <para>
+        Fundamentally, the standard SDK exists so that you can access
+        cross-development tools.
         This paragraph describes why you use the Standard SDK.
         Probably need to compare that against why you would not be interested
         in the extensible SDK here as well.
@@ -37,46 +38,6 @@
         If there is more detail, I need to know about it.
     </para>
 
-    <para role='writernotes'>
-        <emphasis>MANUAL DEVELOPMENT NOTES:</emphasis>
-        Here is a list of items I think need addressed in these early
-        sections:
-        <itemizedlist>
-            <listitem><para role='writernotes'><emphasis>What is your situation?</emphasis></para>
-                <para role='writernotes'>In other words, is the developer on a machine that
-                has YP on it?
-                Are they on a machine that does not?
-                Is the image they are developing against available as a
-                pre-built, down-loadable image and can they get it?</para>
-                <para role='writernotes'>Depending on the scenario, there are different ways
-                to make sure the machine they are using is ready to use a
-                standard SDK.
-                I think we need to cover the various situations in this
-                section.
-                </para></listitem>
-            <listitem><para role='writernotes'><emphasis>What are the recommendations?</emphasis></para>
-                <para role='writernotes'>What is the most common development scenario?
-                Is there a recommended development flow we want to present
-                when using a standard SDK?
-                What conditions in a development scenario warrant use of
-                just the standard SDK as compared to the extensible SDK?
-                </para></listitem>
-            <listitem><para role='writernotes'><emphasis>What procedures do we want to cover to set up
-                the standard SDK?</emphasis></para>
-                <para role='writernotes'>There is a ton of setup information in the
-                current ADT manual regarding getting, building, and installing
-                an SDK.
-                We would ignore the stuff about the ADT installer script
-                since I presume that is going away.
-                But, there are steps to download and existing
-                <filename>.sh</filename> install script, build out the
-                toolchains assuming your system has YP on it and you can run
-                BitBake, getting the root filesystem, getting an image so you
-                run QEMU on your system, etc.
-                </para></listitem>
-        </itemizedlist>
-    </para>
-
     <para>
         The installed Standard SDK consists of several files and directories.
         Basically, it contains an SDK environment setup script, some
@@ -161,15 +122,16 @@
         into <filename>/opt/poky</filename>.
         However, when you run the SDK installer, you can choose an
         installation directory.
+        <note>
+            You must change the permissions on the toolchain
+            installer script so that it is executable.
+        </note>
     </para>
 
     <para>
         The following command shows how to run the installer given a
         toolchain tarball for a 64-bit x86 development host system and
         a 32-bit x86 target architecture.
-        When you run the installer, the script prompts you for a
-        system password so that you permissions can change enabling
-        you to run the installer script.
         The example assumes the toolchain installer is located in
         <filename>~/Downloads/</filename>.
         <note>
@@ -180,17 +142,16 @@
             run the installer again.
         </note>
         <literallayout class='monospaced'>
-     $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
-     Poky (Yocto Project Reference Distro) SDK installer version 2.1+snapshot
-     ========================================================================
-     Enter target directory for SDK (default: /opt/poky/2.1+snapshot):
-     You are about to install the SDK to "/opt/poky/2.1+snapshot". Proceed[Y/n]? Y
-     [sudo] password for scottrif:
-     Extracting SDK.......................done
+     $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-2.1.sh
+     Poky (Yocto Project Reference Distro) SDK installer version 2.0
+     ===============================================================
+     Enter target directory for SDK (default: /opt/poky/2.1):
+     You are about to install the SDK to "/opt/poky/2.1". Proceed[Y/n]? Y
+     Extracting SDK.......................................................................done
      Setting it up...done
      SDK has been successfully set up and is ready to be used.
      Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
-      $ . /opt/poky/2.1+snapshot/environment-setup-i586-poky-linux
+      $ . /opt/poky/2.1/environment-setup-i586-poky-linux
         </literallayout>
     </para>
 
@@ -221,11 +182,11 @@
         Environment setup scripts begin with the string
         "<filename>environment-setup</filename>" and include as part of their
         name the tuned target architecture.
-        For example, the setup script for an IA-based target machine using
-        i586 tuning and located in the default SDK installation
-        directory is as follows:
+        For example, the command to source a setup script for an IA-based
+        target machine using i586 tuning and located in the default SDK
+        installation directory is as follows:
         <literallayout class='monospaced'>
-     $ source /opt/poky/&DISTRO;+snapshot/environment-setup-i586-poky-linux
+     $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
         </literallayout>
         When you run the setup script, many environment variables are
         defined:
@@ -256,6 +217,228 @@
     </para>
 </section>
 
+<section id='autotools-based-projects'>
+    <title>Autotools-Based Projects</title>
+
+    <para>
+        Once you have a suitable cross-toolchain installed, it is very easy to
+        develop a project outside of the OpenEmbedded build system.
+        This section presents a simple "Helloworld" example that shows how
+        to set up, compile, and run the project.
+    </para>
+
+    <section id='creating-and-running-a-project-based-on-gnu-autotools'>
+        <title>Creating and Running a Project Based on GNU Autotools</title>
+
+        <para>
+            Follow these steps to create a simple Autotools-based project:
+            <orderedlist>
+                <listitem><para><emphasis>Create your directory:</emphasis>
+                    Create a clean directory for your project and then make
+                    that directory your working location:
+                    <literallayout class='monospaced'>
+     $ mkdir $HOME/helloworld
+     $ cd $HOME/helloworld
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Populate the directory:</emphasis>
+                    Create <filename>hello.c</filename>, <filename>Makefile.am</filename>,
+                    and <filename>configure.in</filename> files as follows:
+                    <itemizedlist>
+                        <listitem><para>For <filename>hello.c</filename>, include
+                            these lines:
+                            <literallayout class='monospaced'>
+     #include &lt;stdio.h&gt;
+
+     main()
+        {
+           printf("Hello World!\n");
+        }
+                            </literallayout></para></listitem>
+                        <listitem><para>For <filename>Makefile.am</filename>,
+                            include these lines:
+                            <literallayout class='monospaced'>
+     bin_PROGRAMS = hello
+     hello_SOURCES = hello.c
+                            </literallayout></para></listitem>
+                        <listitem><para>For <filename>configure.in</filename>,
+                            include these lines:
+                            <literallayout class='monospaced'>
+     AC_INIT(hello.c)
+     AM_INIT_AUTOMAKE(hello,0.1)
+     AC_PROG_CC
+     AC_PROG_INSTALL
+     AC_OUTPUT(Makefile)
+                            </literallayout></para></listitem>
+                    </itemizedlist></para></listitem>
+                <listitem><para><emphasis>Source the cross-toolchain
+                    environment setup file:</emphasis>
+                    Installation of the cross-toolchain creates a cross-toolchain
+                    environment setup script in the directory that the ADT
+                    was installed.
+                    Before you can use the tools to develop your project, you must
+                    source this setup script.
+                    The script begins with the string "environment-setup" and contains
+                    the machine architecture, which is followed by the string
+                    "poky-linux".
+                    Here is an example that sources a script from the
+                    default ADT installation directory that uses the
+                    32-bit Intel x86 Architecture and the
+                    &DISTRO_NAME; Yocto Project release:
+                    <literallayout class='monospaced'>
+     $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Generate the local aclocal.m4
+                    files and create the configure script:</emphasis>
+                    The following GNU Autotools generate the local
+                    <filename>aclocal.m4</filename> files and create the
+                    configure script:
+                    <literallayout class='monospaced'>
+     $ aclocal
+     $ autoconf
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Generate files needed by GNU
+                    coding standards:</emphasis>
+                    GNU coding standards require certain files in order for the
+                    project to be compliant.
+                    This command creates those files:
+                    <literallayout class='monospaced'>
+     $ touch NEWS README AUTHORS ChangeLog
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Generate the configure
+                    file:</emphasis>
+                    This command generates the <filename>configure</filename>:
+                    <literallayout class='monospaced'>
+     $ automake -a
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Cross-compile the project:</emphasis>
+                    This command compiles the project using the cross-compiler.
+                    The
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink>
+                    environment variable provides the minimal arguments for
+                    GNU configure:
+                    <literallayout class='monospaced'>
+     $ ./configure ${CONFIGURE_FLAGS}
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Make and install the project:</emphasis>
+                    These two commands generate and install the project into the
+                    destination directory:
+                    <literallayout class='monospaced'>
+     $ make
+     $ make install DESTDIR=./tmp
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Verify the installation:</emphasis>
+                    This command is a simple way to verify the installation
+                    of your project.
+                    Running the command prints the architecture on which
+                    the binary file can run.
+                    This architecture should be the same architecture that
+                    the installed cross-toolchain supports.
+                    <literallayout class='monospaced'>
+     $ file ./tmp/usr/local/bin/hello
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Execute your project:</emphasis>
+                    To execute the project in the shell, simply enter the name.
+                    You could also copy the binary to the actual target hardware
+                    and run the project there as well:
+                    <literallayout class='monospaced'>
+     $ ./hello
+                    </literallayout>
+                    As expected, the project displays the "Hello World!" message.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+
+    <section id='passing-host-options'>
+        <title>Passing Host Options</title>
+
+        <para>
+            For an Autotools-based project, you can use the cross-toolchain by just
+            passing the appropriate host option to <filename>configure.sh</filename>.
+            The host option you use is derived from the name of the environment setup
+            script found in the directory in which you installed the cross-toolchain.
+            For example, the host option for an ARM-based target that uses the GNU EABI
+            is <filename>armv5te-poky-linux-gnueabi</filename>.
+            You will notice that the name of the script is
+            <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
+            Thus, the following command works to update your project and
+            rebuild it using the appropriate cross-toolchain tools:
+            <literallayout class='monospaced'>
+     $ ./configure --host=armv5te-poky-linux-gnueabi \
+        --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable>
+            </literallayout>
+            <note>
+                If the <filename>configure</filename> script results in problems recognizing the
+                <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> option,
+                regenerate the script to enable the support by doing the following and then
+                run the script again:
+                <literallayout class='monospaced'>
+     $ libtoolize --automake
+     $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \
+        [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>]
+     $ autoconf
+     $ autoheader
+     $ automake -a
+                </literallayout>
+            </note>
+        </para>
+    </section>
+</section>
+
+<section id='makefile-based-projects'>
+    <title>Makefile-Based Projects</title>
+
+    <para>
+        For Makefile-based projects, the cross-toolchain environment variables
+        established by running the cross-toolchain environment setup script
+        are subject to general <filename>make</filename> rules.
+    </para>
+
+    <para>
+        To illustrate this, consider the following four cross-toolchain
+        environment variables:
+        <literallayout class='monospaced'>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types
+        </literallayout>
+        Now, consider the following three cases:
+        <itemizedlist>
+            <listitem><para><emphasis>Case 1 - No Variables Set in the <filename>Makefile</filename>:</emphasis>
+                Because these variables are not specifically set in the
+                <filename>Makefile</filename>, the variables retain their
+                values based on the environment.
+                </para></listitem>
+            <listitem><para><emphasis>Case 2 - Variables Set in the <filename>Makefile</filename>:</emphasis>
+                Specifically setting variables in the
+                <filename>Makefile</filename> during the build results in the
+                environment settings of the variables being overwritten.
+                </para></listitem>
+            <listitem><para><emphasis>Case 3 - Variables Set when the <filename>Makefile</filename> is Executed from the Command Line:</emphasis>
+                Executing the <filename>Makefile</filename> from the command
+                line results in the variables being overwritten with
+                command-line content regardless of what is being set in the
+                <filename>Makefile</filename>.
+                In this case, environment variables are not considered unless
+                you use the "-e" flag during the build:
+                <literallayout class='monospaced'>
+     $ make -e <replaceable>file</replaceable>
+                </literallayout>
+                If you use this flag, then the environment values of the
+                variables override any variables specifically set in the
+                <filename>Makefile</filename>.
+                </para></listitem>
+        </itemizedlist>
+        <note>
+            For the list of variables set up by the cross-toolchain environment
+            setup script, see the
+            "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>"
+            section.
+        </note>
+    </para>
+</section>
+
 <section id='sdk-using-the-sdk-to-task-1'>
     <title>Using the SDK to <replaceable>item 1</replaceable></title>