From 50021cba20a09b1ed685db5466f940b17d4880ac Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Wed, 20 Apr 2011 14:20:19 +0100 Subject: Drop documentation directory, this is replaced by the new yocto-docs repository --- documentation/poky-ref-manual/development.xml | 1125 ------------------------- 1 file changed, 1125 deletions(-) delete mode 100644 documentation/poky-ref-manual/development.xml (limited to 'documentation/poky-ref-manual/development.xml') diff --git a/documentation/poky-ref-manual/development.xml b/documentation/poky-ref-manual/development.xml deleted file mode 100644 index 45df028f8..000000000 --- a/documentation/poky-ref-manual/development.xml +++ /dev/null @@ -1,1125 +0,0 @@ - - - -Platform Development with Poky - -
- Software development - - Poky supports several methods of software development. You can use the method that is - best for you. This chapter describes each development method. - - -
- External Development Using the Application Development Toolkit (ADT) - - 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 Reference: Images - appendix. - - - These tarballs unpack into the - /opt/poky directory and contain - a setup script (e.g. - /opt/poky/environment-setup-i586-poky-linux), 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. - - - Using the toolchain with autotool-enabled packages is straightforward - just pass the - appropriate host option to configure. - Following is an example: - - $ ./configure --host=arm-poky-linux-gnueabi - - For other projects it is usually a case of ensuring the cross tools are used: - - CC=arm-poky-linux-gnueabi-gcc and LD=arm-poky-linux-gnueabi-ld - - -
- -
- Using the Eclipse Plug-in - - 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. - - - 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 - under IDE Plugins. - The community is free to continue supporting it beyond the Yocto Project 0.9 - Release. - - - 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 - - "Working Within Eclipse" chapter in the - - "Application Development Toolkit (ADT) User's Guide." - - - - - - -
- -
- Developing Externally in QEMU - - Running Poky QEMU images is covered in the - - Yocto Project Quick Start in the "A Quick Test Run" section. - - - 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. export CC="distcc"). - Alternatively, if a suitable SDK/toolchain is present in - /opt/poky it is also - automatically be used. - - - - 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. - -
- -
- Developing in Poky Directly - - Working directly in Poky is a fast and effective development technique. - The idea is that you can directly edit files in - WORKDIR - or the source directory S - 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: - - - - - $ 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 - - - - - 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. - - - - It is useful when making changes directly to the work directory files to do - so using "quilt" as detailed in the - modifying packages with quilt section. You can copy the resulting patches - into the recipe directory and use them directly in the SRC_URI. - - - For a review of the skills used in this section see the Bitbake and Running Specific Tasks Sections. - -
- -
- Developing with 'devshell' - - - 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. - - - - - $ bitbake matchbox-desktop -c devshell - - - - - This command opens a terminal with a shell prompt within the Poky - environment. Consequently, the following occurs: - - The PATH variable includes the cross toolchain. - The pkgconfig variables find the correct .pc files. - "configure" finds the Poky site files as well as any other necessary files. - - 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 (S) - directory. - When you are finished, you just exit the shell or close the terminal window. - - - - The default shell used by "devshell" is the gnome-terminal. - You can use other forms of terminal can by setting the - TERMCMD and - TERMCMDRUN variables - in local.conf. - For examples of the other options available, see - meta/conf/bitbake.conf. - - - 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. - - - - It is worth remembering that inside "devshell" you need to use the full - compiler name such as arm-poky-linux-gnueabi-gcc - instead of just gcc. - 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. - -
- -
- Developing within Poky with an External SCM-based Package - - - 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. - - - - To enable this behavior simply add - SRCREV_pn- - PN = "${AUTOREV}" to - local.conf, where PN - is the name of the package for which you want to enable automatic source - revision updating. - -
-
- -
- Debugging with GDB Remotely - - - 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 for the GDB source. - - - For best results install -dbg packages for the applications - you are going to debug. - Doing so makes available extra debug symbols that will give you more meaningful output. - - - - 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. - - - 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. - - - 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. - - - - 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 - on their site. - - -
- Launching GDBSERVER on the Target - - First, make sure GDBSERVER is installed on the target. If not, - install the package gdbserver, which needs the - libthread-db1 package. - - - As an example, to launch GDBSERVER on the target and make it ready to "debug" a - program located at /path/to/inferior, connect - to the target and launch: - - $ gdbserver localhost:2345 /path/to/inferior - - 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. - -
- -
- Launching GDB on the Host Computer - - - Running GDB on the host computer takes a number of stages. - This section describes those stages. - - -
- Building the Cross-GDB Package - - 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: - -/usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb - - where "arm" is the target architecture and "linux-gnueabi" the target ABI. - - - - Alternatively, Poky can build the gdb-cross binary. - For example, the following command builds it: - - $ bitbake gdb-cross - - Once the binary is built you can find it here: - -tmp/sysroots/<host-arch>/usr/bin/<target-abi>-gdb - - - -
-
- - Making the Inferior Binaries Available - - - 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. - - - - 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. - - - - Alternatively, Poky can build a custom directory of files for a specific - debugging purpose by reusing its tmp/rootfs directory. - This directory contains the contents of the last built image. - This process assumes two things: - - The image running on the target was the last image to - be built by Poky. - The package (foo in the following - example) that contains the inferior binary to be debugged has been built - without optimization and has debugging information available. - - - - These steps show how to build the custom directory of files: - - - Install the package (foo in this case) to - tmp/rootfs: - -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 - - Install the debugging information: - -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 - - - -
-
- - Launch the Host GDB - - 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 foo binary - as well as the debugging information: - - $ <target-abi>-gdb rootfs/usr/bin/foo - - Once the GDB prompt appears, you must instruct GDB to load all the libraries - of the inferior binary from tmp/rootfs as follows: - - $ set solib-absolute-prefix /path/to/tmp/rootfs - - The pathname /path/to/tmp/rootfs must either be - the absolute path to tmp/rootfs or the location at which - binaries with debugging information reside. - - - At this point you can have GDB connect to the GDBSERVER that is running - on the remote target by using the following command form: - - $ target remote remote-target-ip-address:2345 - - The remote-target-ip-address is the IP address of the - remote target where the GDBSERVER is running. - Port 2345 is the port on which the GDBSERVER is running. - - -
-
- - Using the Debugger - - 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: - - (gdb) break main - (gdb) continue - - - - For more information about using GDB, see the project's online documentation at - . - -
-
- -
- -
- Profiling with OProfile - - - OProfile 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. - - - - To use OProfile you need an image that has OProfile installed. - The easiest way to do this is with "tools-profile" in - IMAGE_FEATURES. - 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 - IMAGE_FEATURES or by - installing the appropriate -dbg packages. - - - 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 - SELECTED_OPTIMIZATION - to "-fexpensive-optimizations -fno-omit-framepointer - -frename-registers -O2". - You can also achieve it by setting - DEBUG_BUILD to "1" in - local.conf. - If you use the DEBUG_BUILD variable you will also add extra debug information - that can make the debug packages large. - - -
- Profiling on the Target - - - Using OProfile you can perform all the profiling work on the target device. - A simple OProfile session might look like the following: - - - - -# opcontrol --reset -# opcontrol --start --separate=lib --no-vmlinux -c 5 -[do whatever is being profiled] -# opcontrol --stop -$ opreport -cl - - - - - 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. - - - To profile the kernel, you would specify the - --vmlinux=/path/to/vmlinux option. - The vmlinux file is usually in /boot/ - in Poky and must match the running kernel. - - - 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. - - - 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. - - - On ARM, binaries need to have the frame pointer enabled for callgraphing to work. - To accomplish this use the -fno-omit-framepointer option - with gcc. - - - For more information on using OProfile, see the OProfile - online documentation at - . - -
- -
- Using OProfileUI - - - A graphical user interface for OProfile is also available. - You can download and build it from the Yocto Project at - . - If the "tools-profile" image feature is selected, all necessary binaries - are installed onto the target device for OProfileUI interaction. - - - - - 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 - OProfileUI README for the most recent information. - - -
- Online Mode - - - 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. - - - You can change the port using the --port command-line - option. - - - - 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: - - - - - - Connect - Connects to the remote host. - You can also supply the IP address or hostname. - - - - - Disconnect - Disconnects from the target. - - - - - Start - Starts profiling on the device. - - - - - 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. - - - - - Download - Downloads the data from the target and generates the profile, - which appears in the viewer. - - - - - 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. - - - - - Save - Saves the data downloaded from the target to another directory for later - examination. - - - - - Open - Loads previously saved data. - - - - - - 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. - - - - Downloaded archives reside in /tmp and are cleared up - when they are no longer in use. - - - - 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 - /boot/vmlinux-KERNELVERSION, 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: opkg install kernel-vmlinux. - 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. - - - - 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 "Launching GDB - on the Host Computer" 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. - -
- -
- Offline Mode - - - If network access to the target is unavailable, you can generate - an archive for processing in "oprofile-viewer" as follows: - - - - - # opcontrol --reset - # opcontrol --start --separate=lib --no-vmlinux -c 5 - [do whatever is being profiled] - # opcontrol --stop - # oparchive -o my_archive - - - - - In the above example my_archive 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. - -
-
-
- - - - - -- cgit v1.2.3