diff options
Diffstat (limited to 'documentation')
| -rw-r--r-- | documentation/adt-manual/adt-eclipse.xml | 443 |
1 files changed, 408 insertions, 35 deletions
diff --git a/documentation/adt-manual/adt-eclipse.xml b/documentation/adt-manual/adt-eclipse.xml index 2bb5bd5125..9fa39cf5cf 100644 --- a/documentation/adt-manual/adt-eclipse.xml +++ b/documentation/adt-manual/adt-eclipse.xml @@ -2,54 +2,427 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <chapter id='adt-eclipse'> - -<title>Yocto Project Kernel Architecture and Use Manual</title> - -<section id='eclipse'> - <title>Introduction</title> +<title>Working Within Eclipse</title> <para> - The Yocto Project presents the kernel as a fully patched, history-clean git - repository. - The git tree represents the selected features, board support, - and configurations extensively tested by Yocto Project. - The Yocto Project kernel allows the end user to leverage community - best practices to seamlessly manage the development, build and debug cycles. + 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 and deployment and execution of + your output into a QEMU emulation session. + You can also perform cross-debugging and profiling. + The environment also has 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 manual describes the Yocto Project kernel by providing information - on its history, organization, benefits, and use. - The manual consists of two sections: - <itemizedlist> - <listitem><para>Concepts - Describes concepts behind the kernel. - You will understand how the kernel is organized and why it is organized in - the way it is. You will understand the benefits of the kernel's organization - and the mechanisms used to work with the kernel and how to apply it in your - design process.</para></listitem> - <listitem><para>Using the Kernel - Describes best practices and "how-to" information - that lets you put the kernel to practical use. Some examples are "How to Build a - Project Specific Tree", "How to Examine Changes in a Branch", and "Saving Kernel - Modifications."</para></listitem> - </itemizedlist> + 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> - For more information on the kernel, see the following links: - <itemizedlist> - <listitem><para><ulink url='http://ldn.linuxfoundation.org/book/1-a-guide-kernel-development-process'></ulink></para></listitem> - <listitem><para><ulink url='http://userweb.kernel.org/~akpm/stuff/tpp.txt'></ulink></para></listitem> - <listitem><para><ulink url='http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD'></ulink></para></listitem> - </itemizedlist> - <para> - You can find more information on Yocto Project by visiting the website at - <ulink url='http://www.yoctoproject.org'></ulink>. - </para> + To develop within the Eclipse IDE you need to do the following: + <orderedlist> + <listitem><para>Be sure the optimal version of Eclipse IDE + is installed.</para></listitem> + <listitem><para>Install required Eclipse plug-ins prior to installing + 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 Eclipse IDE</title> + <para> + It is recommended that you have the Helios 3.6.1 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. + 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 and complete the installation. + </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 meta-data 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 ‐‐vmargs 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='installing-required-plug-ins-and-the-eclipse-yocto-plug-in'> + <title>Installing Required Plug-ins and the Eclipse Yocto Plug-in</title> + <para> + Before installing the Yocto Plug-in you need to be sure that the + CDT 7.0, RSE 3.2, and Autotools plug-ins are all installed. + After installing these three plug-ins, you can install the + Eclipse Yocto Plug-in. + Use the following URLs for the plug-ins: + <orderedlist> + <listitem><para><emphasis>CDT 7.0</emphasis> – + <ulink url='http://download.eclipse.org/tools/cdt/releases/helios/'></ulink>: + For CDT main features select the checkbox so you get all items. + For CDT optional features expand the selections and check + “C/C++ Remote Launch”.</para></listitem> + <listitem><para><emphasis>RSE 3.2</emphasis> – + <ulink url='http://download.eclipse.org/tm/updates/3.2'></ulink>: + Check the box next to “TM and RSE Main Features” so you select all + those items. + Note that all items in the main features depend on 3.2.1 version. + Expand the items under “TM and RSE Uncategorized 3.2.1” and + select the following: “Remote System Explorer End-User Runtime”, + “Remote System Explorer Extended SDK”, “Remote System Explorer User Actions”, + “RSE Core”, “RSE Terminals UI”, and “Target Management Terminal”.</para></listitem> + <listitem><para><emphasis>Autotools</emphasis> – + <ulink url='http://download.eclipse.org/technology/linuxtools/update'></ulink>: + Expand the items under “Linux Tools” and select “Autotools support + for CDT (Incubation)”.</para></listitem> + <listitem><para><emphasis>Yocto Plug-in</emphasis> – + <ulink url='http://www.yoctoproject.org/downloads/eclipse-plugin/'></ulink>: + Check the box next to “Development tools & SDKs for Yocto Linux” + to select all the items.</para></listitem> + </orderedlist> + </para> + <para> + Follow these general steps to install a plug-in: + <orderedlist> + <listitem><para>From within the Eclipse IDE select the + “Install New Software” item from the “Help” menu.</para></listitem> + <listitem><para>Click “Add…” in the “Work with:” area.</para></listitem> + <listitem><para>Enter the URL for the repository and leave the “Name” + field blank.</para></listitem> + <listitem><para>Check the boxes next to the software you need to + install and then complete the installation. + For information on the specific software packages you need to include, + see the previous list.</para></listitem> + </orderedlist> + </para> + </section> + + <section id='configuring-the-plug-in'> + <title>Configuring the Plug-in</title> + <para> + Configuring the Eclipse Yocto Plug-in involves choosing the Cross + Compiler Options, selecting the Target Architecture, and choosing + the Target Options. + These settings are the default settings for all projects. + You do have opportunities to change them later if you choose to when + you configure the project. + See “Configuring the Cross Toolchain” section later in the manual. + </para> + <para> + To start, you need to do the following from within the Eclipse IDE: + <itemizedlist> + <listitem><para>Choose Windows -> Preferences to display + the Preferences Dialog</para></listitem> + <listitem><para>Click “Yocto SDK”</para></listitem> + </itemizedlist> + </para> + + <section id='configuring-the-cross-compiler-options'> + <title>Configuring the Cross-Compiler Options</title> + <para> + Choose between ‘SDK Root Mode’ and ‘Poky Tree Mode’ for Cross + Compiler Options. + <itemizedlist> + <listitem><para><emphasis>SDK Root Mode</emphasis> – Select this mode + when you are not concerned with building an image or you do not have + a Poky build tree on your system. + For example, suppose you are an application developer and do not + need to build an image. + You just want to use an architecture-specific toolchain on an + existing kernel and root filesystem. + When you use SDK Root Mode you are using the toolchain installed + in the <filename>/opt/poky</filename> directory.</para></listitem> + <listitem><para><emphasis>Poky Tree Mode</emphasis> – Select this mode + if you are concerned with building images for hardware or your + development environment already has a build tree. + In this case you likely already have a Poky build tree installed on + your system or you (or someone else) will be building one. + When you use the Poky Tree Mode you are using the toolchain bundled + inside the Poky build tree. + If you use this mode you must also supply the Poky Root Location + in the Preferences Dialog.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='configuring-the-sysroot'> + <title>Configuring the Sysroot</title> + <para> + Specify the sysroot, which is used by both the QEMU user-space + NFS boot process and by the cross-toolchain regardless of the + mode you select (SDK Root Mode or Poky Tree Mode). + For example, sysroot is the location to which you extract the + downloaded image’s root filesystem to through the ADT Installer. + </para> + </section> + + <section id='selecting-the-target-architecture'> + <title>Selecting the Target Architecture</title> + <para> + Use the pull-down Target Architecture menu and select the + target architecture. + </para> + <para> + The Target Architecture is the type of hardware you are + going to use or emulate. + This pull-down menu should have the supported architectures. + If the architecture you need is not listed in the menu then you + will need to re-visit + <xref linkend='adt-prepare'> + “Preparing to Use the Application Development Toolkit (ADT)”</xref> + section earlier in this document. + </para> + </section> + + <section id='choosing-the-target-options'> + <title>Choosing the Target Options</title> + <para> + You can choose to emulate hardware using the QEMU emulator, or you + can choose to use actual hardware. + <itemizedlist> + <listitem><para><emphasis>External HW</emphasis> – Select this option + if you will be using actual hardware.</para></listitem> + <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 you can specify custom options.</para> + <para>In Poky Tree Mode the kernel you built will be located in the + Poky Build tree in <filename>tmp/deploy/images</filename> directory. + In SDK Root Mode the pre-built kernel 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. + Use the <filename>man qemu</filename> command to get help on all the options. + The following is an example custom: + <literallayout class='monospaced'> + serial ‘<-m 256 –full-screen>’ + </literallayout> + </para> + <para> + Regardless of the mode, Sysroot is already defined in the “Sysroot” + field.</para></listitem> + </itemizedlist> + </para> + <para> + Click the “OK” 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 projects in a terminal window see + <xref linkend='using-the-command-line'> “Using the Command Line”</xref> + section. + </para> + <para> + To create a project based on a Yocto template and then display the source code, + follow these steps: + <orderedlist> + <listitem><para>Select File -> New -> Project.</para></listitem> + <listitem><para>Double click “CC++”.</para></listitem> + <listitem><para>Double click “C Project” to create the project.</para></listitem> + <listitem><para>Double click “Yocto SDK Project”.</para></listitem> + <listitem><para>Select “Hello World ANSI C Autotools Project”. + This is an Autotools-based project based on a Yocto Project template.</para></listitem> + <listitem><para>Put a name in the “Project name:” field.</para></listitem> + <listitem><para>Click “Next”.</para></listitem> + <listitem><para>Add information in the “Author” field.</para></listitem> + <listitem><para>Use “GNU General Public License v2.0” for the License.</para></listitem> + <listitem><para>Click “Finish”.</para></listitem> + <listitem><para>Answer ‘Yes” to the open perspective prompt.</para></listitem> + <listitem><para>In the Project Explorer expand your project.</para></listitem> + <listitem><para>Expand ‘src’.</para></listitem> + <listitem><para>Double click on your source file and the code appears + in the window. + This is the template.</para></listitem> + </orderedlist> + </para> +</section> +<section id='configuring-the-cross-toolchains'> +<title>Configuring the Cross-Toolchains</title> + <para> + The previous section, <xref linkend='configuring-the-cross-compiler-options'> + “Configuring the Cross-Compiler Options”</xref>, set up the default project + configurations. + You can change these settings for a given project by following these steps: + <orderedlist> + <listitem><para>Select Project -> Invoke Yocto Tools -> Reconfigure Yocto. + This brings up the project Yocto Settings Dialog. + Settings are inherited from the default project configuration. + The information in this dialogue is identical to that chosen earlier + for the Cross Compiler Option (SDK Root Mode or Poky Tree Mode), + the Target Architecture, and the Target Options. + The settings are inherited from the Yocto Plug-in configuration performed + after installing the plug-in.</para></listitem> + <listitem><para>Select Project -> Reconfigure Project. + This runs the <filename>autogen.sh</filename> in the workspace for your project. + The script 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 Project -> Build Project. + You should see the console updated 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> + To start the QEMU emulator from within Eclipse, follow these steps: + <orderedlist> + <listitem><para>Select Run -> External Tools -> External Tools Configurations... + This selection brings up the External Tools Configurations Dialogue.</para></listitem> + <listitem><para>Go to the left navigation area and expand ‘Program’. + You should find the image listed. + For example, qemu-x86_64-poky-linux.</para></listitem> + <listitem><para>Click on the image. + This brings up a new environment in the main area of the External + Tools Configurations Dialogue. + The Main tab is selected.</para></listitem> + <listitem><para>Click “Run” next. + This brings up a shell window.</para></listitem> + <listitem><para>Enter your host root password in the shell window at the prompt. + This sets up a Tap 0 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>ipconfig</filename> command.</para></listitem> + </orderedlist> + </para> +</section> +<section id='deploying-and-debugging-the-application'> +<title>Deploying and Debugging the Application</title> + <para> + Once QEMU is running you can deploy your application and use the emulator + to perform debugging. + Follow these steps to deploy the application. + <orderedlist> + <listitem><para>Select Run -> Debug Configurations...</para></listitem> + <listitem><para>In the left area expand “C/C++Remote Application”.</para></listitem> + <listitem><para>Locate your project and select it to bring up a new + tabbed view in the Debug Configurations dialogue.</para></listitem> + <listitem><para>Enter the absolute path into which you want to deploy + the application. + Use the Remote Absolute File Path for C/C++Application:. + For example, enter <filename>/usr/bin/<programname></filename>.</para></listitem> + <listitem><para>Click on the Debugger tab to see the cross-tool debugger + you are using.</para></listitem> + <listitem><para>Create a new connection to the QEMU instance + by clicking on “new”.</para></listitem> + <listitem><para>Select “TCF, which means Target Communication Framework.</para></listitem> + <listitem><para>Click “Next”.</para></listitem> + <listitem><para>Clear out the “host name” field and enter the IP Address + determined earlier.</para></listitem> + <listitem><para>Click Finish to close the new connections dialogue.</para></listitem> + <listitem><para>Use the drop-down menu now in the “Connection” field and pick + the IP Address you entered.</para></listitem> + <listitem><para>Click “Debug” 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 Yocto Eclipse + Plug-in through the Window -> YoctoTools 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>OProfile:</emphasis> Selecting this tool causes + the oprofile-server on the remote target to launch on the local host machine. + The oprofile-viewer must be installed on the local host machine and the + oprofile-server must be installed on the remote target, respectively, in order + to use. + You can locate both the viewer and server from + <ulink url='http://git.pokylinux.org/cgit/cgit.cgi/oprofileui/'></ulink>. + You need to compile and install the oprofile-viewer from the source code + on your local host machine. + The oprofile-server is installed by default in the image.</para></listitem> + <listitem><para><emphasis>Lttng-ust:</emphasis> Selecting this tool runs + "usttrace" on the remote target, transfers the output data back to the + local host machine and uses "lttv-gui" to graphically display the output. + The "lttv-gui" must be installed on the local host machine to use this tool. + For information on how to use "lttng" to trace an application, see + <ulink url='http://lttng.org/files/ust/manual/ust.html'></ulink>.</para> + <para>For "Application" you must supply the absolute path name of the + application to be traced by user mode lttng. + 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>"Argument" is passed to <filename>usttrace</filename> + running on the remote target.</para></listitem> + <listitem><para><emphasis>PowerTOP:</emphasis> Selecting this tool runs + "PowerTOP" on the remote target machine and displays the results in a + new view called "powertop".</para> + <para>"Time to gather data(sec):" is the time passed in seconds before data + is gathered from the remote target for analysis.</para> + <para>"show pids in wakeups list:" corresponds to the -p argument + passed to "powertop".</para></listitem> + <listitem><para><emphasis>LatencyTOP and Perf:</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.</para></listitem> + </itemizedlist> + </para> +</section> </chapter> <!-- |