From 41c7020d7ae6c81e8fa092f2a0c8e0c3ac976a62 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 23 Jul 2012 11:23:56 -0700 Subject: documentation: Moved the Eclipse chapter to the YP Dev Manual. The detailed chapter that describes how to install and configure the Eclipse Yocto Plug-in has been moved to become a subsection of the "Workflow" chapter in the YP Development Manual. This commit accomplished the bulk move, edits to integrate the information, and fixes to all cross-references. Moving the chapter creates a sectioning issue in the YP Development manual that results in subsections that are six levels deep. Not ideal. Will look at fixing these with a subsequent commit. (From yocto-docs rev: e6abff8f578f2cf6997895260f607395281ae8e8) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-model.xml | 739 ++++++++++++++++++++++++++ 1 file changed, 739 insertions(+) (limited to 'documentation/dev-manual') diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index b5274b8452..3bfd1a3963 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -641,6 +641,745 @@ +
+ Working Within Eclipse + + + The Eclipse IDE is a popular development environment and it fully supports + development using the Yocto Project. + When you install and configure the Eclipse Yocto Project Plug-in into + the Eclipse IDE, you maximize your Yocto Project 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. + + + + This section describes how to install and configure the Eclipse IDE + Yocto Plug-in and how to use it to develop your application. + + +
+ Setting Up the Eclipse IDE + + + To develop within the Eclipse IDE, you need to do the following: + + Install the optimal version of the Eclipse IDE. + Configure the Eclipse IDE. + Install the Eclipse Yocto Plug-in. + Configure the Eclipse Yocto Plug-in. + + + 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. + + + +
+ Installing the Eclipse IDE + + + It is recommended that you have the Indigo 3.7.2 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 particular to your development + host. + 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. + For example, the following commands unpack and install the Eclipse IDE + tarball found in the Downloads area + into a clean directory using the default name eclipse: + + $ cd ~ + $ tar -xzvf ~/Downloads/eclipse-SDK-3.7.2-linux-gtk-x86_64.tar.gz + + + + + 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: + + 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 + + +
+ +
+ Configuring the Eclipse IDE + + + Before installing and configuring the Eclipse Yocto Plug-in, you need to configure + the Eclipse IDE. + Follow these general steps to configure Eclipse: + + Start the Eclipse IDE. + Make sure you are in your Workbench and select + "Install New Software" from the "Help" pull-down menu. + + Select indigo - &ECLIPSE_INDIGO_URL; + from the "Work with:" pull-down menu. + Expand the box next to Programming Languages + and select the Autotools Support for CDT (incubation) + and C/C++ Development Tools boxes. + Expand the box next to "Linux Tools" and select the + "LTTng - Linux Tracing Toolkit(incubation)" boxes. + Complete the installation and restart the Eclipse IDE. + After the Eclipse IDE restarts and from the Workbench, select + "Install New Software" from the "Help" pull-down menu. + Click the + "Available Software Sites" link. + Check the box next to + &ECLIPSE_UPDATES_URL; + and click "OK". + Select &ECLIPSE_UPDATES_URL; + from the "Work with:" pull-down menu. + Check the box next to TM and RSE Main Features. + + Expand the box next to TM and RSE Optional Add-ons + and select every item except RSE Unit Tests and + RSE WinCE Services (incubation). + Complete the installation and restart the Eclipse IDE. + If necessary, select + "Install New Software" from the "Help" pull-down menu so you can click the + "Available Software Sites" link again. + After clicking "Available Software Sites", check the box next to + http://download.eclipse.org/tools/cdt/releases/indigo + and click "OK". + Select &ECLIPSE_INDIGO_CDT_URL; + from the "Work with:" pull-down menu. + Check the box next to CDT Main Features. + + Expand the box next to CDT Optional Features + and select C/C++ Remote Launch and + Target Communication Framework (incubation). + Complete the installation and restart the Eclipse IDE. + + +
+ +
+ Installing or Accessing the Eclipse Yocto Plug-in + + + 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. + If you don't want to permanently install the plug-in but just want to try it out + within the Eclipse environment, you can import the plug-in project from the + Yocto Project source repositories. + + +
+ Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site + + + To install the Eclipse Yocto Plug-in from the update site, + follow these steps: + + Start up the Eclipse IDE. + In Eclipse, select "Install New Software" from the "Help" menu. + Click "Add..." in the "Work with:" area. + Enter + &ECLIPSE_DL_PLUGIN_URL; + in the URL field and provide a meaningful name in the "Name" field. + Click "OK" to have the entry added to the "Work with:" + drop-down list. + Select the entry for the plug-in from the "Work with:" drop-down + list. + Check the box next to Development tools and SDKs for Yocto Linux. + + Complete the remaining software installation steps and + then restart the Eclipse IDE to finish the installation of the plug-in. + + + +
+ +
+ Installing the Plug-in Using the Latest Source Code + + + To install the Eclipse Yocto Plug-in from the latest source code, follow these steps: + + Open a shell and create a Git repository with: + + $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse + + For this example, the repository is named + ~/yocto-eclipse. + Locate the build.sh script in the + Git repository you created in the previous step. + The script is located in the scripts. + Be sure to set and export the ECLIPSE_HOME environment + variable to the top-level directory in which you installed the Indigo + version of Eclipse. + For example, if your Eclipse directory is $HOME/eclipse, + use the following: + + $ export ECLIPSE_HOME=$HOME/eclipse + + Run the build.sh script and provide the + name of the Git branch along with the Yocto Project release you are + using. + Here is an example that uses the master Git repository + and the 1.1M4 release: + + $ scripts/build.sh master 1.1M4 + + After running the script, the file + org.yocto.sdk-<release>-<date>-archive.zip + is in the current directory. + If necessary, start the Eclipse IDE and be sure you are in the + Workbench. + Select "Install New Software" from the "Help" pull-down menu. + + Click "Add". + Provide anything you want in the "Name" field. + Click "Archive" and browse to the ZIP file you built + in step four. + This ZIP file should not be "unzipped", and must be the + *archive.zip file created by running the + build.sh script. + Check the box next to the new entry in the installation window and complete + the installation. + Restart the Eclipse IDE if necessary. + + + + + At this point you should be able to configure the Eclipse Yocto Plug-in as described in the + "Configuring the Eclipse Yocto Plug-in" + section. +
+ +
+ Importing the Plug-in Project into the Eclipse Environment + + + Importing the Eclipse Yocto Plug-in project from the Yocto Project source repositories + is useful when you want to try out the latest plug-in from the tip of plug-in's + development tree. + It is important to understand when you import the plug-in you are not installing + it into the Eclipse application. + Rather, you are importing the project and just using it. + To import the plug-in project, follow these steps: + + Open a shell and create a Git repository with: + + $ git clone git://git.yoctoproject.org/eclipse-poky yocto-eclipse + + For this example, the repository is named + ~/yocto-eclipse. + In Eclipse, select "Import" from the "File" menu. + Expand the "General" box and select "existing projects into workspace" + and then click "Next". + Select the root directory and browse to + ~/yocto-eclipse/plugins. + Three plug-ins exist: "org.yocto.bc.ui", "org.yocto.sdk.ide", and + "org.yocto.sdk.remotetools". + Select and import all of them. + + + + + The left navigation pane in the Eclipse application shows the default projects. + Right-click on one of these projects and run it as an Eclipse application. + This brings up a second instance of Eclipse IDE that has the Yocto Plug-in. + +
+
+ +
+ Configuring the Eclipse Yocto Plug-in + + + 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). + + + + To start, you need to do the following from within the Eclipse IDE: + + Choose Windows -> Preferences to display + the Preferences Dialog + Click Yocto Project ADT + + + +
+ Configuring the Cross-Compiler Options + + + 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. + + Selecting the Toolchain Type: + Choose between Standalone pre-built toolchain + and Build system derived toolchain for Cross + Compiler Options. + + + Standalone Pre-built Toolchain: + 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. + + + Build System Derived Toolchain: + Select this mode if the cross-toolchain has been installed and built + as part of the build directory. + When you select Build system derived toolchain, + you are using the toolchain bundled + inside the build directory. + + + + Point to the Toolchain: + If you are using a stand-alone pre-built toolchain, you should be pointing to the + &YOCTO_ADTPATH_DIR; directory. + This is the location for toolchains installed by the ADT Installer or by hand. + Sections "Configuring + and Running the ADT Installer Script" and + "Using a Cross-Toolchain Tarball" + in the Yocto Project Application Developer's Guide + describe two ways to install a stand-alone cross-toolchain in the + /opt/poky directory. + It is possible to install a stand-alone cross-toolchain in a directory + other than /opt/poky. + However, doing so is discouraged. + If you are using a system-derived toolchain, the path you provide + for the Toolchain Root Location + field is the build directory. + See the "Using + BitBake and the build directory" section in the Yocto Project Application + Developer's Guide for information on how to install the toolchain into the build +directory. + Specify the Sysroot Location: + 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. + + Select the Target Architecture: + The target architecture is the type of hardware you are + going to use or emulate. + Use the pull-down Target Architecture 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 "Building an Image" section + of The Yocto Project Quick Start for more information. + + +
+ +
+ Configuring the Target Options + + + You can choose to emulate hardware using the QEMU emulator, or you + can choose to run your image on 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 specify any custom options. + If you selected Build system derived toolchain, + the target kernel you built will be located in the + build directory in tmp/deploy/images directory. + If you selected Standalone pre-built toolchain, the + pre-built image 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. + In particular, the options serial, + nographic, and kvm must all + be outside the brackets. + Use the man qemu command to get help on all the options + and their use. + The following is an example: + + serial ‘<-m 256 -full-screen>’ + + + Regardless of the mode, Sysroot is already defined as part of the + Cross Compiler Options configuration in the + Sysroot Location: field. + External HW: Select this option + if you will be using actual hardware. + + + + + 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 Makefile-based projects in a terminal window, see the section + "Using the Command Line" + in the Yocto Project Application Developer's Guide. + + + + 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. + Expand Yocto Project ADT Project. + Select Hello World ANSI C Autotools Project. + This is an Autotools-based project based on a Yocto template. + Put a name in the Project name: field. + Do not use hyphens as part of the name. + Click Next. + Add information in the Author and + Copyright notice fields. + Be sure the License field is correct. + Click Finish. + If the "open perspective" prompt appears, click "Yes" so that you + in the C/C++ perspective. + The left-hand navigation pane shows your project. + You can display your source by double clicking the project's source file. + + + +
+ +
+ Configuring the Cross-Toolchains + + + The earlier section, "Configuring + the Eclipse Yocto Plug-in", sets up the default project + configurations. + You can override these settings for a given project by following these steps: + + Select Project -> Change Yocto Project Settings: + This selection brings up the Yocot Project Settings Dialog + and allows you to make changes specific to an individual project. + + By default, the Cross Compiler Options and Target Options for a project + are inherited from settings you provide using the Preferences + Dialog as described earlier + in the "Configuring the Eclipse + Yocto Plug-in" section. + The Yocto Project Settings + Dialog allows you to override those default settings + for a given project. + Make your configurations for the project and click "OK". + Select Project -> Reconfigure Project: + This selection reconfigures the project by running + autogen.sh in the workspace for your project. + The script also runs libtoolize, aclocal, + autoconf, autoheader, + automake --a, and + ./configure. + Click on the Console tab beneath your source code to + see the results of reconfiguring your project. + + +
+ +
+ Building the Project + + + To build the project, select Project -> Build Project. + The console should update 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: + + Expose the Run -> External Tools menu. + Your image should appear as a selectable menu item. + + Select your image from the menu to launch the + emulator in a new window. + If needed, 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 can begin operating within that + environment. + For example, you could determine the IP Address + for the user-space NFS by using the ifconfig command. + + + +
+ +
+ Deploying and Debugging the Application + + + Once the QEMU emulator is running the image, using the Eclipse IDE + 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 Dialog. + Enter the absolute path into which you want to deploy + the application. + Use the Remote Absolute File Path for C/C++Application: field. + For example, enter /usr/bin/<programname>. + Click on the Debugger tab to see the cross-tool debugger + you are using. + Click on the Main tab. + 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 Dialog. + 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 Eclipse IDE through the + 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 must compile and install the oprofile-viewer 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 oprofile version 0.9.4 or + greater installed on the host. + You can locate both the viewer and server from + . + The oprofile-server is installed by default on + the core-image-sato-sdk image. + Lttng-ust: Selecting this tool runs + usttrace on the remote target, transfers the output 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 + . + 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. + Before you use the lttng-ust tool, you need to setup + the lttng Eclipse plug-in and create a lttng + project. + Do the following: + + Follow these + instructions + to download and install the lttng parser library. + + Select Window -> Open Perspective -> Other + and then select LTTng. + Click OK to change the Eclipse perspective + into the LTTng perspective. + Create a new LTTng project by selecting + File -> New -> Project. + Choose LTTng -> LTTng Project. + Click YoctoTools -> lttng-ust to start user mode + lttng on the remote target. + + After the output data has been transferred from the remote target back to the local + host machine, new traces will be imported into the selected LTTng project. + Then you can go to the LTTng project, right click the imported + trace, and set the trace type as the LTTng kernel trace. + Finally, right click the imported trace and select Open + to display the data graphically. + 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. + + +
+ +
+ Customizing an Image Using a BitBake Commander Project and Hob + + + Within Eclipse, you can create a Yocto BitBake Commander project, + edit the metadata, and then use the + Hob to build a customized + image all within one IDE. + + +
+ Creating the Yocto BitBake Commander Project + + + To create a Yocto BitBake Commander project, follow these steps: + + Select Window -> Open Perspective -> Other + and then choose Bitbake Commander. + Click OK to change the Eclipse perspective into the + Bitbake Commander perspective. + Select File -> New -> Project to create a new Yocto + Bitbake Commander project. + Choose Yocto Project Bitbake Commander -> New Yocto Project + and click Next. + Enter the Project Name and choose the Project Location. + The Yocto project's metadata files will be put under the directory + <project_location>/<project_name>. + If that directory does not exist, you need to check + the "Clone from Yocto Git Repository" box, which would execute a + git clone command to get the project's metadata files. + + Select Finish to create the project. + + +
+ +
+ Editing the Metadata Files + + + After you create the Yocto Bitbake Commander project, you can modify the metadata files + by opening them in the project. + When editing recipe files (.bb files), you can view BitBake + variable values and information by hovering the mouse pointer over the variable name and + waiting a few seconds. + + + + To edit the metadata, follow these steps: + + Select your Yocto Bitbake Commander project. + Select File -> New -> Yocto BitBake Commander -> BitBake Recipe + to open a new recipe wizard. + Point to your source by filling in the "SRC_URL" field. + For example, you can add a recipe to your + source directory + by defining "SRC_URL" as follows: + + ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz + + Click "Populate" to calculate the archive md5, sha256, + license checksum values and to auto-generate the recipe filename. + Fill in the "Description" field. + Be sure values for all required fields exist. + Click Finish. + + +
+ +
+ Building and Customizing the Image + + + To build and customize the image in Eclipse, follow these steps: + + Select your Yocto Bitbake Commander project. + Select Project -> Launch HOB. + Enter the build directory where you want to put your final images. + Click OK to launch Hob. + Use Hob to customize and build your own images. + For information on Hob, see the + Hob Project Page on the + Yocto Project website. + + +
+
+
+
Workflow Using Stand-alone Cross-development Toolchains -- cgit v1.2.3-54-g00ecf