diff options
Diffstat (limited to 'documentation/poky-ref-manual/development.xml')
| -rw-r--r-- | documentation/poky-ref-manual/development.xml | 1125 |
1 files changed, 0 insertions, 1125 deletions
diff --git a/documentation/poky-ref-manual/development.xml b/documentation/poky-ref-manual/development.xml deleted file mode 100644 index 45df028f86..0000000000 --- a/documentation/poky-ref-manual/development.xml +++ /dev/null @@ -1,1125 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<chapter id="platdev"> -<title>Platform Development with Poky</title> - - <section id="platdev-appdev"> - <title>Software development</title> - <para> - Poky supports several methods of software development. You can use the method that is - best for you. This chapter describes each development method. - </para> - - <section id="platdev-appdev-external-sdk"> - <title>External Development Using the Application Development Toolkit (ADT)</title> - <para> - The meta-toolchain and meta-toolchain-sdk targets build tarballs that contain toolchains and - libraries suitable for application development outside of Poky. - For information on these targets see the <ulink linkend='ref-images'>Reference: Images</ulink> - appendix. - </para> - <para> - These tarballs unpack into the - <filename class="directory">/opt/poky</filename> directory and contain - a setup script (e.g. - <filename>/opt/poky/environment-setup-i586-poky-linux</filename>), from which - you can source to initialize a suitable environment. Sourcing these files adds the - compiler, QEMU scripts, QEMU binary, a special version of pkgconfig and other - useful utilities to the PATH variable. Variables to assist pkgconfig and - autotools are also defined so that, for example, configure can find pre-generated test - results for tests that need target hardware on which to run. - </para> - <para> - Using the toolchain with autotool-enabled packages is straightforward - just pass the - appropriate host option to configure. - Following is an example: - <literallayout class='monospaced'> - $ ./configure --host=arm-poky-linux-gnueabi - </literallayout> - For other projects it is usually a case of ensuring the cross tools are used: - <literallayout class='monospaced'> - CC=arm-poky-linux-gnueabi-gcc and LD=arm-poky-linux-gnueabi-ld - </literallayout> - </para> - </section> - - <section id="using-the-eclipse-and-anjuta-plug-ins"> - <title>Using the Eclipse Plug-in</title> - <para> - The current release of the Yocto Project supports the Eclipse IDE plug-in - to make developing software easier for the application developer. - The plug-in provides capability extensions to the graphical IDE to allow - for cross compilation, deployment and execution of the output in a QEMU - emulation session. - Support of the Eclipse plug-in also allows for cross debugging and - profiling. - Additionally, the Eclipse plug-in provides a suite of tools - that allows the developer to perform remote profiling, tracing, collection of - power data, collection of latency data and collection of performance data. - </para> - <note> - The current release of the Yocto Project no longer supports the Anjuta plug-in. - However, the Poky Anjuta Plug-in is available to download directly from the Poky - Git repository located through the web interface at - <ulink url="http://git.yoctoproject.org/"></ulink> under IDE Plugins. - The community is free to continue supporting it beyond the Yocto Project 0.9 - Release. - </note> - <para> - To use the Eclipse plug-in you need the Eclipse Framework (Helios 3.6.1) along - with other plug-ins installed into the Eclipse IDE. - Once you have your environment setup you need to configure the Eclipse plug-in. - For information on how to install and configure the Eclipse plug-in, see the - <ulink url='http://www.yoctoproject.org/docs/adt-manual/adt-manual.html#adt-eclipse'> - "Working Within Eclipse"</ulink> chapter in the - <ulink url='http://www.yoctoproject.org/docs/adt-manual/adt-manual.html'> - "Application Development Toolkit (ADT) User's Guide."</ulink> - </para> - - - -<!-- - - <section id="the-eclipse-plug-in"> - <title>The Eclipse Plug-in</title> - <para> - To use the Eclipse plug-in, a toolchain and SDK built by Poky is required along with - the Eclipse Framework (Helios 3.6.1). - To install the plug-in you need to be in the Eclipse IDE and select - the following menu: - <literallayout class='monospaced'> - Help -> Install New Software - </literallayout> - Specify the target URL as - <ulink url='http://www.yoctoproject.org/downloads/eclipse-plugin/'></ulink>. - </para> - <para> - If you want to download the source code for the plug-in you can find it in the Poky - git repository, which has a web interface, and is located at - <ulink url="http://git.yoctoproject.org"></ulink> under IDE Plugins. - </para> - - <section id="installing-and-setting-up-the-eclipse-ide"> - <title>Installing and Setting up the Eclipse IDE</title> - <para> - If you don't have the Eclipse IDE (Helios 3.6.1) on your system you need to - download and install it from <ulink url="http://www.eclipse.org/downloads"></ulink>. - Choose the Eclipse Classic, which contains the Eclipse Platform, Java Development - Tools (JDT), and the Plug-in Development Environment. - </para> - <note> - <para> - Due to the Java Virtual Machine's garbage collection (GC) process the - permanent generation space (PermGen) is not cleaned up. This space stores - meta-data descriptions of classes. The default value is set too small - and it could trigger an out-of-memory error like the following: - <literallayout class='monospaced'> - Java.lang.OutOfMemoryError: PermGen space - </literallayout> - This error causes the applications to hang. - </para> - </note> - <para> - To fix this issue you can use the <filename>-vmargs</filename> - option when you start Eclipse to increase the size of the permanent generation space: - <literallayout class='monospaced'> - Eclipse -vmargs -XX:PermSize=256M - </literallayout> - </para> - </section> - - <section id="installing-the-yocto-plug-in"> - <title>Installing the Yocto Plug-in</title> - <para> - Once you have the Eclipse IDE installed and configured you need to install the - Yocto plug-in. You do this similar to installing the Eclipse plug-ins in the - previous section. - </para> - <para> - Do the following to install the Yocto plug-in into the Eclipse IDE: - <orderedlist> - <listitem><para>Select the "Help -> Install New Software" item.</para></listitem> - <listitem><para>In the "Work with:" area click "Add..." and enter the URL for - the Yocto plug-in, which is - <ulink url='http://www.yoctoproject.org/downloads/eclipse-plugin/'></ulink></para></listitem> - <listitem><para>Finish out the installation of the update similar to any other - Eclipse plug-in.</para></listitem> - </orderedlist> - </para> - </section> - - <section id="configuring-yocto-eclipse-plug-in"> - <title>Configuring Yocto Eclipse plug-in</title> - <para> - To configure the Yocto Eclipse plug-in you need to select the mode and the - architecture with which you will be working. Start by selecting "Preferences" - from the "Window" menu and then select "Yocto SDK". - </para> - <para> - If you normally will use an installed Yocto - SDK (under <filename>/opt/poky</filename>) select “SDK Root Mode”. Otherwise, if your crosstool chain - and sysroot are within your poky tree, select “Poky Tree Mode”. - If you are in SDK Root Mode you need to provide your poky tree path, for - example, <filename>$<Poky_tree>/build/</filename>. - </para> - <para> - Next, you need to select the architecture. - Use the drop down list and select the architecture that you’ll be primarily - working against. - For target option, select your typical target QEMU vs External hardware. If you - choose QEMU, you’ll need to specify your QEMU kernel file with full path and the - rootfs mount point. Yocto QEMU boots off user mode NFS. - See the <link linkend='platdev-appdev-qemu'>Developing Externally in QEMU</link> section for - how to set it up. - </para> - <para> - To make your settings the defaults for every new Yocto project created using - the Eclipse IDE, simply save the settings. - </para> - </section> - - <section id="using-the-yocto-eclipse-plug-in"> - <title>Using the Yocto Eclipse Plug-in</title> - <para> - As an example, this section shows you how to cross-compile a Yocto C project that - is autotools-based, deploy the project into QEMU, and then run the debugger against it. - You need to configure the project, trigger the <filename> autogen.sh</filename>, build - the image, start QEMU, and then debug. - </para> - <para> - The following steps show how to create a Yocto autotools-based project using a given template: - </para> - <orderedlist> - <listitem><para>Select "File -> New -> Project" to start the wizard.</para></listitem> - <listitem><para>Expand "C/C++" and select "C Project".</para></listitem> - <listitem><para>Click "Next" and select a template (e.g. "Hello World ANSI C Project").</para></listitem> - <listitem><para>Complete the steps to create the new Yocto autotools-based project using - your chosen template.</para></listitem> - </orderedlist> - <para> - By default, the project uses the Yocto preferences settings as defined using the procedure in - <link linkend="configuring-yocto-eclipse-plug-in">the previous section</link>. - If there are any specific setup requirements for the newly created project - you need to reconfigure the Yocto plug-in through the menu selection by doing the following: - </para> - <orderedlist> - <listitem><para>Select the "Project -> Invoke Yocto Tools -> Reconfigure Yocto" menu item.</para></listitem> - <listitem><para>Complete the dialogue to specify the specific toolchain and QEMU setup information.</para></listitem> - </orderedlist> - <para> - To build the project follow these steps: - </para> - <orderedlist> - <listitem><para>Select "Project -> Reconfigure Project" to trigger the - <filename>autogen.sh</filename> command.</para></listitem> - <listitem><para>Select "Project -> Build" to build the project.</para></listitem> - </orderedlist> - <para> - To start QEMU follow these steps: - </para> - <orderedlist> - <listitem><para>Select "Run -> External Tools" and see if there is - a QEMU instance for the desired target. - If one exists, click on the instance to start QEMU. - If your target does not exist, click "External Tools Configuration" and - you should find an instance of QEMU for your architecture - under the entry under "Program".</para></listitem> - <listitem><para>Wait for the boot to complete.</para></listitem> - </orderedlist> - <para> - To deploy your project and start debugging follow these steps: - </para> - <orderedlist> - <listitem><para>Highlight your project in the project explorer.</para></listitem> - <listitem><para>Select "Run -> Debug Configurations" to bring up your remote debugging configuration - in the right-hand window.</para></listitem> - <listitem><para>Expand “C/C++ Remote Application”.</para></listitem> - <listitem><para>Select "projectname_ gdb_target-poky-linux". - You need to be sure there is an entry for the remote target. - If no entry exists, click "New..." to bring up the wizard. - Use the wizard to select TCF and enter the IP address of you remote target in the - “Host name:” field. - Back in the Remote Debug Configure window, specify in the - “Remote Absolute File Path for C/C++ Application” field the absolute path for the program on - the remote target. - By default, the program deploys into the remote target. - If you don't want this behavior then check “Skip download to target path”.</para></listitem> - <listitem><para>Click "Debug” to start the remote debugging session.</para></listitem> - </orderedlist> - </section> - - <section id="using-yocto-eclipse-plug-in-remote-tools-suite"> - <title>Using Yocto Eclipse plug-in Remote Tools Suite</title> - <para> - Remote tools allow you to perform system profiling, kernel tracing, - examine power consumption, and so forth. To see and access the remote tools use the - "Window -> YoctoTools" 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>OProfile: Selecting this tool causes the oprofile-server on the remote - target to launch on the local host machine. The oprofile-viewer - must be installed on the local host machine and the oprofile-server must be - installed on the remote target, respectively, in order to use .</para></listitem> - <listitem><para>lttng: Selecting this tool runs "usttrace" on the remote target, transfers - the output data back to the local host machine and uses "lttv-gui" to graphically - display the output. The "lttv-gui" must be installed on the - local host machine to use this tool. - For information on how to use "lttng" to trace an - application, see <ulink url="http://lttng.org/files/ust/manual/ust.html"></ulink>. - <para> - For "Application" you must supply the absolute path name of the application to - be traced by user mode lttng. For example, typing <filename>/path/to/foo" - </filename> triggers "usttrace /path/to/foo" on the - remote target to trace the program <filename>/path/to/foo</filename>. - </para> - <para> - "Argument" is passed to "usttrace" running on the remote target. - </para></para> - </listitem> - <listitem><para>powertop: Selecting this tool runs "powertop" on the - remote target machine and displays the results in a new view called "powertop". - <para> - "Time to gather data(sec):" is the time passed in seconds before data is - gathered from the remote target for analysis. - </para> - <para> - "show pids in wakeups list:" corresponds to the <filename>-p</filename> - argument passed to "powertop". - </para></para> - </listitem> - <listitem><para>latencytop and perf: "latencytop" identifies - system latency, while "perf" monitors the system's performance - counter registers. Selecting either of these tools causes an RSE - terminal view to appear from which you can run the tools. Both tools refresh the - entire screen to display results while they run.</para></listitem> - </itemizedlist> - </para> - </section> - </section> - - <section id="the-anjuta-plug-in"> - <title>The Anjuta Plug-in</title> - <note> - <para> - Support for the Anjuta plug-in ends after Yocto project 0.9 Release. - However, the source code can be downloaded from the git repository listed later in - this section. - The community is free to continue supporting it post 0.9 Release. - </para> - </note> - <para> - An Anjuta IDE plug-in exists to make developing software within the Poky framework - easier for the application developer familiar with that environment. - The plug-in presents a graphical IDE that allows you to cross-compile, cross-debug, - profile, deploy, and execute an application. - </para> - <para> - To use the plug-in, a toolchain and SDK built by Poky, Anjuta, its development headers and the Anjuta - Plug-in are all required. - The Poky Anjuta Plug-in is available to download as a tarball at the OpenedHand - labs <ulink url="http://labs.o-hand.com/anjuta-poky-sdk-plugin/"></ulink> page or - directly from the Poky Git repository located at git://git.yoctoproject.org/anjuta-poky. - You can access the source code from a web interface to the repository at - <ulink url="http://git.yoctoproject.org/"></ulink> under IDE Plugins. - </para> - <para> - See the README file contained in the project for more information on - Anjuta dependencies and building the plug-in. - If you want to disable remote gdb debugging, pass the "‐‐disable-gdb-integration" switch when - you configure the plug-in. - </para> - <section id="setting-up-the-anjuta-plugin"> - <title>Setting Up the Anjuta Plug-in</title> - <para> - Follow these steps to set up the plug-in: - <orderedlist> - <listitem><para>Extract the tarball for the toolchain into / as root. - The toolchain will be installed into <filename>/opt/poky</filename>.</para></listitem> - <listitem><para>To use the plug-in, first open or create an existing project. - If you are creating a new project, the "C GTK+" - project type will allow itself to be cross-compiled. - However, you should be aware that this type uses "glade" for the UI.</para></listitem> - <listitem><para>To activate the plug-in, select "Edit -> Preferences" and then choose - "General" from the left hand side. - Choose the "Installed plug-ins" tab, scroll down to "Poky SDK" and - check the box.</para></listitem> - </orderedlist> - The plug-in is now activated but not configured. - </para> - </section> - <section id="configuring-the-anjuta-plugin"> - <title>Configuring the Anjuta Plug-in</title> - <para> - You can find the configuration options for the SDK by choosing the Poky - SDK icon from the left hand side. - You need to define the following options: - <itemizedlist> - <listitem><para>SDK root: If you use an external toolchain you need to set - SDK root, which is the root directory of the SDK's sysroot. - For an i586 SDK directory is <filename>/opt/poky/</filename>. - This directory will contain "bin", "include", "var" and so forth under your - selected target architecture subdirectory - <filename>/opt/poky/sysroot/i586-poky-linux/</filename>. - The cross-compile tools you need are in - <filename>/opt/poky/sysroot/i586-pokysdk-linux/</filename>.</para></listitem> - <listitem><para>Poky root: If you have a local Poky build tree, you need to - set the Poky root, which is the root directory of the poky build tree. - If you build your i586 target architecture under the subdirectory of - <filename>build_x86</filename> within your Poky tree, the Poky root directory - should be <filename>$<poky_tree>/build_x86/</filename>.</para></listitem> - <listitem><para>Target Architecture: This is the cross compile triplet, - for example, "i586-poky-linux". - This target triplet is the prefix extracted from the set up script file's name. - For example, if the script file name is - <filename>/opt/poky/environment-setup-i586-poky-linux</filename> then the extracted target - triplet is "i586-poky-linux".</para></listitem> - <listitem><para>Kernel: Use the file chooser to select the kernel used with QEMU.</para></listitem> - <listitem><para>Root filesystem: Use the file chooser to select the root - filesystem directory. This directory is where you use "poky-extract-sdk" to extract the - poky-image-sdk tarball.</para></listitem> - </itemizedlist> - </para> - </section> - <section id="using-the-anjuta-plug-in"> - <title>Using the Anjuta Plug-in</title> - <para> - The steps in this section show how to cross-compile a project, deploy it into - QEMU, run a debugger against it and then perform a system-wide profile. - <orderedlist> - <listitem><para>Choose "Build -> Run Configure" or "Build -> Run Autogenerate" to run - "configure" or "autogen", respectively for the project. - Either command passes command-line arguments to instruct the - cross-compile.</para></listitem> - <listitem><para>Choose "Build -> Build Project" to build and compile the project. - If you have previously built the project in the same tree without using - the cross-compiler you might find that your project fails to link. - If this is the case, simply select "Build -> Clean Project" to remove the - old binaries. - After you clean the project you can then try building it again.</para></listitem> - <listitem><para>Choose "Tools -> Start QEMU" to start QEMU. - After QEMU starts any error messages will appear in the message view. - Once Poky has fully booted within QEMU you can deploy the project - into it.</para></listitem> - <listitem><para>Once the project is built and you have QEMU running choose - "Tools -> Deploy" to install the package into a temporary - directory and then copy it using "rsync" over SSH into the target. - A progress bar and appropriate messages appear in the message view.</para></listitem> - <listitem><para>To debug a program installed onto the target choose - "Tools -> Debug remote". - Choosing this menu item causes prompts to appear to define the local binary - for debugging and also for the command line used to run on the target. - When you provide the command line be sure to include the full path to the to binary - installed in the target. - When the command line runs a "gdbserver" over SSH is started on the target and - an instance of "cross-gdb" starts in a local terminal. - The instance of "cross-gdb" will be preloaded to connect to the server and use the SDK root to - find symbols. - It also connects to the target and loads in various libraries as well as the - target program. - You should define any breakpoints or watchpoints at this point in the process since you might not - be able to interrupt the execution later. - To stop the debugger on the target choose "Tools -> Stop debugger".</para></listitem> - <listitem><para>It is also possible to execute a command in the target over SSH. - Doing so causes the appropriate environment to be established for execution. - To execute a command choose "Choose Tools -> Run remote". - This selection opens a terminal with the SSH command inside.</para></listitem> - <listitem><para>To perform a system-wide profile against the system running in QEMU choose - "Tools -> Profile remote". - This choice starts up "OProfileUI" with the appropriate parameters to - connect to the server running inside QEMU and also supplies the path - for debug information necessary to get a useful profile.</para></listitem> - </orderedlist> - </para> - </section> - </section> - - ---> - - </section> - - <section id="platdev-appdev-qemu"> - <title>Developing Externally in QEMU</title> - <para> - Running Poky QEMU images is covered in the - <ulink url="http://www.yoctoproject.org/docs/yocto-quick-start/yocto-project-qs.html"> - Yocto Project Quick Start</ulink> in the "A Quick Test Run" section. - </para> - <para> - Poky's QEMU images contain a complete native toolchain. This means - you can develop applications within QEMU similar to the way you would in a normal system. - Using qemux86 on an x86 machine is fast since the - guest and host architectures match. - On the other hand, using qemuarm can be slower but gives - faithful emulation of ARM-specific issues. To speed things up, these - images support using "distcc" to call a cross-compiler outside the - emulated system. If "runqemu" was used to start - QEMU, and "distccd" is present on the host system, any Bitbake cross-compiling - toolchain available from the build system is automatically - used from within QEMU simply by calling "distcc". You can accomplish this by defining the - cross-compiler variable (e.g. <filename>export CC="distcc"</filename>). - Alternatively, if a suitable SDK/toolchain is present in - <filename>/opt/poky</filename> it is also - automatically be used. - </para> - - <para> - There are several options for connecting into the emulated system. - QEMU provides a framebuffer interface that has standard consoles - available. There is also a serial connection available that has a - console to the system running on it and uses standard IP networking. - The images have a dropbear ssh server running with the root password - disabled to allow standard ssh and scp commands to work. The images - also contain an NFS server that exports the guest's root filesystem, which - allows it to be made available to the host. - </para> - </section> - - <section id="platdev-appdev-insitu"> - <title>Developing in Poky Directly</title> - <para> - Working directly in Poky is a fast and effective development technique. - The idea is that you can directly edit files in - <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm> - or the source directory <glossterm><link linkend='var-S'>S</link></glossterm> - and then force specific tasks to rerun in order to test the changes. - An example session working on the matchbox-desktop package might - look like this: - </para> - - <para> - <literallayout class='monospaced'> - $ bitbake matchbox-desktop - $ sh - $ cd tmp/work/armv5te-poky-linux-gnueabi/matchbox-desktop-2.0+svnr1708-r0/ - $ cd matchbox-desktop-2 - $ vi src/main.c - $ exit - $ bitbake matchbox-desktop -c compile -f - $ bitbake matchbox-desktop - </literallayout> - </para> - - <para> - This example builds the package, changes into the work directory for the package, - changes a file, then recompiles the package. Instead of using "sh" as it is in the example, - you can also use two different terminals. However, the risk of using two terminals - is that a command like "unpack" could destroy the changes you've made to the - work directory. Consequently, you need to work carefully. - </para> - - <para> - It is useful when making changes directly to the work directory files to do - so using "quilt" as detailed in the <link linkend='usingpoky-modifying-packages-quilt'> - modifying packages with quilt</link> section. You can copy the resulting patches - into the recipe directory and use them directly in the <glossterm><link - linkend='var-SRC_URI'>SRC_URI</link></glossterm>. - </para> - <para> - For a review of the skills used in this section see the <link - linkend="usingpoky-components-bitbake">Bitbake</link> and <link - linkend="usingpoky-debugging-taskrunning">Running Specific Tasks</link> Sections. - </para> - </section> - - <section id="platdev-appdev-devshell"> - <title>Developing with 'devshell'</title> - - <para> - When debugging certain commands or even when just editing packages, the - 'devshell' can be a useful tool. - Use a command like the following to start this tool. - </para> - - <para> - <literallayout class='monospaced'> - $ bitbake matchbox-desktop -c devshell - </literallayout> - </para> - - <para> - This command opens a terminal with a shell prompt within the Poky - environment. Consequently, the following occurs: - <itemizedlist> - <listitem><para>The PATH variable includes the cross toolchain.</para></listitem> - <listitem><para>The pkgconfig variables find the correct <filename>.pc</filename> files.</para></listitem> - <listitem><para>"configure" finds the Poky site files as well as any other necessary files.</para></listitem> - </itemizedlist> - Within this environment, you can run "configure" or "compile" commands as if they - were being run by Poky itself. - The working directory also automatically changes to the (<glossterm><link linkend='var-S'>S</link></glossterm>) - directory. - When you are finished, you just exit the shell or close the terminal window. - </para> - - <para> - The default shell used by "devshell" is the gnome-terminal. - You can use other forms of terminal can by setting the <glossterm> - <link linkend='var-TERMCMD'>TERMCMD</link></glossterm> and <glossterm> - <link linkend='var-TERMCMDRUN'>TERMCMDRUN</link></glossterm> variables - in <filename>local.conf</filename>. - For examples of the other options available, see - <filename>meta/conf/bitbake.conf</filename>. - </para> - <para> - An external shell is launched rather than opening directly into the original terminal - window. - This allows easier interaction with Bitbake's multiple threads as well as - for a future client/server split. - Note that "devshell" will still work over X11 forwarding or similar situations. - </para> - - <para> - It is worth remembering that inside "devshell" you need to use the full - compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename> - instead of just <filename>gcc</filename>. - The same applies to other applications such as gcc, bintuils, libtool and so forth. - Poky will have setup environmental variables such as CC to assist applications, such as make, - find the correct tools. - </para> - </section> - - <section id="platdev-appdev-srcrev"> - <title>Developing within Poky with an External SCM-based Package</title> - - <para> - If you're working on a recipe that pulls from an external SCM it - is possible to have Poky notice new changes added to the - SCM and then build the latest version using them. - This only works for SCMs from which it is possible to get a sensible revision number for changes. - Currently it works for svn, git and bzr repositories. - </para> - - <para> - To enable this behavior simply add <glossterm> - <link linkend='var-SRCREV'>SRCREV</link></glossterm>_pn-<glossterm> - <link linkend='var-PN'>PN</link></glossterm> = "${AUTOREV}" to - <filename>local.conf</filename>, where <glossterm><link linkend='var-PN'>PN</link></glossterm> - is the name of the package for which you want to enable automatic source - revision updating. - </para> - </section> - </section> - -<section id="platdev-gdb-remotedebug"> - <title>Debugging with GDB Remotely</title> - - <para> - GNU Project Debugger (GDB) - allows you to examine running programs to understand and fix problems and - also to perform post-mortem style analysis of program crashes. - GDB is available as a package within Poky and by default is installed in sdk images. - See <ulink url="http://sourceware.org/gdb/"/> for the GDB source. - </para> - <tip><para> - For best results install <filename>-dbg</filename> packages for the applications - you are going to debug. - Doing so makes available extra debug symbols that will give you more meaningful output. - </para></tip> - - <para> - Sometimes, due to memory or disk space constraints, it is not possible - to use GDB directly on the remote target to debug applications. - These constraints arise because GDB needs to load the debugging information and the - binaries of the process being debugged. - Additionally, GDB needs to perform many computations to locate information such as function - names, variable names and values, stack traces and so forth - even before starting the - debugging process. - These extra computations place more load on the target system and can alter the - characteristics of the program being debugged. - </para> - <para> - To help get past these constraints you can use GDBSERVER. - It runs on the remote target and does not load any debugging information - from the debugged process. - Instead, a GDB instance processes the debugging information that is run on a - remote computer - the host GDB. - The host GDB then sends control commands to GDBSERVER to make it stop or start the debugged - program, as well as read or write memory regions of that debugged - program. - All the debugging information loaded and processed as well - as all the heavy debugging is done by the host GDB. - Offloading these processes gives the GDBSERVER running on the target a chance to remain - small and fast. - </para> - <para> - Because the host GDB is responsible for loading the debugging information and - for doing the necessary processing to make actual debugging happen, the - user has to make sure the host can access the unstripped binaries complete - with their debugging information and also compiled with no optimizations. - The host GDB must also have local access to all the libraries used by the - debugged program. - Because GDBSERVER does not need any local debugging information the binaries on - the remote target can remain stripped. - However, the binaries must also be compiled without optimization - so they match the host's binaries. - </para> - - <para> - To remain consistent with GDB documentation and terminology the binary being debugged - on the remote target machine is referred to as the 'inferior' binary. - For documentation on GDB see the GDB site at - <ulink url="http://sourceware.org/gdb/documentation/">on their site</ulink>. - </para> - - <section id="platdev-gdb-remotedebug-launch-gdbserver"> - <title>Launching GDBSERVER on the Target</title> - <para> - First, make sure GDBSERVER is installed on the target. If not, - install the package <filename>gdbserver</filename>, which needs the - <filename>libthread-db1</filename> package. - </para> - <para> - As an example, to launch GDBSERVER on the target and make it ready to "debug" a - program located at <filename>/path/to/inferior</filename>, connect - to the target and launch: - <literallayout class='monospaced'> - $ gdbserver localhost:2345 /path/to/inferior - </literallayout> - GDBSERVER should now be listening on port 2345 for debugging - commands coming from a remote GDB process that is running on the host computer. - Communication between GDBSERVER and the host GDB are done using TCP. - To use other communication protocols please refer to the GDBSERVER documentation. - </para> - </section> - - <section id="platdev-gdb-remotedebug-launch-gdb"> - <title>Launching GDB on the Host Computer</title> - - <para> - Running GDB on the host computer takes a number of stages. - This section describes those stages. - </para> - - <section id="platdev-gdb-remotedebug-launch-gdb-buildcross"> - <title>Building the Cross-GDB Package</title> - <para> - A suitable GDB cross-binary is required that runs on your host computer but - also knows about the the ABI of the remote target. - You can get this binary from the the Poky toolchain - for example: - <programlisting> -/usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb - </programlisting> - where "arm" is the target architecture and "linux-gnueabi" the target ABI. - </para> - - <para> - Alternatively, Poky can build the <filename>gdb-cross</filename> binary. - For example, the following command builds it: - <literallayout class='monospaced'> - $ bitbake gdb-cross - </literallayout> - Once the binary is built you can find it here: - <programlisting> -tmp/sysroots/<host-arch>/usr/bin/<target-abi>-gdb - </programlisting> - </para> - - </section> - <section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins"> - - <title>Making the Inferior Binaries Available</title> - - <para> - The inferior binary (complete with all debugging symbols) as well as any - libraries (and their debugging symbols) on which the inferior binary depends - need to be available. - There are a number of ways you can make these available. - </para> - - <para> - Perhaps the easiest is to have an 'sdk' image that corresponds to the plain - image installed on the device. - In the case of 'poky-image-sato', 'poky-image-sdk' would contain suitable symbols. - Because the sdk images already have the debugging symbols installed it is just a - question of expanding the archive to some location and then informing GDB. - </para> - - <para> - Alternatively, Poky can build a custom directory of files for a specific - debugging purpose by reusing its <filename>tmp/rootfs</filename> directory. - This directory contains the contents of the last built image. - This process assumes two things: - <itemizedlist> - <listitem><para>The image running on the target was the last image to - be built by Poky.</para></listitem> - <listitem><para>The package (<filename>foo</filename> in the following - example) that contains the inferior binary to be debugged has been built - without optimization and has debugging information available.</para></listitem> - </itemizedlist> - </para> - <para> - These steps show how to build the custom directory of files: - </para> - <orderedlist> - <listitem><para>Install the package (<filename>foo</filename> in this case) to - <filename>tmp/rootfs</filename>: - <programlisting> -tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ -tmp/work/<target-abi>/poky-image-sato-1.0-r0/temp/opkg.conf -o \ -tmp/rootfs/ update - </programlisting></para></listitem> - <listitem><para>Install the debugging information: - <programlisting> -tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ -tmp/work/<target-abi>/poky-image-sato-1.0-r0/temp/opkg.conf \ --o tmp/rootfs install foo - -tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \ -tmp/work/<target-abi>/poky-image-sato-1.0-r0/temp/opkg.conf \ --o tmp/rootfs install foo-dbg - </programlisting></para></listitem> - </orderedlist> - - </section> - <section id="platdev-gdb-remotedebug-launch-gdb-launchhost"> - - <title>Launch the Host GDB</title> - <para> - To launch the host GDB, you run the cross-gdb binary and provide the inferior - binary as part of the command line. - For example, the following command form continues with the example used in - the previous section. - This command form loads the <filename>foo</filename> binary - as well as the debugging information: - <literallayout class='monospaced'> - $ <target-abi>-gdb rootfs/usr/bin/foo - </literallayout> - Once the GDB prompt appears, you must instruct GDB to load all the libraries - of the inferior binary from <filename>tmp/rootfs</filename> as follows: - <literallayout class='monospaced'> - $ set solib-absolute-prefix /path/to/tmp/rootfs - </literallayout> - The pathname <filename>/path/to/tmp/rootfs</filename> must either be - the absolute path to <filename>tmp/rootfs</filename> or the location at which - binaries with debugging information reside. - </para> - <para> - At this point you can have GDB connect to the GDBSERVER that is running - on the remote target by using the following command form: - <literallayout class='monospaced'> - $ target remote remote-target-ip-address:2345 - </literallayout> - The <filename>remote-target-ip-address</filename> is the IP address of the - remote target where the GDBSERVER is running. - Port 2345 is the port on which the GDBSERVER is running. - </para> - - </section> - <section id="platdev-gdb-remotedebug-launch-gdb-using"> - - <title>Using the Debugger</title> - <para> - You can now proceed with debugging as normal - as if you were debugging - on the local machine. - For example, to instruct GDB to break in the "main" function and then - continue with execution of the inferior binary use the following commands - from within GDB: - <literallayout class='monospaced'> - (gdb) break main - (gdb) continue - </literallayout> - </para> - <para> - For more information about using GDB, see the project's online documentation at - <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>. - </para> - </section> - </section> - -</section> - -<section id="platdev-oprofile"> - <title>Profiling with OProfile</title> - - <para> - <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a - statistical profiler well suited for finding performance - bottlenecks in both userspace software and in the kernel. - This profiler provides answers to questions like "Which functions does my application spend - the most time in when doing X?" - Because Poky is well integrated with OProfile it makes profiling applications on target - hardware straightforward. - </para> - - <para> - To use OProfile you need an image that has OProfile installed. - The easiest way to do this is with "tools-profile" in - <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>. - You also need debugging symbols to be available on the system where the analysis - takes place. - You can gain access to the symbols by using "dbg-pkgs" in - <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> or by - installing the appropriate <filename>-dbg</filename> packages. - </para> - <para> - For successful call graph analysis the binaries must preserve the frame - pointer register and should also be compiled with the - "-fno-omit-framepointer" flag. - In Poky you can achieve this by setting - <glossterm><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION - </link></glossterm> to "-fexpensive-optimizations -fno-omit-framepointer - -frename-registers -O2". - You can also achieve it by setting - <glossterm><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></glossterm> to "1" in - <filename>local.conf</filename>. - If you use the DEBUG_BUILD variable you will also add extra debug information - that can make the debug packages large. - </para> - - <section id="platdev-oprofile-target"> - <title>Profiling on the Target</title> - - <para> - Using OProfile you can perform all the profiling work on the target device. - A simple OProfile session might look like the following: - </para> - - <para> - <literallayout class='monospaced'> -# opcontrol --reset -# opcontrol --start --separate=lib --no-vmlinux -c 5 -[do whatever is being profiled] -# opcontrol --stop -$ opreport -cl - </literallayout> - </para> - - <para> - In this example, the reset command clears any previously profiled data. - The next command starts OProfile. - The options used when starting the profiler separate dynamic library data - within applications, disable kernel profiling, and enable callgraphing up to - five levels deep. - </para> - <note><para> - To profile the kernel, you would specify the - <parameter>--vmlinux=/path/to/vmlinux</parameter> option. - The vmlinux file is usually in <filename class="directory">/boot/</filename> - in Poky and must match the running kernel. - </para></note> - <para> - After you perform your profiling tasks, the next command stops the profiler. - After that you can view results with the "opreport" command with options - to see the separate library symbols and callgraph information. - </para> - <para> - Callgraphing logs information about time spent in functions and about a function's - calling function (parent) and called functions (children). - The higher the callgraphing depth, - the more accurate the results. - However, higher depths also increase the logging - overhead. - Consequently, you should take care when setting the callgraphing depth. - </para> - <note><para> - On ARM, binaries need to have the frame pointer enabled for callgraphing to work. - To accomplish this use the <filename>-fno-omit-framepointer</filename> option - with <filename>gcc</filename>. - </para></note> - <para> - For more information on using OProfile, see the OProfile - online documentation at - <ulink url="http://oprofile.sourceforge.net/docs/"/>. - </para> - </section> - - <section id="platdev-oprofile-oprofileui"> - <title>Using OProfileUI</title> - - <para> - A graphical user interface for OProfile is also available. - You can download and build it from the Yocto Project at - <ulink url="http://git.yoctoproject.org/cgit.cgi/oprofileui/"></ulink>. - If the "tools-profile" image feature is selected, all necessary binaries - are installed onto the target device for OProfileUI interaction. - </para> - -<!-- DISABLED, Need a more 'contextual' shot? - <screenshot> - <mediaobject> - <imageobject> - <imagedata fileref="screenshots/ss-oprofile-viewer.png" format="PNG"/> - </imageobject> - <caption> - <para>OProfileUI Viewer showing an application being profiled on a remote device</para> - </caption> - </mediaobject> - </screenshot> - - <para> - In order to convert the data in the sample format from the target - to the host you need the <filename>opimport</filename> program. - This program is not included in standard Debian OProfile packages. - However, an OProfile package with this addition is available from the - <ulink url='http://debian.o-hand.com/'>OpenedHand repository</ulink>. - We recommend using OProfile 0.9.3 or greater. - </para> ---> - <para> - Even though Poky usually includes all needed patches on the target device, you - might find you need other OProfile patches for recent OProfileUI features. - If so, see the <ulink url='http://git.yoctoproject.org/cgit.cgi/oprofileui/tree/README'> - OProfileUI README</ulink> for the most recent information. - </para> - - <section id="platdev-oprofile-oprofileui-online"> - <title>Online Mode</title> - - <para> - Using OProfile in online mode assumes a working network connection with the target - hardware. - With this connection, you just need to run "oprofile-server" on the device. - By default OProfile listens on port 4224. - </para> - <note><para> - You can change the port using the <filename>--port</filename> command-line - option. - </para></note> - - <para> - The client program is called "oprofile-viewer" and its UI is relatively - straightforward. - You access key functionality through the buttons on the toolbar, which - are duplicated in the menus. - The buttons are: - </para> - - <itemizedlist> - <listitem> - <para> - Connect - Connects to the remote host. - You can also supply the IP address or hostname. - </para> - </listitem> - <listitem> - <para> - Disconnect - Disconnects from the target. - </para> - </listitem> - <listitem> - <para> - Start - Starts profiling on the device. - </para> - </listitem> - <listitem> - <para> - Stop - Stops profiling on the device and downloads the data to the local - host. - Stopping the profiler generates the profile and displays it in the viewer. - </para> - </listitem> - <listitem> - <para> - Download - Downloads the data from the target and generates the profile, - which appears in the viewer. - </para> - </listitem> - <listitem> - <para> - Reset - Resets the sample data on the device. - Resetting the data removes sample information collected from previous - sampling runs. - Be sure you reset the data if you do not want to include old sample information. - </para> - </listitem> - <listitem> - <para> - Save - Saves the data downloaded from the target to another directory for later - examination. - </para> - </listitem> - <listitem> - <para> - Open - Loads previously saved data. - </para> - </listitem> - </itemizedlist> - - <para> - The client downloads the complete 'profile archive' from - the target to the host for processing. - This archive is a directory that contains the sample data, the object files - and the debug information for the object files. - The archive is then converted using the "oparchconv" script, which is - included in this distribution. - The script uses "opimport" to convert the archive from - the target to something that can be processed on the host. - </para> - - <para> - Downloaded archives reside in <filename>/tmp</filename> and are cleared up - when they are no longer in use. - </para> - - <para> - If you wish to perform kernel profiling you need to be sure - a "vmlinux" file that matches the running kernel is available. - In Poky, that file is usually located in - <filename>/boot/vmlinux-KERNELVERSION</filename>, where KERNEL-version is the - version of the kernel. - Poky generates separate vmlinux packages for each kernel - it builds so it should be a question of just making sure a matching package is - installed - for example: <filename>opkg install kernel-vmlinux</filename>. - The files are automatically installed into development and profiling images - alongside OProfile. - There is a configuration option within the OProfileUI settings page where - you can enter the location of the vmlinux file. - </para> - - <para> - Waiting for debug symbols to transfer from the device can be slow, and it - is not always necessary to actually have them on the device for OProfile use. - All that is needed is a copy of the filesystem with the debug symbols present - on the viewer system. - The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launching GDB - on the Host Computer</link>" section covers how to create such a directory with Poky and - how to use the OProfileUI Settings dialog to specify the location. - If you specify the directory, it will be used when the file checksums - match those on the system you are profiling. - </para> - </section> - - <section id="platdev-oprofile-oprofileui-offline"> - <title>Offline Mode</title> - - <para> - If network access to the target is unavailable, you can generate - an archive for processing in "oprofile-viewer" as follows: - </para> - - <para> - <literallayout class='monospaced'> - # opcontrol --reset - # opcontrol --start --separate=lib --no-vmlinux -c 5 - [do whatever is being profiled] - # opcontrol --stop - # oparchive -o my_archive - </literallayout> - </para> - - <para> - In the above example <filename>my_archive</filename> is the name of the - archive directory where you would like the profile archive to be kept. - After the directory is created, you can copy it to another host and load it - using "oprofile-viewer" open functionality. - If necessary, the archive is converted. - </para> - </section> - </section> -</section> - - - -</chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> |