Yocto 2.4
Move OpenBMC to Yocto 2.4(rocko)
Tested: Built and verified Witherspoon and Palmetto images
Change-Id: I12057b18610d6fb0e6903c60213690301e9b0c67
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-eclipse-project.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-eclipse-project.xml
new file mode 100644
index 0000000..bdb8344
--- /dev/null
+++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-eclipse-project.xml
@@ -0,0 +1,1211 @@
+<!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.
+ </para>
+
+ <section id='workflow-using-eclipse'>
+ <title>Workflow Using <trademark class='trade'>Eclipse</trademark></title>
+
+ <para>
+ The following figure and supporting list summarize the
+ application development general workflow that employs both the
+ SDK Eclipse.
+ </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>:
+ See
+ "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
+ and
+ "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
+ sections both in the Yocto Project Reference Manual for
+ requirements.
+ In particular, be sure your host system has the
+ <filename>xterm</filename> package installed.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Secure the Yocto Project kernel target
+ image</emphasis>:
+ You must have a target kernel image that has been built
+ using the OpenEmbedded build system.</para>
+ <para>Depending on whether the Yocto Project has a
+ pre-built image that matches your target architecture
+ 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 QEMU emulator.
+ </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.
+ </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>:
+ At this point, 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.
+ If you are not using Eclipse, you need to use the
+ cross-development tools you have installed to create
+ the image.</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 Neon
+ and Mars versions of the Eclipse IDE.
+ This section provides information on how to use the Neon
+ release with the Yocto Project.
+ For information on how to use the Mars version of Eclipse
+ with the Yocto Project, see
+ "<link linkend='sdk-appendix-latest-yp-eclipse-plug-in'>Appendix C</link>.
+ </note>
+ </para>
+
+ <section id='neon-setting-up-the-eclipse-ide'>
+ <title>Setting Up the Neon Version of the Eclipse IDE</title>
+
+ <para>
+ To develop within the Eclipse IDE, you need to do the
+ following:
+ <orderedlist>
+ <listitem><para>
+ Install the Neon 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='neon-installing-eclipse-ide'>
+ <title>Installing the Neon Eclipse IDE</title>
+
+ <para>
+ Follow these steps to locate, install, and configure
+ Neon Eclipse:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Locate the Neon Download:</emphasis>
+ Open a browser and go to
+ <ulink url='http://www.eclipse.org/neon/'>http://www.eclipse.org/neon/</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>
+ Accept the default "cpp-neon" directory and
+ click "Install".
+ Accept any license agreements and approve any
+ certificates.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Launch Neon:</emphasis>
+ Click the "Launch" button and accept the
+ default "workspace".
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='neon-configuring-the-mars-eclipse-ide'>
+ <title>Configuring the Neon Eclipse IDE</title>
+
+ <para>
+ Follow these steps to configure the Neon 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
+ "Neon - http://download.eclipse.org/releases/neon"
+ 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.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='neon-installing-the-eclipse-yocto-plug-in'>
+ <title>Installing or Accessing the Neon 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='neon-new-software'>
+ <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
+
+ <para>
+ To install the Neon 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;/neon</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 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='neon-zip-file-method'>
+ <title>Installing the Plug-in Using the Latest Source Code</title>
+
+ <para>
+ To install the Neon Eclipse Yocto Plug-in from the
+ latest source code, follow these steps:
+ <orderedlist>
+ <listitem><para>
+ Be sure your development system
+ has JDK 1.8+
+ </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 create the correct tag:
+ <literallayout class='monospaced'>
+ $ cd ~/eclipse-poky
+ $ git checkout neon/yocto-&DISTRO;
+ </literallayout>
+ This creates a local tag named
+ <filename>neon/yocto-&DISTRO;</filename>
+ based on the branch
+ <filename>origin/neon-master</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-poky/scripts/eclipse ./build.sh -l neon/yocto-&DISTRO; master yocto-&DISTRO; 2>&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:
+ <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 Neon Eclipse Yocto Plug-in</link>"
+ section.
+ </para>
+ </section>
+ </section>
+
+ <section id='neon-configuring-the-eclipse-yocto-plug-in'>
+ <title>Configuring the Neon Eclipse Yocto Plug-in</title>
+
+ <para>
+ Configuring the Neon 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 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='neon-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_REF_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_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
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ 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
+ <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='neon-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_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></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='neon-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='neon-configuring-the-cross-toolchains'>
+ <title>Configuring the Cross-Toolchains</title>
+
+ <para>
+ The earlier section,
+ "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon 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='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon 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='neon-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='neon-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
+ 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='neon-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 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
+ <filename>192.168.7.2</filename>.
+ However, if a previous QEMU session did not exit
+ cleanly, the IP address increments (e.g.
+ <filename>192.168.7.3</filename>).
+ <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 <filename>root</filename>, 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='neon-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
+-->