ref-manual, mega-manual: New section for images/SDK

Fixes [YOCTO #2808]

Added a new section for the closer look at how BitBake creates
images and the SDK installer files.  This included the section
itself, a new .PNG figure that had to be added to the figures
directory of both the ref-manual and the mega-manual.  Finally,
the Makefile needed to be edited so that the tarballs for the
ref-manual and mega-manual also included the new figure.

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

5 files changed, 174 insertions, 3 deletions

diff --git a/documentation/Makefile b/documentation/Makefile
index ca70bce772..e286ea4ddc 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/package-feeds.png figures/layer-input.png figures/images-sdk.png
         endif
 
 MANUALS = $(DOC)/$(DOC).html
@@ -214,7 +214,8 @@ TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
         figures/buildhistory.png figures/buildhistory-web.png eclipse \
         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/user-configuration.png figures/yocto-environment-ref.png \
+        figures/images-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
new file mode 100644
index 0000000000..c124a452a3
--- /dev/null
+++ b/documentation/mega-manual/figures/images-sdk.png
diff --git a/documentation/ref-manual/figures/images-sdk.png b/documentation/ref-manual/figures/images-sdk.png
new file mode 100644
index 0000000000..c124a452a3
--- /dev/null
+++ b/documentation/ref-manual/figures/images-sdk.png
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
index d482511516..1d19ffd07f 100644
--- a/documentation/ref-manual/ref-structure.xml
+++ b/documentation/ref-manual/ref-structure.xml
@@ -356,7 +356,14 @@
         <title><filename>build/tmp/deploy/</filename></title>
 
         <para>
-            This directory contains any "end result" output from the OpenEmbedded build process.
+            This directory contains any "end result" output from the
+            OpenEmbedded build process.
+            The <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
+            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.
         </para>
     </section>
 
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index c7a49da946..6ae8ee50e0 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -796,6 +796,169 @@
             <filename>do_package_write_ipk</filename> for IPK packages).
         </para>
     </section>
+
+    <section id='images-and-application-development-sdk'>
+        <title>Images and Application Development SDK</title>
+
+        <para>
+            The purpose of using the OpenEmbedded build system is to produce
+            an image or a Software Development Kit (SDK).
+            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.
+            This section is going to look more closely at this output:
+            <imagedata fileref="figures/images-sdk.png" align="center" width="5in" depth="4in" />
+        </para>
+
+        <section id='images-dev-environment'>
+            <title>Images</title>
+
+            <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 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>
+
+            <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.
+            </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>
+            </para>
+        </section>
+    </section>
 </section>
 
 <section id="cross-development-toolchain-generation">