From 6ee6a144918ed141bb1da2fca7d98ca465539be0 Mon Sep 17 00:00:00 2001 From: Kristi Rifenbark Date: Tue, 27 Mar 2018 10:11:06 -0700 Subject: sdk-manual: Added new appendix for Neon Fixed [YOCTO #12417] (From yocto-docs rev: 9f6b874740b98c5b3eed1c06dcf5fbe687279ca8) Signed-off-by: Kristi Rifenbark Signed-off-by: Richard Purdie --- documentation/ref-manual/resources.xml | 2 +- documentation/sdk-manual/sdk-appendix-neon.xml | 920 +++++++++++++++++++++++ documentation/sdk-manual/sdk-eclipse-project.xml | 20 +- 3 files changed, 931 insertions(+), 11 deletions(-) create mode 100644 documentation/sdk-manual/sdk-appendix-neon.xml (limited to 'documentation') diff --git a/documentation/ref-manual/resources.xml b/documentation/ref-manual/resources.xml index a6a90febc2..9ad4d2eaa9 100644 --- a/documentation/ref-manual/resources.xml +++ b/documentation/ref-manual/resources.xml @@ -252,7 +252,7 @@ - Eclipse IDE Yocto Plug-in: + Eclipse IDE Yocto Plug-in: Instructions that demonstrate how an application developer uses the Eclipse Yocto Project Plug-in feature within diff --git a/documentation/sdk-manual/sdk-appendix-neon.xml b/documentation/sdk-manual/sdk-appendix-neon.xml new file mode 100644 index 0000000000..ca6198cadc --- /dev/null +++ b/documentation/sdk-manual/sdk-appendix-neon.xml @@ -0,0 +1,920 @@ + %poky; ] > + + + Using Eclipse Neon + + + This release of the Yocto Project supports both the Oxygen and Neon + versions of the Eclipse IDE. + This appendix presents information that describes how to obtain and + configure the Neon 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" + Chapter. + + +
+ Setting Up the Neon Version of the Eclipse IDE + + + To develop within the Eclipse IDE, you need to do the following: + + Install the Neon 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 Neon Eclipse IDE + + + Follow these steps to locate, install, and configure + Neon Eclipse: + + Locate the Neon Download: + Open a browser and go to + http://www.eclipse.org/neon/. + + 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-neon-2-linux-gtk-x86_64.tar.gz + + Everything unpacks into a folder named "Eclipse". + + Launch the Installer: + Use the following commands to launch the installer: + + $ cd ~/eclipse-installer + $ ./eclipse-inst + + + Select Your IDE: + From the list, select the "Eclipse IDE for C/C++ + Developers". + + Install the Software: + Accept the default "cpp-neon" directory and click + "Install". + Accept any license agreements and approve any + certificates. + + Launch Neon: + Click the "Launch" button and accept the default + "workspace". + + + +
+ +
+ Configuring the Neon Eclipse IDE + + + Follow these steps to configure the Neon 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 + "Neon - http://download.eclipse.org/releases/neon" + from the "Work with:" pull-down menu. + + Expand the box next to + "Linux Tools" and select the following + + C/C++ Remote (Over TCF/TE) Run/Debug Launcher + 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 box: + + C/C++ Development Tools SDK + + + + Complete the installation by clicking through + appropriate "Next" and "Finish" buttons. + + + +
+ +
+ Installing or Accessing the Neon 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 Neon 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;/neon + 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 SDK 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 Neon Eclipse Yocto Plug-in from the latest + source code, follow these steps: + + Be sure your development system + has JDK 1.8+ + + 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-yocto + + + Use Git to checkout the correct + tag: + + $ cd ~/eclipse-yocto + $ git checkout neon/yocto-&DISTRO; + + This creates a local tag named + neon/yocto-&DISTRO; based on + the branch origin/neon-master. + 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-yocto/scripts/eclipse ./build.sh -l neon/yocto-&DISTRO; master yocto-&DISTRO; 2>&1 | tee build.log + + The previous example command adds the tag you + need for neon/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: + + 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 Neon Eclipse Yocto Plug-in" + section. +
+
+ +
+ Configuring the Neon Eclipse Yocto Plug-in + + + Configuring the Neon 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 when you either built + it or downloaded it. + + If you downloaded the root filesystem + for the target hardware rather than + built it, you must download the + sato-sdk image + in order to build any c/c++ projects. + + 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/build/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 the 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 are 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 Neon 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 Neon 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 Tasks 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 a TCF connection instead. + + Click "Next". + + Clear out the "Connection name" field and + enter any name you want for the connection. + + Put the IP address for the connection in + the "Host" field. + For QEMU, the default is 192.168.7.2. + However, if a previous QEMU session did not exit + cleanly, the IP address increments (e.g. + 192.168.7.3). + + You can find the IP address for the current QEMU + session by looking in the xterm that opens when + you launch QEMU. + + + Enter root, which + is the default for QEMU, for the "User" field. + Be sure to leave the password field empty. + + 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/ProjectName + (e.g. /home/root/hello). + 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. + Tips + + + 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. + + + If browsing to a directory fails or times + out, but you can + ssh into your QEMU + or target from the command line and you + have proxies set up, it is likely that + Eclipse is sending the SSH traffic to a + proxy. + In this case, either use TCF , or click on + "Configure proxy settings" in the + connection dialog and add the target IP + address to the "bypass proxy" section. + You might also need to change + "Active Provider" from Native to Manual. + + + + + + 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-eclipse-project.xml b/documentation/sdk-manual/sdk-eclipse-project.xml index 76963a1b51..6014e5b19a 100644 --- a/documentation/sdk-manual/sdk-eclipse-project.xml +++ b/documentation/sdk-manual/sdk-eclipse-project.xml @@ -179,13 +179,13 @@ collection of power data, collection of latency data, and collection of performance data. - This release of the Yocto Project supports both the Neon - and Mars versions of the Eclipse IDE. - This section provides information on how to use the Neon + This release of the Yocto Project supports both the Oxygen + and Neon versions of the Eclipse IDE. + This section provides information on how to use the Oxygen release with the Yocto Project. - For information on how to use the Mars version of Eclipse + For information on how to use the Neon version of Eclipse with the Yocto Project, see - "Appendix C. + "Appendix C. @@ -533,14 +533,14 @@ At this point you should be able to configure the Eclipse Yocto Plug-in as described in the - "Configuring the Neon Eclipse Yocto Plug-in" + "Configuring the Oxygen Eclipse Yocto Plug-in" section. -
- Configuring the Neon Eclipse Yocto Plug-in +
+ Configuring the Oxygen Eclipse Yocto Plug-in Configuring the Neon Eclipse Yocto Plug-in involves @@ -862,7 +862,7 @@ The earlier section, - "Configuring the Neon Eclipse Yocto Plug-in", + "Configuring the Oxygen Eclipse Yocto Plug-in", sets up the default project configurations. You can override these settings for a given project by following these steps: @@ -877,7 +877,7 @@ Target Options for a project are inherited from settings you provided using the Preferences Dialog as described earlier in the - "Configuring the Neon Eclipse Yocto Plug-in" + "Configuring the Oxygen Eclipse Yocto Plug-in" section. The Yocto Project Settings Dialog allows you to override those default settings for a given -- cgit v1.2.3-54-g00ecf