path: root/documentation/adt-manual/adt-eclipse.xml

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<chapter id='adt-eclipse'>
<title>Working Within Eclipse</title>

    <para>
        The Eclipse IDE is a popular development environment and it fully supports 
        development using Yocto Project.  
        When you install and configure the Eclipse Yocto Project Plug-in into 
        the Eclipse IDE, you maximize your Yocto Project design 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.  
        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.
    </para>
    <para>
        This section describes how to install and configure the Eclipse IDE 
        Yocto Plug-in and how to use it to develop your Yocto Project.
    </para>

<section id='setting-up-the-eclipse-ide'>
    <title>Setting Up the Eclipse IDE</title>

    <para>
        To develop within the Eclipse IDE, you need to do the following:
        <orderedlist>
            <listitem><para>Install the optimal 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>
    </para>

    <section id='installing-eclipse-ide'>
    <title>Installing the Eclipse IDE</title>

        <para>
            It is recommended that you have the Indigo 3.7 version of the 
            Eclipse IDE installed on your development system.  
            If you don’t have this version, you can find it at 
            <ulink url='http://www.eclipse.org/downloads'></ulink>.  
            From that site, choose the Eclipse Classic version particular to your development
            host.  
            This version contains the Eclipse Platform, the Java Development 
            Tools (JDT), and the Plug-in Development Environment.
        </para>

        <para>
            Once you have downloaded the tarball, extract it into a clean 
            directory.
            For example, the following command unpacks and installs the Eclipse IDE
            into a clean directory using the default name <filename>eclipse</filename>:
            <literallayout class='monospaced'>
     $ tar -xzvf ~/Downloads/Eclipse-SDK-3.7-linux-gtk-x86_64.tar.gz
            </literallayout>
        </para>

        <para>
            One issue exists that you need to be aware of regarding the Java 
            Virtual machine’s garbage collection (GC) process.  
            The GC process does not clean up the permanent generation 
            space (PermGen).  
            This space stores metadata descriptions of classes.  
            The default value is set too small and it could trigger an 
            out-of-memory error such as the following:
            <literallayout class='monospaced'>
     Java.lang.OutOfMemoryError: PermGen space
            </literallayout>
        </para>

        <para>
            This error causes the application to hang.
        </para>

        <para>
            To fix this issue, you can use the <filename>--vmargs</filename>
            option when you start Eclipse to increase the size of the permanent generation space:
            <literallayout class='monospaced'>
     eclipse --vmargs --XX:PermSize=256M
            </literallayout>
        </para>
    </section>

    <section id='configuring-the-eclipse-ide'>
    <title>Configuring the Eclipse IDE</title>

        <para>
            Before installing and configuring the Eclipse Yocto Plug-in, you need to configure
            the Eclipse IDE.  
            Follow these general steps to configure Eclipse:
            <orderedlist>
                <listitem><para>Start the Eclipse IDE.</para></listitem>
                <listitem><para>Select "Install New Software" from the "Help" pull-down menu.
                    </para></listitem>
                <listitem><para>Select <filename>Indego - http://download.eclipse.org/releases/indego</filename>
                    from the "Work with:" pull-down menu.</para></listitem>
                <listitem><para>Expand the box next to <filename>Programming Languages</filename>
                    and select the <filename>Autotools Support for CDT (incubation)</filename>
                    and <filename>C/C++ Development Tools</filename> boxes.</para></listitem>
                <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
                <listitem><para>Select "Install New Software" from the "Help" pull-down menu.</para></listitem>
                <listitem><para>After the Eclipse IDE restarts, click the 
                    "Available Software Sites" link.</para></listitem>
                <listitem><para>Check the box next to 
                    <filename>http://download.eclipse.org/tm/updates/3.3</filename>
                    and click "OK".</para></listitem>
                <listitem><para>Select <filename>http://download.eclipse.org/tm/updates/3.3</filename>
                    from the "Work with:" pull-down menu.</para></listitem>
                <listitem><para>Check the box next to <filename>TM and RSE Main Features</filename>.
                    </para></listitem>
                <listitem><para>Expand the box next to <filename>TM and RSE Optional Add-ons</filename>
                    and select every item except <filename>RSE Unit Tests</filename> and 
                    <filename>RSE WinCE Services (incubation)</filename>.</para></listitem>
                <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
                <listitem><para>After the Eclipse IDE restarts, click the 
                    "Available Software Sites" link.</para></listitem>
                <listitem><para>Check the box next to 
                    <filename>http://download.eclipse.org/tools/cdt/releases/indego</filename>
                    and click "OK".</para></listitem>
                <listitem><para>Select <filename>http://download.eclipse.org/tools/cdt/releases/indego</filename>
                    from the "Work with:" pull-down menu.</para></listitem>
                <listitem><para>Check the box next to <filename>CDT Main Features</filename>.
                    </para></listitem>
                <listitem><para>Expand the box next to <filename>CDT Optional Features</filename>
                    and select <filename>C/C++ Remote Launch</filename> and 
                    <filename>Target Communication Framework (incubation)</filename>.</para></listitem>
                <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem>
            </orderedlist>
        </para>
    </section>

    <section id='installing-the-eclipse-yocto-plug-in'>
    <title>Installing the Eclipse Yocto Plug-in</title>

        <para>
            To install the Eclipse Yocto Plug-in, follow these special steps.  
            The steps are WIP and are not final. 
            Once they are final they will be replaced with the actual steps:
            <orderedlist>
                <listitem><para>Open a shell and create a Git repository with:
                    <literallayout class='monospaced'>
     $ git clone git://git.yoctoproject.org/yocto-eclipse yocto-eclipse
                    </literallayout></para></listitem>
                <listitem><para>In Eclipse, select "Import" from the "File" menu.</para></listitem>
                <listitem><para>Expand the "General" box and pick "existing projects into workspace".
                    </para></listitem>
                <listitem><para>Select the root directory and browse to "~/yocto-eclipse/plugins".
                    </para></listitem>
                <listitem><para>There will be three things there.
                    Select each one and install one at a time.
                    Do all three.</para></listitem>
                <listitem><para>Restart everything.</para></listitem>
            </orderedlist>
        </para>

        <para>
            At this point I should be able to invoke Eclipse from the shell using the following:
                    <literallayout class='monospaced'>
     $ cd ~/eclipse
     $ ./eclipse -vmargs -XX:PermSize=256M
                    </literallayout>
            What is shown is the default projects in the left pane. 
            I should be able to right-click on one of these and run as an Eclipse application to 
            bring up the Eclipse instance again with the Eclipse Yocto Plug-in working.
            This brings up a second instance of Eclipse IDE that has the Yocto Plug-in.
       </para>            
    </section>

    <section id='configuring-the-eclipse-yocto-plug-in'>
    <title>Configuring the Eclipse Yocto Plug-in</title>

        <para>
            Configuring the 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 <filename>Windows -&gt; Preferences</filename> to display 
                    the Preferences Dialog</para></listitem>
                <listitem><para>Click <filename>Yocto ADT</filename></para></listitem>
            </itemizedlist>
        </para>

        <section id='configuring-the-cross-compiler-options'>
        <title>Configuring the Cross-Compiler Options</title>

            <para>
                To configure the Cross Compiler 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 mode 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.
                                    </para></listitem>
                               <listitem><para><emphasis>
                                    <filename>Build System Derived Toolchain:</filename></emphasis> 
                                    Select this mode if the cross-toolchain has been installed and built 
                                    as part of the Yocto Project build tree.  
                                    When you select <filename>Build system derived toolchain</filename>,
                                    you are using the toolchain bundled 
                                    inside the Yocto Project build tree.
                                    </para></listitem>
                            </itemizedlist>
                        </para></listitem>
                    <listitem><para><emphasis>Point to the Toolchain:</emphasis>
                        If you are using a stand-alone pre-built toolchain, you should be pointing to the
                        <filename>/opt/poky/$SDKVERSION</filename> directory.
                        This is the location for toolchains installed by the ADT Installer or by hand.
                        Sections "<link linkend='configuring-and-running-the-adt-installer-script'>Configuring 
                        and Running the ADT Installer Script</link>" and 
                        "<link linkend='using-an-existing-toolchain-tarball'>Using a Cross-Toolchain 
                        Tarball</link>" describe two ways to install
                        a stand-alone cross-toolchain in the 
                        <filename>/opt/poky</filename> directory.
                        <note>It is possible to install a stand-alone cross-toolchain in a directory
                        other than <filename>/opt/poky</filename>.
                        However, doing so is discouraged.</note></para>
                        <para>If you are using a system-derived toolchain, the path you provide 
                        for the <filename>Toolchain Root Location</filename>
                        field is the Yocto Project's build directory.
                        See section "<link linkend='using-the-toolchain-from-within-the-build-tree'>Using 
                        BitBake and the Yocto Project Build Tree</link>" for 
                        information on how to install the toolchain into the Yocto 
                        Project build tree.</para></listitem> 
                    <listitem><para><emphasis>Specify the Sysroot Location:</emphasis>
                        This location is where the root filesystem for the 
                        target hardware is created on the development system by the ADT Installer.
                        The QEMU user-space tools, the 
                        NFS boot process, and the cross-toolchain all use the sysroot location.
                        </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='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'>Building an Image</ulink>" section of the  
                        <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html'>
                        The Yocto Project Quick Start</ulink> for more information.</para></listitem>
                </itemizedlist>
            </para>
        </section>

        <section id='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><filename>QEMU:</filename></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 <filename>Build system derived toolchain</filename>, 
                        the target kernel you built will be located in the 
                        Yocto Project build tree in <filename>tmp/deploy/images</filename> directory.   
                        If you selected <filename>Standalone pre-built toolchain</filename>, the 
                        pre-built image you downloaded is located 
                        in the directory you specified when you downloaded the image.</para>
                        <para>Most custom options are for advanced QEMU users to further 
                        customize their QEMU instance.  
                        These options are specified between paired angled brackets.  
                        Some options must be specified outside the brackets.
                        In particular, the options <filename>serial</filename>, 
                        <filename>nographic</filename>, and <filename>kvm</filename> must all 
                        be outside the brackets.  
                        Use the <filename>man qemu</filename> command to get help on all the options
                        and their use.  
                        The following is an example:
                        <literallayout class='monospaced'>
    serial ‘&lt;-m 256 -full-screen&gt;’
                        </literallayout></para>
                        <para>
                        Regardless of the mode, Sysroot is already defined as part of the 
                        Cross Compiler Options configuration in the 
                        <filename>Sysroot Location:</filename> field.</para></listitem>
                    <listitem><para><emphasis><filename>External HW:</filename></emphasis> Select this option 
                        if you will be using actual hardware.</para></listitem>
                </itemizedlist>
            </para>

            <para>
                Click the <filename>OK</filename> button to save your plug-in configurations.
            </para>
        </section>
    </section>
</section>

<section id='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 section
        "<link linkend='using-the-command-line'>Using the Command Line</link>".
    </para>

    <para>
        To create a project based on a Yocto template and then display the source code, 
        follow these steps:
        <orderedlist>
            <listitem><para>Select <filename>File -&gt; New -&gt; Project</filename>.</para></listitem>
            <listitem><para>Double click <filename>CC++</filename>.</para></listitem>
            <listitem><para>Double click <filename>C Project</filename> to create the project.</para></listitem>
            <listitem><para>Expand <filename>Yocto ADT Project</filename>.</para></listitem>
            <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>.  
                This is an Autotools-based project based on a Yocto Project template.</para></listitem>
            <listitem><para>Put a name in the <filename>Project name:</filename> field.
                Do not use hyphens as part of the name.</para></listitem>
            <listitem><para>Click <filename>Next</filename>.</para></listitem>
            <listitem><para>Add information in the <filename>Author</filename> and
                <filename>Copyright notice</filename> fields.</para></listitem>
            <listitem><para>Be sure the <filename>License</filename> field is correct.</para></listitem>
            <listitem><para>Click <filename>Finish</filename>.</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='configuring-the-cross-toolchains'>
<title>Configuring the Cross-Toolchains</title>

    <para>
        The previous section, "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring 
        the Eclipse Yocto Plug-in</link>", sets up the default project 
        configurations.  
        You can change these settings for a given project by following these steps:
        <orderedlist>
            <listitem><para>Select <filename>Window -&gt; Preferences</filename>:  
                This selection brings up the <filename>Preferences</filename> Dialog.  
                If the Yocto ADT Preferences are not automatically displayed, you can navigate to 
                that dialog by selection <filename>Yocto ADT</filename> in the left-hand 
                panel.</para>
                <para>Yocto ADT Settings are inherited from the default project configuration.  
                The information in this dialog is identical to that chosen earlier 
                for the Cross Compiler Options and Target Options as described in the
                "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse 
                Yocto Plug-in</link>" section.</para></listitem>
            <listitem><para>Select <filename>Project -&gt; Reconfigure Project</filename>:   
                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>.</para></listitem>
        </orderedlist>
    </para>
</section>

<section id='building-the-project'>
<title>Building the Project</title>

    <para>
        To build the project, select <filename>Project -&gt; Build Project</filename>.  
        The console should update and you can note the cross-compiler you are using.
    </para>
</section>

<section id='starting-qemu-in-user-space-nfs-mode'>
<title>Starting QEMU in User Space NFS Mode</title>

    <para>
        WRITER'S NOTE:  I might need to make sure the target sysroot is pointing to qemux86-sato
        at this point.  
        I am not sure it really inherits it from the Eclipse IDE settings.
    </para>

    <para>
        To start the QEMU emulator from within Eclipse, follow these steps:
        <orderedlist>
            <listitem><para>Expose the <filename>Run -&gt; External Tools -&gt; External Tools 
                Configurations...</filename> menu.
                Your image should appear as a selectable menu item.
                </para></listitem>
            <listitem><para>Select your image in the navigation pane to launch the 
                emulator in a new window.</para></listitem>
            <listitem><para>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 need to determine the IP Address 
                for the user-space NFS.  
                You can do that by going to a terminal in the QEMU and entering the 
            <filename>ifconfig</filename> command.</para></listitem>
        </orderedlist>
    </para>
</section>

<section id='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 and use the emulator 
        to perform debugging.  
        Follow these steps to deploy the application.
        <orderedlist>
            <listitem><para>Select <filename>Run -&gt; Debug Configurations...</filename></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 <filename>Debug Configurations</filename> Dialog.</para></listitem>
            <listitem><para>Enter the absolute path into which you want to deploy 
                the application.  
                Use the <filename>Remote Absolute File Path for C/C++Application:</filename> field.  
                For example, enter <filename>/usr/bin/&lt;programname&gt;</filename>.</para></listitem>
            <listitem><para>Click on the <filename>Debugger</filename> tab to see the cross-tool debugger 
                you are using.</para></listitem>
            <listitem><para>Click on the <filename>Main</filename> tab.</para></listitem>
            <listitem><para>Create a new connection to the QEMU instance 
                by clicking on <filename>new</filename>.</para></listitem>
            <listitem><para>Select <filename>TCF</filename>, which means Target Communication 
                Framework.</para></listitem>
            <listitem><para>Click <filename>Next</filename>.</para></listitem>
            <listitem><para>Clear out the <filename>host name</filename> field and enter the IP Address 
                determined earlier.</para></listitem>
            <listitem><para>Click <filename>Finish</filename> to close the new connections 
                Dialog.</para></listitem>
            <listitem><para>Use the drop-down menu now in the <filename>Connection</filename> field and pick 
                the IP Address you entered.</para></listitem>
            <listitem><para>Click <filename>Debug</filename> to bring up a login screen 
                and login.</para></listitem>
            <listitem><para>Accept the debug perspective.</para></listitem>
        </orderedlist>
    </para>
</section>

<section id='running-user-space-tools'>
<title>Running User-Space 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 IDE through the 
        <filename>Window -&gt; YoctoTools</filename> 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 <filename>New</filename> to create one.
    </para>

    <para>
        Here are some specifics about the remote tools:
        <itemizedlist>
            <listitem><para><emphasis><filename>OProfile</filename>:</emphasis>  Selecting this tool causes 
                the <filename>oprofile-server</filename> on the remote target to launch on 
                the local host machine.  
                The <filename>oprofile-viewer</filename> must be installed on the local host machine and the 
                <filename>oprofile-server</filename> must be installed on the remote target, 
                respectively, in order to use.
                You must compile and install the <filename>oprofile-viewer</filename> from the source code 
                on your local host machine.
                Furthermore, in order to convert the target's sample format data into a form that the 
                host can use, you must have <filename>oprofile</filename> version 0.9.4 or 
                greater installed on the host.</para>
                <para>You can locate both the viewer and server from 
                <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/oprofileui/'></ulink>.
                <note>The <filename>oprofile-server</filename> is installed by default on 
                the <filename>core-image-sato-sdk</filename> image.</note></para></listitem>
            <listitem><para><emphasis><filename>Lttng-ust</filename>:</emphasis> Selecting this tool runs 
                <filename>usttrace</filename> on the remote target, transfers the output data back to the 
                local host machine, and uses <filename>lttv-gui</filename> to graphically display the output.  
                The <filename>lttv-gui</filename> must be installed on the local host machine to use this tool.  
                For information on how to use <filename>lttng</filename> to trace an application, see 
                <ulink url='http://lttng.org/files/ust/manual/ust.html'></ulink>.</para>
                <para>For <filename>Application</filename>, you must supply the absolute path name of the 
                application to be traced by user mode <filename>lttng</filename>.  
                For example, typing <filename>/path/to/foo</filename> triggers 
                <filename>usttrace /path/to/foo</filename> on the remote target to trace the 
                program <filename>/path/to/foo</filename>.</para>
                <para><filename>Argument</filename> is passed to <filename>usttrace</filename>
                running on the remote target.</para></listitem>
            <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> Selecting this tool runs 
                <filename>powertop</filename> on the remote target machine and displays the results in a 
                new view called <filename>powertop</filename>.</para>
                <para><filename>Time to gather data(sec):</filename> is the time passed in seconds before data 
                is gathered from the remote target for analysis.</para>
                <para><filename>show pids in wakeups list:</filename> corresponds to the 
                <filename>-p</filename> argument 
                passed to <filename>powertop</filename>.</para></listitem>
                <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis>  
                <filename>latencytop</filename> identifies system latency, while 
                <filename>perf</filename> 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.</para></listitem>
        </itemizedlist>
    </para>
</section> 

</chapter>
<!--
vim: expandtab tw=80 ts=4
-->