[gnome-continuous-yocto/gnomeostree-3.28-rocko: 2104/8267] sdk-manual: Created new Mars Eclipse appendix
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-continuous-yocto/gnomeostree-3.28-rocko: 2104/8267] sdk-manual: Created new Mars Eclipse appendix
- Date: Sat, 16 Dec 2017 22:45:41 +0000 (UTC)
commit 4d5dc4a8908c4f67268f2058e1ea6d76f72ca0ef
Author: Scott Rifenbark <srifenbark gmail com>
Date: Fri Aug 12 10:20:16 2016 -0700
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>
documentation/sdk-manual/sdk-appendix-mars.xml | 878 ++++++++++++++++++++++++
documentation/sdk-manual/sdk-intro.xml | 71 +--
documentation/sdk-manual/sdk-manual.xml | 2 +
documentation/sdk-manual/sdk-using.xml | 152 +----
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 0000000..185dd42
--- /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>&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 ‘<-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='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 781cebf..0995f79 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 b690a14..39a8689 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 9354ace..f8e2f00 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>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
