[Subtree] Removing import-layers directory

As part of the move to subtrees, need to bring all the import layers
content to the top level.

Change-Id: I4a163d10898cbc6e11c27f776f60e1a470049d8f
Signed-off-by: Dave Cobbley <david.j.cobbley@linux.intel.com>
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>

1 files changed, 417 insertions, 0 deletions

diff --git a/poky/documentation/sdk-manual/sdk-intro.xml b/poky/documentation/sdk-manual/sdk-intro.xml
new file mode 100644
index 000000000..8642be61a
--- /dev/null
+++ b/poky/documentation/sdk-manual/sdk-intro.xml
@@ -0,0 +1,417 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='sdk-intro'>
+<title>Introduction</title>
+
+<section id='sdk-manual-intro'>
+    <title>Introduction</title>
+
+    <para>
+        Welcome to the Yocto Project Application Development and the
+        Extensible Software Development Kit (eSDK) manual.
+        This manual provides information that explains how to use both the
+        Yocto Project extensible and standard SDKs to develop
+        applications and images.
+        Additionally, the manual also provides information on how to use
+        the popular <trademark class='trade'>Eclipse</trademark> IDE as part
+        of your application development workflow within the SDK environment.
+        <note>
+            Prior to the 2.0 Release of the Yocto Project, application
+            development was primarily accomplished through the use of the
+            Application Development Toolkit (ADT) and the availability
+            of stand-alone cross-development toolchains and other tools.
+            With the 2.1 Release of the Yocto Project, application development
+            has transitioned to within a tool-rich extensible SDK and the more
+            traditional standard SDK.
+        </note>
+    </para>
+
+    <para>
+        All SDKs consist of the following:
+        <itemizedlist>
+            <listitem><para>
+                <emphasis>Cross-Development Toolchain</emphasis>:
+                This toolchain contains a compiler, debugger, and various
+                miscellaneous tools.
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Libraries, Headers, and Symbols</emphasis>:
+                The libraries, headers, and symbols are specific to the image
+                (i.e. they match the image).
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Environment Setup Script</emphasis>:
+                This <filename>*.sh</filename> file, once run, sets up the
+                cross-development environment by defining variables and
+                preparing for SDK use.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        Additionally, an extensible SDK has tools that allow you to easily add
+        new applications and libraries to an image, modify the source of an
+        existing component, test changes on the target hardware, and easily
+        integrate an application into the
+        <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>.
+    </para>
+
+    <para>
+        You can use an SDK to independently develop and test code
+        that is destined to run on some target machine.
+        SDKs are 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>
+        Another feature for the SDKs is that only one set of cross-compiler
+        toolchain binaries are produced for any given 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 every target still needs a sysroot because
+        those binaries are target-specific.
+    </para>
+
+    <para>
+        The SDK development environment consists of the following:
+        <itemizedlist>
+            <listitem><para>
+                The self-contained SDK, which is an
+                architecture-specific cross-toolchain and
+                matching sysroots (target and native) all built by the
+                OpenEmbedded build system (e.g. the SDK).
+                The toolchain and sysroots are based on a
+                <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
+                configuration and extensions,
+                which allows you to cross-develop on the host machine for the
+                target hardware.
+                Additionally, the extensible SDK contains the
+                <filename>devtool</filename> functionality.
+                </para></listitem>
+            <listitem><para>
+                The Quick EMUlator (QEMU), which lets you simulate
+                target hardware.
+                QEMU is not literally part of the SDK.
+                You must build and include this emulator separately.
+                However, QEMU plays an important role in the development
+                process that revolves around use of the SDK.
+                </para></listitem>
+            <listitem><para>
+                The Eclipse IDE Yocto Plug-in.
+                This plug-in is available for you if you are an Eclipse
+                user.
+                In the same manner as QEMU, the plug-in is not literally part
+                of the SDK but is rather available for use as part of the
+                development process.
+                </para></listitem>
+            <listitem><para>
+                Various performance-related
+                <ulink url='http://www.eclipse.org/linuxtools/index.php'>tools</ulink>
+                that can enhance your development experience.
+                These tools are also separate from the actual SDK but can be
+                independently obtained and used in the development process.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        In summary, the extensible and standard SDK share many features.
+        However, the extensible SDK has powerful development tools to help you
+        more quickly develop applications.
+        Following is a table that summarizes the primary differences between
+        the standard and extensible SDK types when considering which to
+        build:
+        <informaltable frame='none'>
+            <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+                <colspec colname='c1' colwidth='1*'/>
+                <colspec colname='c2' colwidth='1*'/>
+                <colspec colname='c3' colwidth='1*'/>
+                <thead>
+                    <row>
+                        <entry align="left"><emphasis>Feature</emphasis></entry>
+                        <entry align="left"><emphasis>Standard SDK</emphasis></entry>
+                        <entry align="left"><emphasis>Extensible SDK</emphasis></entry>
+                    </row>
+                </thead>
+                <tbody>
+                    <row>
+                        <entry align="left">Toolchain</entry>
+                        <entry align="left">Yes</entry>
+                        <entry align="left">Yes*</entry>
+                    </row>
+                    <row>
+                        <entry align="left">Debugger</entry>
+                        <entry align="left">Yes</entry>
+                        <entry align="left">Yes*</entry>
+                    </row>
+                    <row>
+                        <entry align="left">Size</entry>
+                        <entry align="left">100+ MBytes</entry>
+                        <entry align="left">1+ GBytes (or 300+ MBytes for minimal w/toolchain)</entry>
+                    </row>
+                    <row>
+                        <entry align="left"><filename>devtool</filename></entry>
+                        <entry align="left">No</entry>
+                        <entry align="left">Yes</entry>
+                    </row>
+                    <row>
+                        <entry align="left">Build Images</entry>
+                        <entry align="left">No</entry>
+                        <entry align="left">Yes</entry>
+                    </row>
+                    <row>
+                        <entry align="left">Updateable</entry>
+                        <entry align="left">No</entry>
+                        <entry align="left">Yes</entry>
+                    </row>
+                    <row>
+                        <entry align="left">Managed Sysroot**</entry>
+                        <entry align="left">No</entry>
+                        <entry align="left">Yes</entry>
+                    </row>
+                    <row>
+                        <entry align="left">Installed Packages</entry>
+                        <entry align="left">No***</entry>
+                        <entry align="left">Yes****</entry>
+                    </row>
+                    <row>
+                        <entry align="left">Construction</entry>
+                        <entry align="left">Packages</entry>
+                        <entry align="left">Shared State</entry>
+                    </row>
+                </tbody>
+            </tgroup>
+        </informaltable>
+        <literallayout class='monospaced'>
+     * Extensible SDK contains the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default.
+
+     ** Sysroot is managed through the use of <filename>devtool</filename>.  Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries.
+
+     *** You can add runtime package management to the standard SDK but it is not supported by default.
+
+     **** You must build and make the shared state available to extensible SDK users for "packages" you want to enable users to install.
+        </literallayout>
+    </para>
+
+    <section id='the-cross-development-toolchain'>
+        <title>The Cross-Development Toolchain</title>
+
+        <para>
+            The
+            <ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain'>Cross-Development Toolchain</ulink>
+            consists of a cross-compiler, cross-linker, and cross-debugger
+            that are used to develop user-space applications for targeted
+            hardware.
+            Additionally, for an extensible SDK, the toolchain also has
+            built-in <filename>devtool</filename> functionality.
+            This toolchain is created by running a SDK installer script
+            or through a
+            <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+            that is based on your metadata configuration or extension for
+            your targeted device.
+            The cross-toolchain works with a matching target sysroot.
+        </para>
+    </section>
+
+    <section id='sysroot'>
+        <title>Sysroots</title>
+
+        <para>
+            The native and target sysroots contain needed headers and libraries
+            for generating binaries that run on the target architecture.
+            The target sysroot is based on the target root filesystem image
+            that is built by the OpenEmbedded build system and uses the same
+            metadata configuration used to build the cross-toolchain.
+        </para>
+    </section>
+
+    <section id='the-qemu-emulator'>
+        <title>The QEMU Emulator</title>
+
+        <para>
+            The QEMU emulator allows you to simulate your hardware while
+            running your application or image.
+            QEMU is not part of the SDK but is made available a number of
+            different ways:
+            <itemizedlist>
+                <listitem><para>
+                    If you have cloned the <filename>poky</filename> Git
+                    repository to create a
+                    <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+                    and you have sourced the environment setup script, QEMU is
+                    installed and automatically available.
+                    </para></listitem>
+                <listitem><para>
+                    If you have downloaded a Yocto Project release and unpacked
+                    it to create a Source Directory and you have sourced the
+                    environment setup script, QEMU is installed and
+                    automatically available.
+                    </para></listitem>
+                <listitem><para>
+                    If you have installed the cross-toolchain tarball and you
+                    have sourced the toolchain's setup environment script, QEMU
+                    is also installed and automatically available.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='eclipse-overview'>
+        <title><trademark class='trade'>Eclipse</trademark> Yocto Plug-in</title>
+
+        <para>
+            The Eclipse IDE is a popular development environment and it fully
+            supports development using the Yocto Project.
+            When you install and configure the Eclipse Yocto Project Plug-in
+            into the Eclipse IDE, you maximize your Yocto Project experience.
+            Installing and configuring the Plug-in results in an environment
+            that has extensions specifically designed to let you more easily
+            develop software.
+            These extensions allow for cross-compilation, deployment, and
+            execution of your output into a QEMU emulation session.
+            You can also perform cross-debugging and profiling.
+            The environment also supports many performance-related
+            <ulink url='http://www.eclipse.org/linuxtools/index.php'>tools</ulink>
+            that enhance your development experience.
+            <note>
+                Previous releases of the Eclipse Yocto Plug-in supported
+                "user-space tools" (i.e. LatencyTOP, PowerTOP, Perf, SystemTap,
+                and Lttng-ust) that also added to the development experience.
+                These tools have been deprecated with the release of the
+                Eclipse Yocto Plug-in.
+            </note>
+        </para>
+
+        <para>
+            For information about the application development workflow that
+            uses the Eclipse IDE and for a detailed example of how to install
+            and configure the Eclipse Yocto Project Plug-in, see the
+            "<link linkend='sdk-eclipse-project'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>"
+            Chapter.
+        </para>
+    </section>
+
+    <section id='performance-enhancing-tools'>
+        <title>Performance Enhancing Tools</title>
+
+        <para>
+            Supported performance enhancing tools are available that let you
+            profile, debug, and perform tracing on your projects developed
+            using Eclipse.
+            For information on these tools see
+            <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
+        </para>
+    </section>
+</section>
+
+<section id='sdk-development-model'>
+    <title>SDK Development Model</title>
+
+    <para>
+        Fundamentally, the SDK fits into the development process as follows:
+        <imagedata fileref="figures/sdk-environment.png" align="center" width="6in" depth="5in" scalefit="100" />
+        The SDK is installed on any machine and can be used to develop
+        applications, images, and kernels.
+        An SDK can even be used by a QA Engineer or Release Engineer.
+        The fundamental concept is that the machine that has the SDK installed
+        does not have to be associated with the machine that has the
+        Yocto Project installed.
+        A developer can independently compile and test an object on their
+        machine and then, when the object is ready for integration into an
+        image, they can simply make it available to the machine that has the
+        Yocto Project.
+        Once the object is available, the image can be rebuilt using the
+        Yocto Project to produce the modified image.
+    </para>
+
+    <para>
+        You just need to follow these general steps:
+        <orderedlist>
+            <listitem><para>
+                <emphasis>Install the SDK for your target hardware:</emphasis>
+                For information on how to install the SDK, see the
+                "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
+                section.
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Download or Build the Target Image:</emphasis>
+                The Yocto Project supports several target architectures
+                and has many pre-built kernel images and root filesystem
+                images.</para>
+
+                <para>If you are going to develop your application on
+                hardware, go to the
+                <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
+                download area and choose a target machine area
+                from which to download the kernel image and root filesystem.
+                This download area could have several files in it that
+                support development using actual hardware.
+                For example, the area might contain
+                <filename>.hddimg</filename> files that combine the
+                kernel image with the filesystem, boot loaders, and
+                so forth.
+                Be sure to get the files you need for your particular
+                development process.</para>
+
+                <para>If you are going to develop your application and
+                then run and test it using the QEMU emulator, go to the
+                <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink>
+                download area.
+                From this area, go down into the directory for your
+                target architecture (e.g. <filename>qemux86_64</filename>
+                for an <trademark class='registered'>Intel</trademark>-based
+                64-bit architecture).
+                Download the kernel, root filesystem, and any other files you
+                need for your process.
+                <note>
+                    To use the root filesystem in QEMU, you need to extract it.
+                    See the
+                    "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"
+                    section for information on how to extract the root
+                    filesystem.
+                </note>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Develop and Test your Application:</emphasis>
+                At this point, you have the tools to develop your application.
+                If you need to separately install and use the QEMU emulator,
+                you can go to
+                <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink>
+                to download and learn about the emulator.
+                See the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
+                chapter in the Yocto Project Development Tasks Manual
+                for information on using QEMU within the Yocto
+                Project.
+                </para></listitem>
+        </orderedlist>
+    </para>
+
+    <para>
+        The remainder of this manual describes how to use the extensible
+        and standard SDKs.
+        Information also exists in appendix form that describes how you can
+        build, install, and modify an SDK.
+    </para>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->