diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml')
-rw-r--r-- | import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml | 1549 |
1 files changed, 144 insertions, 1405 deletions
diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml index 1ea47d3bb..7281e83ef 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml @@ -3,74 +3,82 @@ [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > <chapter id='sdk-using-the-standard-sdk'> - -<title>Using the Standard SDK</title> - -<para> - This chapter describes the standard SDK and how to use it. - Information covers the pieces of the SDK, how to install it, and presents - several task-based procedures common for developing with a standard SDK. - <note> - The tasks you can perform using a standard SDK are also applicable - when you are using an extensible SDK. - For information on the differences when using an extensible SDK as - compared to an extensible SDK, see the - "<link linkend='sdk-extensible'>Using the Extensible SDK</link>" - chapter. - </note> -</para> - -<section id='sdk-standard-sdk-intro'> - <title>Why use the Standard SDK and What is in It?</title> + <title>Using the Standard SDK</title> <para> - The Standard SDK provides a cross-development toolchain and libraries - tailored to the contents of a specific image. - You would use the Standard SDK if you want a more traditional toolchain - experience. + This chapter describes the standard SDK and how to install it. + Information includes unique installation and setup aspects for the + standard SDK. + <note> + For a side-by-side comparison of main features supported for a + standard SDK as compared to an extensible SDK, see the + "<link linkend='sdk-manual-intro'>Introduction</link>" + section. + </note> </para> <para> - The installed Standard SDK consists of several files and directories. - Basically, it contains an SDK environment setup script, some - configuration files, and host and target root filesystems to support - usage. - You can see the directory structure in the - "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>" - section. + You can use a standard SDK to work on Makefile, Autotools, and + Eclipse-based projects. + See the + "<link linkend='sdk-working-projects'>Working with Different Types of Projects</link>" + chapter for more information. </para> -</section> -<section id='sdk-installing-the-sdk'> - <title>Installing the SDK</title> + <section id='sdk-standard-sdk-intro'> + <title>Why use the Standard SDK and What is in It?</title> - <para> - The first thing you need to do is install the SDK on your host - development machine by running the <filename>.sh</filename> - installation script. - </para> + <para> + The Standard SDK provides a cross-development toolchain and + libraries tailored to the contents of a specific image. + You would use the Standard SDK if you want a more traditional + toolchain experience as compared to the extensible SDK, which + provides an internal build system and the + <filename>devtool</filename> functionality. + </para> - <para> - You can download a tarball installer, which includes the - pre-built toolchain, the <filename>runqemu</filename> - script, and support files from the appropriate directory under - <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. - Toolchains are available for 32-bit and 64-bit x86 development - systems from the <filename>i686</filename> and - <filename>x86_64</filename> directories, respectively. - The toolchains the Yocto Project provides are based off the - <filename>core-image-sato</filename> image and contain - libraries appropriate for developing against that image. - Each type of development system supports five or more target - architectures. - </para> + <para> + The installed Standard SDK consists of several files and + directories. + Basically, it contains an SDK environment setup script, some + configuration files, and host and target root filesystems to + support usage. + You can see the directory structure in the + "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>" + section. + </para> + </section> - <para> - The names of the tarball installer scripts are such that a - string representing the host system appears first in the - filename and then is immediately followed by a string - representing the target architecture. - <literallayout class='monospaced'> + <section id='sdk-installing-the-sdk'> + <title>Installing the SDK</title> + + <para> + The first thing you need to do is install the SDK on your host + development machine by running the <filename>*.sh</filename> + installation script. + </para> + + <para> + You can download a tarball installer, which includes the + pre-built toolchain, the <filename>runqemu</filename> + script, and support files from the appropriate directory under + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. + Toolchains are available for 32-bit and 64-bit x86 development + systems from the <filename>i686</filename> and + <filename>x86_64</filename> directories, respectively. + The toolchains the Yocto Project provides are based off the + <filename>core-image-sato</filename> image and contain + libraries appropriate for developing against that image. + Each type of development system supports five or more target + architectures. + </para> + + <para> + The names of the tarball installer scripts are such that a + string representing the host system appears first in the + filename and then is immediately followed by a string + representing the target architecture. + <literallayout class='monospaced'> poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh Where: @@ -88,1378 +96,109 @@ Yocto Project: &DISTRO;, &DISTRO;+snapshot - </literallayout> - For example, the following toolchain installer is for a 64-bit - development host system and a i586-tuned target architecture - based off the SDK for <filename>core-image-sato</filename> and - using the current &DISTRO; snapshot: - <literallayout class='monospaced'> - poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh - </literallayout> - </para> - - <para> - The SDK and toolchains are self-contained and by default are installed - into <filename>/opt/poky</filename>. - However, when you run the SDK installer, you can choose an - installation directory. - <note> - You must change the permissions on the toolchain - installer script so that it is executable: - <literallayout class='monospaced'> - $ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-2.1.sh </literallayout> - </note> - </para> - - <para> - The following command shows how to run the installer given a - toolchain tarball for a 64-bit x86 development host system and - a 32-bit x86 target architecture. - The example assumes the toolchain installer is located in - <filename>~/Downloads/</filename>. - <note> - If you do not have write permissions for the directory - into which you are installing the SDK, the installer - notifies you and exits. - Be sure you have write permissions in the directory and - run the installer again. - </note> - <literallayout class='monospaced'> - $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-2.1.sh - Poky (Yocto Project Reference Distro) SDK installer version 2.0 - =============================================================== - Enter target directory for SDK (default: /opt/poky/2.1): - You are about to install the SDK to "/opt/poky/2.1". Proceed[Y/n]? Y - Extracting SDK.......................................................................done - Setting it up...done - SDK has been successfully set up and is ready to be used. - Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. - $ . /opt/poky/2.1/environment-setup-i586-poky-linux - </literallayout> - </para> - - <para> - Again, reference the - "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>" - section for more details on the resulting directory structure of - the installed SDK. - </para> -</section> - -<section id='sdk-running-the-sdk-environment-setup-script'> - <title>Running the SDK Environment Setup Script</title> - - <para> - Once you have the SDK installed, you must run the SDK environment - setup script before you can actually use it. - This setup script resides in the directory you chose when you installed - the SDK. - For information on where this setup script can reside, see the - "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>" - Appendix. - </para> - - <para> - Before running the script, be sure it is the one that matches the - architecture for which you are developing. - Environment setup scripts begin with the string - "<filename>environment-setup</filename>" and include as part of their - name the tuned target architecture. - For example, the command to source a setup script for an IA-based - target machine using i586 tuning and located in the default SDK - installation directory is as follows: - <literallayout class='monospaced'> - $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux - </literallayout> - When you run the setup script, many environment variables are - defined: - <literallayout class='monospaced'> - <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation - <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files - <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target - <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler - <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler - <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor - <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler - <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker - <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger - <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols - <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib' - <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy' - <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump' - <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar' - <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm' - <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools - <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools - <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure - <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags - <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags - <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link - <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags - </literallayout> - </para> -</section> - -<section id='autotools-based-projects'> - <title>Autotools-Based Projects</title> - - <para> - Once you have a suitable cross-toolchain installed, it is very easy to - develop a project outside of the OpenEmbedded build system. - This section presents a simple "Helloworld" example that shows how - to set up, compile, and run the project. - </para> - - <section id='creating-and-running-a-project-based-on-gnu-autotools'> - <title>Creating and Running a Project Based on GNU Autotools</title> - - <para> - Follow these steps to create a simple Autotools-based project: - <orderedlist> - <listitem><para><emphasis>Create your directory:</emphasis> - Create a clean directory for your project and then make - that directory your working location: - <literallayout class='monospaced'> - $ mkdir $HOME/helloworld - $ cd $HOME/helloworld - </literallayout></para></listitem> - <listitem><para><emphasis>Populate the directory:</emphasis> - Create <filename>hello.c</filename>, <filename>Makefile.am</filename>, - and <filename>configure.in</filename> files as follows: - <itemizedlist> - <listitem><para>For <filename>hello.c</filename>, include - these lines: - <literallayout class='monospaced'> - #include <stdio.h> - - main() - { - printf("Hello World!\n"); - } - </literallayout></para></listitem> - <listitem><para>For <filename>Makefile.am</filename>, - include these lines: - <literallayout class='monospaced'> - bin_PROGRAMS = hello - hello_SOURCES = hello.c - </literallayout></para></listitem> - <listitem><para>For <filename>configure.in</filename>, - include these lines: - <literallayout class='monospaced'> - AC_INIT(hello.c) - AM_INIT_AUTOMAKE(hello,0.1) - AC_PROG_CC - AC_PROG_INSTALL - AC_OUTPUT(Makefile) - </literallayout></para></listitem> - </itemizedlist></para></listitem> - <listitem><para><emphasis>Source the cross-toolchain - environment setup file:</emphasis> - Installation of the cross-toolchain creates a cross-toolchain - environment setup script in the directory that the SDK - was installed. - Before you can use the tools to develop your project, you must - source this setup script. - The script begins with the string "environment-setup" and contains - the machine architecture, which is followed by the string - "poky-linux". - Here is an example that sources a script from the - default SDK installation directory that uses the - 32-bit Intel x86 Architecture and the - &DISTRO_NAME; Yocto Project release: - <literallayout class='monospaced'> - $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux - </literallayout></para></listitem> - <listitem><para><emphasis>Generate the local aclocal.m4 - files and create the configure script:</emphasis> - The following GNU Autotools generate the local - <filename>aclocal.m4</filename> files and create the - configure script: - <literallayout class='monospaced'> - $ aclocal - $ autoconf - </literallayout></para></listitem> - <listitem><para><emphasis>Generate files needed by GNU - coding standards:</emphasis> - GNU coding standards require certain files in order for the - project to be compliant. - This command creates those files: - <literallayout class='monospaced'> - $ touch NEWS README AUTHORS ChangeLog - </literallayout></para></listitem> - <listitem><para><emphasis>Generate the configure - file:</emphasis> - This command generates the <filename>configure</filename>: - <literallayout class='monospaced'> - $ automake -a - </literallayout></para></listitem> - <listitem><para><emphasis>Cross-compile the project:</emphasis> - This command compiles the project using the cross-compiler. - The - <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - environment variable provides the minimal arguments for - GNU configure: - <literallayout class='monospaced'> - $ ./configure ${CONFIGURE_FLAGS} - </literallayout></para></listitem> - <listitem><para><emphasis>Make and install the project:</emphasis> - These two commands generate and install the project into the - destination directory: - <literallayout class='monospaced'> - $ make - $ make install DESTDIR=./tmp - </literallayout></para></listitem> - <listitem><para><emphasis>Verify the installation:</emphasis> - This command is a simple way to verify the installation - of your project. - Running the command prints the architecture on which - the binary file can run. - This architecture should be the same architecture that - the installed cross-toolchain supports. - <literallayout class='monospaced'> - $ file ./tmp/usr/local/bin/hello - </literallayout></para></listitem> - <listitem><para><emphasis>Execute your project:</emphasis> - To execute the project in the shell, simply enter the name. - You could also copy the binary to the actual target hardware - and run the project there as well: - <literallayout class='monospaced'> - $ ./hello - </literallayout> - As expected, the project displays the "Hello World!" message. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='passing-host-options'> - <title>Passing Host Options</title> - - <para> - For an Autotools-based project, you can use the cross-toolchain by just - passing the appropriate host option to <filename>configure.sh</filename>. - The host option you use is derived from the name of the environment setup - script found in the directory in which you installed the cross-toolchain. - For example, the host option for an ARM-based target that uses the GNU EABI - is <filename>armv5te-poky-linux-gnueabi</filename>. - You will notice that the name of the script is - <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>. - Thus, the following command works to update your project and - rebuild it using the appropriate cross-toolchain tools: + For example, the following SDK installer is for a 64-bit + development host system and a i586-tuned target architecture + based off the SDK for <filename>core-image-sato</filename> and + using the current &DISTRO; snapshot: <literallayout class='monospaced'> - $ ./configure --host=armv5te-poky-linux-gnueabi \ - --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable> + poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh </literallayout> <note> - If the <filename>configure</filename> script results in problems recognizing the - <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> option, - regenerate the script to enable the support by doing the following and then - run the script again: - <literallayout class='monospaced'> - $ libtoolize --automake - $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \ - [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>] - $ autoconf - $ autoheader - $ automake -a - </literallayout> + As an alternative to downloading an SDK, you can build the + SDK installer. + For information on building the installer, see the + "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" + section. + Another helpful resource for building an installer is the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink> + wiki page. + This wiki page focuses on development when using the Eclipse + IDE. </note> </para> - </section> -</section> - -<section id='makefile-based-projects'> - <title>Makefile-Based Projects</title> - - <para> - For Makefile-based projects, the cross-toolchain environment variables - established by running the cross-toolchain environment setup script - are subject to general <filename>make</filename> rules. - </para> - <para> - To illustrate this, consider the following four cross-toolchain - environment variables: - <literallayout class='monospaced'> - <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux - <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux - <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types - <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types - </literallayout> - Now, consider the following three cases: - <itemizedlist> - <listitem><para><emphasis>Case 1 - No Variables Set in the <filename>Makefile</filename>:</emphasis> - Because these variables are not specifically set in the - <filename>Makefile</filename>, the variables retain their - values based on the environment. - </para></listitem> - <listitem><para><emphasis>Case 2 - Variables Set in the <filename>Makefile</filename>:</emphasis> - Specifically setting variables in the - <filename>Makefile</filename> during the build results in the - environment settings of the variables being overwritten. - </para></listitem> - <listitem><para><emphasis>Case 3 - Variables Set when the <filename>Makefile</filename> is Executed from the Command Line:</emphasis> - Executing the <filename>Makefile</filename> from the command - line results in the variables being overwritten with - command-line content regardless of what is being set in the - <filename>Makefile</filename>. - In this case, environment variables are not considered unless - you use the "-e" flag during the build: + <para> + The SDK and toolchains are self-contained and by default are + installed into <filename>/opt/poky</filename>. + However, when you run the SDK installer, you can choose an + installation directory. + <note> + You must change the permissions on the SDK + installer script so that it is executable: <literallayout class='monospaced'> - $ make -e <replaceable>file</replaceable> + $ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh </literallayout> - If you use this flag, then the environment values of the - variables override any variables specifically set in the - <filename>Makefile</filename>. - </para></listitem> - </itemizedlist> - <note> - For the list of variables set up by the cross-toolchain environment - setup script, see the - "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>" - section. - </note> - </para> -</section> - -<section id='sdk-developing-applications-using-eclipse'> - <title>Developing Applications Using <trademark class='trade'>Eclipse</trademark></title> - - <para> - If you are familiar with the popular Eclipse IDE, you can use an - Eclipse Yocto Plug-in to allow you to develop, deploy, and test your - application all from within Eclipse. - This section describes general workflow using the SDK and Eclipse - and how to configure and set up Eclipse. - </para> - - <section id='workflow-using-eclipse'> - - <title>Workflow Using <trademark class='trade'>Eclipse</trademark></title> - - <para> - The following figure and supporting list summarize the application - development general workflow that employs both the SDK Eclipse. + </note> </para> <para> - <imagedata fileref="figures/sdk-eclipse-dev-flow.png" - width="7in" depth="7in" align="center" scale="100" /> + The following command shows how to run the installer given a + toolchain tarball for a 64-bit x86 development host system and + a 32-bit x86 target architecture. + The example assumes the SDK installer is located in + <filename>~/Downloads/</filename>. + <note> + If you do not have write permissions for the directory + into which you are installing the SDK, the installer + notifies you and exits. + Be sure you have write permissions in the directory and + run the installer again. + </note> + <literallayout class='monospaced'> + $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + Poky (Yocto Project Reference Distro) SDK installer version &DISTRO; + =============================================================== + Enter target directory for SDK (default: /opt/poky/&DISTRO;): + You are about to install the SDK to "/opt/poky/&DISTRO;". Proceed[Y/n]? Y + Extracting SDK.......................................................................done + Setting it up...done + SDK has been successfully set up and is ready to be used. + Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. + $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + </literallayout> </para> <para> - <orderedlist> - <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>: - See - "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" - and - "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" sections both - in the Yocto Project Reference Manual for requirements. - In particular, be sure your host system has the - <filename>xterm</filename> package installed. - </para></listitem> - <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>: - You must have a target kernel image that has been built using the OpenEmbedded - build system.</para> - <para>Depending on whether the Yocto Project has a pre-built image that matches your target - architecture and where you are going to run the image while you develop your application - (QEMU or real hardware), the area from which you get the image differs. - <itemizedlist> - <listitem><para>Download the image from - <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> - if your target architecture is supported and you are going to develop - and test your application on actual hardware.</para></listitem> - <listitem><para>Download the image from - <ulink url='&YOCTO_QEMU_DL_URL;'> - <filename>machines/qemu</filename></ulink> if your target architecture is supported - and you are going to develop and test your application using the QEMU - emulator.</para></listitem> - <listitem><para>Build your image if you cannot find a pre-built image that matches - your target architecture. - If your target architecture is similar to a supported architecture, you can - modify the kernel image before you build it. - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>" - section in the Yocto Project Development - manual for an example.</para></listitem> - </itemizedlist></para> - <para>For information on pre-built kernel image naming schemes for images - that can run on the QEMU emulator, see the - <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. - </para></listitem> - <listitem><para><emphasis>Install the SDK</emphasis>: - The SDK provides a target-specific cross-development toolchain, the root filesystem, - the QEMU emulator, and other tools that can help you develop your application. - For information on how to install the SDK, see the - "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" - section. - </para></listitem> - <listitem><para><emphasis>Secure the target root filesystem - and the Cross-development toolchain</emphasis>: - You need to find and download the appropriate root filesystem and - the cross-development toolchain.</para> - <para>You can find the tarballs for the root filesystem in the same area used - for the kernel image. - Depending on the type of image you are running, the root filesystem you need differs. - For example, if you are developing an application that runs on an image that - supports Sato, you need to get a root filesystem that supports Sato.</para> - <para>You can find the cross-development toolchains at - <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>. - Be sure to get the correct toolchain for your development host and your - target architecture. - See the "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>" - section for information and the - "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" - section for installation information. - </para></listitem> - <listitem><para><emphasis>Create and build your application</emphasis>: - At this point, you need to have source files for your application. - Once you have the files, you can use the Eclipse IDE to import them and build the - project. - If you are not using Eclipse, you need to use the cross-development tools you have - installed to create the image.</para></listitem> - <listitem><para><emphasis>Deploy the image with the application</emphasis>: - If you are using the Eclipse IDE, you can deploy your image to the hardware or to - QEMU through the project's preferences. - If you are not using the Eclipse IDE, then you need to deploy the application - to the hardware using other methods. - Or, if you are using QEMU, you need to use that tool and - load your image in for testing. - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" - chapter in the Yocto Project Development Manual - for information on using QEMU. - </para></listitem> - <listitem><para><emphasis>Test and debug the application</emphasis>: - Once your application is deployed, you need to test it. - Within the Eclipse IDE, you can use the debugging environment along with the - set of installed user-space tools to debug your application. - Of course, the same user-space tools are available separately if you choose - not to use the Eclipse IDE.</para></listitem> - </orderedlist> + Again, reference the + "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>" + section for more details on the resulting directory structure of + the installed SDK. </para> </section> - <section id='adt-eclipse'> - <title>Working Within Eclipse</title> + <section id='sdk-running-the-sdk-environment-setup-script'> + <title>Running the SDK Environment Setup Script</title> <para> - The Eclipse IDE is a popular development environment and it fully - supports development using the Yocto Project. - <note> - This release of the Yocto Project supports both the Luna - and Kepler versions of the Eclipse IDE. - Thus, the following information provides setup information for - both versions. - </note> + Once you have the SDK installed, you must run the SDK environment + setup script before you can actually use it. + This setup script resides in the directory you chose when you + installed the SDK. + For information on where this setup script can reside, see the + "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>" + Appendix. </para> <para> - 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 as well as - actual target hardware. - 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. - </para> - - <para> - This section describes how to install and configure the Eclipse IDE - Yocto Plug-in and how to use it to develop your application. + Before running the script, be sure it is the one that matches the + architecture for which you are developing. + Environment setup scripts begin with the string + "<filename>environment-setup</filename>" and include as part of + their name the tuned target architecture. + For example, the command to source a setup script for an IA-based + target machine using i586 tuning and located in the default SDK + installation directory is as follows: + <literallayout class='monospaced'> + $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + </literallayout> + When you run the setup script, the same environment variables are + defined as are when you run the setup script for an extensible SDK. + See the + "<link linkend='sdk-running-the-extensible-sdk-environment-setup-script'>Running the Extensible SDK Environment Setup Script</link>" + section for more information. </para> - - <section id='setting-up-the-eclipse-ide'> - <title>Setting Up the Eclipse IDE</title> - - <para> - To develop within the Eclipse IDE, you need to do the following: - <orderedlist> - <listitem><para>Install the optimal version of the Eclipse - IDE.</para></listitem> - <listitem><para>Configure the Eclipse IDE. - </para></listitem> - <listitem><para>Install the Eclipse Yocto Plug-in. - </para></listitem> - <listitem><para>Configure the Eclipse Yocto Plug-in. - </para></listitem> - </orderedlist> - <note> - 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. - </note> - </para> - - <section id='installing-eclipse-ide'> - <title>Installing the Eclipse IDE</title> - - <para> - It is recommended that you have the Luna SR2 (4.4.2) - version of the Eclipse IDE installed on your development - system. - However, if you currently have the Kepler 4.3.2 version - installed and you do not want to upgrade the IDE, you can - configure Kepler to work with the Yocto Project. - </para> - - <para> - If you do not have the Luna SR2 (4.4.2) Eclipse IDE - installed, you can find the tarball at - <ulink url='&ECLIPSE_MAIN_URL;'></ulink>. - From that site, choose the appropriate download from the - "Eclipse IDE for C/C++ Developers". - This version contains the Eclipse Platform, the Java - Development Tools (JDT), and the Plug-in Development - Environment. - </para> - - <para> - Once you have downloaded the tarball, extract it into a - clean directory. - For example, the following commands unpack and install the - downloaded Eclipse IDE tarball into a clean directory - using the default name <filename>eclipse</filename>: - <literallayout class='monospaced'> - $ cd ~ - $ tar -xzvf ~/Downloads/eclipse-cpp-luna-SR2-linux-gtk-x86_64.tar.gz - </literallayout> - </para> - </section> - - <section id='configuring-the-eclipse-ide'> - <title>Configuring the Eclipse IDE</title> - - <para> - This section presents the steps needed to configure the - Eclipse IDE. - </para> - - <para> - Before installing and configuring the Eclipse Yocto Plug-in, - you need to configure the Eclipse IDE. - Follow these general steps: - <orderedlist> - <listitem><para>Start the Eclipse IDE.</para></listitem> - <listitem><para>Make sure you are in your Workbench and - select "Install New Software" from the "Help" - pull-down menu.</para></listitem> - <listitem><para>Select - <filename>Luna - &ECLIPSE_LUNA_URL;</filename> - from the "Work with:" pull-down menu. - <note> - For Kepler, select - <filename>Kepler - &ECLIPSE_KEPLER_URL;</filename> - </note> - </para></listitem> - <listitem><para>Expand the box next to "Linux Tools" - and select the - <filename>Linux Tools LTTng Tracer Control</filename>, - <filename>Linux Tools LTTng Userspace Analysis</filename>, - and - <filename>LTTng Kernel Analysis</filename> boxes. - If these selections do not appear in the list, - that means the items are already installed. - <note> - For Kepler, select - <filename>LTTng - Linux Tracing Toolkit</filename> - box. - </note> - </para></listitem> - <listitem><para>Expand the box next to "Mobile and - Device Development" and select the following boxes. - Again, if any of the following items are not - available for selection, that means the items are - already installed: - <itemizedlist> - <listitem><para><filename>C/C++ Remote Launch (Requires RSE Remote System Explorer)</filename></para></listitem> - <listitem><para><filename>Remote System Explorer End-user Runtime</filename></para></listitem> - <listitem><para><filename>Remote System Explorer User Actions</filename></para></listitem> - <listitem><para><filename>Target Management Terminal (Core SDK)</filename></para></listitem> - <listitem><para><filename>TCF Remote System Explorer add-in</filename></para></listitem> - <listitem><para><filename>TCF Target Explorer</filename></para></listitem> - </itemizedlist></para></listitem> - <listitem><para>Expand the box next to "Programming - Languages" and select the - <filename>C/C++ Autotools Support</filename> - and <filename>C/C++ Development Tools</filename> - boxes. - For Luna, these items do not appear on the list - as they are already installed. - </para></listitem> - <listitem><para>Complete the installation and restart - the Eclipse IDE.</para></listitem> - </orderedlist> - </para> - </section> - - <section id='installing-the-eclipse-yocto-plug-in'> - <title>Installing or Accessing the Eclipse Yocto Plug-in</title> - - <para> - 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. - </para> - - <section id='new-software'> - <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> - - <para> - To install the Eclipse Yocto Plug-in from the update - site, follow these steps: - <orderedlist> - <listitem><para>Start up the Eclipse IDE. - </para></listitem> - <listitem><para>In Eclipse, select "Install New - Software" from the "Help" menu. - </para></listitem> - <listitem><para>Click "Add..." in the "Work with:" - area.</para></listitem> - <listitem><para>Enter - <filename>&ECLIPSE_DL_PLUGIN_URL;/luna</filename> - in the URL field and provide a meaningful name - in the "Name" field. - <note> - If you are using Kepler, use - <filename>&ECLIPSE_DL_PLUGIN_URL;/kepler</filename> - in the URL field. - </note></para></listitem> - <listitem><para>Click "OK" to have the entry added - to the "Work with:" drop-down list. - </para></listitem> - <listitem><para>Select the entry for the plug-in - from the "Work with:" drop-down list. - </para></listitem> - <listitem><para>Check the boxes next to - <filename>Yocto Project ADT Plug-in</filename>, - <filename>Yocto Project Bitbake Commander Plug-in</filename>, - and - <filename>Yocto Project Documentation plug-in</filename>. - </para></listitem> - <listitem><para>Complete the remaining software - installation steps and then restart the Eclipse - IDE to finish the installation of the plug-in. - <note> - You can click "OK" when prompted about - installing software that contains unsigned - content. - </note> - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='zip-file-method'> - <title>Installing the Plug-in Using the Latest Source Code</title> - - <para> - To install the Eclipse Yocto Plug-in from the latest - source code, follow these steps: - <orderedlist> - <listitem><para>Be sure your development system - is not using OpenJDK to build the plug-in - by doing the following: - <orderedlist> - <listitem><para>Use the Oracle JDK. - If you don't have that, go to - <ulink url='http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html'></ulink> - and download the latest appropriate - Java SE Development Kit tarball for - your development system and - extract it into your home directory. - </para></listitem> - <listitem><para>In the shell you are going - to do your work, export the location of - the Oracle Java. - The previous step creates a new folder - for the extracted software. - You need to use the following - <filename>export</filename> command - and provide the specific location: - <literallayout class='monospaced'> - export PATH=~/<replaceable>extracted_jdk_location</replaceable>/bin:$PATH - </literallayout> - </para></listitem> - </orderedlist> - </para></listitem> - <listitem><para>In the same shell, create a Git - repository with: - <literallayout class='monospaced'> - $ cd ~ - $ git clone git://git.yoctoproject.org/eclipse-poky - </literallayout> - </para></listitem> - <listitem><para>Be sure to checkout the correct - tag. - For example, if you are using Luna, do the - following: - <literallayout class='monospaced'> - $ git checkout luna/yocto-&DISTRO; - </literallayout> - This puts you in a detached HEAD state, which - is fine since you are only going to be building - and not developing. - <note> - If you are building kepler, checkout the - <filename>kepler/yocto-&DISTRO;</filename> - branch. - </note> - </para></listitem> - <listitem><para>Change to the - <filename>scripts</filename> - directory within the Git repository: - <literallayout class='monospaced'> - $ cd scripts - </literallayout> - </para></listitem> - <listitem><para>Set up the local build environment - by running the setup script: - <literallayout class='monospaced'> - $ ./setup.sh - </literallayout> - </para></listitem> - <listitem><para>When the script finishes execution, - it prompts you with instructions on how to run - the <filename>build.sh</filename> script, which - is also in the <filename>scripts</filename> - directory of the Git repository created - earlier. - </para></listitem> - <listitem><para>Run the <filename>build.sh</filename> - script as directed. - Be sure to provide the tag name, documentation - branch, and a release name. - Here is an example that uses the - <filename>luna/yocto-&DISTRO;</filename> tag, the - <filename>master</filename> documentation - branch, and - <filename>&DISTRO_NAME_NO_CAP;</filename> for the - release name: - <literallayout class='monospaced'> - $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh luna/yocto-&DISTRO; master &DISTRO_NAME_NO_CAP; 2>&1 | tee -a build.log - </literallayout> - After running the script, the file - <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename> - is in the current directory. - </para></listitem> - <listitem><para>If necessary, start the Eclipse IDE - and be sure you are in the Workbench. - </para></listitem> - <listitem><para>Select "Install New Software" from - the "Help" pull-down menu. - </para></listitem> - <listitem><para>Click "Add".</para></listitem> - <listitem><para>Provide anything you want in the - "Name" field. - </para></listitem> - <listitem><para>Click "Archive" and browse to the - ZIP file you built in step eight. - This ZIP file should not be "unzipped", and must - be the <filename>*archive.zip</filename> file - created by running the - <filename>build.sh</filename> script. - </para></listitem> - <listitem><para>Click the "OK" button. - </para></listitem> - <listitem><para>Check the boxes that appear in - the installation window to install the - <filename>Yocto Project ADT Plug-in</filename>, - <filename>Yocto Project Bitbake Commander Plug-in</filename>, - and the - <filename>Yocto Project Documentation plug-in</filename>. - </para></listitem> - <listitem><para>Finish the installation by clicking - through the appropriate buttons. - You can click "OK" when prompted about - installing software that contains unsigned - content. - </para></listitem> - <listitem><para>Restart the Eclipse IDE if - necessary. - </para></listitem> - </orderedlist> - </para> - - <para> - At this point you should be able to configure the - Eclipse Yocto Plug-in as described in the - "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" - section.</para> - </section> - </section> - - <section id='configuring-the-eclipse-yocto-plug-in'> - <title>Configuring the Eclipse Yocto Plug-in</title> - - <para> - 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). - </para> - - <para> - To start, you need to do the following from within the - Eclipse IDE: - <itemizedlist> - <listitem><para>Choose "Preferences" from the - "Window" menu to display the Preferences Dialog. - </para></listitem> - <listitem><para>Click "Yocto Project ADT" to display - the configuration screen. - </para></listitem> - </itemizedlist> - </para> - - <section id='configuring-the-cross-compiler-options'> - <title>Configuring the Cross-Compiler Options</title> - - <para> - 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. - <itemizedlist> - <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis> - Choose between - <filename>Standalone pre-built toolchain</filename> - and - <filename>Build system derived toolchain</filename> - for Cross Compiler Options. - <itemizedlist> - <listitem><para><emphasis> - <filename>Standalone Pre-built Toolchain:</filename></emphasis> - 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.</para></listitem> - <listitem><para><emphasis> - <filename>Build System Derived Toolchain:</filename></emphasis> - Select this mode if the - cross-toolchain has been installed - and built as part of the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. - When you select - <filename>Build system derived toolchain</filename>, - you are using the toolchain bundled - inside the Build Directory. - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para><emphasis>Point to the Toolchain:</emphasis> - If you are using a stand-alone pre-built - toolchain, you should be pointing to where it is - installed. - See the - "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" - section for information about how the SDK is - installed.</para> - <para>If you are using a system-derived - toolchain, the path you provide for the - <filename>Toolchain Root Location</filename> - field is the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. - See the - "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" - section.</para></listitem> - <listitem><para><emphasis>Specify the Sysroot Location:</emphasis> - This location is where the root filesystem for - the target hardware resides. - </para> - <para>The location of - the sysroot filesystem depends on where you - separately extracted and installed the - filesystem.</para> - <para>For information on how to install the - toolchain and on how to extract and install the - sysroot filesystem, see the - "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" - section. - </para></listitem> - <listitem><para><emphasis>Select the Target Architecture:</emphasis> - The target architecture is the type of hardware - you are going to use or emulate. - Use the pull-down - <filename>Target Architecture</filename> 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 - "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" - section of the Yocto Project Quick Start for - more information.</para></listitem> - </itemizedlist> - </para> - </section> - - <section id='configuring-the-target-options'> - <title>Configuring the Target Options</title> - - <para> - You can choose to emulate hardware using the QEMU - emulator, or you can choose to run your image on actual - hardware. - <itemizedlist> - <listitem><para><emphasis>QEMU:</emphasis> - 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.</para> - <para>If you selected - <filename>Build system derived toolchain</filename>, - the target kernel you built will be located in - the Build Directory in - <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename> - directory. - If you selected - <filename>Standalone pre-built toolchain</filename>, - the pre-built image you downloaded is located - in the directory you specified when you - downloaded the image.</para> - <para>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 - <filename>serial</filename>, - <filename>nographic</filename>, and - <filename>kvm</filename> must all be outside the - brackets. - Use the <filename>man qemu</filename> command - to get help on all the options and their use. - The following is an example: - <literallayout class='monospaced'> - serial ‘<-m 256 -full-screen>’ - </literallayout></para> - <para> - Regardless of the mode, Sysroot is already - defined as part of the Cross-Compiler Options - configuration in the - <filename>Sysroot Location:</filename> field. - </para></listitem> - <listitem><para><emphasis>External HW:</emphasis> - Select this option if you will be using actual - hardware.</para></listitem> - </itemizedlist> - </para> - - <para> - Click the "OK" to save your plug-in configurations. - </para> - </section> - </section> - </section> - - <section id='creating-the-project'> - <title>Creating the Project</title> - - <para> - 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 - "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>" - section. - <note> - Do not use special characters in project names - (e.g. spaces, underscores, etc.). Doing so can - cause configuration to fail. - </note> - </para> - - <para> - To create a project based on a Yocto template and then display - the source code, follow these steps: - <orderedlist> - <listitem><para>Select "Project" from the "File -> New" menu. - </para></listitem> - <listitem><para>Double click <filename>CC++</filename>. - </para></listitem> - <listitem><para>Double click <filename>C Project</filename> - to create the project.</para></listitem> - <listitem><para>Expand <filename>Yocto Project ADT Autotools Project</filename>. - </para></listitem> - <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>. - This is an Autotools-based project based on a Yocto - template.</para></listitem> - <listitem><para>Put a name in the <filename>Project name:</filename> - field. - Do not use hyphens as part of the name. - </para></listitem> - <listitem><para>Click "Next".</para></listitem> - <listitem><para>Add information in the - <filename>Author</filename> and - <filename>Copyright notice</filename> fields. - </para></listitem> - <listitem><para>Be sure the <filename>License</filename> - field is correct.</para></listitem> - <listitem><para>Click "Finish".</para></listitem> - <listitem><para>If the "open perspective" prompt appears, - click "Yes" so that you in the C/C++ perspective. - </para></listitem> - <listitem><para>The left-hand navigation pane shows your - project. - You can display your source by double clicking the - project's source file.</para></listitem> - </orderedlist> - </para> - </section> - - <section id='configuring-the-cross-toolchains'> - <title>Configuring the Cross-Toolchains</title> - - <para> - The earlier section, - "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>", - sets up the default project configurations. - You can override these settings for a given project by following - these steps: - <orderedlist> - <listitem><para>Select "Change Yocto Project Settings" from - the "Project" menu. - This selection brings up the Yocto Project Settings - Dialog and allows you to make changes specific to an - individual project.</para> - <para>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 - "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" section. - The Yocto Project Settings Dialog allows you to override - those default settings for a given project. - </para></listitem> - <listitem><para>Make your configurations for the project - and click "OK". - </para></listitem> - <listitem><para>Right-click in the navigation pane and - select "Reconfigure Project" from the pop-up menu. - This selection reconfigures the project by running - <filename>autogen.sh</filename> in the workspace for - your project. - The script also runs <filename>libtoolize</filename>, - <filename>aclocal</filename>, - <filename>autoconf</filename>, - <filename>autoheader</filename>, - <filename>automake --a</filename>, and - <filename>./configure</filename>. - Click on the "Console" tab beneath your source code to - see the results of reconfiguring your project. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='building-the-project'> - <title>Building the Project</title> - - <para> - To build the project select "Build Project" from the - "Project" menu. - The console should update and you can note the cross-compiler - you are using. - <note> - When building "Yocto Project ADT 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: - <orderedlist> - <listitem><para> - Select the project. - </para></listitem> - <listitem><para> - Select "Folder" from the - <filename>File > New</filename> menu. - </para></listitem> - <listitem><para> - In the "New Folder" Dialog, select "Link to alternate - location (linked folder)". - </para></listitem> - <listitem><para> - Click "Browse" to navigate to the include folder inside - the same sysroot location selected in the Yocto Project - configuration preferences. - </para></listitem> - <listitem><para> - Click "OK". - </para></listitem> - <listitem><para> - Click "Finish" to save the linked folder. - </para></listitem> - </orderedlist> - </note> - </para> - </section> - - <section id='starting-qemu-in-user-space-nfs-mode'> - <title>Starting QEMU in User-Space NFS Mode</title> - - <para> - To start the QEMU emulator from within Eclipse, follow these - steps: - <note> - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" - chapter in the Yocto Project Development Manual - for more information on using QEMU. - </note> - <orderedlist> - <listitem><para>Expose and select "External Tools" from - the "Run" menu. - Your image should appear as a selectable menu item. - </para></listitem> - <listitem><para>Select your image from the menu to launch - the emulator in a new window. - </para></listitem> - <listitem><para>If needed, enter your host root password in - the shell window at the prompt. - This sets up a <filename>Tap 0</filename> connection - needed for running in user-space NFS mode. - </para></listitem> - <listitem><para>Wait for QEMU to launch.</para></listitem> - <listitem><para>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 - <filename>ifconfig</filename> command. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='deploying-and-debugging-the-application'> - <title>Deploying and Debugging the Application</title> - - <para> - 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. - <note> - 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: - <literallayout class='monospaced'> - ssh -XY user_name@remote_host_ip - </literallayout> - After running the command, add the command to be executed - in Eclipse's run configuration before the application - as follows: - <literallayout class='monospaced'> - export DISPLAY=:10.0 - </literallayout> - </note> - <orderedlist> - <listitem><para>Select "Debug Configurations..." from the - "Run" menu.</para></listitem> - <listitem><para>In the left area, expand - <filename>C/C++Remote Application</filename>. - </para></listitem> - <listitem><para>Locate your project and select it to bring - up a new tabbed view in the Debug Configurations Dialog. - </para></listitem> - <listitem><para>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 - <filename>/usr/bin/<replaceable>programname</replaceable></filename>. - </para></listitem> - <listitem><para>Click on the "Debugger" tab to see the - cross-tool debugger you are using.</para></listitem> - <listitem><para>Click on the "Main" tab.</para></listitem> - <listitem><para>Create a new connection to the QEMU instance - by clicking on "new".</para></listitem> - <listitem><para>Select <filename>TCF</filename>, which means - Target Communication Framework.</para></listitem> - <listitem><para>Click "Next".</para></listitem> - <listitem><para>Clear out the "host name" field and enter - the IP Address determined earlier.</para></listitem> - <listitem><para>Click "Finish" to close the - New Connections Dialog.</para></listitem> - <listitem><para>Use the drop-down menu now in the - "Connection" field and pick the IP Address you entered. - </para></listitem> - <listitem><para>Click "Debug" to bring up a login screen - and login.</para></listitem> - <listitem><para>Accept the debug perspective. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='running-user-space-tools'> - <title>Running User-Space Tools</title> - - <para> - 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 "YoctoProjectTools" menu. - </para> - - <para> - 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. - </para> - - <para> - Here are some specifics about the remote tools: - <itemizedlist> - <listitem><para><emphasis><filename>Lttng2.0 trace import</filename>:</emphasis> - Selecting this tool transfers the remote target's - <filename>Lttng</filename> tracing 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 <ulink url='http://lttng.org/documentation'></ulink> - and the - "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>" - section, which is in the Yocto Project Profiling and - Tracing Manual. - <note>Do not use - <filename>Lttng-user space (legacy)</filename> tool. - This tool no longer has any upstream support.</note> - </para> - <para>Before you use the - <filename>Lttng2.0 trace import</filename> tool, - you need to setup the Lttng Eclipse plug-in and create a - Tracing project. - Do the following: - <orderedlist> - <listitem><para>Select "Open Perspective" from the - "Window" menu and then select "Other..." to - bring up a menu of other perspectives. - Choose "Tracing". - </para></listitem> - <listitem><para>Click "OK" to change the Eclipse - perspective into the Tracing perspective. - </para></listitem> - <listitem><para>Create a new Tracing project by - selecting "Project" from the "File -> New" menu. - </para></listitem> - <listitem><para>Choose "Tracing Project" from the - "Tracing" menu and click "Next". - </para></listitem> - <listitem><para>Provide a name for your tracing - project and click "Finish". - </para></listitem> - <listitem><para>Generate your tracing data on the - remote target.</para></listitem> - <listitem><para>Select "Lttng2.0 trace import" - from the "Yocto Project Tools" menu to - start the data import process.</para></listitem> - <listitem><para>Specify your remote connection name. - </para></listitem> - <listitem><para>For the Ust directory path, specify - the location of your remote tracing data. - Make sure the location ends with - <filename>ust</filename> (e.g. - <filename>/usr/mysession/ust</filename>). - </para></listitem> - <listitem><para>Click "OK" to complete the import - process. - The data is now in the local tracing project - you created.</para></listitem> - <listitem><para>Right click on the data and then use - the menu to Select "Generic CTF Trace" from the - "Trace Type... -> Common Trace Format" menu to - map the tracing type.</para></listitem> - <listitem><para>Right click the mouse and select - "Open" to bring up the Eclipse Lttng Trace - Viewer so you view the tracing data. - </para></listitem> - </orderedlist></para></listitem> - <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> - Selecting this tool runs PowerTOP on the remote target - machine and displays the results in a new view called - PowerTOP.</para> - <para>The "Time to gather data(sec):" field is the time - passed in seconds before data is gathered from the - remote target for analysis.</para> - <para>The "show pids in wakeups list:" field corresponds - to the <filename>-p</filename> argument passed to - <filename>PowerTOP</filename>.</para></listitem> - <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis> - 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. - For more information on setting up and using - <filename>perf</filename>, see the - "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>" - section in the Yocto Project Profiling and Tracing - Manual. - </para></listitem> - <listitem><para><emphasis><filename>SystemTap</filename>:</emphasis> - Systemtap is a tool that lets you create and reuse - scripts to examine the activities of a live Linux - system. - You can easily extract, filter, and summarize data - that helps you diagnose complex performance or - functional problems. - For more information on setting up and using - <filename>SystemTap</filename>, see the - <ulink url='https://sourceware.org/systemtap/documentation.html'>SystemTap Documentation</ulink>. - </para></listitem> - <listitem><para><emphasis><filename>yocto-bsp</filename>:</emphasis> - The <filename>yocto-bsp</filename> tool lets you - quickly set up a Board Support Package (BSP) layer. - The tool requires a Metadata location, build location, - BSP name, BSP output location, and a kernel - architecture. - For more information on the - <filename>yocto-bsp</filename> tool outside of Eclipse, - see the - "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a new BSP Layer Using the yocto-bsp Script</ulink>" - section in the Yocto Project Board Support Package - (BSP) Developer's Guide. - </para></listitem> - </itemizedlist> - </para> - </section> </section> -</section> - </chapter> <!-- vim: expandtab tw=80 ts=4 |