From f30b84c973945852024d99a1ed4301e2a39a5ec7 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 15 Mar 2011 15:41:35 -0600 Subject: documentation/adt-manual/adt-eclipse.xml: Initial draft for Eclipse chapter. This is the initial draft of the Eclipse chapter. (From OE-Core rev: 44512573d62fa5e209bf227d6811f9a94ec42372) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/adt-manual/adt-eclipse.xml | 443 ++++++++++++++++++++++++++++--- 1 file changed, 408 insertions(+), 35 deletions(-) (limited to 'documentation/adt-manual') 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"> - -Yocto Project Kernel Architecture and Use Manual - -
- Introduction +Working Within Eclipse - 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. - This manual describes the Yocto Project kernel by providing information - on its history, organization, benefits, and use. - The manual consists of two sections: - - 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. - 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." - + This section describes how to install and configure the Eclipse IDE + Yocto Plug-in and how to use it to develop your Yocto Project. + +
+ Setting Up the Eclipse IDE - For more information on the kernel, see the following links: - - - - - - - You can find more information on Yocto Project by visiting the website at - . - + To develop within the Eclipse IDE you need to do the following: + + Be sure the optimal version of Eclipse IDE + is installed. + Install required Eclipse plug-ins prior to installing + the Eclipse Yocto Plug-in. + Configure the Eclipse Yocto Plug-in. + + +
+ Installing Eclipse IDE + + 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 + . + 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. + + + Once you have downloaded the tarball, extract it into a clean + directory and complete the installation. + + + 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: + + Java.lang.OutOfMemoryError: PermGen space + + + + This error causes the application to hang. + + + To fix this issue you can use the ‐‐vmargs option when you start + Eclipse to increase the size of the permanent generation space: + + eclipse ‐‐vmargs ‐‐XX:PermSize=256M + + +
+ +
+ Installing Required Plug-ins and the Eclipse Yocto Plug-in + + 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: + + CDT 7.0 – + : + 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”. + RSE 3.2 – + : + 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”. + Autotools – + : + Expand the items under “Linux Tools” and select “Autotools support + for CDT (Incubation)”. + Yocto Plug-in – + : + Check the box next to “Development tools & SDKs for Yocto Linux” + to select all the items. + + + + Follow these general steps to install a plug-in: + + From within the Eclipse IDE select the + “Install New Software” item from the “Help” menu. + Click “Add…” in the “Work with:” area. + Enter the URL for the repository and leave the “Name” + field blank. + 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. + + +
+ +
+ Configuring the Plug-in + + 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. + + + To start, you need to do the following from within the Eclipse IDE: + + Choose Windows -> Preferences to display + the Preferences Dialog + Click “Yocto SDK” + + + +
+ Configuring the Cross-Compiler Options + + Choose between ‘SDK Root Mode’ and ‘Poky Tree Mode’ for Cross + Compiler Options. + + SDK Root Mode – 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 /opt/poky directory. + Poky Tree Mode – 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. + + +
+ +
+ Configuring the Sysroot + + 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. + +
+ +
+ Selecting the Target Architecture + + Use the pull-down Target Architecture menu and select the + target architecture. + + + 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 + + “Preparing to Use the Application Development Toolkit (ADT)” + section earlier in this document. + +
+ +
+ Choosing the Target Options + + You can choose to emulate hardware using the QEMU emulator, or you + can choose to use actual hardware. + + External HW – Select this option + if you will be using actual hardware. + QEMU – 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. + In Poky Tree Mode the kernel you built will be located in the + Poky Build tree in tmp/deploy/images directory. + In SDK Root Mode the pre-built kernel you downloaded is located + in the directory you specified when you downloaded the image. + 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 man qemu command to get help on all the options. + The following is an example custom: + + serial ‘<-m 256 –full-screen>’ + + + + Regardless of the mode, Sysroot is already defined in the “Sysroot” + field. + + + + Click the “OK” button to save your plug-in configurations. + +
+
+
+Creating the Project + + 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 + “Using the Command Line” + section. + + + To create a project based on a Yocto template and then display the source code, + follow these steps: + + Select File -> New -> Project. + Double click “CC++”. + Double click “C Project” to create the project. + Double click “Yocto SDK Project”. + Select “Hello World ANSI C Autotools Project”. + This is an Autotools-based project based on a Yocto Project template. + Put a name in the “Project name:” field. + Click “Next”. + Add information in the “Author” field. + Use “GNU General Public License v2.0” for the License. + Click “Finish”. + Answer ‘Yes” to the open perspective prompt. + In the Project Explorer expand your project. + Expand ‘src’. + Double click on your source file and the code appears + in the window. + This is the template. + + +
+
+Configuring the Cross-Toolchains + + The previous section, + “Configuring the Cross-Compiler Options”, set up the default project + configurations. + You can change these settings for a given project by following these steps: + + 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. + Select Project -> Reconfigure Project. + This runs the autogen.sh in the workspace for your project. + The script runs libtoolize, aclocal, + autoconf, autoheader, + automake ‐‐a, and + ./configure. + + +
+
+Building the Project + + To build the project, select Project -> Build Project. + You should see the console updated and you can note the cross-compiler you are using. + +
+
+Starting QEMU in User Space NFS Mode + + To start the QEMU emulator from within Eclipse, follow these steps: + + Select Run -> External Tools -> External Tools Configurations... + This selection brings up the External Tools Configurations Dialogue. + Go to the left navigation area and expand ‘Program’. + You should find the image listed. + For example, qemu-x86_64-poky-linux. + 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. + Click “Run” next. + This brings up a shell window. + 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. + Wait for QEMU to launch. + 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 + ipconfig command. + + +
+
+Deploying and Debugging the Application + + Once QEMU is running you can deploy your application and use the emulator + to perform debugging. + Follow these steps to deploy the application. + + Select Run -> Debug Configurations... + In the left area expand “C/C++Remote Application”. + Locate your project and select it to bring up a new + tabbed view in the Debug Configurations dialogue. + 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 /usr/bin/<programname>. + Click on the Debugger tab to see the cross-tool debugger + you are using. + Create a new connection to the QEMU instance + by clicking on “new”. + Select “TCF, which means Target Communication Framework. + Click “Next”. + Clear out the “host name” field and enter the IP Address + determined earlier. + Click Finish to close the new connections dialogue. + Use the drop-down menu now in the “Connection” field and pick + the IP Address you entered. + Click “Debug” to bring up a login screen and login. + Accept the debug perspective. + + +
+
+Running User-Space Tools + + 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. + + + 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. + + + Here are some specifics about the remote tools: + + OProfile: 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 + . + 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. + Lttng-ust: 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 + . + For "Application" you must supply the absolute path name of the + application to be traced by user mode lttng. + For example, typing /path/to/foo triggers + usttrace /path/to/foo on the remote target to trace the + program /path/to/foo. + "Argument" is passed to usttrace + running on the remote target. + PowerTOP: Selecting this tool runs + "PowerTOP" on the remote target machine and displays the results in a + new view called "powertop". + "Time to gather data(sec):" is the time passed in seconds before data + is gathered from the remote target for analysis. + "show pids in wakeups list:" corresponds to the -p argument + passed to "powertop". + LatencyTOP and Perf: "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. + + +