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/adt-manual/adt-eclipse.xml | 740 ------------------------------- documentation/adt-manual/adt-intro.xml | 20 +- documentation/adt-manual/adt-manual.xml | 2 - 3 files changed, 15 insertions(+), 747 deletions(-) delete mode 100644 documentation/adt-manual/adt-eclipse.xml (limited to 'documentation/adt-manual') diff --git a/documentation/adt-manual/adt-eclipse.xml b/documentation/adt-manual/adt-eclipse.xml deleted file mode 100644 index 4d400ad6df..0000000000 --- a/documentation/adt-manual/adt-eclipse.xml +++ /dev/null @@ -1,740 +0,0 @@ - %poky; ] > - - -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" 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 section "Using - BitBake and the build directory" 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". - - - - 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 structure - 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. - - -
-
- - diff --git a/documentation/adt-manual/adt-intro.xml b/documentation/adt-manual/adt-intro.xml index 04c47369f9..93737826b5 100644 --- a/documentation/adt-manual/adt-intro.xml +++ b/documentation/adt-manual/adt-intro.xml @@ -13,11 +13,13 @@ The Yocto Project provides an application development environment based on - an Application Development Toolkit (ADT). - This manual describes the ADT and how you can configure and install it. - You will also learn how to customize the development packages installation, - learn about the Eclipse Yocto Plug-in, and learn how to use command line - development for both Autotools-based and Makefile-based projects. + an Application Development Toolkit (ADT) and the availability of stand-alone + cross-development toolchains and other tools. + This manual describes the ADT and how you can configure and install it, + how to access and use the cross-development toolchains, how to + customize the development packages installation, + how to use command line development for both Autotools-based and Makefile-based projects, + and an introduction to the Eclipse Yocto Plug-in.
@@ -88,6 +90,14 @@ remote profiling, tracing, collection of power data, collection of latency data, and collection of performance data. + + + For information about the application development workflow that uses the Eclipse + IDE and for a detailed example of how to install and configure the Eclipse + Yocto Project Plug-in, see the + "Working Within Eclipse" section + of the Yocto Project Development Manual. +
diff --git a/documentation/adt-manual/adt-manual.xml b/documentation/adt-manual/adt-manual.xml index c553e7cc08..285c347fae 100644 --- a/documentation/adt-manual/adt-manual.xml +++ b/documentation/adt-manual/adt-manual.xml @@ -85,8 +85,6 @@ - -