From 4d5dc4a8908c4f67268f2058e1ea6d76f72ca0ef Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 12 Aug 2016 10:20:16 -0700 Subject: sdk-manual: Created new Mars Eclipse appendix Fixes [YOCTO #7546] First draft of the new appendix supporting the Mars version of eclipse. New appendix file created and entry made to the sdk-manual.xml file to include that new appendix file into the main book. (From yocto-docs rev: 2fb79c29bcbb5c0801f67d4c245c07c3aa9d2ca2) Signed-off-by: Scott Rifenbark sdk-manual: WIP on appendix C Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/sdk-manual/sdk-appendix-mars.xml | 878 +++++++++++++++++++++++++ documentation/sdk-manual/sdk-intro.xml | 71 +- documentation/sdk-manual/sdk-manual.xml | 2 + documentation/sdk-manual/sdk-using.xml | 152 +---- 4 files changed, 914 insertions(+), 189 deletions(-) create mode 100644 documentation/sdk-manual/sdk-appendix-mars.xml diff --git a/documentation/sdk-manual/sdk-appendix-mars.xml b/documentation/sdk-manual/sdk-appendix-mars.xml new file mode 100644 index 0000000000..185dd42092 --- /dev/null +++ b/documentation/sdk-manual/sdk-appendix-mars.xml @@ -0,0 +1,878 @@ + %poky; ] > + + + Using Eclipse Mars + + + This release of the Yocto Project supports both the Neon and Mars + versions of the Eclipse IDE. + This appendix presents information that describes how to obtain and + configure the Mars version of Eclipse. + It also provides a basic project example that you can work through + from start to finish. + For general information on using the Eclipse IDE and the Yocto + Project Eclipse Plug-In, see the + "Developing Applications Using Eclipse" + section. + + +
+ Setting Up the Mars Version of the Eclipse IDE + + + To develop within the Eclipse IDE, you need to do the following: + + Install the Mars 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 Mars Eclipse IDE + + + Follow these steps to locate, install, and configure + Mars Eclipse: + + Locate the Mars Download: + Open a browser and go to + http://www.eclipse.org/mars/. + + Download the Tarball: + Click the "Download" button and then use the "Linux + for Eclipse IDE for C++ Developers" + appropriate for your development system + (e.g. + 64-bit under Linux for Eclipse IDE for C++ Developers + if your development system is a Linux 64-bit machine. + + Unpack the Tarball: + Move to a clean directory and unpack the tarball. + Here is an example: + + $ cd ~ + $ tar -xzvf ~/Downloads/eclipse-cpp-mars-2-linux-gtk-x86_64.tar.gz + + Everything unpacks into a folder named "Eclipse". + + Launch Eclipse: + Double click the "Eclipse" file in the folder to + launch Eclipse. + + + +
+ +
+ Configuring the Mars Eclipse IDE + + + Follow these steps to configure the Mars Eclipse IDE. + + Depending on how you installed Eclipse and what you have + already done, some of the options will not appear. + If you cannot find an option as directed by the manual, + it has already been installed. + + + Be sure Eclipse is running and + you are in your workbench. + + Select "Install New Software" from + the "Help" pull-down menu. + + Select + "Mars - http://download.eclipse.org/releases/mars" + from the "Work with:" pull-down menu. + + Expand the box next to + "Linux Tools" and select "C/C++ Remote + (Over TCF/TE) Run/Debug Launcher" and + "TM Terminal". + + Expand the box next to "Mobile and + Device Development" and select the following + boxes: + + C/C++ Remote (Over TCF/TE) Run/Debug Launcher + Remote System Explorer User Actions + TM Terminal + TCF Remote System Explorer add-in + TCF Target Explorer + + + Expand the box next to + "Programming Languages" and select the + following boxes: + + C/C++ Autotools Support + C/C++ Development Tools SDK + + + + Complete the installation by clicking through + appropriate "Next" and "Finish" buttons. + + + +
+ +
+ Installing or Accessing the Mars 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. + + +
+ Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site + + + To install the Mars 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;/mars + 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 boxes next to the following: + + Yocto Project ADT Plug-in + Yocto Project Bitbake Commander Plug-in + Yocto Project Documentation plug-in + + + Complete the remaining software + installation steps and then restart the Eclipse + IDE to finish the installation of the plug-in. + + You can click "OK" when prompted about + installing software that contains unsigned + content. + + + + +
+ +
+ Installing the Plug-in Using the Latest Source Code + + + To install the Mars Eclipse Yocto Plug-in from the latest + source code, follow these steps: + + Be sure your development system + has JDK 1.7+ + + install X11-related packages: + + $ sudo apt-get install xauth + + + In a new terminal shell, create a Git + repository with: + + $ cd ~ + $ git clone git://git.yoctoproject.org/eclipse-poky + + + Use Git to checkout the correct + tag: + + Developer's Note + + Because the 2.2 tag will not exist until after + the release, I must first do the following + before running the + git checkout mars/yocto-&DISTRO; + command in this step: + + $ git tag mars/yocto-2.2 origin/mars-master + + + + + $ cd ~/eclipse-poky + $ git checkout mars/yocto-&DISTRO; + + This puts you in a detached HEAD state, which + is fine since you are only going to be building + and not developing. + + Change to the + scripts + directory within the Git repository: + + $ cd scripts + + + Set up the local build environment + by running the setup script: + + $ ./setup.sh + + When the script finishes execution, + it prompts you with instructions on how to run + the build.sh script, which + is also in the scripts + directory of the Git repository created + earlier. + + Run the build.sh + script as directed. + Be sure to provide the tag name, documentation + branch, and a release name. + + Following is an example: + + $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l mars/yocto-&DISTRO; master yocto-&DISTRO; 2>&1 | tee build.log + + The previous example command adds the tag you + need for mars/yocto-&DISTRO; + to HEAD, then tells the + build script to use the local (-l) Git checkout + for the build. + 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 earlier. + This ZIP file should not be "unzipped", and must + be the *archive.zip file + created by running the + build.sh script. + + Click the "OK" button. + + Check the boxes that appear in + the installation window to install the + following: + + Developer's Note + + Right now, a check box for BitBake Commander + is appearing. + This probably needs removed. + Do not check this box. + + + + Yocto Project SDK Plug-in + Yocto Project Documentation plug-in + + + Finish the installation by clicking + through the appropriate buttons. + You can click "OK" when prompted about + installing software that contains unsigned + content. + + 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 Mars Eclipse Yocto Plug-in" + section. +
+
+ +
+ Configuring the Mars Eclipse Yocto Plug-in + + + Configuring the Mars 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 "Preferences" from the + "Window" menu to display the Preferences Dialog. + + Click "Yocto Project SDK" to display + the configuration screen. + + + The following sub-sections describe how to configure the + the plug-in. + + Throughout the descriptions, a start-to-finish example for + preparing a QEMU image for use with Eclipse is referenced + as the "wiki" and is linked to the example on the + Cookbook guide to Making an Eclipse Debug Capable Image + wiki page. + + + +
+ Configuring the Cross-Compiler Options + + + Cross Compiler options enable Eclipse to use your specific + cross compiler toolchain. + To configure these 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 type 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. + In other words, you have downloaded + and installed a pre-built toolchain + for an existing image. + + + Build System Derived Toolchain: + Select this type if you built the + toolchain as part of the + Build Directory. + When you select + Build system derived toolchain, + you are using the toolchain built and + bundled inside the Build Directory. + For example, suppose you created a + suitable image using the steps in the + wiki. + In this situation, you would select the + Build system derived toolchain. + + + + Specify the Toolchain Root Location: + If you are using a stand-alone pre-built + toolchain, you should be pointing to where it is + installed (e.g. + /opt/poky/&DISTRO;). + See the + "Installing the SDK" + section for information about how the SDK is + installed. + If you are using a build system derived + toolchain, the path you provide for the + Toolchain Root Location + field is the + Build Directory + from which you run the + bitbake command (e.g + /home/scottrif/poky/build). + For more information, see the + "Building an SDK Installer" + section. + + Specify Sysroot Location: + This location is where the root filesystem for + the target hardware resides. + + This location depends on where you + separately extracted and installed the target + filesystem. + As an example, suppose you prepared an image + using the steps in the + wiki. + If so, the MY_QEMU_ROOTFS + directory is found in the + Build Directory + and you would browse to and select that directory + (e.g. /home/scottrif/build/MY_QEMU_ROOTFS). + + For more information on how to install the + toolchain and on how to extract and install the + sysroot filesystem, see the + "Building an SDK Installer" + section. + + 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 Images" + section of the Yocto Project Quick Start for + more information. + You can also see the + wiki. + + + +
+ +
+ 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 the + Build system derived toolchain, + the target kernel you built will be located in + the + Build Directory + in + tmp/deploy/images/machine + directory. + As an example, suppose you performed the steps in + the + wiki. + In this case, you specify your Build Directory path + followed by the image (e.g. + /home/scottrif/poky/tmp/deploy/images/qemux86/bzImage-qemux86.bin). + + If you selected the 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 "Apply" and "OK" 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 + "Makefile-Based Projects" + section. + + Do not use special characters in project names + (e.g. spaces, underscores, etc.). Doing so can + cause configuration to fail. + + + + + To create a project based on a Yocto template and then display + the source code, follow these steps: + + Select "C Project" from the "File -> New" menu. + + Expand Yocto Project SDK Autotools Project. + + Select Hello World ANSI C Autotools Projects. + 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 + (e.g. hello). + + Click "Next". + + Add appropriate information in the various + fields. + + 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 Mars Eclipse Yocto Plug-in", + sets up the default project configurations. + You can override these settings for a given project by following + these steps: + + Select "Yocto Project Settings" from + the "Project -> Properties" menu. + This selection brings up the Yocto 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 + provided using the Preferences Dialog as described + earlier in the + "Configuring the Mars Eclipse Yocto Plug-in" section. + The Yocto Project Settings Dialog allows you to override + those default settings for a given project. + + Make or verify your configurations for the + project and click "OK". + + Right-click in the navigation pane and + select "Reconfigure Project" from the pop-up menu. + 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 "Build All" from the + "Project" menu. + The console should update and you can note the cross-compiler + you are using. + + When building "Yocto Project SDK Autotools" projects, the + Eclipse IDE might display error messages for + Functions/Symbols/Types that cannot be "resolved", even when + the related include file is listed at the project navigator and + when the project is able to build. + For these cases only, it is recommended to add a new linked + folder to the appropriate sysroot. + Use these steps to add the linked folder: + + + Select the project. + + + Select "Folder" from the + File > New menu. + + + In the "New Folder" Dialog, select "Link to alternate + location (linked folder)". + + + Click "Browse" to navigate to the include folder inside + the same sysroot location selected in the Yocto Project + configuration preferences. + + + Click "OK". + + + Click "Finish" to save the linked folder. + + + + +
+ +
+ Starting QEMU in User-Space NFS Mode + + + To start the QEMU emulator from within Eclipse, follow these + steps: + + See the + "Using the Quick EMUlator (QEMU)" + chapter in the Yocto Project Development Manual + for more information on using QEMU. + + + Expose and select "External Tools + Configurations ..." from the "Run -> External Tools" menu. + + + Locate and select your image in the navigation panel to + the left (e.g. qemu_i586-poky-linux). + + + Click "Run" to launch QEMU. + + The host on which you are running QEMU must have + the rpcbind utility running to be + able to make RPC calls on a server on that machine. + If QEMU does not invoke and you receive error messages + involving rpcbind, follow the + suggestions to get the service running. + As an example, on a new Ubuntu 16.04 LTS installation, + you must do the following in order to get QEMU to + launch: + + $ sudo apt-get install rpcbind + + After installing rpcbind, you + need to edit the + /etc/init.d/rpcbind file to + include the following line: + + OPTIONS="-i -w" + + After modifying the file, you need to start the + service: + + $ sudo service portmap restart + + + + 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. + One useful task at this point would be to determine the + IP Address for the user-space NFS by using the + ifconfig command. + The IP address of the QEMU machine appears in the + xterm window. + You can use this address to help you see which particular + IP address the instance of QEMU is using. + + + +
+ +
+ Deploying and Debugging the Application + + + Once the QEMU emulator is running the image, you can deploy + your application using the Eclipse IDE and then use + the emulator to perform debugging. + Follow these steps to deploy the application. + + Currently, Eclipse does not support SSH port forwarding. + Consequently, if you need to run or debug a remote + application using the host display, you must create a + tunneling connection from outside Eclipse and keep + that connection alive during your work. + For example, in a new terminal, run the following: + + $ ssh -XY user_name@remote_host_ip + + Using the above form, here is an example: + + $ ssh -XY root@192.168.7.2 + + After running the command, add the command to be executed + in Eclipse's run configuration before the application + as follows: + + export DISPLAY=:10.0 + + Be sure to not destroy the connection during your QEMU + session (i.e. do not + exit out of or close that shell). + + + Select "Debug Configurations..." from the + "Run" menu. + 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. + + Click on the "Debugger" tab to see the + cross-tool debugger you are using. + Be sure to change to the debugger perspective in Eclipse. + + Click on the "Main" tab. + + Create a new connection to the QEMU instance + by clicking on "new". + Select SSH, which means + Secure Socket Shell. + Optionally, you can select an TCF connection instead. + + Click "Next". + + Clear out the "host name" field and enter + the IP Address determined earlier (e.g. 192.168.7.2). + + Click "Finish" to close the + New Connections Dialog. + + If necessary, use the drop-down menu now in the + "Connection" field and pick the IP Address you entered. + + Assuming you are connecting as the root user, + which is the default for QEMU x86-64 SDK images provided by + the Yocto Project, in the "Remote Absolute File Path for + C/C++ Application" field, browse to + /home/root. + You could also browse to any other path you have write + access to on the target such as + /usr/bin. + This location is where your application will be located on + the QEMU system. + If you fail to browse to and specify an appropriate + location, QEMU will not understand what to remotely + launch. + Eclipse is helpful in that it auto fills your application + name for you assuming you browsed to a directory. + + If you are prompted to provide a username and to + optionally set a password, be sure you provide + "root" as the username and you leave the password + field blank. + + + + Be sure you change to the "Debug" perspective in Eclipse. + + Click "Debug" + + Accept the debug perspective. + + + +
+ +
+ Using Linuxtools + + + As mentioned earlier in the manual, performance tools exist + (Linuxtools) that enhance your development experience. + These tools are aids in developing and debugging applications and + images. + You can run these tools from within the Eclipse IDE through the + "Linuxtools" menu. + + + + For information on how to configure and use these tools, see + http://www.eclipse.org/linuxtools/. + +
+ + diff --git a/documentation/sdk-manual/sdk-intro.xml b/documentation/sdk-manual/sdk-intro.xml index 781cebf188..0995f79a93 100644 --- a/documentation/sdk-manual/sdk-intro.xml +++ b/documentation/sdk-manual/sdk-intro.xml @@ -113,8 +113,9 @@ of the SDK but is rather available for use as part of the development process. - Various user-space tools that greatly enhance - your application development experience. + Various performance-related + tools + that can enhance your development experience. These tools are also separate from the actual SDK but can be independently obtained and used in the development process. @@ -196,9 +197,16 @@ 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. + The environment also supports many performance-related + tools + that enhance your development experience. + + Previous releases of the Eclipse Yocto Plug-in supported + "user-space tools" (i.e. LatencyTOP, PowerTOP, Perf, SystemTap, + and Lttng-ust) that also added to the development experience. + These tools have been deprecated beginning with this release + of the plug-in. + @@ -210,54 +218,15 @@ -
- User-Space Tools +
+ Performance Enhancing Tools - User-space tools, which are available as part of the SDK - development environment, can be helpful. - The tools include LatencyTOP, PowerTOP, Perf, SystemTap, - and Lttng-ust. - These tools are common development tools for the Linux platform. - - LatencyTOP: LatencyTOP - focuses on latency that causes skips in audio, stutters in - your desktop experience, or situations that overload your - server even when you have plenty of CPU power left. - - PowerTOP: Helps you - determine what software is using the most power. - You can find out more about PowerTOP at - . - Perf: Performance counters - for Linux used to keep track of certain types of hardware - and software events. - For more information on these types of counters see - . - For examples on how to setup and use this tool, see the - "perf" - section in the Yocto Project Profiling and Tracing Manual. - - SystemTap: A free software - infrastructure that simplifies information gathering about - a running Linux system. - This information helps you diagnose performance or - functional problems. - SystemTap is not available as a user-space tool through - the Eclipse IDE Yocto Plug-in. - See - for more information on SystemTap. - For examples on how to setup and use this tool, see the - "SystemTap" - section in the Yocto Project Profiling and Tracing Manual. - - Lttng-ust: A User-space - Tracer designed to provide detailed information on - user-space activity. - See for more - information on Lttng-ust. - - + Supported performance enhancing tools are available that let you + profile, debug, and perform tracing on your projects developed + using Eclipse. + For information on these tools see + http://www.eclipse.org/linuxtools/.
diff --git a/documentation/sdk-manual/sdk-manual.xml b/documentation/sdk-manual/sdk-manual.xml index b690a14012..39a8689195 100644 --- a/documentation/sdk-manual/sdk-manual.xml +++ b/documentation/sdk-manual/sdk-manual.xml @@ -74,6 +74,8 @@ + +