dev-manual: partial update to cross-development toolchain definition.

(From yocto-docs rev: 3a6f396c09a6d6a4e8a7fe9316b57166488d7fee)

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

1 files changed, 71 insertions, 34 deletions

diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index a53aff4f57..4b11f403b0 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -566,55 +566,92 @@
                 </para></listitem>
             <listitem><para id='cross-development-toolchain'>
                 <emphasis>Cross-Development Toolchain:</emphasis>
-                A collection of software development
-                tools and utilities that run on one architecture but
-                allow you to develop software for a different targeted
-                architecture.
+                In general, a cross-development toolchain is a collection of
+                software development tools and utilities that run on one
+                architecture and allow you to develop software for a
+                different, or targeted, architecture.
                 This toolchain contains cross-compilers, linkers, and debuggers
-                that are specific to an architecture.
-                You can use the OpenEmbedded build system to build a
-                cross-development toolchain installer that, when run, installs
-                the toolchain that contains the development tools you
-                need to cross-compile and test your software.
-                The Yocto Project ships with images that contain installers for
-                toolchains for supported architectures as well.
+                that are specific to the target architecture.
                 Sometimes this toolchain is referred to as the
                 meta-toolchain.</para>
-                <para>Following is a list of toolchain recipes with brief
+                <para>
+                <para>The Yocto Project supports two different cross-development
+                    toolchains:
+                    <itemizedlist>
+                        <listitem><para>A toolchain only used by and within
+                            BitBake when building an image for a target
+                            architecture.</para></listitem>
+                        <listitem><para>A toolchain used outside of BitBake
+                            by developers when developing applications that
+                            will run on a targeted device.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+                <para>You can use the OpenEmbedded build system to build an
+                installer for the toolchain used to develop applications.
+                When you run the installer, it installs the toolchain,
+                which contains the development tools you need to cross-compile
+                and test your software.
+                If your target architecture is supported by the Yocto Project,
+                you can take advantage of pre-built images that ship with the
+                Yocto Project and already contain cross-development toolchain
+                installers.
+                </para>
+                <para>Following are some toolchain recipes with brief
                 descriptions of each:
                 <itemizedlist>
                     <listitem><para><filename>gcc-cross-initial</filename>:
-                        The first stage of the bootstrap process that
-                        results in the cross-compiler that runs on the host
-                        and builds software for the target.
-                        This tool is a "native" packages (i.e. it is
-                        designed to run on the development host).
+                        An early stage of the bootstrap process for creating
+                        the cross-compiler used within BitBake.
+                        This stage builds enough of the
+                        <filename>gcc-cross</filename>,
+                        the C library, and other pieces needed to
+                        finish building the final cross-compiler in later
+                        stages.
+                        This tool is a "native" package (i.e. it is
+                        designed to run on the build host).
                         </para></listitem>
                     <listitem><para><filename>gcc-cross</filename>:
-                        The second and final stage of the previously described
-                        bootstrap process.
-                        If you are replacing the cross compiler toolchain
-                        with a custom version, you must replace
-                        <filename>gcc-cross</filename>.
-                        This tool is a "native" package (i.e. it is
-                        designed to run on the development host).
+                        The final stage of the bootstrap process for creating
+                        the cross-compiler used within BitBake.
+                        This stage results in the actual cross-compiler that
+                        BitBake uses when it builds an image for a targeted
+                        device.
+                        <note>
+                            If you are replacing this cross compiler toolchain
+                            with a custom version, you must replace
+                            <filename>gcc-cross</filename>.
+                        </note>
+                        This tool is also a "native" package (i.e. it is
+                        designed to run on the build host).
                         </para></listitem>
                     <listitem><para><filename>gcc-runtime</filename>:
                         Runtime libraries from the toolchain bootstrapping
                         process.
-                        This tool produces a binary for the target.
+                        This tool produces a binary that consists of the
+                        runtime libraries need for the targeted device.
                         </para></listitem>
                     <listitem><para><filename>gcc-crosssdk-initial</filename>:
-                        The first stage of the Software Development Kit (SDK)
-                        cross-compiler that runs on the host and builds for
-                        the SDK.
-                        Often the SDK is not the same target as the host.
-                        This tool is a "native" binary.</para></listitem>
+                        An early stage of the bootstrap process for creating
+                        the cross-compiler that is external to BitBake
+                        (i.e. the compiler used by application developers
+                        to develop software that runs on the target device).
+                        This stage builds enough of the
+                        <filename>gcc-crosssdk</filename> and supporting
+                        pieces so that the final stage of the bootstrap
+                        process can produce the finished cross-compiler.
+                        This tool is a "native" binary that runs on the build
+                        host.
+                        </para></listitem>
                     <listitem><para><filename>gcc-crosssdk</filename>:
-                        The second and final stage of the previously mentioned
-                        SDK cross-compiler.
-                        This tool is a "native" binary.
-                        The tool runs on the host and builds for the SDK.
+                        The final stage of the bootstrap process for creating
+                        the cross-compiler that is external to BitBake.
+                        This tool is a "native" binary that runs on the build
+                        host but generates code that runs on the machine used
+                        for application development (i.e. the
+                        <filename>SDKMACHINE</filename>).
+                        Often the <filename>SDKMACHINE</filename> is not the
+                        same machine as the host build machine.
                         </para></listitem>
                     <listitem><para><filename>gcc-cross-canadian</filename>:
                         A compiler built on one machine (build machine) that