diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2016-08-12 10:20:16 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2016-08-25 23:09:27 +0100 |
commit | 4d5dc4a8908c4f67268f2058e1ea6d76f72ca0ef (patch) | |
tree | 3489d42ca80e9fdb6272d09341c2069b01188ac5 /documentation | |
parent | a3f519e19399e239cf1efde523af426f6a519d4f (diff) | |
download | openembedded-core-contrib-4d5dc4a8908c4f67268f2058e1ea6d76f72ca0ef.tar.gz |
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>
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/sdk-manual/sdk-appendix-mars.xml | 878 | ||||
-rw-r--r-- | documentation/sdk-manual/sdk-intro.xml | 71 | ||||
-rw-r--r-- | documentation/sdk-manual/sdk-manual.xml | 2 | ||||
-rw-r--r-- | 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 0000000000..185dd42092 --- /dev/null +++ b/documentation/sdk-manual/sdk-appendix-mars.xml @@ -0,0 +1,878 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<appendix id='sdk-appendix-mars'> + <title>Using Eclipse Mars</title> + + <para> + This release of the Yocto Project supports both the Neon and Mars + versions of the Eclipse IDE. + This appendix presents information that describes how to obtain and + configure the Mars version of Eclipse. + It also provides a basic project example that you can work through + from start to finish. + For general information on using the Eclipse IDE and the Yocto + Project Eclipse Plug-In, see the + "<link linkend='sdk-developing-applications-using-eclipse'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>" + section. + </para> + + <section id='mars-setting-up-the-eclipse-ide'> + <title>Setting Up the Mars Version of the Eclipse IDE</title> + + <para> + To develop within the Eclipse IDE, you need to do the following: + <orderedlist> + <listitem><para>Install the Mars version of the Eclipse + IDE.</para></listitem> + <listitem><para>Configure the Eclipse IDE. + </para></listitem> + <listitem><para>Install the Eclipse Yocto Plug-in. + </para></listitem> + <listitem><para>Configure the Eclipse Yocto Plug-in. + </para></listitem> + </orderedlist> + <note> + Do not install Eclipse from your distribution's package + repository. + Be sure to install Eclipse from the official Eclipse + download site as directed in the next section. + </note> + </para> + + <section id='mars-installing-eclipse-ide'> + <title>Installing the Mars Eclipse IDE</title> + + <para> + Follow these steps to locate, install, and configure + Mars Eclipse: + <orderedlist> + <listitem><para><emphasis>Locate the Mars Download:</emphasis> + Open a browser and go to + <ulink url='http://www.eclipse.org/mars/'>http://www.eclipse.org/mars/</ulink>. + </para></listitem> + <listitem><para><emphasis>Download the Tarball:</emphasis> + Click the "Download" button and then use the "Linux + for Eclipse IDE for C++ Developers" + appropriate for your development system + (e.g. + <ulink url='http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/mars/2/eclipse-cpp-mars-2-linux-gtk-x86_64.tar.gz'>64-bit under Linux for Eclipse IDE for C++ Developers</ulink> + if your development system is a Linux 64-bit machine. + </para></listitem> + <listitem><para><emphasis>Unpack the Tarball:</emphasis> + Move to a clean directory and unpack the tarball. + Here is an example: + <literallayout class='monospaced'> + $ cd ~ + $ tar -xzvf ~/Downloads/eclipse-cpp-mars-2-linux-gtk-x86_64.tar.gz + </literallayout> + Everything unpacks into a folder named "Eclipse". + </para></listitem> + <listitem><para><emphasis>Launch Eclipse:</emphasis> + Double click the "Eclipse" file in the folder to + launch Eclipse. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='mars-configuring-the-mars-eclipse-ide'> + <title>Configuring the Mars Eclipse IDE</title> + + <para> + Follow these steps to configure the Mars Eclipse IDE. + <note> + Depending on how you installed Eclipse and what you have + already done, some of the options will not appear. + If you cannot find an option as directed by the manual, + it has already been installed. + </note> + <orderedlist> + <listitem><para>Be sure Eclipse is running and + you are in your workbench. + </para></listitem> + <listitem><para>Select "Install New Software" from + the "Help" pull-down menu. + </para></listitem> + <listitem><para>Select + "Mars - http://download.eclipse.org/releases/mars" + from the "Work with:" pull-down menu. + </para></listitem> + <listitem><para>Expand the box next to + "Linux Tools" and select "C/C++ Remote + (Over TCF/TE) Run/Debug Launcher" and + "TM Terminal". + </para></listitem> + <listitem><para>Expand the box next to "Mobile and + Device Development" and select the following + boxes: + <literallayout class='monospaced'> + C/C++ Remote (Over TCF/TE) Run/Debug Launcher + Remote System Explorer User Actions + TM Terminal + TCF Remote System Explorer add-in + TCF Target Explorer + </literallayout> + </para></listitem> + <listitem><para>Expand the box next to + "Programming Languages" and select the + following boxes: + <literallayout class='monospaced'> + C/C++ Autotools Support + C/C++ Development Tools SDK + </literallayout> + </para></listitem> + <listitem><para> + Complete the installation by clicking through + appropriate "Next" and "Finish" buttons. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='mars-installing-the-eclipse-yocto-plug-in'> + <title>Installing or Accessing the Mars Eclipse Yocto Plug-in</title> + + <para> + You can install the Eclipse Yocto Plug-in into the Eclipse + IDE one of two ways: use the Yocto Project's Eclipse + Update site to install the pre-built plug-in or build and + install the plug-in from the latest source code. + </para> + + <section id='mars-new-software'> + <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> + + <para> + To install the Mars Eclipse Yocto Plug-in from the update + site, follow these steps: + <orderedlist> + <listitem><para>Start up the Eclipse IDE. + </para></listitem> + <listitem><para>In Eclipse, select "Install New + Software" from the "Help" menu. + </para></listitem> + <listitem><para>Click "Add..." in the "Work with:" + area. + </para></listitem> + <listitem><para>Enter + <filename>&ECLIPSE_DL_PLUGIN_URL;/mars</filename> + in the URL field and provide a meaningful name + in the "Name" field. + </para></listitem> + <listitem><para>Click "OK" to have the entry added + to the "Work with:" drop-down list. + </para></listitem> + <listitem><para>Select the entry for the plug-in + from the "Work with:" drop-down list. + </para></listitem> + <listitem><para>Check the boxes next to the following: + <literallayout class='monospaced'> + Yocto Project ADT Plug-in + Yocto Project Bitbake Commander Plug-in + Yocto Project Documentation plug-in + </literallayout> + </para></listitem> + <listitem><para>Complete the remaining software + installation steps and then restart the Eclipse + IDE to finish the installation of the plug-in. + <note> + You can click "OK" when prompted about + installing software that contains unsigned + content. + </note> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='mars-zip-file-method'> + <title>Installing the Plug-in Using the Latest Source Code</title> + + <para> + To install the Mars Eclipse Yocto Plug-in from the latest + source code, follow these steps: + <orderedlist> + <listitem><para>Be sure your development system + has JDK 1.7+ + </para></listitem> + <listitem><para>install X11-related packages: + <literallayout class='monospaced'> + $ sudo apt-get install xauth + </literallayout> + </para></listitem> + <listitem><para>In a new terminal shell, create a Git + repository with: + <literallayout class='monospaced'> + $ cd ~ + $ git clone git://git.yoctoproject.org/eclipse-poky + </literallayout> + </para></listitem> + <listitem><para>Use Git to checkout the correct + tag: + + <note><title>Developer's Note</title> + <para role='writernotes'> + Because the 2.2 tag will not exist until after + the release, I must first do the following + before running the + <filename>git checkout mars/yocto-&DISTRO;</filename> + command in this step: + <literallayout class='monospaced'> + $ git tag mars/yocto-2.2 origin/mars-master + </literallayout></para> + </note> + + <literallayout class='monospaced'> + $ cd ~/eclipse-poky + $ git checkout mars/yocto-&DISTRO; + </literallayout> + This puts you in a detached HEAD state, which + is fine since you are only going to be building + and not developing. + </para></listitem> + <listitem><para>Change to the + <filename>scripts</filename> + directory within the Git repository: + <literallayout class='monospaced'> + $ cd scripts + </literallayout> + </para></listitem> + <listitem><para>Set up the local build environment + by running the setup script: + <literallayout class='monospaced'> + $ ./setup.sh + </literallayout> + When the script finishes execution, + it prompts you with instructions on how to run + the <filename>build.sh</filename> script, which + is also in the <filename>scripts</filename> + directory of the Git repository created + earlier. + </para></listitem> + <listitem><para>Run the <filename>build.sh</filename> + script as directed. + Be sure to provide the tag name, documentation + branch, and a release name.</para> + <para> + Following is an example: + <literallayout class='monospaced'> + $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l mars/yocto-&DISTRO; master yocto-&DISTRO; 2>&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 781cebf188..0995f79a93 100644 --- a/documentation/sdk-manual/sdk-intro.xml +++ b/documentation/sdk-manual/sdk-intro.xml @@ -113,8 +113,9 @@ of the SDK but is rather available for use as part of the development process. </para></listitem> - <listitem><para>Various user-space tools that greatly enhance - your application development experience. + <listitem><para>Various performance-related + <ulink url='http://www.eclipse.org/linuxtools/index.php'>tools</ulink> + that can enhance your development experience. These tools are also separate from the actual SDK but can be independently obtained and used in the development process. </para></listitem> @@ -196,9 +197,16 @@ These extensions allow for cross-compilation, deployment, and execution of your output into a QEMU emulation session. You can also perform cross-debugging and profiling. - The environment also supports a suite of tools that allows you to - perform remote profiling, tracing, collection of power data, - collection of latency data, and collection of performance data. + The environment also supports many performance-related + <ulink url='http://www.eclipse.org/linuxtools/index.php'>tools</ulink> + that enhance your development experience. + <note> + Previous releases of the Eclipse Yocto Plug-in supported + "user-space tools" (i.e. LatencyTOP, PowerTOP, Perf, SystemTap, + and Lttng-ust) that also added to the development experience. + These tools have been deprecated beginning with this release + of the plug-in. + </note> </para> <para> @@ -210,54 +218,15 @@ </para> </section> - <section id='user-space-tools'> - <title>User-Space Tools</title> + <section id='performance-enhancing-tools'> + <title>Performance Enhancing Tools</title> <para> - User-space tools, which are available as part of the SDK - development environment, can be helpful. - The tools include LatencyTOP, PowerTOP, Perf, SystemTap, - and Lttng-ust. - These tools are common development tools for the Linux platform. - <itemizedlist> - <listitem><para><emphasis>LatencyTOP:</emphasis> LatencyTOP - focuses on latency that causes skips in audio, stutters in - your desktop experience, or situations that overload your - server even when you have plenty of CPU power left. - </para></listitem> - <listitem><para><emphasis>PowerTOP:</emphasis> Helps you - determine what software is using the most power. - You can find out more about PowerTOP at - <ulink url='https://01.org/powertop/'></ulink>.</para></listitem> - <listitem><para><emphasis>Perf:</emphasis> Performance counters - for Linux used to keep track of certain types of hardware - and software events. - For more information on these types of counters see - <ulink url='https://perf.wiki.kernel.org/'></ulink>. - For examples on how to setup and use this tool, see the - "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>" - section in the Yocto Project Profiling and Tracing Manual. - </para></listitem> - <listitem><para><emphasis>SystemTap:</emphasis> A free software - infrastructure that simplifies information gathering about - a running Linux system. - This information helps you diagnose performance or - functional problems. - SystemTap is not available as a user-space tool through - the Eclipse IDE Yocto Plug-in. - See <ulink url='http://sourceware.org/systemtap'></ulink> - for more information on SystemTap. - For examples on how to setup and use this tool, see the - "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-systemtap'>SystemTap</ulink>" - section in the Yocto Project Profiling and Tracing Manual. - </para></listitem> - <listitem><para><emphasis>Lttng-ust:</emphasis> A User-space - Tracer designed to provide detailed information on - user-space activity. - See <ulink url='http://lttng.org/ust'></ulink> for more - information on Lttng-ust. - </para></listitem> - </itemizedlist> + Supported performance enhancing tools are available that let you + profile, debug, and perform tracing on your projects developed + using Eclipse. + For information on these tools see + <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>. </para> </section> </section> diff --git a/documentation/sdk-manual/sdk-manual.xml b/documentation/sdk-manual/sdk-manual.xml index b690a14012..39a8689195 100644 --- a/documentation/sdk-manual/sdk-manual.xml +++ b/documentation/sdk-manual/sdk-manual.xml @@ -74,6 +74,8 @@ <xi:include href="sdk-appendix-customizing.xml"/> + <xi:include href="sdk-appendix-mars.xml"/> + <!-- <index id='index'> <title>Index</title> </index> diff --git a/documentation/sdk-manual/sdk-using.xml b/documentation/sdk-manual/sdk-using.xml index 9354ace3b9..f8e2f005bd 100644 --- a/documentation/sdk-manual/sdk-using.xml +++ b/documentation/sdk-manual/sdk-using.xml @@ -533,10 +533,10 @@ </para></listitem> <listitem><para><emphasis>Test and debug the application</emphasis>: Once your application is deployed, you need to test it. - Within the Eclipse IDE, you can use the debugging environment along with the - set of installed user-space tools to debug your application. - Of course, the same user-space tools are available separately if you choose - not to use the Eclipse IDE.</para></listitem> + Within the Eclipse IDE, you can use the debugging + environment along with supported performance enhancing + <ulink url='http://www.eclipse.org/linuxtools/'>tools</ulink>. + </para></listitem> </orderedlist> </para> </section> @@ -565,9 +565,11 @@ execution of your output into a QEMU emulation session as well as actual target hardware. You can also perform cross-debugging and profiling. - The environment also supports a suite of tools that allows you - to perform remote profiling, tracing, collection of power data, - collection of latency data, and collection of performance data. + The environment also supports performance enhancing + <ulink url='http://www.eclipse.org/linuxtools/'>tools</ulink> that + allow you to perform remote profiling, tracing, collection of + power data, collection of latency data, and collection of + performance data. </para> <para> @@ -1317,144 +1319,18 @@ </para> </section> - <section id='running-user-space-tools'> - <title>Running User-Space Tools</title> + <section id='running-performance-tools'> + <title>Running Performance Tools</title> <para> As mentioned earlier in the manual, several tools exist that enhance your development experience. These tools are aids in developing and debugging applications and images. - You can run these user-space tools from within the Eclipse + You can run these tools from within the Eclipse IDE through the "YoctoProjectTools" menu. - </para> - - <para> - Once you pick a tool, you need to configure it for the remote - target. - Every tool needs to have the connection configured. - You must select an existing TCF-based RSE connection to the - remote target. - If one does not exist, click "New" to create one. - </para> - - <para> - Here are some specifics about the remote tools: - <itemizedlist> - <listitem><para><emphasis><filename>Lttng2.0 trace import</filename>:</emphasis> - Selecting this tool transfers the remote target's - <filename>Lttng</filename> tracing data back to the - local host machine and uses the Lttng Eclipse plug-in - to graphically display the output. - For information on how to use Lttng to trace an - application, - see <ulink url='http://lttng.org/documentation'></ulink> - and the - "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>" - section, which is in the Yocto Project Profiling and - Tracing Manual. - <note>Do not use - <filename>Lttng-user space (legacy)</filename> tool. - This tool no longer has any upstream support.</note> - </para> - <para>Before you use the - <filename>Lttng2.0 trace import</filename> tool, - you need to setup the Lttng Eclipse plug-in and create a - Tracing project. - Do the following: - <orderedlist> - <listitem><para>Select "Open Perspective" from the - "Window" menu and then select "Other..." to - bring up a menu of other perspectives. - Choose "Tracing". - </para></listitem> - <listitem><para>Click "OK" to change the Eclipse - perspective into the Tracing perspective. - </para></listitem> - <listitem><para>Create a new Tracing project by - selecting "Project" from the "File -> New" menu. - </para></listitem> - <listitem><para>Choose "Tracing Project" from the - "Tracing" menu and click "Next". - </para></listitem> - <listitem><para>Provide a name for your tracing - project and click "Finish". - </para></listitem> - <listitem><para>Generate your tracing data on the - remote target.</para></listitem> - <listitem><para>Select "Lttng2.0 trace import" - from the "Yocto Project Tools" menu to - start the data import process.</para></listitem> - <listitem><para>Specify your remote connection name. - </para></listitem> - <listitem><para>For the Ust directory path, specify - the location of your remote tracing data. - Make sure the location ends with - <filename>ust</filename> (e.g. - <filename>/usr/mysession/ust</filename>). - </para></listitem> - <listitem><para>Click "OK" to complete the import - process. - The data is now in the local tracing project - you created.</para></listitem> - <listitem><para>Right click on the data and then use - the menu to Select "Generic CTF Trace" from the - "Trace Type... -> Common Trace Format" menu to - map the tracing type.</para></listitem> - <listitem><para>Right click the mouse and select - "Open" to bring up the Eclipse Lttng Trace - Viewer so you view the tracing data. - </para></listitem> - </orderedlist></para></listitem> - <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> - Selecting this tool runs PowerTOP on the remote target - machine and displays the results in a new view called - PowerTOP.</para> - <para>The "Time to gather data(sec):" field is the time - passed in seconds before data is gathered from the - remote target for analysis.</para> - <para>The "show pids in wakeups list:" field corresponds - to the <filename>-p</filename> argument passed to - <filename>PowerTOP</filename>.</para></listitem> - <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis> - LatencyTOP identifies system latency, while - Perf monitors the system's performance counter - registers. - Selecting either of these tools causes an RSE terminal - view to appear from which you can run the tools. - Both tools refresh the entire screen to display results - while they run. - For more information on setting up and using - <filename>perf</filename>, see the - "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>" - section in the Yocto Project Profiling and Tracing - Manual. - </para></listitem> - <listitem><para><emphasis><filename>SystemTap</filename>:</emphasis> - Systemtap is a tool that lets you create and reuse - scripts to examine the activities of a live Linux - system. - You can easily extract, filter, and summarize data - that helps you diagnose complex performance or - functional problems. - For more information on setting up and using - <filename>SystemTap</filename>, see the - <ulink url='https://sourceware.org/systemtap/documentation.html'>SystemTap Documentation</ulink>. - </para></listitem> - <listitem><para><emphasis><filename>yocto-bsp</filename>:</emphasis> - The <filename>yocto-bsp</filename> tool lets you - quickly set up a Board Support Package (BSP) layer. - The tool requires a Metadata location, build location, - BSP name, BSP output location, and a kernel - architecture. - For more information on the - <filename>yocto-bsp</filename> tool outside of Eclipse, - see the - "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a new BSP Layer Using the yocto-bsp Script</ulink>" - section in the Yocto Project Board Support Package - (BSP) Developer's Guide. - </para></listitem> - </itemizedlist> + For more information on these tools, see + <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>. </para> </section> </section> |