ref-manual, mega-manual, Makefile: Updates to expanded dev section

Fixes [YOCTO #2808]

Applied review comments to the "Images" and SDK sections that
are part of the "A Closer Look at the Yocto Project Development
Environment" section.  Comments from Paul.  They resulted
in a single figure being removed and split into two new
figures - one for the image part and one for the sdk part.

Some terminology issues were cleaned up in the main sections
as well as the documented variables sections.

Makefile changes involved adding the two new figures and
removing the old combined one.

(From yocto-docs rev: a32908fa68b9786e295097c16f70a5a9c3cc4c1e)

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

10 files changed, 170 insertions, 163 deletions

diff --git a/documentation/Makefile b/documentation/Makefile
index e286ea4ddc..e3a0db4c22 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -198,7 +198,7 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures
         figures/sched-wakeup-profile.png figures/sysprof-callers.png \
         figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png figures/cross-development-toolchains.png \
 	figures/yocto-environment-ref.png figures/user-configuration.png figures/source-input.png \
-	figures/package-feeds.png figures/layer-input.png figures/images-sdk.png
+	figures/package-feeds.png figures/layer-input.png figures/images.png figures/sdk.png
 	endif
 
 MANUALS = $(DOC)/$(DOC).html
@@ -215,7 +215,7 @@ TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
         figures/cross-development-toolchains.png figures/layer-input.png \
 	figures/package-feeds.png figures/source-input.png \
 	figures/user-configuration.png figures/yocto-environment-ref.png \
-	figures/images-sdk.png
+	figures/images.png figures/sdk.png
 MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
 FIGURES = figures
 STYLESHEET = $(DOC)/*.css
diff --git a/documentation/mega-manual/figures/images-sdk.png b/documentation/mega-manual/figures/images-sdk.png
deleted file mode 100644
index c124a452a3..0000000000
--- a/documentation/mega-manual/figures/images-sdk.png
+++ /dev/null
diff --git a/documentation/mega-manual/figures/images.png b/documentation/mega-manual/figures/images.png
new file mode 100644
index 0000000000..09b83c2864
--- /dev/null
+++ b/documentation/mega-manual/figures/images.png
diff --git a/documentation/mega-manual/figures/sdk.png b/documentation/mega-manual/figures/sdk.png
new file mode 100644
index 0000000000..3dddad37bb
--- /dev/null
+++ b/documentation/mega-manual/figures/sdk.png
diff --git a/documentation/ref-manual/figures/images-sdk.png b/documentation/ref-manual/figures/images-sdk.png
deleted file mode 100644
index c124a452a3..0000000000
--- a/documentation/ref-manual/figures/images-sdk.png
+++ /dev/null
diff --git a/documentation/ref-manual/figures/images.png b/documentation/ref-manual/figures/images.png
new file mode 100644
index 0000000000..09b83c2864
--- /dev/null
+++ b/documentation/ref-manual/figures/images.png
diff --git a/documentation/ref-manual/figures/sdk.png b/documentation/ref-manual/figures/sdk.png
new file mode 100644
index 0000000000..3dddad37bb
--- /dev/null
+++ b/documentation/ref-manual/figures/sdk.png
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
index 1d19ffd07f..6ddecd994d 100644
--- a/documentation/ref-manual/ref-structure.xml
+++ b/documentation/ref-manual/ref-structure.xml
@@ -362,8 +362,9 @@
             variable points to this directory.
             For more detail on the contents of the <filename>deploy</filename>
             directory, see the
-            "<link linkend='images-and-application-development-sdk'>Images and Application Development SDK</link>"
-            section.
+            "<link linkend='images-dev-environment'>Images</link>" and
+            "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
+            sections.
         </para>
     </section>
 
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index d65733ec4e..714346fc18 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -780,8 +780,7 @@ Core layer for images cannot be removed
             <glossdef>
                 <para>
                     Points to the area that the OpenEmbedded build system uses
-                    to place images and their related files created with
-                    BitBake.
+                    to place images and their related files.
                     By default, this directory resides within the
                     <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
                     as <filename>tmp/deploy</filename>.
@@ -794,8 +793,9 @@ Core layer for images cannot be removed
                     section.
                     For more detail on the contents of the
                     <filename>deploy</filename> directory, see the
-                    "<link linkend='images-and-application-development-sdk'>Images and Application Development SDK</link>"
-                    section.
+                    "<link linkend='images-dev-environment'>Images</link>" and
+                    "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
+                    sections.
                 </para>
             </glossdef>
         </glossentry>
@@ -4008,18 +4008,21 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
-        <glossentry id='var-TOOLCHAIN_HOSTS_TASKS'><glossterm>TOOLCHAIN_HOSTS_TASKS</glossterm>
+        <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
             <glossdef>
                 <para>
-                    This variable lists packages BitBake uses when it builds
-                    an SDK installer, which is used to extract and set up a
+                    This variable lists packages the OpenEmbedded build system
+                    uses when building an SDK, which contains a
                     cross-development environment.
                     The packages specified by this variable are part of the
                     toolchain set that runs on the
-                    <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
-                    When you build an SDK installer using BitBake, a set of
-                    default tasks apply.
-                    The tasks you specify here are added to those defaults.
+                    <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
+                    and each package should usually have the prefix
+                    "nativesdk-".
+                    When building an SDK using
+                    <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>,
+                    a default list of packages is set in this variable, but
+                    you can add additional packages to the list.
                 </para>
 
                 <para>
@@ -4035,11 +4038,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
         </glossentry>
 
-        <glossentry id='var-TOOLCHAIN_TARGET_TASKS'><glossterm>TOOLCHAIN_TARGET_TASKS</glossterm>
+        <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
             <glossdef>
                 <para>
                     This variable lists packages BitBake uses when it creates
-                    the target part of an SDK installer (i.e. the part built
+                    the target part of an SDK (i.e. the part built
                     for the target hardware), which includes libraries and
                     headers.
                 </para>
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index 6ae8ee50e0..97fd629a74 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -172,7 +172,7 @@
     </para>
 
     <para>
-        The generalized Yocto Project Devevelopment Environment consists of
+        The generalized Yocto Project Development Environment consists of
         several functional areas:
         <itemizedlist>
             <listitem><para><emphasis>User Configuration:</emphasis>
@@ -797,167 +797,170 @@
         </para>
     </section>
 
-    <section id='images-and-application-development-sdk'>
-        <title>Images and Application Development SDK</title>
+    <section id='images-dev-environment'>
+        <title>Images</title>
 
         <para>
-            The purpose of using the OpenEmbedded build system is to produce
-            an image or a Software Development Kit (SDK).
+            The images produced by the OpenEmbedded build system
+            are compressed forms of the
+            root filesystems that are ready to boot on a target device.
             You can see from the main
             <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment</link>
-            figure that the output (shown in red) are images and SDKs.
+            figure that BitBake output in part consists of images.
             This section is going to look more closely at this output:
-            <imagedata fileref="figures/images-sdk.png" align="center" width="5in" depth="4in" />
+            <imagedata fileref="figures/images.png" align="center" width="5in" depth="4in" />
         </para>
 
-        <section id='images-dev-environment'>
-            <title>Images</title>
+        <para>
+            For a list of example images that the Yocto Project provides,
+            the
+            "<link linkend='ref-images'>Images</link>" chapter.
+        </para>
 
-            <para>
-                The images produced by BitBake are compressed forms of the
-                root filesystems that are ready to boot on a target device.
-                You can see the
-                "<link linkend='ref-images'>Images</link>" chapter for a list
-                of example images that the Yocto Project provides.
-            </para>
+        <para>
+            Images are written out to the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+            inside the <filename>deploy/images</filename> folder as shown
+            in the figure.
+            This folder contains any files expected to be loaded on the
+            target device.
+            The
+            <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
+            variable points to the <filename>deploy</filename> directory.
+            <itemizedlist>
+                <listitem><para><filename>&lt;kernel-image&gt;</filename>:
+                    A kernel binary file.
+                    The <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
+                    variable setting determines the naming scheme for the
+                    kernel image file.
+                    Depending on that variable, the file could begin with
+                    a variety of naming strings.
+                    The <filename>deploy/images</filename> directory can
+                    contain multiple image files.</para></listitem>
+                <listitem><para><filename>&lt;root-filesystem-image&gt;</filename>:
+                    Root filesystems for the target device (e.g.
+                    <filename>*.ext3</filename> or <filename>*.bz2</filename>
+                    files).
+                    The <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
+                    variable setting determines the root filesystem image
+                    type.
+                    The <filename>deploy/images</filename> directory can
+                    contain multiple root filesystems.</para></listitem>
+                <listitem><para><filename>&lt;kernel-modules&gt;</filename>:
+                    Tarballs that contain all the modules used by the
+                    kernel.
+                    Kernel module tarballs exist for legacy purposes and
+                    can be suppressed by setting the
+                    <link linkend='var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></link>
+                    variable to "0".
+                    The <filename>deploy/images</filename> directory can
+                    contain multiple kernel module tarballs.
+                    </para></listitem>
+                <listitem><para><filename>&lt;bootloaders&gt;</filename>:
+                    Bootloaders supporting the image, if applicable to the
+                    target machine.
+                    The <filename>deploy/images</filename> directory can
+                    contain multiple bootloaders.
+                    </para></listitem>
+                <listitem><para><filename>&lt;symlinks&gt;</filename>:
+                    The <filename>images/deploy</filename> folder contains
+                    a symbolic link that points to the most recently built file
+                    for each machine.
+                    These links might be useful for external scripts that
+                    need to obtain the latest version of each file.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
 
-            <para>
-                Images are kept in the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
-                inside the <filename>deploy/images</filename> folder as shown
-                in the figure.
-                This folder contains any files expected to be loaded on the
-                target device.
-                The
-                <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
-                variable points to the <filename>deploy</filename> directory.
-                <itemizedlist>
-                    <listitem><para><filename>&lt;image&gt;</filename>:
-                        A <filename>*.bin</filename> image file.
-                        The <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
-                        variable setting determines the naming scheme for the
-                        image file.
-                        Depending on that variable, the file could begin with
-                        a variety of naming strings.
-                        The <filename>deploy/images</filename> directory can
-                        contain multiple image files.</para></listitem>
-                    <listitem><para><filename>&lt;root-filesystem&gt;</filename>:
-                        Root filesystems for the target device (e.g.
-                        <filename>*.ext3</filename> or <filename>*.bz2</filename>
-                        files).
-                        The <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
-                        variable setting determines the root filesystem
-                        type.
-                        The <filename>deploy/images</filename> directory can
-                        contain multiple root filesystems.</para></listitem>
-                    <listitem><para><filename>&lt;kernel-modules&gt;</filename>:
-                        Tarballs that contain all the modules used by the
-                        kernel.
-                        Kernel module tarballs exist for legacy purposes and
-                        can be suppressed by setting the
-                        <link linkend='var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></link>
-                        variable to "0".
-                        The <filename>deploy/images</filename> directory can
-                        contain multiple kernel module tarballs.
-                        </para></listitem>
-                    <listitem><para><filename>&lt;bootloaders&gt;</filename>:
-                        Bootloaders supporting the image.
-                        The <filename>deploy/images</filename> directory can
-                        contain multiple bootloaders.
-                        </para></listitem>
-                    <listitem><para><filename>&lt;symlinks&gt;</filename>:
-                        The <filename>images/deploy</filename> folder contains
-                        a symbolic link for each actual file in the folder.
-                        Links exist for all types of files (i.e. images,
-                        root filesystems, bootloaders, and kernel module
-                        tarballs).
-                        The link scheme for images is such that a single link
-                        exists for the most recently built image.
-                        In addition to that single image link, additional
-                        links exist on a one-for-one basis that map to each
-                        physical image file.</para></listitem>
-                </itemizedlist>
-            </para>
-        </section>
+    <section id='sdk-dev-environment'>
+        <title>Application Development SDK</title>
 
-        <section id='sdk-dev-environment'>
-            <title>Application Development SDK</title>
+        <para>
+            In the overview figure of the
+            <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment</link>
+            the output labeled "Application Development SDK" represents an
+            SDK.
+            This section is going to take a closer look at this output:
+            <imagedata fileref="figures/sdk.png" align="center" width="5in" depth="4in" />
+        </para>
 
+        <para>
+            The specific form of this output is a self-extracting
+            SDK installer (<filename>*.sh</filename>) that, when run,
+            installs the SDK image, which consists of a cross-development
+            toolchain, a set of libraries and headers, and an SDK
+            environment setup script.
+            Running this installer essentially sets up your
+            cross-development environment.
+            You can think of the cross-toolchains as the "host" part
+            because they run on the SDK machine.
+            You can think of the libraries and headers as the "target"
+            part because they are built for the target hardware.
+            The setup script is added so that you can initialize the
+            environment before using the tools.
+        </para>
+
+        <note>
             <para>
-                An Application Development SDK (referred to as an
-                "SDK installer" in this section) is a self-extracting SDK
-                installer file (<filename>*.sh</filename>) that, when run,
-                installs a cross-development toolchain, a set of libraries
-                and headers, and an SDK environment setup script.
-                Running this installer essentially sets up your
-                cross-development environment.
-                You can think of the cross-toolchains as the "host" part
-                because they run on the SDK machine.
-                You can think of the libraries and headers as the "target"
-                part because they are built for the target hardware.
-                The setup script is added so that you can initialize the
-                environment before using the tools.
+                The Yocto Project supports several methods by which you can
+                set up this cross-development environment.
+                These methods include downloading pre-built SDK installers,
+                building and installing your own SDK installer, or running
+                an Application Development Toolkit (ADT) installer to
+                install not just cross-development toolchains
+                but also additional tools to help in this type of
+                development.
             </para>
 
-            <note>
-                <para>
-                    The Yocto Project supports several methods by which you can
-                    set up this cross-development environment.
-                    These methods include downloading pre-built SDK installers,
-                    building and installing your own SKD installer, or running
-                    an Application Development Toolkit (ADT) installer to
-                    install not just cross-development toolchains
-                    but also additional tools to help in this type of
-                    development.
-                </para>
-
-                <para>
-                    For background information on cross-development toolchains
-                    in the Yocto Project development environment, see the
-                    "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
-                    section.
-                    For information on setting up a cross-development
-                    environment, see the
-                    "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
-                    section in the Yocto Project Application Developer's Guide.
-                </para>
-            </note>
-
             <para>
-                When built using BitBake, the SDK installers are kept in the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
-                inside the <filename>deploy/sdk</filename> folder as shown
-                in the figure at the beginning of this section.
-                Several variables exist that help configure these files:
-                <itemizedlist>
-                    <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
-                        Points to the <filename>deploy</filename>
-                        directory.</para></listitem>
-                    <listitem><para><link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>:
-                        Specifies the architecture of the machine
-                        on which the cross-development tools are run to
-                        create packages for the target hardware.
-                        </para></listitem>
-                    <listitem><para><link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link>:
-                        Lists the features to include in the libraries.
-                        </para></listitem>
-                    <listitem><para><link linkend='var-TOOLCHAIN_HOSTS_TASKS'><filename>TOOLCHAIN_HOSTS_TASKS</filename></link>:
-                        Lists packages that make up the host
-                        part of the SDK installer (i.e. the part that runs on
-                        the <filename>SDKMACHINE</filename>).
-                        When you use <filename>bitbake sdk_populate</filename>
-                        to create the SDK installer, a set of default tasks
-                        apply.
-                        This variable allows you to add more tasks.
-                        </para></listitem>
-                    <listitem><para><link linkend='var-TOOLCHAIN_TARGET_TASKS'><filename>TOOLCHAIN_TARGET_TASKS</filename></link>:
-                        Lists packages that make up the target part
-                        of the SDK installer (i.e. the part built for the
-                        target hardware).
-                        </para></listitem>
-                </itemizedlist>
+                For background information on cross-development toolchains
+                in the Yocto Project development environment, see the
+                "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
+                section.
+                For information on setting up a cross-development
+                environment, see the
+                "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
+                section in the Yocto Project Application Developer's Guide.
             </para>
-        </section>
+        </note>
+
+        <para>
+            Once built, the SDK installers are written out to the
+            <filename>deploy/sdk</filename> folder inside the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+            as shown in the figure at the beginning of this section.
+            Several variables exist that help configure these files:
+            <itemizedlist>
+                <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
+                    Points to the <filename>deploy</filename>
+                    directory.</para></listitem>
+                <listitem><para><link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>:
+                    Specifies the architecture of the machine
+                    on which the cross-development tools are run to
+                    create packages for the target hardware.
+                    </para></listitem>
+                <listitem><para><link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link>:
+                    Lists the features to include in the "target" part
+                    of the SDK.
+                    </para></listitem>
+                <listitem><para><link linkend='var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></link>:
+                    Lists packages that make up the host
+                    part of the SDK installer (i.e. the part that runs on
+                    the <filename>SDKMACHINE</filename>).
+                    When you use
+                    <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>
+                    to create the SDK installer, a set of default packages
+                    apply.
+                    This variable allows you to add more packages.
+                    </para></listitem>
+                <listitem><para><link linkend='var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></link>:
+                    Lists packages that make up the target part
+                    of the SDK installer (i.e. the part built for the
+                    target hardware).
+                    </para></listitem>
+            </itemizedlist>
+        </para>
     </section>
 </section>