sdk-manual: Created new Mars Eclipse appendix

Fixes [YOCTO #7546]

First draft of the new appendix supporting the Mars version
of eclipse.  New appendix file created and entry made to
the sdk-manual.xml file to include that new appendix file
into the main book.

(From yocto-docs rev: 2fb79c29bcbb5c0801f67d4c245c07c3aa9d2ca2)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>

sdk-manual: WIP on appendix C

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

4 files changed, 914 insertions, 189 deletions

diff --git a/documentation/sdk-manual/sdk-appendix-mars.xml b/documentation/sdk-manual/sdk-appendix-mars.xml
new file mode 100644
index 0000000000..185dd42092
--- /dev/null
+++ b/documentation/sdk-manual/sdk-appendix-mars.xml
@@ -0,0 +1,878 @@
+<!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; ] >
+
+<appendix id='sdk-appendix-mars'>
+    <title>Using Eclipse Mars</title>
+
+    <para>
+        This release of the Yocto Project supports both the Neon and Mars
+        versions of the Eclipse IDE.
+        This appendix presents information that describes how to obtain and
+        configure the Mars version of Eclipse.
+        It also provides a basic project example that you can work through
+        from start to finish.
+        For general information on using the Eclipse IDE and the Yocto
+        Project Eclipse Plug-In, see the
+        "<link linkend='sdk-developing-applications-using-eclipse'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>"
+        section.
+    </para>
+
+    <section id='mars-setting-up-the-eclipse-ide'>
+        <title>Setting Up the Mars Version of the Eclipse IDE</title>
+
+        <para>
+            To develop within the Eclipse IDE, you need to do the following:
+            <orderedlist>
+                <listitem><para>Install the Mars version of the Eclipse
+                    IDE.</para></listitem>
+                <listitem><para>Configure the Eclipse IDE.
+                    </para></listitem>
+                <listitem><para>Install the Eclipse Yocto Plug-in.
+                    </para></listitem>
+                <listitem><para>Configure the Eclipse Yocto Plug-in.
+                    </para></listitem>
+            </orderedlist>
+            <note>
+                Do not install Eclipse from your distribution's package
+                repository.
+                Be sure to install Eclipse from the official Eclipse
+                download site as directed in the next section.
+            </note>
+        </para>
+
+        <section id='mars-installing-eclipse-ide'>
+            <title>Installing the Mars Eclipse IDE</title>
+
+            <para>
+                Follow these steps to locate, install, and configure
+                Mars Eclipse:
+                <orderedlist>
+                    <listitem><para><emphasis>Locate the Mars Download:</emphasis>
+                        Open a browser and go to
+                        <ulink url='http://www.eclipse.org/mars/'>http://www.eclipse.org/mars/</ulink>.
+                        </para></listitem>
+                    <listitem><para><emphasis>Download the Tarball:</emphasis>
+                        Click the "Download" button and then use the "Linux
+                        for Eclipse IDE for C++ Developers"
+                        appropriate for your development system
+                        (e.g.
+                        <ulink url='http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/mars/2/eclipse-cpp-mars-2-linux-gtk-x86_64.tar.gz'>64-bit under Linux for Eclipse IDE for C++ Developers</ulink>
+                        if your development system is a Linux 64-bit machine.
+                        </para></listitem>
+                    <listitem><para><emphasis>Unpack the Tarball:</emphasis>
+                        Move to a clean directory and unpack the tarball.
+                        Here is an example:
+                        <literallayout class='monospaced'>
+     $ cd ~
+     $ tar -xzvf ~/Downloads/eclipse-cpp-mars-2-linux-gtk-x86_64.tar.gz
+                        </literallayout>
+                        Everything unpacks into a folder named "Eclipse".
+                        </para></listitem>
+                    <listitem><para><emphasis>Launch Eclipse:</emphasis>
+                        Double click the "Eclipse" file in the folder to
+                        launch Eclipse.
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='mars-configuring-the-mars-eclipse-ide'>
+            <title>Configuring the Mars Eclipse IDE</title>
+
+            <para>
+                Follow these steps to configure the Mars Eclipse IDE.
+                <note>
+                    Depending on how you installed Eclipse and what you have
+                    already done, some of the options will not appear.
+                    If you cannot find an option as directed by the manual,
+                    it has already been installed.
+                </note>
+                <orderedlist>
+                    <listitem><para>Be sure Eclipse is running and
+                        you are in your workbench.
+                        </para></listitem>
+                    <listitem><para>Select "Install New Software" from
+                        the "Help" pull-down menu.
+                        </para></listitem>
+                    <listitem><para>Select
+                        "Mars - http://download.eclipse.org/releases/mars"
+                        from the "Work with:" pull-down menu.
+                        </para></listitem>
+                    <listitem><para>Expand the box next to
+                        "Linux Tools" and select "C/C++ Remote
+                        (Over TCF/TE) Run/Debug Launcher" and
+                        "TM Terminal".
+                        </para></listitem>
+                    <listitem><para>Expand the box next to "Mobile and
+                        Device Development" and select the following
+                        boxes:
+                        <literallayout class='monospaced'>
+     C/C++ Remote (Over TCF/TE) Run/Debug Launcher
+     Remote System Explorer User Actions
+     TM Terminal
+     TCF Remote System Explorer add-in
+     TCF Target Explorer
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para>Expand the box next to
+                        "Programming Languages" and select the
+                        following boxes:
+                        <literallayout class='monospaced'>
+     C/C++ Autotools Support
+     C/C++ Development Tools SDK
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para>
+                        Complete the installation by clicking through
+                        appropriate "Next" and "Finish" buttons.
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='mars-installing-the-eclipse-yocto-plug-in'>
+            <title>Installing or Accessing the Mars Eclipse Yocto Plug-in</title>
+
+            <para>
+                You can install the Eclipse Yocto Plug-in into the Eclipse
+                IDE one of two ways:  use the Yocto Project's Eclipse
+                Update site to install the pre-built plug-in or build and
+                install the plug-in from the latest source code.
+            </para>
+
+            <section id='mars-new-software'>
+                <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
+
+                <para>
+                    To install the Mars Eclipse Yocto Plug-in from the update
+                    site, follow these steps:
+                    <orderedlist>
+                        <listitem><para>Start up the Eclipse IDE.
+                            </para></listitem>
+                        <listitem><para>In Eclipse, select "Install New
+                            Software" from the "Help" menu.
+                            </para></listitem>
+                        <listitem><para>Click "Add..." in the "Work with:"
+                            area.
+                            </para></listitem>
+                       <listitem><para>Enter
+                            <filename>&ECLIPSE_DL_PLUGIN_URL;/mars</filename>
+                            in the URL field and provide a meaningful name
+                            in the "Name" field.
+                            </para></listitem>
+                        <listitem><para>Click "OK" to have the entry added
+                            to the "Work with:" drop-down list.
+                            </para></listitem>
+                        <listitem><para>Select the entry for the plug-in
+                            from the "Work with:" drop-down list.
+                            </para></listitem>
+                        <listitem><para>Check the boxes next to the following:
+                            <literallayout class='monospaced'>
+     Yocto Project ADT Plug-in
+     Yocto Project Bitbake Commander Plug-in
+     Yocto Project Documentation plug-in
+                            </literallayout>
+                            </para></listitem>
+                        <listitem><para>Complete the remaining software
+                            installation steps and then restart the Eclipse
+                            IDE to finish the installation of the plug-in.
+                            <note>
+                                You can click "OK" when prompted about
+                                installing software that contains unsigned
+                                content.
+                            </note>
+                            </para></listitem>
+                    </orderedlist>
+                </para>
+            </section>
+
+            <section id='mars-zip-file-method'>
+                <title>Installing the Plug-in Using the Latest Source Code</title>
+
+                <para>
+                    To install the Mars Eclipse Yocto Plug-in from the latest
+                    source code, follow these steps:
+                    <orderedlist>
+                        <listitem><para>Be sure your development system
+                            has JDK 1.7+
+                            </para></listitem>
+                        <listitem><para>install X11-related packages:
+                            <literallayout class='monospaced'>
+     $ sudo apt-get install xauth
+                            </literallayout>
+                            </para></listitem>
+                        <listitem><para>In a new terminal shell, create a Git
+                            repository with:
+                            <literallayout class='monospaced'>
+     $ cd ~
+     $ git clone git://git.yoctoproject.org/eclipse-poky
+                            </literallayout>
+                            </para></listitem>
+                        <listitem><para>Use Git to checkout the correct
+                            tag:
+
+                            <note><title>Developer's Note</title>
+                                <para role='writernotes'>
+                                Because the 2.2 tag will not exist until after
+                                the release, I must first do the following
+                                before running the
+                                <filename>git checkout mars/yocto-&DISTRO;</filename>
+                                command in this step:
+                                <literallayout class='monospaced'>
+     $ git tag mars/yocto-2.2 origin/mars-master
+                                </literallayout></para>
+                            </note>
+
+                            <literallayout class='monospaced'>
+     $ cd ~/eclipse-poky
+     $ git checkout mars/yocto-&DISTRO;
+                            </literallayout>
+                            This puts you in a detached HEAD state, which
+                            is fine since you are only going to be building
+                            and not developing.
+                            </para></listitem>
+                        <listitem><para>Change to the
+                            <filename>scripts</filename>
+                            directory within the Git repository:
+                            <literallayout class='monospaced'>
+     $ cd scripts
+                            </literallayout>
+                            </para></listitem>
+                        <listitem><para>Set up the local build environment
+                            by running the setup script:
+                            <literallayout class='monospaced'>
+     $ ./setup.sh
+                            </literallayout>
+                            When the script finishes execution,
+                            it prompts you with instructions on how to run
+                            the <filename>build.sh</filename> script, which
+                            is also in the <filename>scripts</filename>
+                            directory of the Git repository created
+                            earlier.
+                            </para></listitem>
+                        <listitem><para>Run the <filename>build.sh</filename>
+                            script as directed.
+                            Be sure to provide the tag name, documentation
+                            branch, and a release name.</para>
+                            <para>
+                            Following is an example:
+                            <literallayout class='monospaced'>
+     $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l mars/yocto-&DISTRO; master yocto-&DISTRO; 2>&amp;1 | tee build.log
+                            </literallayout>
+                            The previous example command adds the tag you
+                            need for <filename>mars/yocto-&DISTRO;</filename>
+                            to <filename>HEAD</filename>, then tells the
+                            build script to use the local (-l) Git checkout
+                            for the build.
+                            After running the script, the file
+                            <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename>
+                            is in the current directory.
+                            </para></listitem>
+                        <listitem><para>If necessary, start the Eclipse IDE
+                            and be sure you are in the Workbench.
+                            </para></listitem>
+                        <listitem><para>Select "Install New Software" from
+                            the "Help" pull-down menu.
+                            </para></listitem>
+                        <listitem><para>Click "Add".
+                            </para></listitem>
+                        <listitem><para>Provide anything you want in the
+                            "Name" field.
+                            </para></listitem>
+                        <listitem><para>Click "Archive" and browse to the
+                            ZIP file you built earlier.
+                            This ZIP file should not be "unzipped", and must
+                            be the <filename>*archive.zip</filename> file
+                            created by running the
+                            <filename>build.sh</filename> script.
+                            </para></listitem>
+                        <listitem><para>Click the "OK" button.
+                            </para></listitem>
+                        <listitem><para>Check the boxes that appear in
+                            the installation window to install the
+                            following:
+
+                            <note><title>Developer's Note</title>
+                                <para role='writernotes'>
+                                Right now, a check box for BitBake Commander
+                                is appearing.
+                                This probably needs removed.
+                                Do not check this box.</para>
+                            </note>
+
+                            <literallayout class='monospaced'>
+     Yocto Project SDK Plug-in
+     Yocto Project Documentation plug-in
+                            </literallayout>
+                            </para></listitem>
+                        <listitem><para>Finish the installation by clicking
+                            through the appropriate buttons.
+                            You can click "OK" when prompted about
+                            installing software that contains unsigned
+                            content.
+                            </para></listitem>
+                        <listitem><para>Restart the Eclipse IDE if
+                            necessary.
+                            </para></listitem>
+                    </orderedlist>
+                </para>
+
+                <para>
+                    At this point you should be able to configure the
+                    Eclipse Yocto Plug-in as described in the
+                    "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>"
+                    section.</para>
+            </section>
+        </section>
+
+        <section id='mars-configuring-the-eclipse-yocto-plug-in'>
+            <title>Configuring the Mars Eclipse Yocto Plug-in</title>
+
+            <para>
+                Configuring the Mars Eclipse Yocto Plug-in involves setting the
+                Cross Compiler options and the Target options.
+                The configurations you choose become the default settings
+                for all projects.
+                You do have opportunities to change them later when
+                you configure the project (see the following section).
+            </para>
+
+            <para>
+                To start, you need to do the following from within the
+                Eclipse IDE:
+                <itemizedlist>
+                    <listitem><para>Choose "Preferences" from the
+                        "Window" menu to display the Preferences Dialog.
+                        </para></listitem>
+                    <listitem><para>Click "Yocto Project SDK" to display
+                        the configuration screen.
+                        </para></listitem>
+                </itemizedlist>
+                The following sub-sections describe how to configure the
+                the plug-in.
+                <note>
+                    Throughout the descriptions, a start-to-finish example for
+                    preparing a QEMU image for use with Eclipse is referenced
+                    as the "wiki" and is linked to the example on the
+                    <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>
+                    wiki page.
+                </note>
+            </para>
+
+            <section id='mars-configuring-the-cross-compiler-options'>
+                <title>Configuring the Cross-Compiler Options</title>
+
+                <para>
+                    Cross Compiler options enable Eclipse to use your specific
+                    cross compiler toolchain.
+                    To configure these options, you must select
+                    the type of toolchain, point to the toolchain, specify
+                    the sysroot location, and select the target
+                    architecture.
+                    <itemizedlist>
+                        <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
+                            Choose between
+                            <filename>Standalone pre-built toolchain</filename>
+                            and
+                            <filename>Build system derived toolchain</filename>
+                            for Cross Compiler Options.
+                                <itemizedlist>
+                                    <listitem><para><emphasis>
+                                        <filename>Standalone Pre-built Toolchain:</filename></emphasis>
+                                        Select this type when you are using
+                                        a stand-alone cross-toolchain.
+                                        For example, suppose you are an
+                                        application developer and do not
+                                        need to build a target image.
+                                        Instead, you just want to use an
+                                        architecture-specific toolchain on
+                                        an existing kernel and target root
+                                        filesystem.
+                                        In other words, you have downloaded
+                                        and installed a pre-built toolchain
+                                        for an existing image.
+                                        </para></listitem>
+                                   <listitem><para><emphasis>
+                                        <filename>Build System Derived Toolchain:</filename></emphasis>
+                                        Select this type if you built the
+                                        toolchain as part of the
+                                        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                                        When you select
+                                        <filename>Build system derived toolchain</filename>,
+                                        you are using the toolchain built and
+                                        bundled inside the Build Directory.
+                                        For example, suppose you created a
+                                        suitable image using the steps in the
+                                        <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
+                                        In this situation, you would select the
+                                        <filename>Build system derived toolchain</filename>.
+                                        </para></listitem>
+                                </itemizedlist>
+                            </para></listitem>
+                        <listitem><para><emphasis>Specify the Toolchain Root Location:</emphasis>
+                            If you are using a stand-alone pre-built
+                            toolchain, you should be pointing to where it is
+                            installed (e.g.
+                            <filename>/opt/poky/&DISTRO;</filename>).
+                            See the
+                            "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
+                            section for information about how the SDK is
+                            installed.</para>
+                            <para>If you are using a build system derived
+                            toolchain, the path you provide for the
+                            <filename>Toolchain Root Location</filename>
+                            field is the
+                            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                            from which you run the
+                            <filename>bitbake</filename> command (e.g
+                            <filename>/home/scottrif/poky/build</filename>).</para>
+                            <para>For more information, see the
+                            "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
+                            section.
+                            </para></listitem>
+                        <listitem><para><emphasis>Specify Sysroot Location:</emphasis>
+                            This location is where the root filesystem for
+                            the target hardware resides.
+                            </para>
+                            <para>This location depends on where you
+                            separately extracted and installed the target
+                            filesystem.
+                            As an example, suppose you prepared an image
+                            using the steps in the
+                            <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
+                            If so, the <filename>MY_QEMU_ROOTFS</filename>
+                            directory is found in the
+                            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                            and you would browse to and select that directory
+                            (e.g. <filename>/home/scottrif/build/MY_QEMU_ROOTFS</filename>).
+                            </para>
+                            <para>For more information on how to install the
+                            toolchain and on how to extract and install the
+                            sysroot filesystem, see the
+                            "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
+                            section.
+                            </para></listitem>
+                        <listitem><para><emphasis>Select the Target Architecture:</emphasis>
+                            The target architecture is the type of hardware
+                            you are going to use or emulate.
+                            Use the pull-down
+                            <filename>Target Architecture</filename> menu
+                            to make your selection.
+                            The pull-down menu should have the supported
+                            architectures.
+                            If the architecture you need is not listed in
+                            the menu, you will need to build the image.
+                            See the
+                            "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
+                            section of the Yocto Project Quick Start for
+                            more information.
+                            You can also see the
+                            <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+            </section>
+
+            <section id='mars-configuring-the-target-options'>
+                <title>Configuring the Target Options</title>
+
+                <para>
+                    You can choose to emulate hardware using the QEMU
+                    emulator, or you can choose to run your image on actual
+                    hardware.
+                    <itemizedlist>
+                        <listitem><para><emphasis>QEMU:</emphasis>
+                            Select this option if you will be using the
+                            QEMU emulator.
+                            If you are using the emulator, you also need to
+                            locate the kernel and specify any custom
+                            options.</para>
+                            <para>If you selected the
+                            <filename>Build system derived toolchain</filename>,
+                            the target kernel you built will be located in
+                            the
+                            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                            in
+                            <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>
+                            directory.
+                            As an example, suppose you performed the steps in
+                            the
+                            <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.
+                            In this case, you specify your Build Directory path
+                            followed by the image (e.g.
+                            <filename>/home/scottrif/poky/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>).
+                            </para>
+                            <para>If you selected the standalone pre-built
+                            toolchain, the pre-built image you downloaded is
+                            located in the directory you specified when you
+                            downloaded the image.</para>
+                            <para>Most custom options are for advanced QEMU
+                            users to further customize their QEMU instance.
+                            These options are specified between paired
+                            angled brackets.
+                            Some options must be specified outside the
+                            brackets.
+                            In particular, the options
+                            <filename>serial</filename>,
+                            <filename>nographic</filename>, and
+                            <filename>kvm</filename> must all be outside the
+                            brackets.
+                            Use the <filename>man qemu</filename> command
+                            to get help on all the options and their use.
+                            The following is an example:
+                           <literallayout class='monospaced'>
+    serial ‘&lt;-m 256 -full-screen&gt;’
+                            </literallayout></para>
+                            <para>
+                            Regardless of the mode, Sysroot is already
+                            defined as part of the Cross-Compiler Options
+                            configuration in the
+                            <filename>Sysroot Location:</filename> field.
+                            </para></listitem>
+                        <listitem><para><emphasis>External HW:</emphasis>
+                            Select this option if you will be using actual
+                            hardware.</para></listitem>
+                    </itemizedlist>
+                </para>
+
+                <para>
+                    Click the "Apply" and "OK" to save your plug-in
+                    configurations.
+                </para>
+            </section>
+        </section>
+    </section>
+
+    <section id='mars-creating-the-project'>
+        <title>Creating the Project</title>
+
+        <para>
+            You can create two types of projects:  Autotools-based, or
+            Makefile-based.
+            This section describes how to create Autotools-based projects
+            from within the Eclipse IDE.
+            For information on creating Makefile-based projects in a
+            terminal window, see the
+            "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
+            section.
+            <note>
+                Do not use special characters in project names
+                (e.g. spaces, underscores, etc.).  Doing so can
+                cause configuration to fail.
+            </note>
+        </para>
+
+        <para>
+            To create a project based on a Yocto template and then display
+            the source code, follow these steps:
+            <orderedlist>
+                <listitem><para>Select "C Project" from the "File -> New" menu.
+                    </para></listitem>
+                <listitem><para>Expand <filename>Yocto Project SDK Autotools Project</filename>.
+                    </para></listitem>
+                <listitem><para>Select <filename>Hello World ANSI C Autotools Projects</filename>.
+                    This is an Autotools-based project based on a Yocto
+                    template.
+                    </para></listitem>
+                <listitem><para>Put a name in the <filename>Project name:</filename>
+                    field.
+                    Do not use hyphens as part of the name
+                    (e.g. <filename>hello</filename>).
+                    </para></listitem>
+                <listitem><para>Click "Next".
+                    </para></listitem>
+                <listitem><para>Add appropriate information in the various
+                    fields.
+                    </para></listitem>
+                <listitem><para>Click "Finish".
+                    </para></listitem>
+                <listitem><para>If the "open perspective" prompt appears,
+                    click "Yes" so that you in the C/C++ perspective.
+                    </para></listitem>
+                <listitem><para>The left-hand navigation pane shows your
+                    project.
+                    You can display your source by double clicking the
+                    project's source file.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+
+    <section id='mars-configuring-the-cross-toolchains'>
+        <title>Configuring the Cross-Toolchains</title>
+
+        <para>
+            The earlier section,
+            "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>",
+            sets up the default project configurations.
+            You can override these settings for a given project by following
+            these steps:
+            <orderedlist>
+                <listitem><para>Select "Yocto Project Settings" from
+                    the "Project -> Properties" menu.
+                    This selection brings up the Yocto Project Settings
+                    Dialog and allows you to make changes specific to an
+                    individual project.</para>
+                    <para>By default, the Cross Compiler Options and Target
+                    Options for a project are inherited from settings you
+                    provided using the Preferences Dialog as described
+                    earlier in the
+                    "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>" section.
+                    The Yocto Project Settings Dialog allows you to override
+                    those default settings for a given project.
+                    </para></listitem>
+                <listitem><para>Make or verify your configurations for the
+                    project and click "OK".
+                    </para></listitem>
+                <listitem><para>Right-click in the navigation pane and
+                    select "Reconfigure Project" from the pop-up menu.
+                    This selection reconfigures the project by running
+                    <filename>autogen.sh</filename> in the workspace for
+                    your project.
+                    The script also runs <filename>libtoolize</filename>,
+                    <filename>aclocal</filename>,
+                    <filename>autoconf</filename>,
+                    <filename>autoheader</filename>,
+                    <filename>automake --a</filename>, and
+                    <filename>./configure</filename>.
+                    Click on the "Console" tab beneath your source code to
+                    see the results of reconfiguring your project.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+
+    <section id='mars-building-the-project'>
+        <title>Building the Project</title>
+
+        <para>
+            To build the project select "Build All" from the
+            "Project" menu.
+            The console should update and you can note the cross-compiler
+            you are using.
+            <note>
+                When building "Yocto Project SDK Autotools" projects, the
+                Eclipse IDE might display error messages for
+                Functions/Symbols/Types that cannot be "resolved", even when
+                the related include file is listed at the project navigator and
+                when the project is able to build.
+                For these cases only, it is recommended to add a new linked
+                folder to the appropriate sysroot.
+                Use these steps to add the linked folder:
+                <orderedlist>
+                    <listitem><para>
+                        Select the project.
+                        </para></listitem>
+                    <listitem><para>
+                        Select "Folder" from the
+                        <filename>File > New</filename> menu.
+                        </para></listitem>
+                    <listitem><para>
+                        In the "New Folder" Dialog, select "Link to alternate
+                        location (linked folder)".
+                        </para></listitem>
+                    <listitem><para>
+                        Click "Browse" to navigate to the include folder inside
+                        the same sysroot location selected in the Yocto Project
+                        configuration preferences.
+                        </para></listitem>
+                    <listitem><para>
+                        Click "OK".
+                        </para></listitem>
+                    <listitem><para>
+                        Click "Finish" to save the linked folder.
+                        </para></listitem>
+                </orderedlist>
+            </note>
+        </para>
+    </section>
+
+    <section id='mars-starting-qemu-in-user-space-nfs-mode'>
+        <title>Starting QEMU in User-Space NFS Mode</title>
+
+        <para>
+            To start the QEMU emulator from within Eclipse, follow these
+            steps:
+            <note>
+                See the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>"
+                chapter in the Yocto Project Development Manual
+                for more information on using QEMU.
+            </note>
+            <orderedlist>
+                <listitem><para>Expose and select "External Tools
+                    Configurations ..." from the "Run -> External Tools" menu.
+                    </para></listitem>
+                <listitem><para>
+                    Locate and select your image in the navigation panel to
+                    the left (e.g. <filename>qemu_i586-poky-linux</filename>).
+                    </para></listitem>
+                <listitem><para>
+                    Click "Run" to launch QEMU.
+                    <note>
+                        The host on which you are running QEMU must have
+                        the <filename>rpcbind</filename> utility running to be
+                        able to make RPC calls on a server on that machine.
+                        If QEMU does not invoke and you receive error messages
+                        involving <filename>rpcbind</filename>, follow the
+                        suggestions to get the service running.
+                        As an example, on a new Ubuntu 16.04 LTS installation,
+                        you must do the following in order to get QEMU to
+                        launch:
+                        <literallayout class='monospaced'>
+     $ sudo apt-get install rpcbind
+                        </literallayout>
+                        After installing <filename>rpcbind</filename>, you
+                        need to edit the
+                        <filename>/etc/init.d/rpcbind</filename> file to
+                        include the following line:
+                        <literallayout class='monospaced'>
+     OPTIONS="-i -w"
+                        </literallayout>
+                        After modifying the file, you need to start the
+                        service:
+                        <literallayout class='monospaced'>
+     $ sudo service portmap restart
+                        </literallayout>
+                    </note>
+                    </para></listitem>
+                <listitem><para>If needed, enter your host root password in
+                    the shell window at the prompt.
+                    This sets up a <filename>Tap 0</filename> connection
+                    needed for running in user-space NFS mode.
+                    </para></listitem>
+                <listitem><para>Wait for QEMU to launch.
+                    </para></listitem>
+                <listitem><para>Once QEMU launches, you can begin operating
+                    within that environment.
+                    One useful task at this point would be to determine the
+                    IP Address for the user-space NFS by using the
+                    <filename>ifconfig</filename> command.
+                    The IP address of the QEMU machine appears in the
+                    xterm window.
+                    You can use this address to help you see which particular
+                    IP address the instance of QEMU is using.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+
+    <section id='mars-deploying-and-debugging-the-application'>
+        <title>Deploying and Debugging the Application</title>
+
+        <para>
+            Once the QEMU emulator is running the image, you can deploy
+            your application using the Eclipse IDE and then use
+            the emulator to perform debugging.
+            Follow these steps to deploy the application.
+            <note>
+                Currently, Eclipse does not support SSH port forwarding.
+                Consequently, if you need to run or debug a remote
+                application using the host display, you must create a
+                tunneling connection from outside Eclipse and keep
+                that connection alive during your work.
+                For example, in a new terminal, run the following:
+                <literallayout class='monospaced'>
+     $ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable>
+                </literallayout>
+                Using the above form, here is an example:
+                <literallayout class='monospaced'>
+     $ ssh -XY root@192.168.7.2
+                </literallayout>
+                After running the command, add the command to be executed
+                in Eclipse's run configuration before the application
+                as follows:
+                <literallayout class='monospaced'>
+     export DISPLAY=:10.0
+                </literallayout>
+                Be sure to not destroy the connection during your QEMU
+                session (i.e. do not
+                exit out of or close that shell).
+            </note>
+            <orderedlist>
+                <listitem><para>Select "Debug Configurations..." from the
+                    "Run" menu.</para></listitem>
+                <listitem><para>In the left area, expand
+                    <filename>C/C++Remote Application</filename>.
+                    </para></listitem>
+                <listitem><para>Locate your project and select it to bring
+                    up a new tabbed view in the Debug Configurations Dialog.
+                    </para></listitem>
+                <listitem><para>Click on the "Debugger" tab to see the
+                    cross-tool debugger you are using.
+                    Be sure to change to the debugger perspective in Eclipse.
+                    </para></listitem>
+                <listitem><para>Click on the "Main" tab.
+                    </para></listitem>
+                <listitem><para>Create a new connection to the QEMU instance
+                    by clicking on "new".</para></listitem>
+                <listitem><para>Select <filename>SSH</filename>, which means
+                    Secure Socket Shell.
+                    Optionally, you can select an TCF connection instead.
+                    </para></listitem>
+                <listitem><para>Click "Next".
+                    </para></listitem>
+                <listitem><para>Clear out the "host name" field and enter
+                    the IP Address determined earlier (e.g. 192.168.7.2).
+                    </para></listitem>
+                <listitem><para>Click "Finish" to close the
+                    New Connections Dialog.
+                    </para></listitem>
+                <listitem><para>If necessary, use the drop-down menu now in the
+                    "Connection" field and pick the IP Address you entered.
+                     </para></listitem>
+                <listitem><para>Assuming you are connecting as the root user,
+                    which is the default for QEMU x86-64 SDK images provided by
+                    the Yocto Project, in the "Remote Absolute File Path for
+                    C/C++ Application" field, browse to
+                    <filename>/home/root</filename>.
+                    You could also browse to any other path you have write
+                    access to on the target such as
+                    <filename>/usr/bin</filename>.
+                    This location is where your application will be located on
+                    the QEMU system.
+                    If you fail to browse to and specify an appropriate
+                    location, QEMU will not understand what to remotely
+                    launch.
+                    Eclipse is helpful in that it auto fills your application
+                    name for you assuming you browsed to a directory.
+                    <note>
+                        If you are prompted to provide a username and to
+                        optionally set a password, be sure you provide
+                        "root" as the username and you leave the password
+                        field blank.
+                    </note>
+                    </para></listitem>
+                <listitem><para>
+                    Be sure you change to the "Debug" perspective in Eclipse.
+                    </para></listitem>
+                <listitem><para>Click "Debug"
+                    </para></listitem>
+                <listitem><para>Accept the debug perspective.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+
+    <section id='mars-using-Linuxtools'>
+        <title>Using Linuxtools</title>
+
+        <para>
+            As mentioned earlier in the manual, performance tools exist
+            (Linuxtools) that enhance your development experience.
+            These tools are aids in developing and debugging applications and
+            images.
+            You can run these tools from within the Eclipse IDE through the
+            "Linuxtools" menu.
+        </para>
+
+        <para>
+            For information on how to configure and use these tools, see
+            <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
+        </para>
+    </section>
+</appendix>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/sdk-manual/sdk-intro.xml b/documentation/sdk-manual/sdk-intro.xml
index 781cebf188..0995f79a93 100644
--- a/documentation/sdk-manual/sdk-intro.xml
+++ b/documentation/sdk-manual/sdk-intro.xml
@@ -113,8 +113,9 @@
                 of the SDK but is rather available for use as part of the
                 development process.
                 </para></listitem>
-            <listitem><para>Various user-space tools that greatly enhance
-                your application development experience.
+            <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>
@@ -196,9 +197,16 @@
             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 a suite of tools that allows you to
-            perform remote profiling, tracing, collection of power data,
-            collection of latency data, and collection of performance data.
+            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 beginning with this release
+                of the plug-in.
+            </note>
         </para>
 
         <para>
@@ -210,54 +218,15 @@
         </para>
     </section>
 
-    <section id='user-space-tools'>
-        <title>User-Space Tools</title>
+    <section id='performance-enhancing-tools'>
+        <title>Performance Enhancing Tools</title>
 
         <para>
-            User-space tools, which are available as part of the SDK
-            development environment, can be helpful.
-            The tools include LatencyTOP, PowerTOP, Perf, SystemTap,
-            and Lttng-ust.
-            These tools are common development tools for the Linux platform.
-            <itemizedlist>
-                <listitem><para><emphasis>LatencyTOP:</emphasis> LatencyTOP
-                    focuses on latency that causes skips in audio, stutters in
-                    your desktop experience, or situations that overload your
-                    server even when you have plenty of CPU power left.
-                    </para></listitem>
-                <listitem><para><emphasis>PowerTOP:</emphasis> Helps you
-                    determine what software is using the most power.
-                    You can find out more about PowerTOP at
-                    <ulink url='https://01.org/powertop/'></ulink>.</para></listitem>
-                <listitem><para><emphasis>Perf:</emphasis> Performance counters
-                    for Linux used to keep track of certain types of hardware
-                    and software events.
-                    For more information on these types of counters see
-                    <ulink url='https://perf.wiki.kernel.org/'></ulink>.
-                    For examples on how to setup and use this tool, see the
-                    "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>"
-                    section in the Yocto Project Profiling and Tracing Manual.
-                    </para></listitem>
-                <listitem><para><emphasis>SystemTap:</emphasis> A free software
-                    infrastructure that simplifies information gathering about
-                    a running Linux system.
-                    This information helps you diagnose performance or
-                    functional problems.
-                    SystemTap is not available as a user-space tool through
-                    the Eclipse IDE Yocto Plug-in.
-                    See <ulink url='http://sourceware.org/systemtap'></ulink>
-                    for more information on SystemTap.
-                    For examples on how to setup and use this tool, see the
-                    "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-systemtap'>SystemTap</ulink>"
-                    section in the Yocto Project Profiling and Tracing Manual.
-                    </para></listitem>
-                <listitem><para><emphasis>Lttng-ust:</emphasis> A User-space
-                    Tracer designed to provide detailed information on
-                    user-space activity.
-                    See <ulink url='http://lttng.org/ust'></ulink> for more
-                    information on Lttng-ust.
-                    </para></listitem>
-            </itemizedlist>
+            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>
diff --git a/documentation/sdk-manual/sdk-manual.xml b/documentation/sdk-manual/sdk-manual.xml
index b690a14012..39a8689195 100644
--- a/documentation/sdk-manual/sdk-manual.xml
+++ b/documentation/sdk-manual/sdk-manual.xml
@@ -74,6 +74,8 @@
 
     <xi:include href="sdk-appendix-customizing.xml"/>
 
+    <xi:include href="sdk-appendix-mars.xml"/>
+
 <!--    <index id='index'>
       <title>Index</title>
     </index>
diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml
index 9354ace3b9..f8e2f005bd 100644
--- a/documentation/sdk-manual/sdk-using.xml
+++ b/documentation/sdk-manual/sdk-using.xml
@@ -533,10 +533,10 @@
                     </para></listitem>
                 <listitem><para><emphasis>Test and debug the application</emphasis>:
                     Once your application is deployed, you need to test it.
-                    Within the Eclipse IDE, you can use the debugging environment along with the
-                    set of installed user-space tools to debug your application.
-                    Of course, the same user-space tools are available separately if you choose
-                    not to use the Eclipse IDE.</para></listitem>
+                    Within the Eclipse IDE, you can use the debugging
+                    environment along with supported performance enhancing
+                    <ulink url='http://www.eclipse.org/linuxtools/'>tools</ulink>.
+                    </para></listitem>
            </orderedlist>
         </para>
     </section>
@@ -565,9 +565,11 @@
             execution of your output into a QEMU emulation session as well as
             actual target hardware.
             You can also perform cross-debugging and profiling.
-            The environment also supports a suite of tools that allows you
-            to perform remote profiling, tracing, collection of power data,
-            collection of latency data, and collection of performance data.
+            The environment also supports performance enhancing
+            <ulink url='http://www.eclipse.org/linuxtools/'>tools</ulink> that
+            allow you to perform remote profiling, tracing, collection of
+            power data, collection of latency data, and collection of
+            performance data.
         </para>
 
         <para>
@@ -1317,144 +1319,18 @@
             </para>
         </section>
 
-        <section id='running-user-space-tools'>
-            <title>Running User-Space Tools</title>
+        <section id='running-performance-tools'>
+            <title>Running Performance Tools</title>
 
             <para>
                 As mentioned earlier in the manual, several tools exist that
                 enhance your development experience.
                 These tools are aids in developing and debugging applications
                 and images.
-                You can run these user-space tools from within the Eclipse
+                You can run these tools from within the Eclipse
                 IDE through the "YoctoProjectTools" menu.
-            </para>
-
-            <para>
-                Once you pick a tool, you need to configure it for the remote
-                target.
-                Every tool needs to have the connection configured.
-                You must select an existing TCF-based RSE connection to the
-                remote target.
-                If one does not exist, click "New" to create one.
-            </para>
-
-            <para>
-                Here are some specifics about the remote tools:
-                <itemizedlist>
-                    <listitem><para><emphasis><filename>Lttng2.0 trace import</filename>:</emphasis>
-                        Selecting this tool transfers the remote target's
-                        <filename>Lttng</filename> tracing data back to the
-                        local host machine and uses the Lttng Eclipse plug-in
-                        to graphically display the output.
-                        For information on how to use Lttng to trace an
-                        application,
-                        see <ulink url='http://lttng.org/documentation'></ulink>
-                        and the
-                        "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>"
-                        section, which is in the Yocto Project Profiling and
-                        Tracing Manual.
-                        <note>Do not use
-                            <filename>Lttng-user space (legacy)</filename> tool.
-                            This tool no longer has any upstream support.</note>
-                        </para>
-                        <para>Before you use the
-                        <filename>Lttng2.0 trace import</filename> tool,
-                        you need to setup the Lttng Eclipse plug-in and create a
-                        Tracing project.
-                        Do the following:
-                        <orderedlist>
-                            <listitem><para>Select "Open Perspective" from the
-                                "Window" menu and then select "Other..." to
-                                bring up a menu of other perspectives.
-                                Choose "Tracing".
-                                </para></listitem>
-                            <listitem><para>Click "OK" to change the Eclipse
-                                perspective into the Tracing perspective.
-                                </para></listitem>
-                            <listitem><para>Create a new Tracing project by
-                                selecting "Project" from the "File -> New" menu.
-                                </para></listitem>
-                            <listitem><para>Choose "Tracing Project" from the
-                                "Tracing" menu and click "Next".
-                                </para></listitem>
-                            <listitem><para>Provide a name for your tracing
-                                project and click "Finish".
-                                </para></listitem>
-                            <listitem><para>Generate your tracing data on the
-                                remote target.</para></listitem>
-                            <listitem><para>Select "Lttng2.0 trace import"
-                                from the "Yocto Project Tools" menu to
-                                start the data import process.</para></listitem>
-                            <listitem><para>Specify your remote connection name.
-                                </para></listitem>
-                            <listitem><para>For the Ust directory path, specify
-                                the location of your remote tracing data.
-                                Make sure the location ends with
-                                <filename>ust</filename> (e.g.
-                                <filename>/usr/mysession/ust</filename>).
-                                </para></listitem>
-                            <listitem><para>Click "OK" to complete the import
-                                process.
-                                The data is now in the local tracing project
-                                you created.</para></listitem>
-                            <listitem><para>Right click on the data and then use
-                                the menu to Select "Generic CTF Trace" from the
-                                "Trace Type... -> Common Trace Format" menu to
-                                map the tracing type.</para></listitem>
-                            <listitem><para>Right click the mouse and select
-                                "Open" to bring up the Eclipse Lttng Trace
-                                Viewer so you view the tracing data.
-                                </para></listitem>
-                        </orderedlist></para></listitem>
-                    <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis>
-                        Selecting this tool runs PowerTOP on the remote target
-                        machine and displays the results in a new view called
-                        PowerTOP.</para>
-                        <para>The "Time to gather data(sec):" field is the time
-                        passed in seconds before data is gathered from the
-                        remote target for analysis.</para>
-                        <para>The "show pids in wakeups list:" field corresponds
-                        to the <filename>-p</filename> argument passed to
-                        <filename>PowerTOP</filename>.</para></listitem>
-                    <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis>
-                        LatencyTOP identifies system latency, while
-                        Perf monitors the system's performance counter
-                        registers.
-                        Selecting either of these tools causes an RSE terminal
-                        view to appear from which you can run the tools.
-                        Both tools refresh the entire screen to display results
-                        while they run.
-                        For more information on setting up and using
-                        <filename>perf</filename>, see the
-                        "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>"
-                        section in the Yocto Project Profiling and Tracing
-                        Manual.
-                        </para></listitem>
-                    <listitem><para><emphasis><filename>SystemTap</filename>:</emphasis>
-                        Systemtap is a tool that lets you create and reuse
-                        scripts to examine the activities of a live Linux
-                        system.
-                        You can easily extract, filter, and summarize data
-                        that helps you diagnose complex performance or
-                        functional problems.
-                        For more information on setting up and using
-                        <filename>SystemTap</filename>, see the
-                        <ulink url='https://sourceware.org/systemtap/documentation.html'>SystemTap Documentation</ulink>.
-                        </para></listitem>
-                    <listitem><para><emphasis><filename>yocto-bsp</filename>:</emphasis>
-                        The <filename>yocto-bsp</filename> tool lets you
-                        quickly set up a Board Support Package (BSP) layer.
-                        The tool requires a Metadata location, build location,
-                        BSP name, BSP output location, and a kernel
-                        architecture.
-                        For more information on the
-                        <filename>yocto-bsp</filename> tool outside of Eclipse,
-                        see the
-                        "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a new BSP Layer Using the yocto-bsp Script</ulink>"
-                        section in the Yocto Project Board Support Package
-                        (BSP) Developer's Guide.
-                        </para></listitem>
-                </itemizedlist>
+                For more information on these tools, see
+                <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.
             </para>
         </section>
     </section>