[Feature]add MT2731_MP2_MR2_SVN388 baseline version
Change-Id: Ief04314834b31e27effab435d3ca8ba33b499059
diff --git a/meta/poky/documentation/sdk-manual/sdk-eclipse-project.xml b/meta/poky/documentation/sdk-manual/sdk-eclipse-project.xml
new file mode 100644
index 0000000..15a9ae7
--- /dev/null
+++ b/meta/poky/documentation/sdk-manual/sdk-eclipse-project.xml
@@ -0,0 +1,1248 @@
+<!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-eclipse-project'>
+
+ <title>Developing Applications Using <trademark class='trade'>Eclipse</trademark></title>
+
+ <para>
+ If you are familiar with the popular Eclipse IDE, you can use an
+ Eclipse Yocto Plug-in to allow you to develop, deploy, and test your
+ application all from within Eclipse.
+ This chapter describes general workflow using the SDK and Eclipse
+ and how to configure and set up Eclipse.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ This chapter assumes development of applications on top of
+ an image prepared using the Yocto Project.
+ As such, inclusion of a pre-built image or the building of
+ an image is included in the workflow.
+ </para></listitem>
+ <listitem><para>
+ The chapter also assumes development on a build host that
+ is set up to use the Yocto Project.
+ Realize that you can easily use Eclipse and the Yocto
+ Project plug-in to develop an application for any number
+ of images developed and tested on different machines.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <section id='application-development-workflow-using-eclipse'>
+ <title>Application Development Workflow Using <trademark class='trade'>Eclipse</trademark></title>
+
+ <para>
+ The following figure and supporting list summarize a
+ general workflow for application development that uses the
+ SDK within the Eclipse IDE.
+ The application developed runs on top of an image created using
+ the Yocto Project.
+ </para>
+
+ <para>
+ <imagedata fileref="figures/sdk-eclipse-dev-flow.png"
+ width="7in" depth="7in" align="center" scale="100" />
+ </para>
+
+ <para>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Prepare the Host System for the Yocto Project</emphasis>:
+ Because this example workflow assumes development on a
+ system set up to use the Yocto Project, you need to be
+ sure your
+ <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
+ can use the Yocto Project.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"
+ section in the Yocto Project Development Tasks Manual for
+ information on how to set up your build host.
+ <note>
+ Be sure you install the "xterm" package, which is a
+ <ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host'>graphical and Eclipse plug-in extra</ulink>
+ needed by Eclipse.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Secure the Yocto Project Kernel Target Image</emphasis>:
+ This example workflow assumes application development on
+ top of an image built using the Yocto Project.
+ Depending on whether you are using a pre-built image
+ that matches your target architecture or you are using an
+ image you build using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded Build System</ulink>
+ and where you are going to run the image while you
+ develop your application (QEMU or real hardware), the
+ area from which you get the image differs.
+ <itemizedlist>
+ <listitem><para>
+ Download the image from
+ <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
+ if your target architecture is supported and
+ you are going to develop and test your
+ application on actual hardware.
+ </para></listitem>
+ <listitem><para>
+ Download the image from
+ <ulink url='&YOCTO_QEMU_DL_URL;'>
+ <filename>machines/qemu</filename></ulink> if
+ your target architecture is supported and you
+ are going to develop and test your application
+ using the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>QEMU Emulator</ulink>.
+ </para></listitem>
+ <listitem><para>
+ Build your image if you cannot find a pre-built
+ image that matches your target architecture.
+ If your target architecture is similar to a
+ supported architecture, you can modify the
+ kernel image before you build it.
+ See the
+ "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</ulink>"
+ section in the Yocto Project Linux Kernel
+ Development Manual for an example.
+ You can also see the
+ "<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage#Making_a_Suitable_Qemux86_Image'>Making a Suitable Qemux86 Image</ulink>"
+ wiki for steps needed to build an image suitable
+ for QEMU and for debugging within the Eclipse IDE.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem>
+ <para><emphasis>Install the SDK</emphasis>:
+ The SDK provides a target-specific cross-development
+ toolchain, the root filesystem, the QEMU emulator, and
+ other tools that can help you develop your application.
+ 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>Secure the Target Root Filesystem and the Cross-Development Toolchain</emphasis>:
+ You need to find and download the appropriate root
+ filesystem and the cross-development toolchain.</para>
+
+ <para>You can find the tarballs for the root filesystem
+ in the same area used for the kernel image.
+ Depending on the type of image you are running, the
+ root filesystem you need differs.
+ For example, if you are developing an application that
+ runs on an image that supports Sato, you need to get a
+ root filesystem that supports Sato.</para>
+
+ <para>You can find the cross-development toolchains at
+ <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>.
+ Be sure to get the correct toolchain for your
+ development host and your target architecture.
+ See the "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>"
+ section for information and the
+ "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"
+ section for installation information.
+ <note>
+ As an alternative to downloading an SDK, you can
+ build the SDK installer.
+ For information on building the installer, see the
+ "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"
+ section.
+ Another helpful resource for building an installer
+ is the
+ "<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink>"
+ wiki page.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create and Build Your Application</emphasis>:
+ You need to have source files for your application.
+ Once you have the files, you can use the Eclipse IDE
+ to import them and build the project.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Deploy the Image With the Application</emphasis>:
+ Using the Eclipse IDE, you can deploy your image to the
+ hardware or to QEMU through the project's preferences.
+ You can also use Eclipse to load and test your image
+ under QEMU.
+ 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.
+ </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 supported performance enhancing
+ <ulink url='http://www.eclipse.org/linuxtools/'>Linux Tools</ulink>.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='adt-eclipse'>
+ <title>Working Within Eclipse</title>
+
+ <para>
+ The Eclipse IDE is a popular development environment and it
+ fully supports development using the Yocto Project.
+ </para>
+
+ <para>
+ 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 as well
+ as actual target hardware.
+ You can also perform cross-debugging and profiling.
+ 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.
+ <note>
+ This release of the Yocto Project supports both the Oxygen
+ and Neon versions of the Eclipse IDE.
+ This section provides information on how to use the Oxygen
+ release with the Yocto Project.
+ For information on how to use the Neon version of Eclipse
+ with the Yocto Project, see
+ "<link linkend='sdk-appendix-neon-yp-eclipse-plug-in'>Appendix D</link>".
+ </note>
+ </para>
+
+ <section id='oxygen-setting-up-the-eclipse-ide'>
+ <title>Setting Up the Oxygen Version of the Eclipse IDE</title>
+
+ <para>
+ To develop within the Eclipse IDE, you need to do the
+ following:
+ <orderedlist>
+ <listitem><para>
+ Install the Oxygen 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='oxygen-installing-eclipse-ide'>
+ <title>Installing the Oxygen Eclipse IDE</title>
+
+ <para>
+ Follow these steps to locate, install, and configure
+ Oxygen Eclipse:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Locate the Oxygen Download:</emphasis>
+ Open a browser and go to
+ <ulink url='http://www.eclipse.org/oxygen/'>http://www.eclipse.org/oxygen/</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Download the Tarball:</emphasis>
+ Click through the "Download" buttons to
+ download the file.
+ </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-inst-linux64.tar.gz
+ </literallayout>
+ Everything unpacks into a folder named
+ "eclipse-installer".
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Launch the Installer:</emphasis>
+ Use the following commands to launch the
+ installer:
+ <literallayout class='monospaced'>
+ $ cd ~/eclipse-installer
+ $ ./eclipse-inst
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Select Your IDE:</emphasis>
+ From the list, select the "Eclipse IDE for
+ C/C++ Developers".
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Install the Software:</emphasis>
+ Click "Install" to begin the installation.
+ Accept all the certificates and any license
+ agreements.
+ Click "Install" again to finish the installation.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Launch Oxygen:</emphasis>
+ Accept the default "workspace" and click the
+ "Launch" button.
+ You should see the Eclipse welcome page from which
+ can click "workbench" to enter your workspace.
+ <note>
+ The executable for Eclipse is located in the
+ <filename>eclipse/cpp-oxygen/eclipse</filename>
+ folder.
+ To launch Eclipse outside of the installation
+ process, simply execute that binary.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ ~/eclipse/cpp-oxygen/eclipse/eclipse
+ </literallayout>
+ </note>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='oxygen-configuring-the-eclipse-ide'>
+ <title>Configuring the Oxygen Eclipse IDE</title>
+
+ <para>
+ Follow these steps to configure the Oxygen Eclipse IDE.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ Depending on how you installed Eclipse and what
+ you have already done, some of the options do
+ not appear.
+ If you cannot find an option as directed by the
+ manual, it has already been installed.
+ </para></listitem>
+ <listitem><para>
+ If you want to see all options regardless of
+ whether they are installed or not, deselect the
+ "Hide items that are already installed"
+ check box.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ <orderedlist>
+ <listitem><para>
+ Be sure Eclipse is running and you are in your
+ workbench.
+ Just click "workbench" if you are not in your
+ default workspace.
+ </para></listitem>
+ <listitem><para>
+ Select "Install New Software" from the "Help"
+ pull-down menu.
+ </para></listitem>
+ <listitem><para>
+ Select
+ "Oxygen - http://download.eclipse.org/releases/oxygen"
+ from the "Work with:" pull-down menu.
+ </para></listitem>
+ <listitem><para>
+ Expand the box next to "Linux Tools" and select
+ the following:
+ <literallayout class='monospaced'>
+ C/C++ Remote (Over TCF/TE) Run/Debug Launcher
+ TM Terminal
+ </literallayout>
+ </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 box:
+ <literallayout class='monospaced'>
+ C/C++ Development Tools SDK
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Complete the installation by clicking through
+ appropriate "Next" and "Finish" buttons and then
+ restart the Eclipse IDE.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='oxygen-installing-the-eclipse-yocto-plug-in'>
+ <title>Installing or Accessing the Oxygen 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='oxygen-new-software'>
+ <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
+
+ <para>
+ To install the Oxygen 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;/oxygen</filename>
+ in the URL field and provide a meaningful
+ name in the "Name" field.
+ </para></listitem>
+ <listitem><para>
+ Click "OK" to have the entry automatically
+ populate the "Work with:" field and to have
+ the items for installation appear in the window
+ below.
+ </para></listitem>
+ <listitem><para>
+ Check the boxes next to the following:
+ <literallayout class='monospaced'>
+ Yocto Project SDK 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='oxygen-zip-file-method'>
+ <title>Installing the Plug-in Using the Latest Source Code</title>
+
+ <para>
+ To install the Oxygen Eclipse Yocto Plug-in from the
+ latest source code, follow these steps:
+ <orderedlist>
+ <listitem><para>
+ Be sure your build host has JDK version 1.8
+ or greater.
+ On a Linux build host you can determine the
+ version using the following command:
+ <literallayout class='monospaced'>
+ $ java -version
+ </literallayout>
+ </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-yocto
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Use Git to create the correct tag:
+ <literallayout class='monospaced'>
+ $ cd ~/eclipse-yocto
+ $ git checkout -b oxygen/&DISTRO_NAME_NO_CAP; remotes/origin/oxygen/&DISTRO_NAME_NO_CAP;
+ </literallayout>
+ This creates a local tag named
+ <filename>oxygen/&DISTRO_NAME_NO_CAP;</filename>
+ based on the branch
+ <filename>origin/oxygen/&DISTRO_NAME_NO_CAP;</filename>.
+ You are put into 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-yocto/scripts/eclipse ./build.sh -l oxygen/&DISTRO_NAME_NO_CAP; master yocto-&DISTRO; 2>&1 | tee build.log
+ </literallayout>
+ The previous example command adds the tag
+ you need for
+ <filename>oxygen/&DISTRO_NAME_NO_CAP;</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:
+ <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='oxygen-configuring-the-eclipse-yocto-plug-in'>Configuring the Oxygen Eclipse Yocto Plug-in</link>"
+ section.
+ </para>
+ </section>
+ </section>
+
+ <section id='oxygen-configuring-the-eclipse-yocto-plug-in'>
+ <title>Configuring the Oxygen Eclipse Yocto Plug-In</title>
+
+ <para>
+ Configuring the Oxygen 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:
+ <orderedlist>
+ <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>
+ </orderedlist>
+ The following sub-sections describe how to configure
+ 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='oxygen-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 "Standalone pre-built toolchain"
+ and "Build system derived toolchain" for
+ Cross Compiler Options.
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Standalone Pre-built Toolchain:</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>Build System Derived Toolchain:</emphasis>
+ Select this type if you built the
+ toolchain as part of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>.
+ When you select "Build system derived
+ toolchain", 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
+ "Build system derived toolchain".
+ </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 "Toolchain Root Location" field is the
+ <ulink url='&YOCTO_DOCS_REF_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 when you either built
+ it or downloaded it.
+ <note>
+ If you downloaded the root filesystem
+ for the target hardware rather than
+ built it, you must download the
+ <filename>sato-sdk</filename> image
+ in order to build any c/c++ projects.
+ </note>
+ 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 Build Directory
+ and you would browse to and select that
+ directory (e.g.
+ <filename>/home/scottrif/poky/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 "Target Architecture"
+ 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_DEV_URL;#dev-building-a-simple-image'>Building a Simple Image</ulink>"
+ section of the Yocto Project Development Tasks
+ Manual 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='oxygen-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 Build system derived
+ toolchain, the target kernel you built will be
+ located in the
+ <ulink url='&YOCTO_DOCS_REF_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/build/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 ‘<-m 256 -full-screen>’
+ </literallayout>
+ Regardless of the mode, Sysroot is already
+ defined as part of the Cross-Compiler
+ Options configuration in the "Sysroot
+ Location:" 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 "Apply and Close" to save your plug-in
+ configurations.
+ </para>
+ </section>
+ </section>
+ </section>
+
+ <section id='oxygen-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/C++ Project" from the "File -> New" menu.
+ </para></listitem>
+ <listitem><para>
+ Select "C Managed Build" from the available options and
+ click "Next".
+ </para></listitem>
+ <listitem><para>
+ Expand "Yocto Project SDK Autotools Project".
+ </para></listitem>
+ <listitem><para>
+ Select "Hello World ANSI C Autotools Projects".
+ This is an Autotools-based project based on a Yocto
+ template.
+ </para></listitem>
+ <listitem><para>
+ Put a name in the "Project name:" field.
+ Do not use hyphens as part of the name
+ (e.g. "hello").
+ </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='oxygen-configuring-the-cross-toolchains'>
+ <title>Configuring the Cross-Toolchains</title>
+
+ <para>
+ The earlier section,
+ "<link linkend='oxygen-configuring-the-eclipse-yocto-plug-in'>Configuring the Oxygen 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='oxygen-configuring-the-eclipse-yocto-plug-in'>Configuring the Oxygen 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 "Apply and Close".
+ </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
+ <ulink url='https://en.wikipedia.org/wiki/GNU_Build_System'>Autotools GNU utility programs</ulink>
+ such as Autoconf, Automake, and so forth in the
+ workspace for your project.
+ Click on the "Console" tab beneath your source code
+ to see the results of reconfiguring your project.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='oxygen-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 (i.e.
+ <filename>i586-poky-linux-gcc</filename> in this example).
+ <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 "File -> New" menu.
+ </para></listitem>
+ <listitem><para>
+ In the "New Folder" Dialog, click the "Advanced"
+ button and then activate "Link to
+ alternate location (linked folder)" button.
+ </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 "Finish" to save the linked folder.
+ </para></listitem>
+ </orderedlist>
+ </note>
+ </para>
+ </section>
+
+ <section id='oxygen-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 Tasks 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 a new
+ shell 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='oxygen-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
+ "C/C++Remote Application".
+ </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 "SSH", which
+ means Secure Socket Shell and then click "OK".
+ Optionally, you can select a TCF connection
+ instead.
+ </para></listitem>
+ <listitem><para>
+ Clear out the "Connection name" field and
+ enter any name you want for the connection.
+ </para></listitem>
+ <listitem><para>
+ Put the IP address for the connection in
+ the "Host" field.
+ For QEMU, the default is "192.168.7.2".
+ However, if a previous QEMU session did not exit
+ cleanly, the IP address increments (e.g.
+ "192.168.7.3").
+ <note>
+ You can find the IP address for the current
+ QEMU session by looking in the xterm that
+ opens when you launch QEMU.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ Enter "root", which
+ is the default for QEMU, for the "User" field.
+ Be sure to leave the password field empty.
+ </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><replaceable>ProjectName</replaceable>
+ (e.g. <filename>/home/root/hello</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><title>Tips</title>
+ <itemizedlist>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ If browsing to a directory fails or times
+ out, but you can
+ <filename>ssh</filename> into your QEMU
+ or target from the command line and you
+ have proxies set up, it is likely that
+ Eclipse is sending the SSH traffic to a
+ proxy.
+ In this case, either use TCF , or click on
+ "Configure proxy settings" in the
+ connection dialog and add the target IP
+ address to the "bypass proxy" section.
+ You might also need to change
+ "Active Provider" from Native to Manual.
+ </para></listitem>
+ </itemizedlist>
+ </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='oxygen-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>
+ </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->