summaryrefslogtreecommitdiffstats
path: root/handbook
diff options
context:
space:
mode:
authorRichard Purdie <richard@openedhand.com>2008-02-26 11:46:00 +0000
committerRichard Purdie <richard@openedhand.com>2008-02-26 11:46:00 +0000
commited555de529c5725095a9b4e900a3f09edfe873ff (patch)
treebd23cb7fa2c1a1122a561a8cac08d561ec8c6e48 /handbook
parent18a758b9e99641207883c81cb7862a8737eb0682 (diff)
downloadpoky-ed555de529c5725095a9b4e900a3f09edfe873ff.tar.gz
Remove generated file
git-svn-id: https://svn.o-hand.com/repos/poky/trunk@3868 311d38ba-8fff-0310-9ca6-ca027cbcb966
Diffstat (limited to 'handbook')
-rw-r--r--handbook/poky-handbook.html2429
1 files changed, 0 insertions, 2429 deletions
diff --git a/handbook/poky-handbook.html b/handbook/poky-handbook.html
deleted file mode 100644
index abc32354dd..0000000000
--- a/handbook/poky-handbook.html
+++ /dev/null
@@ -1,2429 +0,0 @@
1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Poky Handbook</title><link rel="stylesheet" href="style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="poky-handbook"></a>Poky Handbook</h1></div><div><h2 class="subtitle">Hitchhiker's Guide to Poky</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Richard</span> <span class="surname">Purdie</span></h3><div class="affiliation"><span class="orgname">OpenedHand Ltd<br></span></div><code class="email">&lt;<a href="mailto:richard@openedhand.com">richard@openedhand.com</a>&gt;</code></div><div class="author"><h3 class="author"><span class="firstname">Tomas</span> <span class="surname">Frydrych</span></h3><div class="affiliation"><span class="orgname">OpenedHand Ltd<br></span></div><code class="email">&lt;<a href="mailto:tf@openedhand.com">tf@openedhand.com</a>&gt;</code></div><div class="author"><h3 class="author"><span class="firstname">Marcin</span> <span class="surname">Juszkiewicz</span></h3><div class="affiliation"><span class="orgname">OpenedHand Ltd<br></span></div><code class="email">&lt;<a href="mailto:hrw@openedhand.com">hrw@openedhand.com</a>&gt;</code></div><div class="author"><h3 class="author"><span class="firstname">Dodji</span> <span class="surname">Seketeli</span></h3><div class="affiliation"><span class="orgname">OpenedHand Ltd<br></span></div><code class="email">&lt;<a href="mailto:dodji@openedhand.com">dodji@openedhand.com</a>&gt;</code></div></div></div><div><p class="copyright">Copyright © 2007 OpenedHand Limited</p></div><div><div class="legalnotice"><a name="id1081631"></a><p>
2 Permission is granted to copy, distribute and/or modify this document under
3 the terms of the <a href="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/" target="_top">Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England &amp; Wales</a> as published by Creative Commons.
4 </p></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision 3.1</td><td align="left">15 Feburary 2008</td></tr><tr><td align="left" colspan="2">Poky 3.1 (Pinky) Documentation Release</td></tr></table></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#intro">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-what-is">1. What is Poky?</a></span></dt><dt><span class="section"><a href="#intro-manualoverview">2. Documentation Overview</a></span></dt><dt><span class="section"><a href="#intro-requirements">3. System Requirements</a></span></dt><dt><span class="section"><a href="#intro-quickstart">4. Quick Start</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-quickstart-build">4.1. Building and Running an Image</a></span></dt><dt><span class="section"><a href="#intro-quickstart-qemu">4.2. Downloading and Using Prebuilt Images</a></span></dt></dl></dd><dt><span class="section"><a href="#intro-getit">5. Obtaining Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-getit-releases">5.1. Releases</a></span></dt><dt><span class="section"><a href="#intro-getit-nightly">5.2. Nightly Builds</a></span></dt><dt><span class="section"><a href="#intro-getit-dev">5.3. Development Checkouts</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#usingpoky">2. Using Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components">1. Poky Overview</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">1.1. Bitbake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">1.3. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">1.4. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-build">2. Running a Build</a></span></dt><dt><span class="section"><a href="#usingpoky-install">3. Installing and Using the Result</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-install-usbnetworking">3.1. USB Networking</a></span></dt><dt><span class="section"><a href="#usingpoky-install-qemu-networking">3.2. QEMU/USB networking with IP masquerading</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-debugging">4. Debugging Build Failures</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-debugging-taskfailures">4.1. Task Failures</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-taskrunning">4.2. Running specific tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-dependencies">4.3. Dependency Graphs</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-bitbake">4.4. General Bitbake Problems</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-buildfile">4.5. Building with no dependencies</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-variables">4.6. Variables</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-others">4.7. Other Tips</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#extendpoky">3. Extending Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-addpkg">1. Adding a Package</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-addpkg-singlec">1.1. Single .c File Package (Hello World!)</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-autotools">1.2. Autotooled Package</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-makefile">1.3. Makefile-Based Package</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-files">1.4. Controlling packages content</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-postinstalls">1.5. Post Install Scripts</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-extend-customimage">2. Customising Images</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-customimage-custombb">2.1. Customising Images through a custom image .bb files</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-customtasks">2.2. Customising Images through custom tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-imagefeatures">2.3. Customising Images through custom IMAGE_FEATURES</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-localconf">2.4. Customising Images through local.conf</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-newmachine">3. Porting Poky to a new machine</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-newmachine-conffile">3.1. Adding the machine configuration file</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-kernel">3.2. Adding a kernel for the machine</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-formfactor">3.3. Adding a formfactor configuration file</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-changes">4. Making and Maintaining Changes</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-changes-collections">4.1. Bitbake Collections</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-commits">4.2. Committing Changes</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-prbump">4.3. Package Revision Incrementing</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-modifing-packages">5. Modifying Package Source Code</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-modifying-packages-quilt">5.1. Modifying Package Source Code with quilt</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#platdev">4. Platform Development with Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-appdev">1. Software development</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-appdev-external-anjuta">1.1. Developing externally using the Anjuta Plugin</a></span></dt><dt><span class="section"><a href="#platdev-appdev-external-sdk">1.2. Developing externally using the Poky SDK</a></span></dt><dt><span class="section"><a href="#platdev-appdev-qemu">1.3. Developing externally in QEMU</a></span></dt><dt><span class="section"><a href="#platdev-appdev-chroot">1.4. Developing externally in a chroot</a></span></dt><dt><span class="section"><a href="#platdev-appdev-insitu">1.5. Developing in Poky directly</a></span></dt><dt><span class="section"><a href="#platdev-appdev-devshell">1.6. Developing with 'devshell'</a></span></dt><dt><span class="section"><a href="#platdev-appdev-srcrev">1.7. Developing within Poky with an external SCM based package</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-gdb-remotedebug">2. Debugging with GDB Remotely</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdbserver">2.1. Launching GDBSERVER on the target</a></span></dt><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdb">2.2. Launching GDB on the host computer</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-oprofile">3. Profiling with OProfile</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-oprofile-target">3.1. Profiling on the target</a></span></dt><dt><span class="section"><a href="#platdev-oprofile-oprofileui">3.2. Using OProfileUI</a></span></dt></dl></dd></dl></dd><dt><span class="appendix"><a href="#ref-structure">1. Reference: Directory Structure</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core">1. Top level core components</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core-bitbake">1.1. <code class="filename">bitbake/</code></a></span></dt><dt><span class="section"><a href="#structure-core-build">1.2. <code class="filename">build/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta">1.3. <code class="filename">meta/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-extras">1.4. <code class="filename">meta-extras/</code></a></span></dt><dt><span class="section"><a href="#structure-core-scripts">1.5. <code class="filename">scripts/</code></a></span></dt><dt><span class="section"><a href="#structure-core-sources">1.6. <code class="filename">sources/</code></a></span></dt><dt><span class="section"><a href="#structure-core-script">1.7. <code class="filename">poky-init-build-env</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-build">2. <code class="filename">build/</code> - The Build Directory</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-build-conf-local.conf">2.1. <code class="filename">build/conf/local.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp">2.2. <code class="filename">build/tmp/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cache">2.3. <code class="filename">build/tmp/cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cross">2.4. <code class="filename">build/tmp/cross/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy">2.5. <code class="filename">build/tmp/deploy/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-deb">2.6. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-images">2.7. <code class="filename">build/tmp/deploy/images/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-ipk">2.8. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-rootfs">2.9. <code class="filename">build/tmp/rootfs/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-staging">2.10. <code class="filename">build/tmp/staging/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-stamps">2.11. <code class="filename">build/tmp/stamps/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-work">2.12. <code class="filename">build/tmp/work/</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-meta">3. <code class="filename">meta/</code> - The Metadata</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-meta-classes">3.1. <code class="filename">meta/classes/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf">3.2. <code class="filename">meta/conf/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-machine">3.3. <code class="filename">meta/conf/machine/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-distro">3.4. <code class="filename">meta/conf/distro/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-packages">3.5. <code class="filename">meta/packages/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-site">3.6. <code class="filename">meta/site/</code></a></span></dt></dl></dd></dl></dd><dt><span class="appendix"><a href="#ref-bitbake">2. Reference: Bitbake</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-bitbake-parsing">1. Parsing</a></span></dt><dt><span class="section"><a href="#ref-bitbake-providers">2. Preferences and Providers</a></span></dt><dt><span class="section"><a href="#ref-bitbake-dependencies">3. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-bitbake-tasklist">4. The Task List</a></span></dt><dt><span class="section"><a href="#ref-bitbake-runtask">5. Running a Task</a></span></dt><dt><span class="section"><a href="#ref-bitbake-commandline">6. Commandline</a></span></dt><dt><span class="section"><a href="#ref-bitbake-fetchers">7. Fetchers</a></span></dt></dl></dd><dt><span class="appendix"><a href="#ref-classes">3. Reference: Classes</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-classes-base">1. The base class - <code class="filename">base.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-autotools">2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-alternatives">3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-rc.d">4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-binconfig">5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-debian">6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-pkgconfig">7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-src-distribute">8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-perl">9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-distutils">10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-devshell">11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-package">12. Packaging - <code class="filename">package*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-kernel">13. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-image">14. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-sanity">15. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-insane">16. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-siteinfo">17. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-others">18. Other Classes</a></span></dt></dl></dd><dt><span class="appendix"><a href="#ref-images">4. Reference: Images</a></span></dt><dt><span class="appendix"><a href="#ref-features">5. Reference: Features</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-features-distro">1. Distro</a></span></dt><dt><span class="section"><a href="#ref-features-machine">2. Machine</a></span></dt><dt><span class="section"><a href="#ref-features-image">3. Reference: Images</a></span></dt></dl></dd><dt><span class="appendix"><a href="#ref-variables-glos">6. Reference: Variables Glossary</a></span></dt><dd><dl><dt><span class="glossary"><a href="#ref-variables-glossary">Glossary</a></span></dt></dl></dd><dt><span class="appendix"><a href="#ref-varlocality">7. Reference: Variable Locality (Distro, Machine, Recipe etc.)</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-config-distro">1. Distro Configuration</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-machine">2. Machine Configuration</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-local">3. Local Configuration (local.conf)</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-required">4. Recipe Variables - Required</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-dependencies">5. Recipe Variables - Dependencies</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-paths">6. Recipe Variables - Paths</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-build">7. Recipe Variables - Extra Build Information</a></span></dt></dl></dd><dt><span class="appendix"><a href="#faq">8. FAQ</a></span></dt><dt><span class="appendix"><a href="#resources">9. Contributing to Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#resources-intro">1. Introduction</a></span></dt><dt><span class="section"><a href="#resources-bugtracker">2. Bugtracker</a></span></dt><dt><span class="section"><a href="#resources-mailinglist">3. Mailing list</a></span></dt><dt><span class="section"><a href="#resources-irc">4. IRC</a></span></dt><dt><span class="section"><a href="#resources-links">5. Links</a></span></dt></dl></dd><dt><span class="appendix"><a href="#contact">10. OpenedHand Contact Information</a></span></dt><dt><span class="index"><a href="#index">Index</a></span></dt></dl></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="intro"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#intro-what-is">1. What is Poky?</a></span></dt><dt><span class="section"><a href="#intro-manualoverview">2. Documentation Overview</a></span></dt><dt><span class="section"><a href="#intro-requirements">3. System Requirements</a></span></dt><dt><span class="section"><a href="#intro-quickstart">4. Quick Start</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-quickstart-build">4.1. Building and Running an Image</a></span></dt><dt><span class="section"><a href="#intro-quickstart-qemu">4.2. Downloading and Using Prebuilt Images</a></span></dt></dl></dd><dt><span class="section"><a href="#intro-getit">5. Obtaining Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-getit-releases">5.1. Releases</a></span></dt><dt><span class="section"><a href="#intro-getit-nightly">5.2. Nightly Builds</a></span></dt><dt><span class="section"><a href="#intro-getit-dev">5.3. Development Checkouts</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-what-is"></a>1. What is Poky?</h2></div></div></div><p>
5 Poky is an open source platform build tool. It is a complete software
6 development environment for the creation of Linux devices. It aids the
7 design, development, building, debugging, simulation and testing of
8 complete modern software stacks using Linux, the X Window System and
9 GNOME Mobile based application frameworks. It is based on
10 <a href="http://openembedded.org/" target="_top">OpenEmbedded</a>
11 but has been customised with a particular focus.
12 </p><p> Poky was setup to:</p><div class="itemizedlist"><ul type="disc"><li><p>Provide an open source Linux, X11, Matchbox, GTK+, <a href="http://gnome.org/mobile" target="_top">GNOME Mobile</a> platform.</p></li><li><p>Create a focused, stable, subset of OpenEmbedded that can be easily and reliably built and developed upon.</p></li><li><p>Fully support a wide range of x86 and ARM hardware</p></li></ul></div><p><a href="http://www.o-hand.com" target="_top">OpenedHand</a> is the principle developer and maintainer of Poky and uses it to:</p><div class="itemizedlist"><ul type="disc"><li><p>Provide <a href="http://www.o-hand.com" target="_top">OpenedHand</a> with stable R&amp;D platform we can build and develop upon.</p></li><li><p>
13 Demonstrate the skills available within <a href="http://www.o-hand.com" target="_top">
14 OpenedHand</a> and provide a showcase for our software products
15 (such as the <a href="http://www.matchbox-project.org/" target="_top">Matchbox</a> and
16 <a href="http://www.pimlico-project.org/" target="_top">Pimlico</a> software packages and
17 Sato, the default user interface in Poky).
18 </p></li><li><p>Provide a base we can supply to our clients for building and developing their customised platforms.</p></li></ul></div><p>
19 Poky is primarily a platform builder which generates filesystem images
20 based on open source software such as the Kdrive X server, the Matchbox
21 window manager, the GTK+ toolkit and the D-Bus message bus system. Images
22 for many kinds of devices can be generated, however the standard example
23 machines target QEMU system emulation (both x86 and ARM) and the ARM based
24 Sharp Zaurus series of devices. Poky's ability to boot inside a QEMU
25 emulator makes it particularly suitable as a test platform for development
26 of embedded software.
27 </p><p>
28 An important component integrated within Poky is Sato, a GNOME Mobile
29 based user interface environment.
30 It is designed to work well with screens at very high DPI and restricted
31 size, such as those often found on smartphones and PDAs. It is coded with
32 focus on efficiency and speed so that it works smoothly on hand-held and
33 other embedded hardware. It will sit neatly on top of any device
34 using the GNOME Mobile stack, providing a well defined user experience.
35 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-manualoverview"></a>2. Documentation Overview</h2></div></div></div><p>
36 The handbook is split into sections covering different aspects of Poky.
37 The <a href="#usingpoky" title="Chapter 2. Using Poky">'Using Poky' section</a> gives an overview
38 of the components that make up Poky followed by information about using and
39 debugging the Poky build system. The <a href="#extendpoky" title="Chapter 3. Extending Poky">'Extending Poky' section</a>
40 gives information about how to extend and customise Poky along with advice
41 on how to manage these changes. The <a href="#platdev" title="Chapter 4. Platform Development with Poky">'Platform Development with Poky'
42 section</a> gives information about interaction between Poky and target
43 hardware for common platform development tasks such as software development,
44 debugging and profiling. The rest of the manual
45 consists of several reference sections each giving details on a specific
46 section of Poky functionality.
47 </p><p>
48 This manual applies to Poky Release 3.1 (Pinky).
49 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-requirements"></a>3. System Requirements</h2></div></div></div><p>
50 We recommend Debian-based distributions, in particular a recent Ubuntu
51 release (7.04 or newer), as the host system for Poky. Nothing in Poky is
52 distribution specific and
53 other distributions will most likely work as long as the appropriate
54 prerequisites are installed - we know of Poky being used successfully on Redhat,
55 SUSE, Gentoo and Slackware host systems.
56 </p><p>On a Debian-based system, you need the following packages installed:</p><div class="itemizedlist"><ul type="disc"><li><p>build-essential</p></li><li><p>python</p></li><li><p>diffstat</p></li><li><p>texinfo</p></li><li><p>texi2html</p></li><li><p>cvs</p></li><li><p>subversion</p></li><li><p>wget</p></li><li><p>gawk</p></li><li><p>help2man</p></li><li><p>bochsbios (only to run qemux86 images)</p></li></ul></div><p>
57 Debian users can add debian.o-hand.com to their APT sources (See
58 <a href="http://debian.o-hand.com" target="_top">http://debian.o-hand.com</a>
59 for instructions on doing this) and then run <span><strong class="command">
60 "apt-get install qemu poky-depends poky-scripts"</strong></span> which will
61 automatically install all these dependencies. OpenedHand can also provide
62 VMware images with Poky and all dependencies pre-installed if required.
63 </p><p>
64 Poky can use a system provided QEMU or build its own depending on how it's
65 configured. See the options in <code class="filename">local.conf</code> for more details.
66 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-quickstart"></a>4. Quick Start</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-quickstart-build"></a>4.1. Building and Running an Image</h3></div></div></div><p>
67 If you want to try Poky, you can do so in a few commands. The example below
68 checks out the Poky source code, sets up a build environment, builds an
69 image and then runs that image under the QEMU emulator in ARM system emulation mode:
70 </p><p>
71 </p><pre class="literallayout">
72$ wget http://pokylinux.org/releases/pinky-3.1.tar.gz
73$ tar zxvf pinky-3.1.tar.gz
74$ cd pinky-3.1/
75$ source poky-init-build-env
76$ bitbake poky-image-sato
77$ runqemu qemuarm
78</pre><p>
79 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
80 This process will need Internet access, about 3 GB of disk space
81 available, and you should expect the build to take about 4 - 5 hours since
82 it is building an entire Linux system from source including the toolchain!
83 </p></div><p>
84 To build for other machines see the <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a></em> variable in build/conf/local.conf
85 which also contains other configuration information. The images/kernels built
86 by Poky are placed in the <code class="filename">tmp/deploy/images</code>
87 directory.
88 </p><p>
89 You could also run <span><strong class="command">"poky-qemu zImage-qemuarm.bin poky-image-sato-qemuarm.ext2"
90 </strong></span> within the images directory if you have the poky-scripts Debian package
91 installed from debian.o-hand.com. This allows the QEMU images to be used standalone
92 outside the Poky build environment.
93 </p><p>
94 To setup networking within QEMU see the <a href="#usingpoky-install-qemu-networking" title="3.2. QEMU/USB networking with IP masquerading">
95 QEMU/USB networking with IP masquerading</a> section.
96 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-quickstart-qemu"></a>4.2. Downloading and Using Prebuilt Images</h3></div></div></div><p>
97 Prebuilt images from Poky are also available if you just want to run the system
98 under QEMU. To use these you need to:
99 </p><div class="itemizedlist"><ul type="disc"><li><p>
100 Add debian.o-hand.com to your APT sources (See
101 <a href="http://debian.o-hand.com" target="_top">http://debian.o-hand.com</a> for instructions on doing this)
102 </p></li><li><p>Install patched QEMU and poky-scripts:</p><p>
103 </p><pre class="literallayout">
104$ apt-get install qemu poky-scripts
105</pre><p>
106 </p></li><li><p>
107 Download a Poky QEMU release kernel (*zImage*qemu*.bin) and compressed
108 filesystem image (poky-image-*-qemu*.ext2.bz2) which
109 you'll need to decompress with 'bzip2 -d'. These are available from the
110 <a href="http://pokylinux.org/releases/blinky-3.0/" target="_top">last release</a>
111 or from the <a href="http://pokylinux.org/autobuild/poky/" target="_top">autobuilder</a>.
112 </p></li><li><p>Start the image:</p><p>
113 </p><pre class="literallayout">
114$ poky-qemu &lt;kernel&gt; &lt;image&gt;
115</pre><p>
116 </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
117 A patched version of QEMU is required at present. A suitable version is available from
118 <a href="http://debian.o-hand.com" target="_top">http://debian.o-hand.com</a>, it can be built
119 by poky (bitbake qemu-native) or can be downloaded/built as part of the toolchain/SDK tarballs.
120 </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-getit"></a>5. Obtaining Poky</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-getit-releases"></a>5.1. Releases</h3></div></div></div><p>Periodically, we make releases of Poky and these are available
121 at <a href="http://pokylinux.org/releases/" target="_top">http://pokylinux.org/releases/</a>.
122 These are more stable and tested than the nightly development images.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-getit-nightly"></a>5.2. Nightly Builds</h3></div></div></div><p>
123 We make nightly builds of Poky for testing purposes and to make the
124 latest developments available. The output from these builds is available
125 at <a href="http://pokylinux.org/autobuild/" target="_top">http://pokylinux.org/autobuild/</a>
126 where the numbers represent the svn revision the builds were made from.
127 </p><p>
128 Automated builds are available for "standard" Poky and for Poky SDKs and toolchains as well
129 as any testing versions we might have such as poky-bleeding. The toolchains can
130 be used either as external standalone toolchains or can be combined with Poky as a
131 prebuilt toolchain to reduce build time. Using the external toolchains is simply a
132 case of untarring the tarball into the root of your system (it only creates files in
133 <code class="filename">/usr/local/poky</code>) and then enabling the option
134 in <code class="filename">local.conf</code>.
135 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-getit-dev"></a>5.3. Development Checkouts</h3></div></div></div><p>
136 Poky is available from our SVN repository located at
137 http://svn.o-hand.com/repos/poky/trunk; a web interface to the repository
138 can be accessed at <a href="http://svn.o-hand.com/view/poky/" target="_top">http://svn.o-hand.com/view/poky/</a>.
139 </p><p>
140 'trunk' is where the deveopment work takes place and you should use this if you're
141 after to work with the latest cutting edge developments. It is possible trunk
142 can suffer temporary periods of instability while new features are developed and
143 if this is undesireable we recommend using one of the release branches.
144 </p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="usingpoky"></a>Chapter 2. Using Poky</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#usingpoky-components">1. Poky Overview</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">1.1. Bitbake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">1.3. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">1.4. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-build">2. Running a Build</a></span></dt><dt><span class="section"><a href="#usingpoky-install">3. Installing and Using the Result</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-install-usbnetworking">3.1. USB Networking</a></span></dt><dt><span class="section"><a href="#usingpoky-install-qemu-networking">3.2. QEMU/USB networking with IP masquerading</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-debugging">4. Debugging Build Failures</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-debugging-taskfailures">4.1. Task Failures</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-taskrunning">4.2. Running specific tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-dependencies">4.3. Dependency Graphs</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-bitbake">4.4. General Bitbake Problems</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-buildfile">4.5. Building with no dependencies</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-variables">4.6. Variables</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-others">4.7. Other Tips</a></span></dt></dl></dd></dl></div><p>
145 This section gives an overview of the components that make up Poky
146 following by information about running poky builds and dealing with any
147 problems that may arise.
148 </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-components"></a>1. Poky Overview</h2></div></div></div><p>
149 At the core of Poky is the bitbake task executor together with various types of
150 configuration files. This section gives an overview of bitbake and the
151 configuration files, in particular what they are used for, and how they
152 interact.
153 </p><p>
154 Bitbake handles the parsing and execution of the data
155 files. The data itself is of various types; recipes which give
156 details about particular pieces of software, class data which is an
157 abstraction of common build information (e.g. how to build a Linux kernel)
158 and configuration data for machines, policy decisions, etc., which acts as
159 a glue and binds everything together. Bitbake knows how to combine multiple
160 data sources together, each data source being referred to as a <a href="#usingpoky-changes-collections" title="4.1. Bitbake Collections">'collection'</a>.
161 </p><p>
162 The <a href="#ref-structure" title="Appendix 1. Reference: Directory Structure">directory structure walkthrough</a>
163 section gives details on the meaning of specific directories but some
164 brief details on the core components follows:
165 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-components-bitbake"></a>1.1. Bitbake</h3></div></div></div><p>
166 Bitbake is the tool at the heart of Poky and is responsible
167 for parsing the metadata, generating a list of tasks from it
168 and then executing them. To see a list of the options it
169 supports look at <span><strong class="command">bitbake --help</strong></span>.
170 </p><p>
171 The most common usage is <span><strong class="command">bitbake packagename</strong></span> where
172 packagename is the name of the package you wish to build
173 (from now on called the target). This often equates to the first part of a .bb
174 filename, so to run the <code class="filename">matchbox-desktop_1.2.3.bb</code> file, you
175 might type <span><strong class="command">bitbake matchbox-desktop</strong></span>.
176 Several different versions of matchbox-desktop might exist and
177 bitbake will choose the one selected by the distribution configuration
178 (more details about how bitbake chooses between different versions
179 and providers is available in the <a href="#ref-bitbake-providers" title="2. Preferences and Providers">
180 'Preferences and Providers' section</a>). Bitbake will also try to execute any
181 dependent tasks first so before building matchbox-desktop it
182 would build a cross compiler and glibc if not already built.
183 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-components-metadata"></a>1.2. Metadata (Recipes)</h3></div></div></div><p>
184 The .bb files are usually referred to as 'recipes'. In general, a
185 recipe contains information about a single piece of software such
186 as where to download the source, any patches that are needed,
187 any special configuration options, how to compile the source files
188 and how to package the compiled output.
189 </p><p>
190 'package' can also used to describe recipes but since the same
191 word is used for the packaged output from Poky (i.e. .ipk or .deb
192 files), this document will avoid it.
193 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-components-classes"></a>1.3. Classes</h3></div></div></div><p>
194 Class (.bbclass) files contain information which is useful to share
195 between metadata files. An example is the autotools class which contains
196 the common settings that any application using autotools would use. The
197 <a href="#ref-classes" title="Appendix 3. Reference: Classes">classes reference section</a> gives details
198 on common classes and how to use them.
199 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-components-configuration"></a>1.4. Configuration</h3></div></div></div><p>
200 The configuration (.conf) files define various configuration variables
201 which govern what Poky does. These are split into several areas, such
202 as machine configuration options, distribution configuration options,
203 compiler tuning options, general common configuration and user
204 configuration (local.conf).
205 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-build"></a>2. Running a Build</h2></div></div></div><p>
206 First the Poky build environment needs to be setup using the following command:
207 </p><p>
208 </p><pre class="literallayout">
209$ source poky-init-build-env
210</pre><p>
211 </p><p>
212 Once the Poky build environment is setup, a target can now be built using:
213 </p><p>
214 </p><pre class="literallayout">
215$ bitbake &lt;target&gt;
216</pre><p>
217 </p><p>
218 The target is the name of the recipe you want to build. Common targets are the
219 images (in <code class="filename">meta/packages/images/</code>)
220 or the name of a recipe for a specific piece of software like
221 <span class="application">busybox</span>. More details about the standard images
222 are available in the <a href="#ref-images" title="Appendix 4. Reference: Images">image reference section</a>.
223 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-install"></a>3. Installing and Using the Result</h2></div></div></div><p>
224 Once an image has been built it often needs to be installed. The images/kernels built
225 by Poky are placed in the <code class="filename">tmp/deploy/images</code>
226 directory. Running qemux86 and qemuarm images is covered in the <a href="#intro-quickstart-qemu" title="4.2. Downloading and Using Prebuilt Images">Running an Image</a> section. See your
227 board/machine documentation for information about how to install these images.
228 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-install-usbnetworking"></a>3.1. USB Networking</h3></div></div></div><p>
229 Devices commonly have USB connectivity. To connect to the usbnet interface, on
230 the host machine run:
231 </p><p>
232 </p><pre class="programlisting">
233modprobe usbnet
234ifconfig usb0 192.168.0.200
235route add 192.168.0.202 usb0
236</pre><p>
237 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-install-qemu-networking"></a>3.2. QEMU/USB networking with IP masquerading</h3></div></div></div><p>
238 On Ubuntu, Debian or similar distributions you can have the network automatically
239 configured. You can also enable masquerading between the QEMU system and the rest
240 of your network. To do this you need to edit <code class="filename">/etc/network/interfaces</code> to include:
241 </p><pre class="programlisting">
242allow-hotplug tap0
243iface tap0 inet static
244 address 192.168.7.200
245 netmask 255.255.255.0
246 network 192.168.7.0
247 post-up iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.7.0/24
248 post-up echo 1 &gt; /proc/sys/net/ipv4/ip_forward
249 post-up iptables -P FORWARD ACCEPT
250</pre><p>
251 </p><p>
252 This ensures the tap0 interface will be up everytime you run QEMU
253 and it will have network/internet access.
254 </p><p>
255 Under emulation there are two steps to configure for internet access
256 via tap0. The first step is to configure routing:
257 </p><pre class="programlisting">
258route add default gw 192.168.7.200 tap0
259</pre><p>
260 </p><p>
261 The second is to configure name resolution which is configured in the
262 <code class="filename">/etc/resolv.conf</code> file. The simplest solution is
263 to copy it's content from the host machine.
264 </p><p>
265 USB connections to devices can be setup and automated in a similar way.
266 First add the following to
267 <code class="filename">/etc/network/interfaces</code>:
268 </p><pre class="programlisting">
269allow-hotplug usb0
270iface usb0 inet static
271 address 192.168.0.200
272 netmask 255.255.255.0
273 network 192.168.0.0
274 post-up iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.0.0/24
275 post-up echo 1 &gt; /proc/sys/net/ipv4/ip_forward
276 post-up iptables -P FORWARD ACCEPT
277</pre><p>
278 </p><p>
279 and then to configure routing on the device you would use:
280 </p><pre class="programlisting">
281route add default gw 192.168.0.202 usb0
282</pre><p>
283 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-debugging"></a>4. Debugging Build Failures</h2></div></div></div><p>
284 The exact method for debugging Poky depends on the nature of the
285 bug(s) and which part of the system they might be from. Standard
286 debugging practises such as comparing to the last
287 known working version and examining the changes, reapplying the
288 changes in steps to identify the one causing the problem etc. are
289 valid for Poky just like any other system. Its impossible to detail
290 every possible potential failure here but there are some general
291 tips to aid debugging:
292 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-taskfailures"></a>4.1. Task Failures</h3></div></div></div><p>The log file for shell tasks is available in <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>.
293 For the compile task of busybox 1.01 on the ARM spitz machine, this
294 might be <code class="filename">tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</code>
295 for example. To see what bitbake ran to generate that log, look at the <code class="filename">run.do_taskname.pid </code>
296 file in the same directory.
297 </p><p>The output from python tasks is sent directly to the console at present.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-taskrunning"></a>4.2. Running specific tasks</h3></div></div></div><p> Any given package consists of a set of tasks, in most
298 cases the series is fetch, unpack, patch, configure,
299 compile, install, package, package_write and build. The
300 default task is "build" and any tasks this depends on are
301 built first hence the standard bitbake behaviour. There are
302 some tasks such as devshell which are not part of the
303 default build chain. If you wish to run such a task you can
304 use the "-c" option to bitbake e.g. <span><strong class="command">bitbake
305 matchbox-desktop -c devshell</strong></span>.
306 </p><p>
307 If you wish to rerun a task you can use the force option
308 "-f". A typical usage session might look like: </p><p>
309 </p><pre class="literallayout">
310% bitbake matchbox-desktop
311[change some source in the WORKDIR for example]
312% bitbake matchbox-desktop -c compile -f
313% bitbake matchbox-desktop</pre><p>
314 </p><p>
315 which would build matchbox-desktop, then recompile it. The
316 final command reruns all tasks after the compile (basically
317 the packaging tasks) since bitbake will notice the the
318 compile has been rerun and hence the other tasks also need
319 to run again.
320 </p><p>
321 You can view a list of tasks in a given package by running
322 the listtasks task e.g. <span><strong class="command">bitbake matchbox-desktop -c
323 listtasks</strong></span>.
324 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-dependencies"></a>4.3. Dependency Graphs</h3></div></div></div><p>
325 Sometimes it can be hard to see why bitbake wants to build
326 some other packages before a given package you've specified.
327 <span><strong class="command">bitbake -g targetname</strong></span> will create
328 <code class="filename">depends.dot</code> and
329 <code class="filename">task-depends.dot</code> files in the current
330 directory. They show
331 which packages and tasks depend on which other packages and
332 tasks and are useful for debugging purposes.
333 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-bitbake"></a>4.4. General Bitbake Problems</h3></div></div></div><p>
334 Debug output from bitbake can be seen with the "-D" option.
335 The debug output gives more information about what bitbake
336 is doing and/or why. Each -D option increases the logging
337 level, the most common usage being "-DDD".
338 </p><p>
339 The output from <span><strong class="command">bitbake -DDD -v targetname</strong></span> can reveal why
340 a certain version of a package might be chosen, why bitbake
341 picked a certain provider or help in other situations where
342 bitbake does something you're not expecting.
343 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-buildfile"></a>4.5. Building with no dependencies</h3></div></div></div><p>
344 If you really want to build a specific .bb file, you can use
345 the form <span><strong class="command">bitbake -b somepath/somefile.bb</strong></span>. Note that this
346 will not check the dependencies so this option should only
347 be used when you know its dependencies already exist. You
348 can specify fragments of the filename and bitbake will see
349 if it can find a unique match.
350 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-variables"></a>4.6. Variables</h3></div></div></div><p>
351 The "-e" option will dump the resulting environment for
352 either the configuration (no package specified) or for a
353 specific package when specified with the "-b" option.
354 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-others"></a>4.7. Other Tips</h3></div></div></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>When adding new packages it is worth keeping an eye open for bad
355 things creeping into compiler commandlines such as references to local
356 system files (<code class="filename">/usr/lib/</code> or <code class="filename">/usr/include/</code> etc.).
357 </p></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
358 If you want to remove the psplash boot splashscreen, add "psplash=false"
359 to the kernel commandline and psplash won't load allowing you to see
360 the console. It's also possible to switch out of the splashscreen by
361 switching virtual console (Fn+Left or Fn+Right on a Zaurus).
362 </p></div></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="extendpoky"></a>Chapter 3. Extending Poky</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#usingpoky-extend-addpkg">1. Adding a Package</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-addpkg-singlec">1.1. Single .c File Package (Hello World!)</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-autotools">1.2. Autotooled Package</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-makefile">1.3. Makefile-Based Package</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-files">1.4. Controlling packages content</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-postinstalls">1.5. Post Install Scripts</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-extend-customimage">2. Customising Images</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-customimage-custombb">2.1. Customising Images through a custom image .bb files</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-customtasks">2.2. Customising Images through custom tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-imagefeatures">2.3. Customising Images through custom IMAGE_FEATURES</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-localconf">2.4. Customising Images through local.conf</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-newmachine">3. Porting Poky to a new machine</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-newmachine-conffile">3.1. Adding the machine configuration file</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-kernel">3.2. Adding a kernel for the machine</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-formfactor">3.3. Adding a formfactor configuration file</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-changes">4. Making and Maintaining Changes</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-changes-collections">4.1. Bitbake Collections</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-commits">4.2. Committing Changes</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-prbump">4.3. Package Revision Incrementing</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-modifing-packages">5. Modifying Package Source Code</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-modifying-packages-quilt">5.1. Modifying Package Source Code with quilt</a></span></dt></dl></dd></dl></div><p>
363 This section gives information about how to extend the functionality
364 already present in Poky, documenting standard tasks such as adding new
365 software packages, extending or customising images or porting poky to
366 new hardware (adding a new machine). It also contains advice about how
367 to manage the process of making changes to Poky to achieve best results.
368 </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-extend-addpkg"></a>1. Adding a Package</h2></div></div></div><p>
369 To add package into Poky you need to write a recipe for it.
370 Writing a recipe means creating a .bb file which sets various
371 variables. The variables
372 useful for recipes are detailed in the <a href="#ref-varlocality-recipe-required" title="4. Recipe Variables - Required">
373 recipe reference</a> section along with more detailed information
374 about issues such as recipe naming.
375 </p><p>
376 The simplest way to add a new package is to base it on a similar
377 pre-existing recipe. There are some examples below of how to add
378 standard types of packages:
379 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-singlec"></a>1.1. Single .c File Package (Hello World!)</h3></div></div></div><p>
380 To build an application from a single file stored locally requires a
381 recipe which has the file listed in the <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em> variable. In addition
382 the <code class="function">do_compile</code> and <code class="function">do_install</code>
383 tasks need to be manually written. The <em class="glossterm"><a href="#var-S" title="S">
384 S</a></em> variable defines the directory containing the source
385 code which in this case is set equal to <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">
386 WORKDIR</a></em>, the directory BitBake uses for the build.
387 </p><pre class="programlisting">
388DESCRIPTION = "Simple helloworld application"
389SECTION = "examples"
390LICENSE = "MIT"
391
392SRC_URI = "file://helloworld.c"
393
394S = "${WORKDIR}"
395
396do_compile() {
397 ${CC} helloworld.c -o helloworld
398}
399
400do_install() {
401 install -d ${D}${bindir}
402 install -m 0755 helloworld ${D}${bindir}
403}
404 </pre><p>
405 As a result of the build process "helloworld" and "helloworld-dbg"
406 packages will be built.
407 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-autotools"></a>1.2. Autotooled Package</h3></div></div></div><p>
408 Applications which use autotools (autoconf, automake)
409 require a recipe which has a source archive listed in
410 <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em> and
411 <span><strong class="command">inherit autotools</strong></span> to instruct BitBake to use the
412 <code class="filename">autotools.bbclass</code> which has
413 definitions of all the steps
414 needed to build an autotooled application.
415 The result of the build will be automatically packaged and if
416 the application uses NLS to localise then packages with
417 locale information will be generated (one package per
418 language).
419 </p><pre class="programlisting">
420DESCRIPTION = "GNU Helloworld application"
421SECTION = "examples"
422LICENSE = "GPLv2"
423
424SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2"
425
426inherit autotools
427 </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-makefile"></a>1.3. Makefile-Based Package</h3></div></div></div><p>
428 Applications which use GNU make require a recipe which has
429 the source archive listed in <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em>.
430 Adding a <code class="function">do_compile</code> step
431 is not needed as by default BitBake will start the "make"
432 command to compile the application. If there is a need for
433 additional options to make then they should be stored in the
434 <em class="glossterm"><a href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a></em> variable - BitBake
435 will pass them into the GNU
436 make invocation. A <code class="function">do_install</code> task is required
437 - otherwise BitBake will run an empty <code class="function">do_install</code>
438 task by default.
439 </p><p>
440 Some applications may require extra parameters to be passed to
441 the compiler, for example an additional header path. This can
442 be done buy adding to the <em class="glossterm"><a href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></em> variable, as in the example below.
443 </p><pre class="programlisting">
444DESCRIPTION = "Tools for managing memory technology devices."
445SECTION = "base"
446DEPENDS = "zlib"
447HOMEPAGE = "http://www.linux-mtd.infradead.org/"
448LICENSE = "GPLv2"
449
450SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz"
451
452CFLAGS_prepend = "-I ${S}/include "
453
454do_install() {
455 oe_runmake install DESTDIR=${D}
456}
457 </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-files"></a>1.4. Controlling packages content</h3></div></div></div><p>
458 The variables <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></em> and
459 <em class="glossterm"><a href="#var-FILES" title="FILES">FILES</a></em> are used to split an
460 application into multiple packages.
461 </p><p>
462 Below the "libXpm" recipe is used as an example. By
463 default the "libXpm" recipe generates one package
464 which contains the library
465 and also a few binaries. The recipe can be adapted to
466 split the binaries into separate packages.
467 </p><pre class="programlisting">
468require xorg-lib-common.inc
469
470DESCRIPTION = "X11 Pixmap library"
471LICENSE = "X-BSD"
472DEPENDS += "libxext"
473PE = "1"
474
475XORG_PN = "libXpm"
476
477PACKAGES =+ "sxpm cxpm"
478FILES_cxpm = "${bindir}/cxpm"
479FILES_sxpm = "${bindir}/sxpm"
480 </pre><p>
481 In this example we want to ship the "sxpm" and "cxpm" binaries
482 in separate packages. Since "bindir" would be packaged into the
483 main <em class="glossterm"><a href="#var-PN" title="PN">PN</a></em>
484 package as standard we prepend the <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></em> variable so
485 additional package names are added to the start of list. The
486 extra <em class="glossterm"><a href="#var-PN" title="PN">FILES</a></em>_*
487 variables then contain information to specify which files and
488 directories goes into which package.
489 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-postinstalls"></a>1.5. Post Install Scripts</h3></div></div></div><p>
490 To add a post-installation script to a package, add
491 a <code class="function">pkg_postinst_PACKAGENAME()</code>
492 function to the .bb file
493 where PACKAGENAME is the name of the package to attach
494 the postinst script to. A post-installation function has the following structure:
495 </p><pre class="programlisting">
496pkg_postinst_PACKAGENAME () {
497#!/bin/sh -e
498# Commands to carry out
499}
500 </pre><p>
501 The script defined in the post installation function
502 gets called when the rootfs is made. If the script succeeds,
503 the package is marked as installed. If the script fails,
504 the package is marked as unpacked and the script will be
505 executed again on the first boot of the image.
506 </p><p>
507 Sometimes it is necessary that the execution of a post-installation
508 script is delayed until the first boot, because the script
509 needs to be executed the device itself. To delay script execution
510 until boot time, the post-installation function should have the
511 following structure:
512 </p><pre class="programlisting">
513pkg_postinst_PACKAGENAME () {
514#!/bin/sh -e
515if [ x"$D" = "x" ]; then
516# Actions to carry out on the device go here
517else
518exit 1
519fi
520}
521 </pre><p>
522 The structure above delays execution until first boot
523 because the <em class="glossterm"><a href="#var-D" title="D">D</a></em> variable points
524 to the 'image'
525 directory when the rootfs is being made at build time but
526 is unset when executed on the first boot.
527 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-extend-customimage"></a>2. Customising Images</h2></div></div></div><p>
528 Poky images can be customised to satisfy
529 particular requirements. Several methods are detailed below
530 along with guidelines of when to use them.
531 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-customimage-custombb"></a>2.1. Customising Images through a custom image .bb files</h3></div></div></div><p>
532 One way to get additional software into an image is by creating a
533 custom image. The recipe will contain two lines:
534 </p><pre class="programlisting">
535IMAGE_INSTALL = "task-poky-x11-base package1 package2"
536
537inherit poky-image
538 </pre><p>
539 By creating a custom image, a developer has total control
540 over the contents of the image. It is important use
541 the correct names of packages in the <em class="glossterm"><a href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></em> variable.
542 The names must be in
543 the OpenEmbedded notation instead of Debian notation, for example
544 "glibc-dev" instead of "libc6-dev" etc.
545 </p><p>
546 The other method of creating a new image is by modifying
547 an existing image. For example if a developer wants to add
548 "strace" into "poky-image-sato" the following recipe can
549 be used:
550 </p><pre class="programlisting">
551require poky-image-sato.bb
552
553IMAGE_INSTALL += "strace"
554 </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-customimage-customtasks"></a>2.2. Customising Images through custom tasks</h3></div></div></div><p>
555 For for complex custom images, the best approach is to create a custom
556 task package which is them used to build the image (or images). A good
557 example of a tasks package is <code class="filename">meta/packages/tasks/task-poky.bb
558 </code>. The <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></em>
559 variable lists the task packages to build (along with the complimentary
560 -dbg and -dev packages). For each package added,
561 <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">RDEPENDS</a></em> and
562 <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">RRECOMMENDS</a></em>
563 entries can then be added each containing a list of packages the parent
564 task package should contain. An example would be:
565 </p><p>
566 </p><pre class="programlisting">
567DESCRIPTION = "My Custom Tasks"
568
569PACKAGES = "\
570 task-custom-apps \
571 task-custom-apps-dbg \
572 task-custom-apps-dev \
573 task-custom-tools \
574 task-custom-tools-dbg \
575 task-custom-tools-dev \
576 "
577
578RDEPENDS_task-custom-apps = "\
579 dropbear \
580 portmap \
581 psplash"
582
583RDEPENDS_task-custom-tools = "\
584 oprofile \
585 oprofileui-server \
586 lttng-control \
587 lttng-viewer"
588
589RRECOMMENDS_task-custom-tools = "\
590 kernel-module-oprofile"
591</pre><p>
592 </p><p>
593 In this example, two tasks packages are created, task-custom-apps and
594 task-custom-tools with the dependencies and recommended package dependencies
595 listed. To build an image using these task packages, you would then add
596 "task-custom-apps" and/or "task-custom-tools" to <em class="glossterm"><a href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></em> or other forms
597 of image dependencies as described in other areas of this section.
598 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-customimage-imagefeatures"></a>2.3. Customising Images through custom <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em></h3></div></div></div><p>
599 Ultimately users may want to add extra image "features" as used by Poky with the
600 <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em>
601 variable. To create these, the best reference is <code class="filename">meta/classes/poky-image.bbclass</code>
602 which illustrates how poky achieves this. In summary, the file looks at the contents of the
603 <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em>
604 variable and based on this generates the <em class="glossterm"><a href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">
605 IMAGE_INSTALL</a></em> variable automatically. Extra features can be added by
606 extending the class or creating a custom class for use with specialised image .bb files.
607 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-customimage-localconf"></a>2.4. Customising Images through local.conf</h3></div></div></div><p>
608 It is possible to customise image contents by abusing
609 variables used by distribution maintainers in local.conf.
610 This method only allows the addition of packages and
611 is not recommended.
612 </p><p>
613 To add an "strace" package into the image the following is
614 added to local.conf:
615 </p><pre class="programlisting">
616DISTRO_EXTRA_RDEPENDS += "strace"
617 </pre><p>
618 However, since the <em class="glossterm"><a href="#var-DISTRO_EXTRA_RDEPENDS" title="DISTRO_EXTRA_RDEPENDS">
619 DISTRO_EXTRA_RDEPENDS</a></em> variable is for
620 distribution maintainers this method does not make
621 adding packages as simple as a custom .bb file. Using
622 this method, a few packages will need to be recreated
623 and the the image built.
624 </p><pre class="programlisting">
625bitbake -cclean task-boot task-base task-poky
626bitbake poky-image-sato
627 </pre><p>
628 Cleaning task-* packages is required because they use the
629 <em class="glossterm"><a href="#var-DISTRO_EXTRA_RDEPENDS" title="DISTRO_EXTRA_RDEPENDS">
630 DISTRO_EXTRA_RDEPENDS</a></em> variable. There is no need to
631 build them by hand as Poky images depend on the packages they contain so
632 dependencies will be built automatically. For this reason we don't use the
633 "rebuild" task in this case since "rebuild" does not care about
634 dependencies - it only rebuilds the specified package.
635 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="platdev-newmachine"></a>3. Porting Poky to a new machine</h2></div></div></div><p>
636 Adding a new machine to Poky is a straightforward process and
637 this section gives an idea of the changes that are needed. This guide is
638 meant to cover adding machines similar to those Poky already supports.
639 Adding a totally new architecture might require gcc/glibc changes as
640 well as updates to the site information and, whilst well within Poky's
641 capabilities, is outside the scope of this section.
642 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-newmachine-conffile"></a>3.1. Adding the machine configuration file</h3></div></div></div><p>
643 A .conf file needs to be added to conf/machine/ with details of the
644 device being added. The name of the file determines the name Poky will
645 use to reference this machine.
646 </p><p>
647 The most important variables to set in this file are <em class="glossterm">
648 <a href="#var-TARGET_ARCH" title="TARGET_ARCH">TARGET_ARCH</a></em>
649 (e.g. "arm"), <em class="glossterm"><a href="#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">
650 PREFERRED_PROVIDER</a></em>_virtual/kernel (see below) and
651 <em class="glossterm"><a href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES
652 </a></em> (e.g. "kernel26 apm screen wifi"). Other variables
653 like <em class="glossterm"><a href="#var-SERIAL_CONSOLE" title="SERIAL_CONSOLE">SERIAL_CONSOLE
654 </a></em> (e.g. "115200 ttyS0"), <em class="glossterm">
655 <a href="#var-KERNEL_IMAGETYPE" title="KERNEL_IMAGETYPE">KERNEL_IMAGETYPE</a>
656 </em> (e.g. "zImage") and <em class="glossterm"><a href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">
657 IMAGE_FSTYPES</a></em> (e.g. "tar.gz jffs2") might also be
658 needed. Full details on what these variables do and the meaning of
659 their contents is available through the links.
660 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-newmachine-kernel"></a>3.2. Adding a kernel for the machine</h3></div></div></div><p>
661 Poky needs to be able to build a kernel for the machine. You need
662 to either create a new kernel recipe for this machine or extend an
663 existing recipe. There are plenty of kernel examples in the
664 packages/linux directory which can be used as references.
665 </p><p>
666 If creating a new recipe the "normal" recipe writing rules apply
667 for setting up a <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI
668 </a></em> including any patches and setting <em class="glossterm">
669 <a href="#var-S" title="S">S</a></em> to point at the source
670 code. You will need to create a configure task which configures the
671 unpacked kernel with a defconfig be that through a "make defconfig"
672 command or more usually though copying in a suitable defconfig and
673 running "make oldconfig". By making use of "inherit kernel" and also
674 maybe some of the linux-*.inc files, most other functionality is
675 centralised and the the defaults of the class normally work well.
676 </p><p>
677 If extending an existing kernel it is usually a case of adding a
678 suitable defconfig file in a location similar to that used by other
679 machine's defconfig files in a given kernel, possibly listing it in
680 the SRC_URI and adding the machine to the expression in <em class="glossterm">
681 <a href="#var-COMPATIBLE_MACHINES" title="COMPATIBLE_MACHINES">COMPATIBLE_MACHINES</a>
682 </em>.
683 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-newmachine-formfactor"></a>3.3. Adding a formfactor configuration file</h3></div></div></div><p>
684 A formfactor configuration file provides information about the
685 target hardware on which Poky is running, and that Poky cannot
686 obtain from other sources such as the kernel. Some examples of
687 information contained in a formfactor configuration file include
688 framebuffer orientation, whether or not the system has a keyboard,
689 the positioning of the keyboard in relation to the screen, and
690 screen resolution.
691 </p><p>
692 Sane defaults should be used in most cases, but if customisation is
693 necessary you need to create a <code class="filename">machconfig</code> file
694 under <code class="filename">meta/packages/formfactor/files/MACHINENAME/</code>
695 where <code class="literal">MACHINENAME</code> is the name for which this infomation
696 applies. For information about the settings available and the defaults, please see
697 <code class="filename">meta/packages/formfactor/files/config</code>.
698 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-changes"></a>4. Making and Maintaining Changes</h2></div></div></div><p>
699 We recognise that people will want to extend/configure/optimise Poky for
700 their specific uses, especially due to the extreme configurability and
701 flexibility Poky offers. To ensure ease of keeping pace with future
702 changes in Poky we recommend making changes to Poky in a controlled way.
703 </p><p>
704 Poky supports the idea of <a href="#usingpoky-changes-collections" title="4.1. Bitbake Collections">"collections"</a> which when used
705 properly can massively ease future upgrades and allow segregation
706 between the Poky core and a given developer's changes. Some other advice on
707 managing changes to Poky is also given in the following section.
708 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-changes-collections"></a>4.1. Bitbake Collections</h3></div></div></div><p>
709 Often, people want to extend Poky either through adding packages
710 or overriding files contained within Poky to add their own
711 functionality. Bitbake has a powerful mechanism called
712 collections which provide a way to handle this which is fully
713 supported and actively encouraged within Poky.
714 </p><p>
715 In the standard tree, meta-extras is an example of how you can
716 do this. As standard the data in meta-extras is not used on a
717 Poky build but local.conf.sample shows how to enable it:
718 </p><p>
719 </p><pre class="literallayout">
720BBFILES := "${OEROOT}/meta/packages/*/*.bb ${OEROOT}/meta-extras/packages/*/*.bb"
721BBFILE_COLLECTIONS = "normal extras"
722BBFILE_PATTERN_normal = "^${OEROOT}/meta/"
723BBFILE_PATTERN_extras = "^${OEROOT}/meta-extras/"
724BBFILE_PRIORITY_normal = "5"
725BBFILE_PRIORITY_extras = "5"</pre><p>
726 </p><p>
727 As can be seen, the extra recipes are added to BBFILES. The
728 BBFILE_COLLECTIONS variable is then set to contain a list of
729 collection names. The BBFILE_PATTERN variables are regular
730 expressions used to match files from BBFILES into a particular
731 collection in this case by using the base pathname.
732 The BBFILE_PRIORITY variable then assigns the different
733 priorities to the files in different collections. This is useful
734 in situations where the same package might appear in both
735 repositories and allows you to choose which collection should
736 'win'.
737 </p><p>
738 This works well for recipes. For bbclasses and configuration
739 files, you can use the BBPATH environment variable. In this
740 case, the first file with the matching name found in BBPATH is
741 the one that is used, just like the PATH variable for binaries.
742 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-changes-commits"></a>4.2. Committing Changes</h3></div></div></div><p>
743 Modifications to Poky are often managed under some kind of source
744 revision control system. The policy for committing to such systems
745 is important as some simple policy can significantly improve
746 usability. The tips below are based on the policy that OpenedHand
747 uses for commits to Poky.
748 </p><p>
749 It helps to use a consistent style for commit messages when committing
750 changes. We've found a style where the first line of a commit message
751 summarises the change and starts with the name of any package affected
752 work well. Not all changes are to specific packages so the prefix could
753 also be a machine name or class name instead. If a change needs a longer
754 description this should follow the summary.
755 </p><p>
756 Any commit should be self contained in that it should leave the
757 metadata in a consistent state, buildable before and after the
758 commit. This helps ensure the autobuilder test results are valid
759 but is good practice regardless.
760 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-changes-prbump"></a>4.3. Package Revision Incrementing</h3></div></div></div><p>
761 If a committed change will result in changing the package output
762 then the value of the <em class="glossterm"><a href="#var-PR" title="PR">PR</a>
763 </em> variable needs to be increased (commonly referred to
764 as 'bumped') as part of that commit. Only integer values are used
765 and <em class="glossterm"><a href="#var-PR" title="PR">PR</a></em> =
766 "r0" should not be added into new recipes as this is default value.
767 When upgrading the version of a package (<em class="glossterm"><a href="#var-PV" title="PV">PV</a></em>), the <em class="glossterm"><a href="#var-PR" title="PR">PR</a></em> variable should be removed.
768 </p><p>
769 The aim is that the package version will only ever increase. If
770 for some reason <em class="glossterm"><a href="#var-PV" title="PV">PV</a></em>
771 will change and but not increase, the <em class="glossterm"><a href="#var-PE" title="PE">PE</a></em> (Package Epoch) can
772 be increased (it defaults to '0'). The version numbers aim to
773 follow the <a href="http://www.debian.org/doc/debian-policy/ch-controlfields.html" target="_top">
774 Debian Version Field Policy Guidelines</a> which define how
775 versions are compared and hence what "increasing" means.
776 </p><p>
777 There are two reasons for doing this, the first is to ensure that
778 when a developer updates and rebuilds, they get all the changes to
779 the repository and don't have to remember to rebuild any sections.
780 The second is to ensure that target users are able to upgrade their
781 devices via their package manager such as with the <span><strong class="command">
782 ipkg update;ipkg upgrade</strong></span> commands (or similar for
783 dpkg/apt or rpm based systems). The aim is to ensure Poky has
784 upgradable packages in all cases.
785 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-modifing-packages"></a>5. Modifying Package Source Code</h2></div></div></div><p>
786 Poky is usually used to build software rather than modifying
787 it. However, there are ways Poky can be used to modify software.
788 </p><p>
789 During building, the sources are available in <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em> directory.
790 Where exactly this is depends on the type of package and the
791 architecture of target device. For a standard recipe not
792 related to <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a></em> it will be
793 <code class="filename">tmp/work/PACKAGE_ARCH-poky-TARGET_OS/PN-PV-PR/</code>.
794 Target device dependent packages use <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE
795 </a></em>
796 instead of <em class="glossterm"><a href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH
797 </a></em>
798 in the directory name.
799 </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
800 Check the package recipe sets the <em class="glossterm"><a href="#var-S" title="S">S</a></em> variable to something
801 other than standard <code class="filename">WORKDIR/PN-PV/</code> value.
802 </p></div><p>
803 After building a package, a user can modify the package source code
804 without problem. The easiest way to test changes is by calling the
805 "compile" task:
806 </p><pre class="programlisting">
807bitbake --cmd compile --force NAME_OF_PACKAGE
808 </pre><p>
809 Other tasks may also be called this way.
810 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-modifying-packages-quilt"></a>5.1. Modifying Package Source Code with quilt</h3></div></div></div><p>
811 By default Poky uses <a href="http://savannah.nongnu.org/projects/quilt" target="_top">quilt</a>
812 to manage patches in <code class="function">do_patch</code> task.
813 It is a powerful tool which can be used to track all
814 modifications done to package sources.
815 </p><p>
816 Before modifying source code it is important to
817 notify quilt so it will track changes into new patch
818 file:
819 </p><pre class="programlisting">
820quilt new NAME-OF-PATCH.patch
821 </pre><p>
822
823 Then add all files which will be modified into that
824 patch:
825 </p><pre class="programlisting">
826quilt add file1 file2 file3
827 </pre><p>
828
829 Now start editing. At the end quilt needs to be used
830 to generate final patch which will contain all
831 modifications:
832 </p><pre class="programlisting">
833quilt refresh
834 </pre><p>
835
836 The resulting patch file can be found in the
837 <code class="filename">patches/</code> subdirectory of the source
838 (<em class="glossterm"><a href="#var-S" title="S">S</a></em>) directory. For future builds it
839 should be copied into
840 Poky metadata and added into <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em> of a recipe:
841 </p><pre class="programlisting">
842SRC_URI += "file://NAME-OF-PATCH.patch;patch=1"
843 </pre><p>
844
845 This also requires a bump of <em class="glossterm"><a href="#var-PR" title="PR">PR</a></em> value in the same recipe as we changed resulting packages.
846 </p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="platdev"></a>Chapter 4. Platform Development with Poky</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#platdev-appdev">1. Software development</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-appdev-external-anjuta">1.1. Developing externally using the Anjuta Plugin</a></span></dt><dt><span class="section"><a href="#platdev-appdev-external-sdk">1.2. Developing externally using the Poky SDK</a></span></dt><dt><span class="section"><a href="#platdev-appdev-qemu">1.3. Developing externally in QEMU</a></span></dt><dt><span class="section"><a href="#platdev-appdev-chroot">1.4. Developing externally in a chroot</a></span></dt><dt><span class="section"><a href="#platdev-appdev-insitu">1.5. Developing in Poky directly</a></span></dt><dt><span class="section"><a href="#platdev-appdev-devshell">1.6. Developing with 'devshell'</a></span></dt><dt><span class="section"><a href="#platdev-appdev-srcrev">1.7. Developing within Poky with an external SCM based package</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-gdb-remotedebug">2. Debugging with GDB Remotely</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdbserver">2.1. Launching GDBSERVER on the target</a></span></dt><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdb">2.2. Launching GDB on the host computer</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-oprofile">3. Profiling with OProfile</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-oprofile-target">3.1. Profiling on the target</a></span></dt><dt><span class="section"><a href="#platdev-oprofile-oprofileui">3.2. Using OProfileUI</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="platdev-appdev"></a>1. Software development</h2></div></div></div><p>
847 Poky supports several methods of software development. These different
848 forms of development are explained below and can be switched
849 between as needed.
850 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-external-anjuta"></a>1.1. Developing externally using the Anjuta Plugin</h3></div></div></div><p>
851 An Anjuta IDE plugin exists to make developing software within the Poky framework
852 easier for the application developer. It presents a graphical IDE from which the
853 developer can cross compile an application then deploy and execute the output in a QEMU
854 emulation session. It also supports cross debugging and profiling.
855 </p><p>
856 To use the plugin, a toolchain and SDK built by Poky is required along with Anjuta and the Anjuta
857 plugin. The Poky Anjuta plugin is available from the OpenedHand SVN repository located at
858 http://svn.o-hand.com/repos/anjuta-poky/trunk/anjuta-plugin-sdk/; a web interface
859 to the repository can be accessed at <a href="http://svn.o-hand.com/view/anjuta-poky/" target="_top">http://svn.o-hand.com/view/anjuta-poky/</a>.
860 See the README file contained in the project for more information.
861 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-external-sdk"></a>1.2. Developing externally using the Poky SDK</h3></div></div></div><p>
862 The meta-toolchain and meta-toolchain-sdk targets (<a href="#ref-images" title="Appendix 4. Reference: Images">see
863 the images section</a>) build tarballs which contain toolchains and
864 libraries suitable for application development outside Poky. These unpack into the
865 <code class="filename">/usr/local/poky</code> directory and contain
866 a setup script, e.g.
867 <code class="filename">/usr/local/poky/eabi-glibc/arm/environment-setup</code> which
868 can be sourced to initialise a suitable environment. After sourcing this, the
869 compiler, QEMU scripts, QEMU binary, a special version of pkgconfig and other
870 useful utilities are added to the PATH. Variables to assist pkgconfig and
871 autotools are also set so that, for example, configure can find pre-generated test
872 results for tests which need target hardware to run.
873 </p><p>
874 Using the toolchain with autotool enabled packages is straightforward, just pass the
875 appropriate host option to configure e.g. "./configure --host=arm-poky-linux-gnueabi".
876 For other projects it is usually a case of ensuring the cross tools are used e.g.
877 CC=arm-poky-linux-gnueabi-gcc and LD=arm-poky-linux-gnueabi-ld.
878 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-qemu"></a>1.3. Developing externally in QEMU</h3></div></div></div><p>
879 Running Poky QEMU images is covered in the <a href="#intro-quickstart-qemu" title="4.2. Downloading and Using Prebuilt Images">Running an Image</a> section.
880 </p><p>
881 Poky's QEMU images contain a complete native toolchain. This means
882 that applications can be developed within QEMU in the same was as a
883 normal system. Using qemux86 on an x86 machine is fast since the
884 guest and host architectures match, qemuarm is slower but gives
885 faithful emulation of ARM specific issues. To speed things up these
886 images support using distcc to call a cross-compiler outside the
887 emulated system too. If <span><strong class="command">runqemu</strong></span> was used to start
888 QEMU, and distccd is present on the host system, any bitbake cross
889 compiling toolchain available from the build system will automatically
890 be used from within qemu simply by calling distcc
891 (<span><strong class="command">export CC="distcc"</strong></span> can be set in the enviroment).
892 Alterntatively, if a suitable SDK/toolchain is present in
893 <code class="filename">/usr/local/poky</code> it will also
894 automatically be used.
895 </p><p>
896 There are several options for connecting into the emulated system.
897 QEMU provides a framebuffer interface which has standard consoles
898 available. There is also a serial connection available which has a
899 console to the system running on it and IP networking as standard.
900 The images have a dropbear ssh server running with the root password
901 disabled allowing standard ssh and scp commands to work. The images
902 also contain an NFS server exporting the guest's root filesystem
903 allowing that to be made available to the host.
904 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-chroot"></a>1.4. Developing externally in a chroot</h3></div></div></div><p>
905 If you have a system that matches the architecture of the Poky machine you're using,
906 such as qemux86, you can run binaries directly from the image on the host system
907 using a chroot combined with tools like <a href="http://projects.o-hand.com/xephyr" target="_top">Xephyr</a>.
908 </p><p>
909 Poky has some scripts to make using its qemux86 images within a chroot easier. To use
910 these you need to install the poky-scripts package or otherwise obtain the
911 <code class="filename">poky-chroot-setup</code> and <code class="filename">poky-chroot-run</code> scripts.
912 You also need Xephyr and chrootuid binaries available. To initialize a system use the setup script:
913 </p><p>
914 </p><pre class="literallayout">
915# poky-chroot-setup &lt;qemux86-rootfs.tgz&gt; &lt;target-directory&gt;
916</pre><p>
917 </p><p>
918 which will unpack the specified qemux86 rootfs tarball into the target-directory.
919 You can then start the system with:
920 </p><p>
921 </p><pre class="literallayout">
922# poky-chroot-run &lt;target-directory&gt; &lt;command&gt;
923</pre><p>
924 </p><p>
925 where the target-directory is the place the rootfs was unpacked to and command is
926 an optional command to run. If no command is specified, the system will drop you
927 within a bash shell. A Xephyr window will be displayed containing the emulated
928 system and you may be asked for a password since some of the commands used for
929 bind mounting directories need to be run using sudo.
930 </p><p>
931 There are limits as to how far the the realism of the chroot environment extends.
932 It is useful for simple development work or quick tests but full system emulation
933 with QEMU offers a much more realistic environment for more complex development
934 tasks. Note that chroot support within Poky is still experimental.
935 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-insitu"></a>1.5. Developing in Poky directly</h3></div></div></div><p>
936 Working directly in Poky is a fast and effective development technique.
937 The idea is that you can directly edit files in
938 <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em>
939 or the source directory <em class="glossterm"><a href="#var-S" title="S">S</a></em>
940 and then force specific tasks to rerun in order to test the changes.
941 An example session working on the matchbox-desktop package might
942 look like this:
943 </p><p>
944 </p><pre class="literallayout">
945$ bitbake matchbox-desktop
946$ sh
947$ cd tmp/work/armv5te-poky-linux-gnueabi/matchbox-desktop-2.0+svnr1708-r0/
948$ cd matchbox-desktop-2
949$ vi src/main.c
950$ exit
951$ bitbake matchbox-desktop -c compile -f
952$ bitbake matchbox-desktop
953</pre><p>
954 </p><p>
955 Here, we build the package, change into the work directory for the package,
956 change a file, then recompile the package. Instead of using sh like this,
957 you can also use two different terminals. The risk with working like this
958 is that a command like unpack could wipe out the changes you've made to the
959 work directory so you need to work carefully.
960 </p><p>
961 It is useful when making changes directly to the work directory files to do
962 so using quilt as detailed in the <a href="#usingpoky-modifying-packages-quilt" title="5.1. Modifying Package Source Code with quilt">
963 modifying packages with quilt</a> section. The resulting patches can be copied
964 into the recipe directory and used directly in the <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em>.
965 </p><p>
966 For a review of the skills used in this section see Sections <a href="#usingpoky-components-bitbake" title="1.1. Bitbake">2.1.1</a> and <a href="#usingpoky-debugging-taskrunning" title="4.2. Running specific tasks">2.4.2</a>.
967 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-devshell"></a>1.6. Developing with 'devshell'</h3></div></div></div><p>
968 When debugging certain commands or even to just edit packages, the
969 'devshell' can be a useful tool. To start it you run a command like:
970 </p><p>
971 </p><pre class="literallayout">
972$ bitbake matchbox-desktop -c devshell
973</pre><p>
974 </p><p>
975 which will open a terminal with a shell prompt within the Poky
976 environment. This means PATH is setup to include the cross toolchain,
977 the pkgconfig variables are setup to find the right .pc files,
978 configure will be able to find the Poky site files etc. Within this
979 environment, you can run configure or compile command as if they
980 were being run by Poky itself. You are also changed into the
981 source (<em class="glossterm"><a href="#var-S" title="S">S</a></em>)
982 directory automatically. When finished with the shell just exit it
983 or close the terminal window.
984 </p><p>
985 The default shell used by devshell is the gnome-terminal. Other
986 forms of terminal can also be used by setting the <em class="glossterm">
987 <a href="#var-TERMCMD" title="TERMCMD">TERMCMD</a></em> and <em class="glossterm">
988 <a href="#var-TERMCMDRUN" title="TERMCMDRUN">TERMCMDRUN</a></em> variables
989 in local.conf. For examples of the other options available, see
990 <code class="filename">meta/conf/bitbake.conf</code>. An external shell is
991 launched rather than opening directly into the original terminal
992 window to make interaction with bitbakes multiple threads easier
993 and also allow a client/server split of bitbake in the future
994 (devshell will still work over X11 forwarding or similar).
995 </p><p>
996 It is worth remembering that inside devshell you need to use the full
997 compiler name such as <span><strong class="command">arm-poky-linux-gnueabi-gcc</strong></span>
998 instead of just <span><strong class="command">gcc</strong></span> and the same applies to other
999 applications from gcc, bintuils, libtool etc. Poky will have setup
1000 environmental variables such as CC to assist applications, such as make,
1001 find the correct tools.
1002 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-srcrev"></a>1.7. Developing within Poky with an external SCM based package</h3></div></div></div><p>
1003 If you're working on a recipe which pulls from an external SCM it
1004 is possible to have Poky notice new changes added to the
1005 SCM and then build the latest version. This only works for SCMs
1006 where its possible to get a sensible revision number for changes.
1007 Currently it works for svn, git and bzr repositories.
1008 </p><p>
1009 To enable this behaviour it is simply a case of adding <em class="glossterm">
1010 <a href="#var-SRCREV" title="SRCREV">SRCREV</a></em>_pn-<em class="glossterm">
1011 <a href="#var-PN" title="PN">PN</a></em> = "${AUTOREV}" to
1012 local.conf where <em class="glossterm"><a href="#var-PN" title="PN">PN</a></em>
1013 is the name of the package for which you want to enable automatic source
1014 revision updating.
1015 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="platdev-gdb-remotedebug"></a>2. Debugging with GDB Remotely</h2></div></div></div><p>
1016 <a href="http://sourceware.org/gdb/" target="_top">GDB</a> (The GNU Project Debugger)
1017 allows you to examine running programs to understand and fix problems and
1018 also to perform postmortem style analsys of program crashes. It is available
1019 as a package within poky and installed by default in sdk images. It works best
1020 when -dbg packages for the application being debugged are installed as the
1021 extra symbols give more meaningful output from GDB.
1022 </p><p>
1023 Sometimes, due to memory or disk space constraints, it is not possible
1024 to use GDB directly on the remote target to debug applications. This is
1025 due to the fact that
1026 GDB needs to load the debugging information and the binaries of the
1027 process being debugged. GDB then needs to perform many
1028 computations to locate information such as function names, variable
1029 names and values, stack traces, etc. even before starting the debugging
1030 process. This places load on the target system and can alter the
1031 characteristics of the program being debugged.
1032 </p><p>
1033 This is where GDBSERVER comes into play as it runs on the remote target
1034 and does not load any debugging information from the debugged process.
1035 Instead, the debugging information processing is done by a GDB instance
1036 running on a distant computer - the host GDB. The host GDB then sends
1037 control commands to GDBSERVER to make it stop or start the debugged
1038 program, as well as read or write some memory regions of that debugged
1039 program. All the debugging information loading and processing as well
1040 as the heavy debugging duty is done by the host GDB, giving the
1041 GDBSERVER running on the target a chance to remain small and fast.
1042 </p><p>
1043 As the host GDB is responsible for loading the debugging information and
1044 doing the necessary processing to make actual debugging happen, the
1045 user has to make sure it can access the unstripped binaries complete
1046 with their debugging information and compiled with no optimisations. The
1047 host GDB must also have local access to all the libraries used by the
1048 debugged program. On the remote target the binaries can remain stripped
1049 as GDBSERVER does not need any debugging information there. However they
1050 must also be compiled without optimisation matching the host's binaries.
1051 </p><p>
1052 The binary being debugged on the remote target machine is hence referred
1053 to as the 'inferior' in keeping with GDB documentation and terminology.
1054 Further documentation on GDB, is available on
1055 <a href="http://sourceware.org/gdb/documentation/" target="_top">on their site</a>.
1056 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-gdb-remotedebug-launch-gdbserver"></a>2.1. Launching GDBSERVER on the target</h3></div></div></div><p>
1057 First, make sure gdbserver is installed on the target. If not,
1058 install the gdbserver package (which needs the libthread-db1
1059 package).
1060 </p><p>
1061 To launch GDBSERVER on the target and make it ready to "debug" a
1062 program located at <span class="emphasis"><em>/path/to/inferior</em></span>, connect
1063 to the target and launch:
1064 </p><pre class="programlisting">$ gdbserver localhost:2345 /path/to/inferior</pre><p>
1065 After that, gdbserver should be listening on port 2345 for debugging
1066 commands coming from a remote GDB process running on the host computer.
1067 Communication between the GDBSERVER and the host GDB will be done using
1068 TCP. To use other communication protocols please refer to the
1069 GDBSERVER documentation.
1070 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-gdb-remotedebug-launch-gdb"></a>2.2. Launching GDB on the host computer</h3></div></div></div><p>
1071 Running GDB on the host computer takes a number of stages, described in the
1072 following sections.
1073 </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-gdb-remotedebug-launch-gdb-buildcross"></a>2.2.1. Build the cross GDB package</h4></div></div></div><p>
1074 A suitable gdb cross binary is required which runs on your host computer but
1075 knows about the the ABI of the remote target. This can be obtained from
1076 the the Poky toolchain, e.g.
1077 <code class="filename">/usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb</code>
1078 which "arm" is the target architecture and "linux-gnueabi" the target ABI.
1079 </p><p>
1080 Alternatively this can be built directly by Poky. To do this you would build
1081 the gdb-cross package so for example you would run:
1082 </p><pre class="programlisting">bitbake gdb-cross</pre><p>
1083 Once built, the cross gdb binary can be found at
1084 </p><pre class="programlisting">tmp/cross/bin/&lt;target-abi&gt;-gdb </pre><p>
1085 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-gdb-remotedebug-launch-gdb-inferiorbins"></a>2.2.2. Making the inferior binaries available</h4></div></div></div><p>
1086 The inferior binary needs to be available to GDB complete with all debugging
1087 symbols in order to get the best possible results along with any libraries
1088 the inferior depends on and their debugging symbols. There are a number of
1089 ways this can be done.
1090 </p><p>
1091 Perhaps the easiest is to have an 'sdk' image corresponding to the plain
1092 image installed on the device. In the case of 'pky-image-sato',
1093 'poky-image-sdk' would contain suitable symbols. The sdk images already
1094 have the debugging symbols installed so its just a question expanding the
1095 archive to some location and telling GDB where this is.
1096 </p><p>
1097 Alternatively, poky can build a custom directory of files for a specific
1098 debugging purpose by reusing its tmp/rootfs directory, on the host computer
1099 in a slightly different way to normal. This directory contains the contents
1100 of the last built image. This process assumes the image running on the
1101 target was the last image to be built by Poky, the package <span class="emphasis"><em>foo</em></span>
1102 contains the inferior binary to be debugged has been built without without
1103 optimisation and has debugging information available.
1104 </p><p>
1105 Firstly you want to install the <span class="emphasis"><em>foo</em></span> package to tmp/rootfs
1106 by doing:
1107 </p><pre class="programlisting">tmp/staging/i686-linux/usr/bin/ipkg-cl -f \
1108tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/ipkg.conf -o \
1109tmp/rootfs/ update</pre><p>
1110 then,
1111 </p><pre class="programlisting">tmp/staging/i686-linux/usr/bin/ipkg-cl -f \
1112tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/ipkg.conf \
1113-o tmp/rootfs install foo
1114
1115tmp/staging/i686-linux/usr/bin/ipkg-cl -f \
1116tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/ipkg.conf \
1117-o tmp/rootfs install foo-dbg</pre><p>
1118 which installs the debugging information too.
1119 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-gdb-remotedebug-launch-gdb-launchhost"></a>2.2.3. Launch the host GDB</h4></div></div></div><p>
1120 To launch the host GDB, run the cross gdb binary identified above with
1121 the inferior binary specified on the commandline:
1122 </p><pre class="programlisting">&lt;target-abi&gt;-gdb rootfs/usr/bin/foo</pre><p>
1123 This loads the binary of program <span class="emphasis"><em>foo</em></span>
1124 as well as its debugging information. Once the gdb prompt
1125 appears, you must instruct GDB to load all the libraries
1126 of the inferior from tmp/rootfs:
1127 </p><pre class="programlisting">set solib-absolute-prefix /path/to/tmp/rootfs</pre><p>
1128 where <code class="filename">/path/to/tmp/rootfs</code> must be
1129 the absolute path to <code class="filename">tmp/rootfs</code> or wherever the
1130 binaries with debugging information are located.
1131 </p><p>
1132 Now, tell GDB to connect to the GDBSERVER running on the remote target:
1133 </p><pre class="programlisting">target remote remote-target-ip-address:2345</pre><p>
1134 Where remote-target-ip-address is the IP address of the
1135 remote target where the GDBSERVER is running. 2345 is the
1136 port on which the GDBSERVER is running.
1137 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-gdb-remotedebug-launch-gdb-using"></a>2.2.4. Using the Debugger</h4></div></div></div><p>
1138 Debugging can now proceed as normal, as if the debugging were being done on the
1139 local machine, for example to tell GDB to break in the <span class="emphasis"><em>main</em></span>
1140 function, for instance:
1141 </p><pre class="programlisting">break main</pre><p>
1142 and then to tell GDB to "continue" the inferior execution,
1143 </p><pre class="programlisting">continue</pre><p>
1144 </p><p>
1145 For more information about using GDB please see the
1146 project's online documentation at <a href="http://sourceware.org/gdb/download/onlinedocs/" target="_top">http://sourceware.org/gdb/download/onlinedocs/</a>.
1147 </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="platdev-oprofile"></a>3. Profiling with OProfile</h2></div></div></div><p>
1148 <a href="http://oprofile.sourceforge.net/" target="_top">OProfile</a> is a
1149 statistical profiler well suited to finding performance
1150 bottlenecks in both userspace software and the kernel. It provides
1151 answers to questions like "Which functions does my application spend
1152 the most time in when doing X?". Poky is well integrated with OProfile
1153 to make profiling applications on target hardware straightforward.
1154 </p><p>
1155 To use OProfile you need an image with OProfile installed. The easiest
1156 way to do this is with "tools-profile" in <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em>. You also
1157 need debugging symbols to be available on the system where the analysis
1158 will take place. This can be achieved with "dbg-pkgs" in <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em> or by
1159 installing the appropriate -dbg packages. For
1160 successful call graph analysis the binaries must preserve the frame
1161 pointer register and hence should be compiled with the
1162 "-fno-omit-framepointer" flag. In Poky this can be achieved with
1163 <em class="glossterm"><a href="#var-SELECTED_OPTIMIZATION" title="SELECTED_OPTIMIZATION">SELECTED_OPTIMIZATION
1164 </a></em> = "-fexpensive-optimizations -fno-omit-framepointer
1165 -frename-registers -O2" or by setting <em class="glossterm"><a href="#var-DEBUG_BUILD" title="DEBUG_BUILD">DEBUG_BUILD</a></em> = "1" in
1166 local.conf (the latter will also add extra debug information making the
1167 debug packages large).
1168 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-oprofile-target"></a>3.1. Profiling on the target</h3></div></div></div><p>
1169 All the profiling work can be performed on the target device. A
1170 simple OProfile session might look like:
1171 </p><p>
1172 </p><pre class="literallayout">
1173# opcontrol --reset
1174# opcontrol --start --separate=lib --no-vmlinux -c 5
1175[do whatever is being profiled]
1176# opcontrol --stop
1177$ opreport -cl
1178</pre><p>
1179 </p><p>
1180 Here, the reset command clears any previously profiled data,
1181 OProfile is then started. The options used to start OProfile mean
1182 dynamic library data is kept separately per application, kernel
1183 profiling is disabled and callgraphing is enabled up to 5 levels
1184 deep. To profile the kernel, you would specify the
1185 <em class="parameter"><code>--vmlinux=/path/to/vmlinux</code></em> option (the vmlinux file is usually in
1186 <code class="filename">/boot/</code> in Poky and must match the running kernel). The profile is
1187 then stopped and the results viewed with opreport with options
1188 to see the separate library symbols and callgraph information.
1189 </p><p>
1190 Callgraphing means OProfile not only logs infomation about which
1191 functions time is being spent in but also which functions
1192 called those functions (their parents) and which functions that
1193 function calls (its children). The higher the callgraphing depth,
1194 the more accurate the results but this also increased the loging
1195 overhead so it should be used with caution. On ARM, binaries need
1196 to have the frame pointer enabled for callgraphing to work (compile
1197 with the gcc option -fno-omit-framepointer).
1198 </p><p>
1199 For more information on using OProfile please see the OProfile
1200 online documentation at <a href="http://oprofile.sourceforge.net/docs/" target="_top">http://oprofile.sourceforge.net/docs/</a>.
1201 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-oprofile-oprofileui"></a>3.2. Using OProfileUI</h3></div></div></div><p>
1202 A graphical user interface for OProfile is also available. You can
1203 either use prebuilt Debian packages from the <a href="http://debian.o-hand.com/" target="_top">OpenedHand repository</a> or
1204 download and build from svn at
1205 http://svn.o-hand.com/repos/oprofileui/trunk/. If the
1206 "tools-profile" image feature is selected, all necessary binaries
1207 are installed onto the target device for OProfileUI interaction.
1208 </p><p>
1209 In order to convert the data in the sample format from the target
1210 to the host the <code class="filename">opimport</code> program is needed.
1211 This is not included in standard Debian OProfile packages but an
1212 OProfile package with this addition is also available from the <a href="http://debian.o-hand.com/" target="_top">OpenedHand repository</a>.
1213 We recommend using OProfile 0.9.3 or greater. Other patches to
1214 OProfile may be needed for recent OProfileUI features, but Poky
1215 usually includes all needed patches on the target device. Please
1216 see the <a href="http://svn.o-hand.com/repos/oprofileui/trunk/README" target="_top">
1217 OProfileUI README</a> for up to date information, and the
1218 <a href="http://labs.o-hand.com/oprofileui" target="_top">OProfileUI website
1219 </a> for more information on the OProfileUI project.
1220 </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-oprofile-oprofileui-online"></a>3.2.1. Online mode</h4></div></div></div><p>
1221 This assumes a working network connection with the target
1222 hardware. In this case you just need to run <span><strong class="command">
1223 "oprofile-server"</strong></span> on the device. By default it listens
1224 on port 4224. This can be changed with the <em class="parameter"><code>--port</code></em> command line
1225 option.
1226
1227 </p><p>
1228 The client program is called <span><strong class="command">oprofile-viewer</strong></span>. The
1229 UI is relatively straightforward, the key functionality is accessed
1230 through the buttons on the toolbar (which are duplicated in the
1231 menus.) These buttons are:
1232 </p><div class="itemizedlist"><ul type="disc"><li><p>
1233 Connect - connect to the remote host, the IP address or hostname for the
1234 target can be supplied here.
1235 </p></li><li><p>
1236 Disconnect - disconnect from the target.
1237 </p></li><li><p>
1238 Start - start the profiling on the device.
1239 </p></li><li><p>
1240 Stop - stop the profiling on the device and download the data to the local
1241 host. This will generate the profile and show it in the viewer.
1242 </p></li><li><p>
1243 Download - download the data from the target, generate the profile and show it
1244 in the viewer.
1245 </p></li><li><p>
1246 Reset - reset the sample data on the device. This will remove the sample
1247 information that was collected on a previous sampling run. Ensure you do this
1248 if you do not want to include old sample information.
1249 </p></li><li><p>
1250 Save - save the data downloaded from the target to another directory for later
1251 examination.
1252 </p></li><li><p>
1253 Open - load data that was previously saved.
1254 </p></li></ul></div><p>
1255 The behaviour of the client is to download the complete 'profile archive' from
1256 the target to the host for processing. This archive is a directory containing
1257 the sample data, the object files and the debug information for said object
1258 files. This archive is then converted using a script included in this
1259 distribution ('oparchconv') that uses 'opimport' to convert the archive from
1260 the target to something that can be processed on the host.
1261 </p><p>
1262 Downloaded archives are kept in /tmp and cleared up when they are no longer in
1263 use.
1264 </p><p>
1265 If you wish to profile into the kernel, this is possible, you just need to ensure
1266 a vmlinux file matching the running kernel is available. In Poky this is usually
1267 located in /boot/vmlinux-KERNELVERSION, where KERNEL-version is the version of
1268 the kernel e.g. 2.6.23. Poky generates separate vmlinux packages for each kernel
1269 it builds so it should be a question of just ensuring a matching package is
1270 installed (<span><strong class="command"> ipkg install kernel-vmlinux</strong></span>. These are automatically
1271 installed into development and profiling images alongside OProfile. There is a
1272 configuration option within the OProfileUI settings page where the location of
1273 the vmlinux file can be entered.
1274 </p><p>
1275 Waiting for debug symbols to transfer from the device can be slow and it's not
1276 always necessary to actually have them on device for OProfile use. All that is
1277 needed is a copy of the filesystem with the debug symbols present on the viewer
1278 system. The <a href="#platdev-gdb-remotedebug-launch-gdb" title="2.2. Launching GDB on the host computer">GDB remote debug
1279 section</a> covers how to create such a directory with Poky and the location
1280 of this directory can again be specified in the OProfileUI settings dialog. If
1281 specified, it will be used where the file checksums match those on the system
1282 being profiled.
1283 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-oprofile-oprofileui-offline"></a>3.2.2. Offline mode</h4></div></div></div><p>
1284 If no network access to the target is available an archive for processing in
1285 'oprofile-viewer' can be generated with the following set of command.
1286 </p><p>
1287 </p><pre class="literallayout">
1288# opcontrol --reset
1289# opcontrol --start --separate=lib --no-vmlinux -c 5
1290[do whatever is being profiled]
1291# opcontrol --stop
1292# oparchive -o my_archive
1293</pre><p>
1294 </p><p>
1295 Where my_archive is the name of the archive directory where you would like the
1296 profile archive to be kept. The directory will be created for you. This can
1297 then be copied to another host and loaded using 'oprofile-viewer''s open
1298 functionality. The archive will be converted if necessary.
1299 </p></div></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-structure"></a>Appendix 1. Reference: Directory Structure</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#structure-core">1. Top level core components</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core-bitbake">1.1. <code class="filename">bitbake/</code></a></span></dt><dt><span class="section"><a href="#structure-core-build">1.2. <code class="filename">build/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta">1.3. <code class="filename">meta/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-extras">1.4. <code class="filename">meta-extras/</code></a></span></dt><dt><span class="section"><a href="#structure-core-scripts">1.5. <code class="filename">scripts/</code></a></span></dt><dt><span class="section"><a href="#structure-core-sources">1.6. <code class="filename">sources/</code></a></span></dt><dt><span class="section"><a href="#structure-core-script">1.7. <code class="filename">poky-init-build-env</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-build">2. <code class="filename">build/</code> - The Build Directory</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-build-conf-local.conf">2.1. <code class="filename">build/conf/local.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp">2.2. <code class="filename">build/tmp/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cache">2.3. <code class="filename">build/tmp/cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cross">2.4. <code class="filename">build/tmp/cross/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy">2.5. <code class="filename">build/tmp/deploy/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-deb">2.6. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-images">2.7. <code class="filename">build/tmp/deploy/images/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-ipk">2.8. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-rootfs">2.9. <code class="filename">build/tmp/rootfs/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-staging">2.10. <code class="filename">build/tmp/staging/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-stamps">2.11. <code class="filename">build/tmp/stamps/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-work">2.12. <code class="filename">build/tmp/work/</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-meta">3. <code class="filename">meta/</code> - The Metadata</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-meta-classes">3.1. <code class="filename">meta/classes/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf">3.2. <code class="filename">meta/conf/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-machine">3.3. <code class="filename">meta/conf/machine/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-distro">3.4. <code class="filename">meta/conf/distro/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-packages">3.5. <code class="filename">meta/packages/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-site">3.6. <code class="filename">meta/site/</code></a></span></dt></dl></dd></dl></div><p>
1300 Poky consists of several components and understanding what these are
1301 and where they're located is one of the keys to using it. This section walks
1302 through the Poky directory structure giving information about the various
1303 files and directories.
1304</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="structure-core"></a>1. Top level core components</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-bitbake"></a>1.1. <code class="filename">bitbake/</code></h3></div></div></div><p>
1305 A copy of BitBake is included within Poky for ease of use, and should
1306 usually match the current BitBake stable release from the BitBake project.
1307 Bitbake, a metadata interpreter, reads the Poky metadata and runs the tasks
1308 defined in the Poky metadata. Failures are usually from the metadata, not
1309 BitBake itself, so most users don't need to worry about BitBake. The
1310 <code class="filename">bitbake/bin/</code> directory is placed
1311 into the PATH environment variable by the <a href="#structure-core-script" title="1.7. poky-init-build-env">poky-init-build-env</a> script.
1312 </p><p>
1313 For more information on BitBake please see the BitBake project site at
1314 <a href="http://bitbake.berlios.de/" target="_top">http://bitbake.berlios.de/</a>
1315 and the BitBake on-line manual at <a href="http://bitbake.berlios.de/manual/" target="_top">http://bitbake.berlios.de/manual/</a>.
1316 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-build"></a>1.2. <code class="filename">build/</code></h3></div></div></div><p>
1317 This directory contains user configuration files and the output
1318 from Poky.
1319 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-meta"></a>1.3. <code class="filename">meta/</code></h3></div></div></div><p>
1320 This directory contains the core metadata, a key part of Poky. Within this
1321 directory there are definitions of the machines, the Poky distribution
1322 and the packages that make up a given system.
1323 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-meta-extras"></a>1.4. <code class="filename">meta-extras/</code></h3></div></div></div><p>
1324 This directory is similar to <code class="filename">meta/</code>,
1325 and contains some extra metadata not included in standard Poky. These are
1326 disabled by default, and are not supported as part of Poky.
1327 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-scripts"></a>1.5. <code class="filename">scripts/</code></h3></div></div></div><p>
1328 This directory contains various integration scripts which implement
1329 extra functionality in the Poky environment, such as the QEMU
1330 scripts. This directory is appended to the PATH environment variable by the
1331 <a href="#structure-core-script" title="1.7. poky-init-build-env">poky-init-build-env</a> script.
1332 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-sources"></a>1.6. <code class="filename">sources/</code></h3></div></div></div><p>
1333 While not part of a checkout, Poky will create this directory as
1334 part of any build. Any downloads are placed in this directory (as
1335 specified by the <em class="glossterm"><a href="#var-DL_DIR" title="DL_DIR">DL_DIR</a>
1336 </em> variable). This directory can be shared between Poky
1337 builds to save downloading files multiple times. SCM checkouts are
1338 also stored here as e.g. <code class="filename">sources/svn/
1339 </code>, <code class="filename">sources/cvs/</code> or
1340 <code class="filename">sources/git/</code> and the
1341 sources directory may contain archives of checkouts for various
1342 revisions or dates.
1343 </p><p>
1344 It's worth noting that BitBake creates <code class="filename">.md5
1345 </code> stamp files for downloads. It uses these to mark downloads as
1346 complete as well as for checksum and access accounting purposes. If you add
1347 a file manually to the directory, you need to touch the corresponding
1348 <code class="filename">.md5</code> file too.
1349 </p><p>
1350 This location can be overridden by setting <em class="glossterm"><a href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></em> in <code class="filename">local.conf
1351 </code>. This directory can be shared between builds and even between
1352 machines via NFS, so downloads are only made once, speeding up builds.
1353 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-script"></a>1.7. <code class="filename">poky-init-build-env</code></h3></div></div></div><p>
1354 This script is used to setup the Poky build environment. Sourcing this file in
1355 a shell makes changes to PATH and sets other core BitBake variables based on the
1356 current working directory. You need to use this before running Poky commands.
1357 Internally it uses scripts within the <code class="filename">scripts/
1358 </code> directory to do the bulk of the work.
1359 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="structure-build"></a>2. <code class="filename">build/</code> - The Build Directory</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-conf-local.conf"></a>2.1. <code class="filename">build/conf/local.conf</code></h3></div></div></div><p>
1360 This file contains all the local user configuration of Poky. If there
1361 is no <code class="filename">local.conf</code> present, it is created from
1362 <code class="filename">local.conf.sample</code>. The <code class="filename">local.conf</code>
1363 file contains documentation on the various configuration options. Any
1364 variable set here overrides any variable set elsewhere within Poky unless
1365 that variable is hardcoded within Poky (e.g. by using '=' instead of '?=').
1366 Some variables are hardcoded for various reasons but these variables are
1367 relatively rare.
1368 </p><p>
1369 Edit this file to set the <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a></em> for which you want to build, which package types you
1370 wish to use (PACKAGE_CLASSES) or where downloaded files should go
1371 (<em class="glossterm"><a href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></em>).
1372 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp"></a>2.2. <code class="filename">build/tmp/</code></h3></div></div></div><p>
1373 This is created by BitBake if it doesn't exist and is where all the Poky output
1374 is placed. To clean Poky and start a build from scratch (other than downloads),
1375 you can wipe this directory. The <code class="filename">tmp/
1376 </code> directory has some important sub-components detailed below.
1377 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-cache"></a>2.3. <code class="filename">build/tmp/cache/</code></h3></div></div></div><p>
1378 When BitBake parses the metadata it creates a cache file of the result which can
1379 be used when subsequently running commands. These are stored here on
1380 a per machine basis.
1381 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-cross"></a>2.4. <code class="filename">build/tmp/cross/</code></h3></div></div></div><p>
1382 The cross compiler when generated is placed into this directory and those
1383 beneath it.
1384 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-deploy"></a>2.5. <code class="filename">build/tmp/deploy/</code></h3></div></div></div><p>Any 'end result' output from Poky is placed under here.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-deploy-deb"></a>2.6. <code class="filename">build/tmp/deploy/deb/</code></h3></div></div></div><p>
1385 Any .deb packages emitted by Poky are placed here, sorted into feeds for
1386 different architecture types.
1387 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-deploy-images"></a>2.7. <code class="filename">build/tmp/deploy/images/</code></h3></div></div></div><p>
1388 Complete filesystem images are placed here. If you want to flash the resulting
1389 image from a build onto a device, look here for them.
1390 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-deploy-ipk"></a>2.8. <code class="filename">build/tmp/deploy/ipk/</code></h3></div></div></div><p>Any resulting .ipk packages emitted by Poky are placed here.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-rootfs"></a>2.9. <code class="filename">build/tmp/rootfs/</code></h3></div></div></div><p>
1391 This is a temporary scratch area used when creating filesystem images. It is run
1392 under fakeroot and is not useful once that fakeroot session has ended as
1393 information is lost. It is left around since it is still useful in debugging
1394 image creation problems.
1395 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-staging"></a>2.10. <code class="filename">build/tmp/staging/</code></h3></div></div></div><p>
1396 Any package needing to share output with other packages does so within staging.
1397 This means it contains any shared header files and any shared libraries amongst
1398 other data. It is subdivided by architecture so multiple builds can run within
1399 the one build directory.
1400 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-stamps"></a>2.11. <code class="filename">build/tmp/stamps/</code></h3></div></div></div><p>
1401 This is used by BitBake for accounting purposes to keep track of which tasks
1402 have been run and when. It is also subdivided by architecture. The files are
1403 empty and the important information is the filenames and timestamps.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-work"></a>2.12. <code class="filename">build/tmp/work/</code></h3></div></div></div><p>
1404 This directory contains various subdirectories for each architecture, and each package built by BitBake has its own work directory under the appropriate architecture subdirectory. All tasks are executed from this work directory. As an example, the source for a particular package will be unpacked, patched, configured and compiled all within its own work directory.
1405 </p><p>
1406 It is worth considering the structure of a typical work directory. An
1407 example is the linux-rp kernel, version 2.6.20 r7 on the machine spitz
1408 built within Poky. For this package a work directory of <code class="filename">tmp/work/spitz-poky-linux-gnueabi/linux-rp-2.6.20-r7/
1409 </code>, referred to as <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR
1410 </a></em>, is created. Within this directory, the source is
1411 unpacked to linux-2.6.20 and then patched by quilt (see <a href="#usingpoky-modifying-packages-quilt" title="5.1. Modifying Package Source Code with quilt">Section 3.5.1</a>).
1412 Within the <code class="filename">linux-2.6.20</code> directory,
1413 standard Quilt directories <code class="filename">linux-2.6.20/patches</code>
1414 and <code class="filename">linux-2.6.20/.pc</code> are created,
1415 and standard quilt commands can be used.
1416 </p><p>
1417 There are other directories generated within <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em>. The most important
1418 is <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em><code class="filename">/temp/</code> which has log files for each
1419 task (<code class="filename">log.do_*.pid</code>) and the scripts BitBake runs for
1420 each task (<code class="filename">run.do_*.pid</code>). The <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em><code class="filename">/image/</code> directory is where <span><strong class="command">make
1421 install</strong></span> places its output which is then split into subpackages
1422 within <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em><code class="filename">/install/</code>.
1423 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="structure-meta"></a>3. <code class="filename">meta/</code> - The Metadata</h2></div></div></div><p>
1424 As mentioned previously, this is the core of Poky. It has several
1425 important subdivisions:
1426 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-classes"></a>3.1. <code class="filename">meta/classes/</code></h3></div></div></div><p>
1427 Contains the <code class="filename">*.bbclass</code> files. Class
1428 files are used to abstract common code allowing it to be reused by multiple
1429 packages. The <code class="filename">base.bbclass</code> file is inherited by every
1430 package. Examples of other important classes are
1431 <code class="filename">autotools.bbclass</code> that in theory allows any
1432 Autotool-enabled package to work with Poky with minimal effort, or
1433 <code class="filename">kernel.bbclass</code> that contains common code and functions
1434 for working with the linux kernel. Functions like image generation or
1435 packaging also have their specific class files (<code class="filename">image.bbclass
1436 </code>, <code class="filename">rootfs_*.bbclass</code> and
1437 <code class="filename">package*.bbclass</code>).
1438 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-conf"></a>3.2. <code class="filename">meta/conf/</code></h3></div></div></div><p>
1439 This is the core set of configuration files which start from
1440 <code class="filename">bitbake.conf</code> and from which all other configuration
1441 files are included (see the includes at the end of the file, even
1442 <code class="filename">local.conf</code> is loaded from there!). While
1443 <code class="filename">bitbake.conf</code> sets up the defaults, these can often be
1444 overridden by user (<code class="filename">local.conf</code>), machine or
1445 distribution configuration files.
1446 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-conf-machine"></a>3.3. <code class="filename">meta/conf/machine/</code></h3></div></div></div><p>
1447 Contains all the machine configuration files. If you set MACHINE="spitz", the
1448 end result is Poky looking for a <code class="filename">spitz.conf</code> file in this directory. The includes
1449 directory contains various data common to multiple machines. If you want to add
1450 support for a new machine to Poky, this is the directory to look in.
1451 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-conf-distro"></a>3.4. <code class="filename">meta/conf/distro/</code></h3></div></div></div><p>
1452 Any distribution specific configuration is controlled from here. OpenEmbedded
1453 supports multiple distributions of which Poky is one. Poky only contains the
1454 Poky distribution so poky.conf is the main file here. This includes the
1455 versions and SRCDATES for applications which are configured here. An example of
1456 an alternative configuration is poky-bleeding.conf although this mainly inherits
1457 its configuration from Poky itself.
1458 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-packages"></a>3.5. <code class="filename">meta/packages/</code></h3></div></div></div><p>
1459 Each application (package) Poky can build has an associated .bb file which are
1460 all stored under this directory. Poky finds them through the BBFILES variable
1461 which defaults to packages/*/*.bb. Adding a new piece of software to Poky
1462 consists of adding the appropriate .bb file. The .bb files from OpenEmbedded
1463 upstream are usually compatible although they are not supported.
1464 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-site"></a>3.6. <code class="filename">meta/site/</code></h3></div></div></div><p>
1465 Certain autoconf test results cannot be determined when cross compiling since it
1466 can't run tests on a live system. This directory therefore contains a list of
1467 cached results for various architectures which is passed to autoconf.
1468 </p></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-bitbake"></a>Appendix 2. Reference: Bitbake</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref-bitbake-parsing">1. Parsing</a></span></dt><dt><span class="section"><a href="#ref-bitbake-providers">2. Preferences and Providers</a></span></dt><dt><span class="section"><a href="#ref-bitbake-dependencies">3. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-bitbake-tasklist">4. The Task List</a></span></dt><dt><span class="section"><a href="#ref-bitbake-runtask">5. Running a Task</a></span></dt><dt><span class="section"><a href="#ref-bitbake-commandline">6. Commandline</a></span></dt><dt><span class="section"><a href="#ref-bitbake-fetchers">7. Fetchers</a></span></dt></dl></div><p>
1469 Bitbake a program written in Python which interprets the metadata
1470 that makes up Poky. At some point, people wonder what actually happens
1471 when you type <span><strong class="command">bitbake poky-image-sato</strong></span>. This section
1472 aims to give an overview of what happens behind the scenes from a
1473 BitBake perspective.
1474 </p><p>
1475 It is worth noting that bitbake aims to be a generic "task" executor
1476 capable of handling complex dependency relationships. As such it has no
1477 real knowledge of what the tasks its executing actually do. It just
1478 considers a list of tasks with dependencies and handles metadata
1479 consisting of variables in a certain format which get passed to the
1480 tasks.
1481 </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-parsing"></a>1. Parsing</h2></div></div></div><p>
1482 The first thing BitBake does is work out its configuration by
1483 looking for a file called <code class="filename">bitbake.conf</code>.
1484 Bitbake searches through the <code class="varname">BBPATH</code> environment
1485 variable looking for a <code class="filename">conf/</code>
1486 directory containing a <code class="filename">bitbake.conf</code> file and
1487 adds the first <code class="filename">bitbake.conf</code> file found in
1488 <code class="varname">BBPATH</code> (similar to the PATH environment variable).
1489 For Poky, <code class="filename">bitbake.conf</code> is found in <code class="filename">meta/conf/</code>.
1490 </p><p>
1491 In Poky, <code class="filename">bitbake.conf</code> lists other configuration
1492 files to include from a <code class="filename">conf/</code>
1493 directory below the directories listed in <code class="varname">BBPATH</code>.
1494 In general the most important configuration file from a user's perspective
1495 is <code class="filename">local.conf</code>, which contains a users customized
1496 settings for Poky. Other notable configuration files are the distribution
1497 configuration file (set by the <em class="glossterm"><a href="#var-DISTRO" title="DISTRO">
1498 DISTRO</a></em> variable) and the machine configuration file
1499 (set by the <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a>
1500 </em> variable). The <em class="glossterm"><a href="#var-DISTRO" title="DISTRO">
1501 DISTRO</a></em> and <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">
1502 MACHINE</a></em> environment variables are both usually set in
1503 the <code class="filename">local.conf</code> file. Valid distribution
1504 configuration files are available in the <code class="filename">
1505 meta/conf/distro/</code> directory and valid machine configuration
1506 files in the <code class="filename">meta/conf/machine/</code>
1507 directory. Within the <code class="filename">
1508 meta/conf/machine/include/</code> directory are various <code class="filename">
1509 tune-*.inc</code> configuration files which provide common
1510 "tuning" settings specific to and shared between particular
1511 architectures and machines.
1512 </p><p>
1513 After the parsing of the configuration files some standard classes
1514 are included. In particular, <code class="filename">base.bbclass</code> is
1515 always included, as will any other classes
1516 specified in the configuration using the <em class="glossterm"><a href="#var-INHERIT" title="INHERIT">INHERIT</a></em>
1517 variable. Class files are searched for in a classes subdirectory
1518 under the paths in <code class="varname">BBPATH</code> in the same way as
1519 configuration files.
1520 </p><p>
1521 After the parsing of the configuration files is complete, the
1522 variable <em class="glossterm"><a href="#var-BBFILES" title="BBFILES">BBFILES</a></em>
1523 is set, usually in
1524 <code class="filename">local.conf</code>, and defines the list of places to search for
1525 <code class="filename">.bb</code> files. By
1526 default this specifies the <code class="filename">meta/packages/
1527 </code> directory within Poky, but other directories such as
1528 <code class="filename">meta-extras/</code> can be included
1529 too. If multiple directories are specified a system referred to as
1530 <a href="#usingpoky-changes-collections" title="4.1. Bitbake Collections">"collections"</a> is used to
1531 determine which files have priority.
1532 </p><p>
1533 Bitbake parses each <code class="filename">.bb</code> file in
1534 <em class="glossterm"><a href="#var-BBFILES" title="BBFILES">BBFILES</a></em> and
1535 stores the values of various variables. In summary, for each
1536 <code class="filename">.bb</code>
1537 file the configuration + base class of variables are set, followed
1538 by the data in the <code class="filename">.bb</code> file
1539 itself, followed by any inherit commands that
1540 <code class="filename">.bb</code> file might contain.
1541 </p><p>
1542 Parsing <code class="filename">.bb</code> files is a time
1543 consuming process, so a cache is kept to speed up subsequent parsing.
1544 This cache is invalid if the timestamp of the <code class="filename">.bb</code>
1545 file itself has changed, or if the timestamps of any of the include,
1546 configuration or class files the <code class="filename">.bb</code>
1547 file depends on have changed.
1548 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-providers"></a>2. Preferences and Providers</h2></div></div></div><p>
1549 Once all the <code class="filename">.bb</code> files have been
1550 parsed, BitBake will proceed to build "poky-image-sato" (or whatever was
1551 specified on the commandline) and looks for providers of that target.
1552 Once a provider is selected, BitBake resolves all the dependencies for
1553 the target. In the case of "poky-image-sato", it would lead to
1554 <code class="filename">task-oh.bb</code> and <code class="filename">task-base.bb</code>
1555 which in turn would lead to packages like <span class="application">Contacts</span>,
1556 <span class="application">Dates</span>, <span class="application">BusyBox</span>
1557 and these in turn depend on glibc and the toolchain.
1558 </p><p>
1559 Sometimes a target might have multiple providers and a common example
1560 is "virtual/kernel" that is provided by each kernel package. Each machine
1561 will often elect the best provider of its kernel with a line like the
1562 following in the machine configuration file:
1563 </p><pre class="programlisting"><em class="glossterm"><a href="#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">PREFERRED_PROVIDER</a></em>_virtual/kernel = "linux-rp"</pre><p>
1564 The default <em class="glossterm"><a href="#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">
1565 PREFERRED_PROVIDER</a></em> is the provider with the same name as
1566 the target.
1567 </p><p>
1568 Understanding how providers are chosen is complicated by the fact
1569 multiple versions might be present. Bitbake defaults to the highest
1570 version of a provider by default. Version comparisons are made using
1571 the same method as Debian. The <em class="glossterm"><a href="#var-PREFERRED_VERSION" title="PREFERRED_VERSION">PREFERRED_VERSION</a></em>
1572 variable can be used to specify a particular version
1573 (usually in the distro configuration) but the order can
1574 also be influenced by the <em class="glossterm"><a href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></em>
1575 variable. By default files
1576 have a preference of "0". Setting the
1577 <em class="glossterm"><a href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></em> to "-1" will
1578 make a package unlikely to be used unless it was explicitly referenced and
1579 "1" makes it likely the package will be used.
1580 <em class="glossterm"><a href="#var-PREFERRED_VERSION" title="PREFERRED_VERSION">PREFERRED_VERSION</a></em> overrides
1581 any default preference. <em class="glossterm"><a href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></em>
1582 is often used to mark more
1583 experimental new versions of packages until they've undergone sufficient
1584 testing to be considered stable.
1585 </p><p>
1586 The end result is that internally, BitBake has now built a list of
1587 providers for each target it needs in order of priority.
1588 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-dependencies"></a>3. Dependencies</h2></div></div></div><p>
1589 Each target BitBake builds consists of multiple tasks (e.g. fetch,
1590 unpack, patch, configure, compile etc.). For best performance on
1591 multi-core systems, BitBake considers each task as an independent
1592 entity with a set of dependencies. There are many variables that
1593 are used to signify these dependencies and more information can be found
1594 found about these in the <a href="http://bitbake.berlios.de/manual/" target="_top">
1595 BitBake manual</a>. At a basic level it is sufficient to know
1596 that BitBake uses the <em class="glossterm"><a href="#var-DEPENDS" title="DEPENDS">DEPENDS</a></em> and
1597 <em class="glossterm"><a href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></em> variables when
1598 calculating dependencies and descriptions of these variables are
1599 available through the links.
1600 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-tasklist"></a>4. The Task List</h2></div></div></div><p>
1601 Based on the generated list of providers and the dependency information,
1602 BitBake can now calculate exactly which tasks it needs to run and in what
1603 order. The build now starts with BitBake forking off threads up to
1604 the limit set in the <em class="glossterm"><a href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a></em> variable
1605 as long there are tasks ready to run, i.e. tasks with all their
1606 dependencies met.
1607 </p><p>
1608 As each task completes, a timestamp is written to the directory
1609 specified by the <em class="glossterm"><a href="#var-STAMPS" title="STAMPS">STAMPS</a></em> variable (usually
1610 <code class="filename">build/tmp/stamps/*/</code>). On
1611 subsequent runs, BitBake looks at the <em class="glossterm"><a href="#var-STAMPS" title="STAMPS">STAMPS</a></em>
1612 directory and will not rerun
1613 tasks its already completed unless a timestamp is found to be invalid.
1614 Currently, invalid timestamps are only considered on a per <code class="filename">.bb</code> file basis so if for example the configure stamp has a timestamp greater than the
1615 compile timestamp for a given target the compile task would rerun but this
1616 has no effect on other providers depending on that target. This could
1617 change or become configurable in future versions of BitBake. Some tasks
1618 are marked as "nostamp" tasks which means no timestamp file will be written
1619 and the task will always rerun.
1620 </p><p>Once all the tasks have been completed BitBake exits.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-runtask"></a>5. Running a Task</h2></div></div></div><p>
1621 It's worth noting what BitBake does to run a task. A task can either
1622 be a shell task or a python task. For shell tasks, BitBake writes a
1623 shell script to <code class="filename">${WORKDIR}/temp/run.do_taskname.pid</code>
1624 and then executes the script. The generated
1625 shell script contains all the exported variables, and the shell functions
1626 with all variables expanded. Output from the shell script is
1627 sent to the file <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>.
1628 Looking at the
1629 expanded shell functions in the run file and the output in the log files
1630 is a useful debugging technique.
1631 </p><p>
1632 Python functions are executed internally to BitBake itself and
1633 logging goes to the controlling terminal. Future versions of BitBake will
1634 write the functions to files in a similar way to shell functions and
1635 logging will also go to the log files in a similar way.
1636 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-commandline"></a>6. Commandline</h2></div></div></div><p>
1637 To quote from "bitbake --help":
1638 </p><pre class="screen">Usage: bitbake [options] [package ...]
1639
1640Executes the specified task (default is 'build') for a given set of BitBake files.
1641It expects that BBFILES is defined, which is a space separated list of files to
1642be executed. BBFILES does support wildcards.
1643Default BBFILES are the .bb files in the current directory.
1644
1645Options:
1646 --version show program's version number and exit
1647 -h, --help show this help message and exit
1648 -b BUILDFILE, --buildfile=BUILDFILE
1649 execute the task against this .bb file, rather than a
1650 package from BBFILES.
1651 -k, --continue continue as much as possible after an error. While the
1652 target that failed, and those that depend on it,
1653 cannot be remade, the other dependencies of these
1654 targets can be processed all the same.
1655 -f, --force force run of specified cmd, regardless of stamp status
1656 -i, --interactive drop into the interactive mode also called the BitBake
1657 shell.
1658 -c CMD, --cmd=CMD Specify task to execute. Note that this only executes
1659 the specified task for the providee and the packages
1660 it depends on, i.e. 'compile' does not implicitly call
1661 stage for the dependencies (IOW: use only if you know
1662 what you are doing). Depending on the base.bbclass a
1663 listtasks tasks is defined and will show available
1664 tasks
1665 -r FILE, --read=FILE read the specified file before bitbake.conf
1666 -v, --verbose output more chit-chat to the terminal
1667 -D, --debug Increase the debug level. You can specify this more
1668 than once.
1669 -n, --dry-run don't execute, just go through the motions
1670 -p, --parse-only quit after parsing the BB files (developers only)
1671 -d, --disable-psyco disable using the psyco just-in-time compiler (not
1672 recommended)
1673 -s, --show-versions show current and preferred versions of all packages
1674 -e, --environment show the global or per-package environment (this is
1675 what used to be bbread)
1676 -g, --graphviz emit the dependency trees of the specified packages in
1677 the dot syntax
1678 -I IGNORED_DOT_DEPS, --ignore-deps=IGNORED_DOT_DEPS
1679 Stop processing at the given list of dependencies when
1680 generating dependency graphs. This can help to make
1681 the graph more appealing
1682 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
1683 Show debug logging for the specified logging domains
1684 -P, --profile profile the command and print a report</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-fetchers"></a>7. Fetchers</h2></div></div></div><p>
1685 As well as the containing the parsing and task/dependency handling
1686 code, bitbake also contains a set of "fetcher" modules which allow
1687 fetching of source code from various types of sources. Example
1688 sources might be from disk with the metadata, from websites, from
1689 remote shell accounts or from SCM systems like cvs/subversion/git.
1690 </p><p>
1691 The fetchers are usually triggered by entries in
1692 <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em>. Information about the
1693 options and formats of entries for specific fetchers can be found in the
1694 <a href="http://bitbake.berlios.de/manual/" target="_top">BitBake manual</a>.
1695 </p><p>
1696 One useful feature for certain SCM fetchers is the ability to
1697 "auto-update" when the upstream SCM changes version. Since this
1698 requires certain functionality from the SCM only certain systems
1699 support it, currently Subversion, Bazaar and to a limited extent, Git. It
1700 works using the <em class="glossterm"><a href="#var-SRCREV" title="SRCREV">SRCREV</a>
1701 </em> variable. See the <a href="#platdev-appdev-srcrev" title="1.7. Developing within Poky with an external SCM based package">
1702 developing with an external SCM based project</a> section for more
1703 information.
1704 </p></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-classes"></a>Appendix 3. Reference: Classes</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref-classes-base">1. The base class - <code class="filename">base.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-autotools">2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-alternatives">3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-rc.d">4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-binconfig">5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-debian">6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-pkgconfig">7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-src-distribute">8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-perl">9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-distutils">10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-devshell">11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-package">12. Packaging - <code class="filename">package*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-kernel">13. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-image">14. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-sanity">15. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-insane">16. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-siteinfo">17. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-others">18. Other Classes</a></span></dt></dl></div><p>
1705 Class files are used to abstract common functionality and share it amongst multiple
1706 <code class="filename">.bb</code> files. Any metadata usually found in a
1707 <code class="filename">.bb</code> file can also be placed in a class
1708 file. Class files are identified by the extension
1709 <code class="filename">.bbclass</code> and are usually placed
1710 in a <code class="filename">classes/</code> directory beneath the
1711 <code class="filename">meta/</code> directory or the <code class="filename">build/</code> directory in the same way as <code class="filename">.conf</code> files in the <code class="filename">conf</code> directory. Class files are searched for
1712 in BBPATH in the same was as <code class="filename">.conf</code> files too.
1713</p><p>
1714 In most cases inheriting the class is enough to enable its features, although
1715 for some classes you may need to set variables and/or override some of the
1716 default behaviour.
1717</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-base"></a>1. The base class - <code class="filename">base.bbclass</code></h2></div></div></div><p>
1718 The base class is special in that every <code class="filename">.bb</code>
1719 file inherits it automatically. It contains definitions of standard basic
1720 tasks such as fetching, unpacking, configuring (empty by default), compiling
1721 (runs any Makefile present), installing (empty by default) and packaging
1722 (empty by default). These are often overridden or extended by other classes
1723 such as <code class="filename">autotools.bbclass</code> or
1724 <code class="filename">package.bbclass</code>. The class contains some commonly
1725 some commonly used functions such as <code class="function">oe_libinstall</code>
1726 and <code class="function">oe_runmake</code>. The end of the class file has a
1727 list of standard mirrors for software projects for use by the fetcher code.
1728 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-autotools"></a>2. Autotooled Packages - <code class="filename">autotools.bbclass</code></h2></div></div></div><p>
1729 Autotools (autoconf, automake, libtool) brings standardisation and this
1730 class aims to define a set of tasks (configure, compile etc.) that will
1731 work for all autotooled packages. It should usualy be enough to define
1732 a few standard variables as documented in the <a href="#usingpoky-extend-addpkg-autotools" title="1.2. Autotooled Package">simple autotools
1733 example</a> section and then simply "inherit autotools". This class
1734 can also work with software that emulates autotools.
1735 </p><p>
1736 Its useful to have some idea of the tasks this class defines work and
1737 what they do behind the scenes.
1738 </p><div class="itemizedlist"><ul type="disc"><li><p>
1739 'do_configure' regenearates the configure script and
1740 then launches it with a standard set of arguments used during
1741 cross-compilation. Additional parameters can be passed to
1742 <span><strong class="command">configure</strong></span> through the <em class="glossterm"><a href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a></em> variable.
1743 </p></li><li><p>
1744 'do_compile' runs <span><strong class="command">make</strong></span> with arguments specifying
1745 the compiler and linker. Additional arguments can be passed through
1746 the <em class="glossterm"><a href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a>
1747 </em> variable.
1748 </p></li><li><p>
1749 'do_install' runs <span><strong class="command">make install</strong></span> passing a DESTDIR
1750 option taking its value from the standard <em class="glossterm"><a href="#var-DESTDIR" title="DESTDIR">DESTDIR</a></em> variable.
1751 </p></li></ul></div><p>
1752 By default the class does not stage headers and libraries so
1753 the recipe author needs to add their own <code class="function">do_stage()</code>
1754 task. For typical recipes the following example code will usually be
1755 enough:
1756 </p><pre class="programlisting">
1757do_stage() {
1758autotools_stage_all
1759}</pre><p>
1760 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-update-alternatives"></a>3. Alternatives - <code class="filename">update-alternatives.bbclass</code></h2></div></div></div><p>
1761 Several programs can fulfill the same or similar function and
1762 they can be installed with the same name. For example the <span><strong class="command">ar</strong></span>
1763 command is available from the "busybox", "binutils" and "elfutils" packages.
1764 This class handles the renaming of the binaries so multiple packages
1765 can be installed which would otherwise conflict and yet the
1766 <span><strong class="command">ar</strong></span> command still works regardless of which are installed
1767 or subsequently removed. It renames the conflicting binary in each package
1768 and symlinks the highest priority binary during installation or removal
1769 of packages.
1770
1771 Four variables control this class:
1772 </p><div class="variablelist"><dl><dt><span class="term">ALTERNATIVE_NAME</span></dt><dd><p>
1773 Name of binary which will be replaced (<span><strong class="command">ar</strong></span> in this example)
1774 </p></dd><dt><span class="term">ALTERNATIVE_LINK</span></dt><dd><p>
1775 Path to resulting binary ("/bin/ar" in this example)
1776 </p></dd><dt><span class="term">ALTERNATIVE_PATH</span></dt><dd><p>
1777 Path to real binary ("/usr/bin/ar.binutils" in this example)
1778 </p></dd><dt><span class="term">ALTERNATIVE_PRIORITY</span></dt><dd><p>
1779 Priority of binary, the version with the most features should have the highest priority
1780 </p></dd></dl></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-update-rc.d"></a>4. Initscripts - <code class="filename">update-rc.d.bbclass</code></h2></div></div></div><p>
1781 This class uses update-rc.d to safely install an initscript on behalf of
1782 the package. Details such as making sure the initscript is stopped before
1783 a package is removed and started when the package is installed are taken
1784 care of. Three variables control this class,
1785 <a href="#var-INITSCRIPT_PACKAGES" title="INITSCRIPT_PACKAGES">INITSCRIPT_PACKAGES</a>,
1786 <a href="#var-INITSCRIPT_NAME" title="INITSCRIPT_NAME">INITSCRIPT_NAME</a> and
1787 <a href="#var-INITSCRIPT_PARAMS" title="INITSCRIPT_PARAMS">INITSCRIPT_PARAMS</a>. See the
1788 links for details.
1789 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-binconfig"></a>5. Binary config scripts - <code class="filename">binconfig.bbclass</code></h2></div></div></div><p>
1790 Before pkg-config became widespread, libraries shipped shell
1791 scripts to give information about the libraries and include paths needed
1792 to build software (usually named 'LIBNAME-config'). This class assists
1793 any recipe using such scripts.
1794 </p><p>
1795 During staging Bitbake installs such scripts into the <code class="filename">staging/</code> directory. It also changes all
1796 paths to point into the <code class="filename">staging/</code>
1797 directory so all builds which use the script will use the correct
1798 directories for the cross compiling layout.
1799 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-debian"></a>6. Debian renaming - <code class="filename">debian.bbclass</code></h2></div></div></div><p>
1800 This class renames packages so that they follow the Debian naming
1801 policy, i.e. 'glibc' becomes 'libc6' and 'glibc-devel' becomes
1802 'libc6-dev'.
1803 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-pkgconfig"></a>7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></h2></div></div></div><p>
1804 Pkg-config brought standardisation and this class aims to make its
1805 integration smooth for all libraries which make use of it.
1806 </p><p>
1807 During staging Bitbake installs pkg-config data into the <code class="filename">staging/</code> directory. By making use of
1808 sysroot functionality within pkgconfig this class no longer has to
1809 manipulate the files.
1810 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-src-distribute"></a>8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></h2></div></div></div><p>
1811 Many software licenses require providing the sources for compiled
1812 binaries. To simplify this process two classes were created:
1813 <code class="filename">src_distribute.bbclass</code> and
1814 <code class="filename">src_distribute_local.bbclass</code>.
1815 </p><p>
1816 Result of their work are <code class="filename">tmp/deploy/source/</code>
1817 subdirs with sources sorted by <em class="glossterm"><a href="#var-LICENSE" title="LICENSE">LICENSE</a>
1818 </em> field. If recipe lists few licenses (or has entries like "Bitstream Vera") source archive is put in each
1819 license dir.
1820 </p><p>
1821 Src_distribute_local class has three modes of operating:
1822 </p><div class="itemizedlist"><ul type="disc"><li><p>copy - copies the files to the distribute dir</p></li><li><p>symlink - symlinks the files to the distribute dir</p></li><li><p>move+symlink - moves the files into distribute dir, and symlinks them back</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-perl"></a>9. Perl modules - <code class="filename">cpan.bbclass</code></h2></div></div></div><p>
1823 Recipes for Perl modules are simple - usually needs only
1824 pointing to source archive and inheriting of proper bbclass.
1825 Building is split into two methods dependly on method used by
1826 module authors.
1827 </p><p>
1828 Modules which use old Makefile.PL based build system require
1829 using of <code class="filename">cpan.bbclass</code> in their recipes.
1830 </p><p>
1831 Modules which use Build.PL based build system require
1832 using of <code class="filename">cpan_build.bbclass</code> in their recipes.
1833 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-distutils"></a>10. Python extensions - <code class="filename">distutils.bbclass</code></h2></div></div></div><p>
1834 Recipes for Python extensions are simple - usually needs only
1835 pointing to source archive and inheriting of proper bbclass.
1836 Building is split into two methods dependly on method used by
1837 module authors.
1838 </p><p>
1839 Extensions which use autotools based build system require using
1840 of autotools and distutils-base bbclasses in their recipes.
1841 </p><p>
1842 Extensions which use distutils build system require using
1843 of <code class="filename">distutils.bbclass</code> in their recipes.
1844 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-devshell"></a>11. Developer Shell - <code class="filename">devshell.bbclass</code></h2></div></div></div><p>
1845 This class adds the devshell task. Its usually up to distribution policy
1846 to include this class (Poky does). See the <a href="#platdev-appdev-devshell" title="1.6. Developing with 'devshell'">developing with 'devshell' section</a>
1847 for more information about using devshell.
1848 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-package"></a>12. Packaging - <code class="filename">package*.bbclass</code></h2></div></div></div><p>
1849 The packaging classes add support for generating packages from the output
1850 from builds. The core generic functionality is in
1851 <code class="filename">package.bbclass</code>, code specific to particular package
1852 types is contained in various sub classes such as
1853 <code class="filename">package_deb.bbclass</code> and <code class="filename">package_ipk.bbclass</code>.
1854 Most users will
1855 want one or more of these classes and this is controlled by the <em class="glossterm">
1856 <a href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></em>
1857 variable. The first class listed in this variable will be used for image
1858 generation. Since images are generated from packages a packaging class is
1859 needed to enable image generation.
1860 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-kernel"></a>13. Building kernels - <code class="filename">kernel.bbclass</code></h2></div></div></div><p>
1861 This class handle building of Linux kernels and the class contains code to know how to build both 2.4 and 2.6 kernel trees. All needed headers are
1862 staged into <em class="glossterm"><a href="#var-STAGING_KERNEL_DIR" title="STAGING_KERNEL_DIR">STAGING_KERNEL_DIR</a></em>
1863 directory to allow building of out-of-tree modules using <code class="filename">module.bbclass</code>.
1864 </p><p>
1865 The means that each kerel module built is packaged separately and inter-modules dependencies are
1866 created by parsing the <span><strong class="command">modinfo</strong></span> output. If all modules are
1867 required then installing "kernel-modules" package will install all
1868 packages with modules and various other kernel packages such as "kernel-vmlinux" are also generated.
1869 </p><p>
1870 Various other classes are used by the kernel and module classes internally including
1871 <code class="filename">kernel-arch.bbclass</code>, <code class="filename">module_strip.bbclass</code>,
1872 <code class="filename">module-base.bbclass</code> and <code class="filename">linux-kernel-base.bbclass</code>.
1873 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-image"></a>14. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></h2></div></div></div><p>
1874 Those classes add support for creating images in many formats. First the
1875 rootfs is created from packages by one of the <code class="filename">rootfs_*.bbclass</code>
1876 files (depending on package format used) and then image is created.
1877
1878 The <em class="glossterm"><a href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a></em>
1879 variable controls which types of image to generate.
1880
1881 The list of packages to install into the image is controlled by the
1882 <em class="glossterm"><a href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></em>
1883 variable.
1884 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-sanity"></a>15. Host System sanity checks - <code class="filename">sanity.bbclass</code></h2></div></div></div><p>
1885 This class checks prerequisite software is present to try and identify
1886 and notify the user of problems which will affect their build. It also
1887 performs basic checks of the users configuration from local.conf to
1888 prevent common mistakes and resulting build failures. Its usually up to
1889 distribution policy to include this class (Poky does).
1890 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-insane"></a>16. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></h2></div></div></div><p>
1891 This class adds a step to package generation which sanity checks the
1892 packages generated by Poky. There are an ever increasing range of checks
1893 this makes, checking for common problems which break builds/packages/images,
1894 see the bbclass file for more information. Its usually up to distribution
1895 policy to include this class (Poky doesn't at the time of writing but plans
1896 to soon).
1897 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-siteinfo"></a>17. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></h2></div></div></div><p>
1898 Autotools can require tests which have to execute on the target hardware.
1899 Since this isn't possible in general when cross compiling, siteinfo is
1900 used to provide cached test results so these tests can be skipped over but
1901 the correct values used. The <a href="#structure-meta-site" title="3.6. meta/site/">meta/site directory</a>
1902 contains test results sorted into different categories like architecture, endianess and
1903 the libc used. Siteinfo provides a list of files containing data relevant to
1904 the current build in the <em class="glossterm"><a href="#var-CONFIG_SITE" title="CONFIG_SITE">CONFIG_SITE
1905 </a></em> variable which autotools will automatically pick up.
1906 </p><p>
1907 The class also provides variables like <em class="glossterm"><a href="#var-SITEINFO_ENDIANESS" title="SITEINFO_ENDIANESS">SITEINFO_ENDIANESS</a></em>
1908 and <em class="glossterm"><a href="#var-SITEINFO_BITS" title="SITEINFO_BITS">SITEINFO_BITS</a>
1909 </em> which can be used elsewhere in the metadata.
1910 </p><p>
1911 This class is included from <code class="filename">base.bbclass</code> and is hence always active.
1912 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-others"></a>18. Other Classes</h2></div></div></div><p>
1913 Only the most useful/important classes are covered here but there are
1914 others, see the <code class="filename">meta/classes</code> directory for the rest.
1915 </p></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-images"></a>Appendix 4. Reference: Images</h2></div></div></div><p>
1916 Poky has several standard images covering most people's standard needs. A full
1917 list of image targets can be found by looking in the <code class="filename">
1918 meta/packages/images/</code> directory. The standard images are listed below
1919 along with details of what they contain:
1920 </p><div class="itemizedlist"><ul type="disc"><li><p>
1921 <span class="emphasis"><em>poky-image-minimal</em></span> - A small image, just enough
1922 to allow a device to boot
1923 </p></li><li><p>
1924 <span class="emphasis"><em>poky-image-base</em></span> - console only image with full
1925 support of target device hardware
1926 </p></li><li><p>
1927 <span class="emphasis"><em>poky-image-core</em></span> - X11 image with simple apps like
1928 terminal, editor and file manager
1929 </p></li><li><p>
1930 <span class="emphasis"><em>poky-image-sato</em></span> - X11 image with Sato theme and
1931 Pimlico applications. Also contains terminal, editor and file manager.
1932 </p></li><li><p>
1933 <span class="emphasis"><em>poky-image-sdk</em></span> - X11 image like poky-image-sato but
1934 also include native toolchain and libraries needed to build applications
1935 on the device itself. Also includes testing and profiling tools and debug
1936 symbols.
1937 </p></li><li><p>
1938 <span class="emphasis"><em>meta-toolchain</em></span> - This generates a tarball containing
1939 a standalone toolchain which can be used externally to Poky. It is self
1940 contained and unpacks to the <code class="filename">/usr/local/poky</code>
1941 directory. It also contains a copy of QEMU and the scripts neccessary to run
1942 poky QEMU images.
1943 </p></li><li><p>
1944 <span class="emphasis"><em>meta-toolchain-sdk</em></span> - This includes everything in
1945 meta-toolchain but also includes development headers and libraries
1946 forming a complete standalone SDK. See the <a href="#platdev-appdev-external-sdk" title="1.2. Developing externally using the Poky SDK">
1947 Developing using the Poky SDK</a> and <a href="#platdev-appdev-external-anjuta" title="1.1. Developing externally using the Anjuta Plugin">
1948 Developing using the Anjuta Plugin</a> sections for more information.
1949 </p></li></ul></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-features"></a>Appendix 5. Reference: Features</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref-features-distro">1. Distro</a></span></dt><dt><span class="section"><a href="#ref-features-machine">2. Machine</a></span></dt><dt><span class="section"><a href="#ref-features-image">3. Reference: Images</a></span></dt></dl></div><p>'Features' provide a mechanism for working out which packages
1950 should be included in the generated images. Distributions can
1951 select which features they want to support through the
1952 <a href="#var-DISTRO_FEATURES"><em class="glossterm"><a href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></em></a>
1953 variable which is set in the distribution configuration file
1954 (poky.conf for Poky). Machine features are set in the
1955 <a href="#var-MACHINE_FEATURES"><em class="glossterm"><a href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></em></a>
1956 variable which is set in the machine configuration file and
1957 specifies which hardware features a given machine has.
1958 </p><p>These two variables are combined to work out which kernel modules,
1959 utilities and other packages to include. A given distribution can
1960 support a selected subset of features so some machine features might not
1961 be included if the distribution itself doesn't support them.
1962 </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-features-distro"></a>1. Distro</h2></div></div></div><p>The items below are valid options for <a href="#var-DISTRO_FEATURES"><em class="glossterm"><a href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></em></a>.
1963 </p><div class="itemizedlist"><ul type="disc"><li><p>
1964 alsa - ALSA support will be included (OSS compatibility
1965 kernel modules will be installed if available)
1966 </p></li><li><p>
1967 bluetooth - Include bluetooth support (integrated BT only)
1968 </p></li><li><p>
1969 ext2 - Include tools for supporting for devices with internal
1970 HDD/Microdrive for storing files (instead of Flash only devices)
1971 </p></li><li><p>
1972 irda - Include Irda support
1973 </p></li><li><p>
1974 keyboard - Include keyboard support (e.g. keymaps will be
1975 loaded during boot).
1976 </p></li><li><p>
1977 pci - Include PCI bus support
1978 </p></li><li><p>
1979 pcmcia - Include PCMCIA/CompactFlash support
1980 </p></li><li><p>
1981 usbgadget - USB Gadget Device support (for USB
1982 networking/serial/storage)
1983 </p></li><li><p>
1984 usbhost - USB Host support (allows to connect external
1985 keyboard, mouse, storage, network etc)
1986 </p></li><li><p>
1987 wifi - WiFi support (integrated only)
1988 </p></li><li><p>
1989 cramfs - CramFS support
1990 </p></li><li><p>
1991 ipsec - IPSec support
1992 </p></li><li><p>
1993 ipv6 - IPv6 support
1994 </p></li><li><p>
1995 nfs - NFS client support (for mounting NFS exports on
1996 device)
1997 </p></li><li><p>
1998 ppp - PPP dialup support
1999 </p></li><li><p>
2000 smbfs - SMB networks client support (for mounting
2001 Samba/Microsoft Windows shares on device)
2002 </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-features-machine"></a>2. Machine</h2></div></div></div><p>The items below are valid options for <a href="#var-MACHINE_FEATURES"><em class="glossterm"><a href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></em></a>.
2003 </p><div class="itemizedlist"><ul type="disc"><li><p>
2004 acpi - Hardware has ACPI (x86/x86_64 only)
2005 </p></li><li><p>
2006 alsa - Hardware has ALSA audio drivers
2007 </p></li><li><p>
2008 apm - Hardware uses APM (or APM emulation)
2009 </p></li><li><p>
2010 bluetooth - Hardware has integrated BT
2011 </p></li><li><p>
2012 ext2 - Hardware HDD or Microdrive
2013 </p></li><li><p>
2014 irda - Hardware has Irda support
2015 </p></li><li><p>
2016 keyboard - Hardware has a keyboard
2017 </p></li><li><p>
2018 pci - Hardware has a PCI bus
2019 </p></li><li><p>
2020 pcmcia - Hardware has PCMCIA or CompactFlash sockets
2021 </p></li><li><p>
2022 screen - Hardware has a screen
2023 </p></li><li><p>
2024 serial - Hardware has serial support (usually RS232)
2025 </p></li><li><p>
2026 touchscreen - Hardware has a touchscreen
2027 </p></li><li><p>
2028 usbgadget - Hardware is USB gadget device capable
2029 </p></li><li><p>
2030 usbhost - Hardware is USB Host capable
2031 </p></li><li><p>
2032 wifi - Hardware has integrated WiFi
2033 </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-features-image"></a>3. Reference: Images</h2></div></div></div><p>
2034 The contents of images generated by Poky can be controlled by the <a href="#var-IMAGE_FEATURES"><em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em></a>
2035 variable in local.conf. Through this you can add several different
2036 predefined packages such as development utilities or packages with debug
2037 information needed to investigate application problems or profile applications.
2038 </p><p>
2039 Current list of <a href="#var-IMAGE_FEATURES"><em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em></a> contains:
2040 </p><div class="itemizedlist"><ul type="disc"><li><p>
2041 apps-console-core - Core console applications such as ssh daemon,
2042 avahi daemon, portmap (for mounting NFS shares)
2043 </p></li><li><p>
2044 x11-base - X11 server + minimal desktop
2045 </p></li><li><p>
2046 x11-sato - OpenedHand Sato environment
2047 </p></li><li><p>
2048 apps-x11-core - Core X11 applications such as an X Terminal, file manager, file editor
2049 </p></li><li><p>
2050 apps-x11-games - A set of X11 games
2051 </p></li><li><p>
2052 apps-x11-pimlico - OpenedHand Pimlico application suite
2053 </p></li><li><p>
2054 tools-sdk - A full SDK which runs on device
2055 </p></li><li><p>
2056 tools-debug - Debugging tools such as strace and gdb
2057 </p></li><li><p>
2058 tools-profile - Profiling tools such as oprofile, exmap and LTTng
2059 </p></li><li><p>
2060 tools-testapps - Device testing tools (e.g. touchscreen debugging)
2061 </p></li><li><p>
2062 nfs-server - NFS server (exports / over NFS to everybody)
2063 </p></li><li><p>
2064 dev-pkgs - Development packages (headers and extra library links) for all packages
2065 installed in a given image
2066 </p></li><li><p>
2067 dbg-pkgs - Debug packages for all packages installed in a given image
2068 </p></li></ul></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-variables-glos"></a>Appendix 6. Reference: Variables Glossary</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="glossary"><a href="#ref-variables-glossary">Glossary</a></span></dt></dl></div><p>
2069 This section lists common variables used in Poky and gives an overview
2070 of their function and contents.
2071</p><div class="glossary"><div class="titlepage"><div><div><h2 class="title"><a name="ref-variables-glossary"></a>Glossary</h2></div></div></div><p>
2072 <a href="#var-glossary-a" title="A">A</a>
2073 <a href="#var-glossary-b" title="B">B</a>
2074 <a href="#var-glossary-c" title="C">C</a>
2075 <a href="#var-glossary-d" title="D">D</a>
2076 <a href="#var-glossary-e" title="E">E</a>
2077 <a href="#var-glossary-f" title="F">F</a>
2078
2079 <a href="#var-glossary-h" title="H">H</a>
2080 <a href="#var-glossary-i" title="I">I</a>
2081
2082 <a href="#var-glossary-k" title="K">K</a>
2083 <a href="#var-glossary-l" title="L">L</a>
2084 <a href="#var-glossary-m" title="M">M</a>
2085
2086
2087 <a href="#var-glossary-p" title="P">P</a>
2088
2089 <a href="#var-glossary-r" title="R">R</a>
2090 <a href="#var-glossary-s" title="S">S</a>
2091 <a href="#var-glossary-t" title="T">T</a>
2092
2093
2094 <a href="#var-glossary-w" title="W">W</a>
2095
2096
2097
2098 </p><div class="glossdiv"><h3 class="title">A</h3><dl><dt><a name="var-AUTHOR"></a>AUTHOR</dt><dd><p>E-mail address to contact original author(s) - to
2099 send patches, forward bugs...</p></dd><dt><a name="var-AUTOREV"></a>AUTOREV</dt><dd><p>Use current (newest) source revision - used with
2100 <em class="glossterm"><a href="#var-SRCREV" title="SRCREV">SRCREV</a></em>
2101 variable.</p></dd></dl></div><div class="glossdiv"><h3 class="title">B</h3><dl><dt><a name="var-BB_NUMBER_THREADS"></a>BB_NUMBER_THREADS</dt><dd><p>Number of BitBake threads</p></dd><dt><a name="var-BBFILES"></a>BBFILES</dt><dd><p>List of recipes used by BitBake to build software</p></dd><dt><a name="var-BBINCLUDELOGS"></a>BBINCLUDELOGS</dt><dd><p>Variable which controls how BitBake displays logs on build failure.</p></dd></dl></div><div class="glossdiv"><h3 class="title">C</h3><dl><dt><a name="var-CFLAGS"></a>CFLAGS</dt><dd><p>
2102 Flags passed to C compiler for the target system. Evaluates to the same
2103 as <a href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a>.
2104 </p></dd><dt><a name="var-COMPATIBLE_MACHINES"></a>COMPATIBLE_MACHINES</dt><dd><p>A regular expression which evalutates to match the machines the recipe
2105 works with. It stops recipes being run on machines they're incompatible with
2106 which is partciuarly useful with kernels. It also helps to to increase parsing
2107 speed as if its found the current machine is not compatible, further parsing
2108 of the recipe is skipped.</p></dd><dt><a name="var-CONFIG_SITE"></a>CONFIG_SITE</dt><dd><p>
2109 Contains a list of files which containing autoconf test results relevant
2110 to the current build. This variable is used by the autotools utilities
2111 when running configure.
2112 </p></dd><dt><a name="var-CVS_TARBALL_STASH"></a>CVS_TARBALL_STASH</dt><dd><p>Location to search for
2113 pre-generated tarballs when fetching from remote SCM
2114 repositories (CVS/SVN/GIT)</p></dd></dl></div><div class="glossdiv"><h3 class="title">D</h3><dl><dt><a name="var-D"></a>D</dt><dd><p>Destination directory</p></dd><dt><a name="var-DEBUG_BUILD"></a>DEBUG_BUILD</dt><dd><p>
2115 Build packages with debugging information. This influences the value
2116 <a href="#var-SELECTED_OPTIMIZATION" title="SELECTED_OPTIMIZATION">SELECTED_OPTIMIZATION</a>
2117 takes.
2118 </p></dd><dt><a name="var-DEBUG_OPTIMIZATION"></a>DEBUG_OPTIMIZATION</dt><dd><p>
2119 The options to pass in <a href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a>
2120 and <a href="#var-CFLAGS" title="CFLAGS">CFLAGS</a> when compiling a system for debugging.
2121 This defaults to "-O -fno-omit-frame-pointer -g".
2122 </p></dd><dt><a name="var-DEFAULT_PREFERENCE"></a>DEFAULT_PREFERENCE</dt><dd><p>Priority of recipe</p></dd><dt><a name="var-DEPENDS"></a>DEPENDS</dt><dd><p>
2123 A list of build time dependencies for a given recipe. These indicate
2124 recipes that must have staged before this recipe can configure.
2125 </p></dd><dt><a name="var-DESCRIPTION"></a>DESCRIPTION</dt><dd><p>Package description used by package
2126 managers</p></dd><dt><a name="var-DESTDIR"></a>DESTDIR</dt><dd><p>Destination directory</p></dd><dt><a name="var-DISTRO"></a>DISTRO</dt><dd><p>Short name of distribution</p></dd><dt><a name="var-DISTRO_EXTRA_RDEPENDS"></a>DISTRO_EXTRA_RDEPENDS</dt><dd><p>List of packages required by distribution.</p></dd><dt><a name="var-DISTRO_EXTRA_RRECOMMENDS"></a>DISTRO_EXTRA_RRECOMMENDS</dt><dd><p>List of packages which extend usability of
2127 image. Those packages will be automatically
2128 installed but can be removed by user.</p></dd><dt><a name="var-DISTRO_FEATURES"></a>DISTRO_FEATURES</dt><dd><p>Features of the distribution.</p></dd><dt><a name="var-DISTRO_NAME"></a>DISTRO_NAME</dt><dd><p>Long name of distribution</p></dd><dt><a name="var-DISTRO_VERSION"></a>DISTRO_VERSION</dt><dd><p>Version of distribution</p></dd><dt><a name="var-DL_DIR"></a>DL_DIR</dt><dd><p>Directory where all fetched sources will be stored</p></dd></dl></div><div class="glossdiv"><h3 class="title">E</h3><dl><dt><a name="var-ENABLE_BINARY_LOCALE_GENERATION"></a>ENABLE_BINARY_LOCALE_GENERATION</dt><dd><p>Variable which control which locales for glibc are
2129 to be generated during build (useful if target device
2130 has 64M RAM or less)</p></dd><dt><a name="var-EXTRA_OECONF"></a>EXTRA_OECONF</dt><dd><p>Additional 'configure' script options</p></dd><dt><a name="var-EXTRA_OEMAKE"></a>EXTRA_OEMAKE</dt><dd><p>Additional GNU make options</p></dd></dl></div><div class="glossdiv"><h3 class="title">F</h3><dl><dt><a name="var-FILES"></a>FILES</dt><dd><p>list of directories/files which will be placed
2131 in packages</p></dd><dt><a name="var-FULL_OPTIMIZATION"></a>FULL_OPTIMIZATION</dt><dd><p>
2132 The options to pass in <a href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a>
2133 and <a href="#var-CFLAGS" title="CFLAGS">CFLAGS</a> when compiling an optimised system.
2134 This defaults to "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
2135 </p></dd></dl></div><div class="glossdiv"><h3 class="title">H</h3><dl><dt><a name="var-HOMEPAGE"></a>HOMEPAGE</dt><dd><p>Website where more info about package can be found</p></dd></dl></div><div class="glossdiv"><h3 class="title">I</h3><dl><dt><a name="var-IMAGE_FEATURES"></a>IMAGE_FEATURES</dt><dd><p><a href="#ref-features-image" title="3. Reference: Images">List of
2136 features</a> present in resulting images</p></dd><dt><a name="var-IMAGE_FSTYPES"></a>IMAGE_FSTYPES</dt><dd><p>Formats of rootfs images which we want to have
2137 created</p></dd><dt><a name="var-IMAGE_INSTALL"></a>IMAGE_INSTALL</dt><dd><p>List of packages used to build image</p></dd><dt><a name="var-INHIBIT_PACKAGE_STRIP"></a>INHIBIT_PACKAGE_STRIP</dt><dd><p>
2138 This variable causes the build to not strip binaries in
2139 resulting packages.
2140 </p></dd><dt><a name="var-INHERIT"></a>INHERIT</dt><dd><p>
2141 This variable causes the named class to be inherited at
2142 this point during parsing. Its only valid in configuration
2143 files.
2144 </p></dd><dt><a name="var-INITSCRIPT_PACKAGES"></a>INITSCRIPT_PACKAGES</dt><dd><p>
2145 Scope: Used in recipes when using update-rc.d.bbclass. Optional, defaults to PN.
2146 </p><p>
2147 A list of the packages which contain initscripts. If multiple
2148 packages are specified you need to append the package name
2149 to the other INITSCRIPT_* as an override.
2150 </p></dd><dt><a name="var-INITSCRIPT_NAME"></a>INITSCRIPT_NAME</dt><dd><p>
2151 Scope: Used in recipes when using update-rc.d.bbclass. Mandatory.
2152 </p><p>
2153 The filename of the initscript (as installed to ${etcdir}/init.d).
2154 </p></dd><dt><a name="var-INITSCRIPT_PARAMS"></a>INITSCRIPT_PARAMS</dt><dd><p>
2155 Scope: Used in recipes when using update-rc.d.bbclass. Mandatory.
2156 </p><p>
2157 Specifies the options to pass to update-rc.d. An example is
2158 "start 99 5 2 . stop 20 0 1 6 ." which gives the script a
2159 runlevel of 99, starts the script in initlevels 2 and 5 and
2160 stops it in levels 0, 1 and 6.
2161 </p></dd></dl></div><div class="glossdiv"><h3 class="title">K</h3><dl><dt><a name="var-KERNEL_IMAGETYPE"></a>KERNEL_IMAGETYPE</dt><dd><p>The type of kernel to build for a device, usually set by the
2162 machine configuration files and defaults to "zImage". This is used
2163 when building the kernel and is passed to "make" as the target to
2164 build.</p></dd></dl></div><div class="glossdiv"><h3 class="title">L</h3><dl><dt><a name="var-LICENSE"></a>LICENSE</dt><dd><p>List of package source licenses.</p></dd></dl></div><div class="glossdiv"><h3 class="title">M</h3><dl><dt><a name="var-MACHINE"></a>MACHINE</dt><dd><p>Target device</p></dd><dt><a name="var-MACHINE_ESSENTIAL_RDEPENDS"></a>MACHINE_ESSENTIAL_RDEPENDS</dt><dd><p>List of packages required to boot device</p></dd><dt><a name="var-MACHINE_ESSENTIAL_RRECOMMENDS"></a>MACHINE_ESSENTIAL_RRECOOMENDS</dt><dd><p>List of packages required to boot device (usually
2165 additional kernel modules)</p></dd><dt><a name="var-MACHINE_EXTRA_RDEPENDS"></a>MACHINE_EXTRA_RDEPENDS</dt><dd><p>List of packages required to use device</p></dd><dt><a name="var-MACHINE_EXTRA_RRECOMMENDS"></a>MACHINE_EXTRA_RRECOMMNEDS</dt><dd><p>List of packages useful to use device (for example
2166 additional kernel modules)</p></dd><dt><a name="var-MACHINE_FEATURES"></a>MACHINE_FEATURES</dt><dd><p>List of device features - defined in <a href="#ref-features-machine" title="2. Machine">machine
2167 features section</a></p></dd><dt><a name="var-MAINTAINER"></a>MAINTAINER</dt><dd><p>E-mail of distribution maintainer</p></dd></dl></div><div class="glossdiv"><h3 class="title">P</h3><dl><dt><a name="var-PACKAGE_ARCH"></a>PACKAGE_ARCH</dt><dd><p>Architecture of resulting package</p></dd><dt><a name="var-PACKAGE_CLASSES"></a>PACKAGE_CLASSES</dt><dd><p>List of resulting packages formats</p></dd><dt><a name="var-PACKAGE_EXTRA_ARCHS"></a>PACKAGE_EXTRA_ARCHS</dt><dd><p>List of architectures compatible with device
2168 CPU. Usable when build is done for few different
2169 devices with misc processors (like XScale and
2170 ARM926-EJS)</p></dd><dt><a name="var-PACKAGES"></a>PACKAGES</dt><dd><p>List of packages to be created from recipe.
2171 The default value is "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev"</p></dd><dt><a name="var-PN"></a>PN</dt><dd><p>Name of package.
2172 </p></dd><dt><a name="var-PR"></a>PR</dt><dd><p>Revision of package.
2173 </p></dd><dt><a name="var-PV"></a>PV</dt><dd><p>Version of package.
2174 The default value is "1.0"</p></dd><dt><a name="var-PE"></a>PE</dt><dd><p>
2175 Epoch of the package. The default value is "1". The field is used
2176 to make upgrades possible when the versioning scheme changes in
2177 some backwards incompatible way.
2178 </p></dd><dt><a name="var-PREFERRED_PROVIDER"></a>PREFERRED_PROVIDER</dt><dd><p>If multiple recipes provide an item, this variable
2179 determines which one should be given preference. It
2180 should be set to the "$PN" of the recipe to be preferred.</p></dd><dt><a name="var-PREFERRED_VERSION"></a>PREFERRED_VERSION</dt><dd><p>
2181 If there are multiple versions of recipe available, this
2182 variable determines which one should be given preference. It
2183 should be set to the "$PV" of the recipe to be preferred.
2184 </p></dd><dt><a name="var-POKYLIBC"></a>POKYLIBC</dt><dd><p>Libc implementation selector - glibc or uclibc can be selected.</p></dd><dt><a name="var-POKYMODE"></a>POKYMODE</dt><dd><p>Toolchain selector. It can be external toolchain
2185 built from Poky or few supported combinations of
2186 upstream GCC or CodeSourcery Labs toolchain.</p></dd></dl></div><div class="glossdiv"><h3 class="title">R</h3><dl><dt><a name="var-RCONFLICTS"></a>RCONFLICTS</dt><dd><p>List of packages which which conflict with this
2187 one. Package will not be installed if they will not
2188 be removed first.</p></dd><dt><a name="var-RDEPENDS"></a>RDEPENDS</dt><dd><p>
2189 A list of run-time dependencies for a package. These packages
2190 need to be installed alongside the package it applies to so
2191 the package will run correctly, an example is a perl script
2192 which would rdepend on perl. Since this variable applies to
2193 output packages there would usually be an override attached
2194 to this variable like RDEPENDS_${PN}-dev. Names in this field
2195 should be as they are in <a href="#var-PACKAGES" title="PACKAGES">PACKAGES
2196 </a> namespave before any renaming of the output package
2197 by classes like debian.bbclass.
2198 </p></dd><dt><a name="var-ROOT_FLASH_SIZE"></a>ROOT_FLASH_SIZE</dt><dd><p>Size of rootfs in megabytes</p></dd><dt><a name="var-RRECOMMENDS"></a>RRECOMMENDS</dt><dd><p>List of packages which extend usability of
2199 package. Those packages will be automatically
2200 installed but can be removed by user.</p></dd><dt><a name="var-RREPLACES"></a>RREPLACES</dt><dd><p>List of packages which are replaced with this
2201 one.</p></dd></dl></div><div class="glossdiv"><h3 class="title">S</h3><dl><dt><a name="var-S"></a>S</dt><dd><p>
2202 Path to unpacked sources (by default:
2203 "${<a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a>}/${<a href="#var-PN" title="PN">PN</a>}-${<a href="#var-PV" title="PV">PV</a>}")
2204 </p></dd><dt><a name="var-SECTION"></a>SECTION</dt><dd><p>Section where package should be put - used
2205 by package managers</p></dd><dt><a name="var-SELECTED_OPTIMIZATION"></a>SELECTED_OPTIMIZATION</dt><dd><p>
2206 The variable takes the value of <a href="#var-FULL_OPTIMIZATION" title="FULL_OPTIMIZATION">FULL_OPTIMIZATION</a>
2207 unless <a href="#var-DEBUG_BUILD" title="DEBUG_BUILD">DEBUG_BUILD</a> = "1" in which case
2208 <a href="#var-DEBUG_OPTIMIZATION" title="DEBUG_OPTIMIZATION">DEBUG_OPTIMIZATION</a> is used.
2209 </p></dd><dt><a name="var-SERIAL_CONSOLE"></a>SERIAL_CONSOLE</dt><dd><p>Speed and device for serial port used to attach
2210 serial console. This is given to kernel as "console"
2211 param and after boot getty is started on that port
2212 so remote login is possible.</p></dd><dt><a name="var-SHELLCMDS"></a>SHELLCMDS</dt><dd><p>
2213 A list of commands to run within the a shell, used by <em class="glossterm"><a href="#var-TERMCMDRUN" title="TERMCMDRUN">TERMCMDRUN</a></em>. It defaults to
2214 <em class="glossterm"><a href="#var-SHELLRCCMD" title="SHELLRCCMD">SHELLRCCMD</a></em>.
2215 </p></dd><dt><a name="var-SHELLRCCMD"></a>SHELLRCCMD</dt><dd><p>
2216 How to launch a shell, defaults to bash.
2217 </p></dd><dt><a name="var-SITEINFO_ENDIANESS"></a>SITEINFO_ENDIANESS</dt><dd><p>
2218 Contains "le" for little-endian or "be" for big-endian depending
2219 on the endian byte order of the target system.
2220 </p></dd><dt><a name="var-SITEINFO_BITS"></a>SITEINFO_BITS</dt><dd><p>
2221 Contains "32" or "64" depending on the number of bits for the
2222 CPU of the target system.
2223 </p></dd><dt><a name="var-SRC_URI"></a>SRC_URI</dt><dd><p>List of source files (local or remote ones)</p></dd><dt><a name="var-SRC_URI_OVERRIDES_PACKAGE_ARCH"></a>SRC_URI_OVERRIDES_PACKAGE_ARCH</dt><dd><p>
2224 By default there is code which automatically detects whether
2225 <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em>
2226 contains files which are machine specific and if this is the case it
2227 automatically changes
2228 <em class="glossterm"><a href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></em>.
2229 Setting this variable to "0" disables that behaviour.
2230 </p></dd><dt><a name="var-SRCDATE"></a>SRCDATE</dt><dd><p>
2231 Date of source code used to build package (if it was fetched
2232 from SCM).
2233 </p></dd><dt><a name="var-SRCREV"></a>SRCREV</dt><dd><p>
2234 Revision of source code used to build package (Subversion,
2235 GIT, Bazaar only).
2236 </p></dd><dt><a name="var-STAGING_KERNEL_DIR"></a>STAGING_KERNEL_DIR</dt><dd><p>
2237 Directory with kernel headers required to build out-of-tree
2238 modules.
2239 </p></dd><dt><a name="var-STAMPS"></a>STAMPS</dt><dd><p>
2240 Directory (usually TMPDIR/stamps) with timestamps of
2241 executed tasks.
2242 </p></dd></dl></div><div class="glossdiv"><h3 class="title">T</h3><dl><dt><a name="var-TARGET_ARCH"></a>TARGET_ARCH</dt><dd><p>The architecture of the device we're building for.
2243 A number of values are possible but Poky primarily supports
2244 "arm" and "i586".</p></dd><dt><a name="var-TARGET_CFLAGS"></a>TARGET_CFLAGS</dt><dd><p>
2245 Flags passed to C compiler for the target system. Evaluates to the same
2246 as <a href="#var-CFLAGS" title="CFLAGS">CFLAGS</a>.
2247 </p></dd><dt><a name="var-TARGET_FPU"></a>TARGET_FPU</dt><dd><p>Method of handling FPU code. For FPU-less targets
2248 (most of ARM cpus) it has to be set to "soft" otherwise
2249 kernel emulation will get used which will result in
2250 performance penalty.</p></dd><dt><a name="var-TARGET_OS"></a>TARGET_OS</dt><dd><p>Type of target operating system. Can be "linux"
2251 for glibc based system, "linux-uclibc" for uClibc. For
2252 ARM/EABI targets there are also "linux-gnueabi" and
2253 "linux-uclibc-gnueabi" values possible.</p></dd><dt><a name="var-TERMCMD"></a>TERMCMD</dt><dd><p>
2254 This command is used by bitbake to lauch a terminal window with a
2255 shell. The shell is unspecified so the user's default shell is used.
2256 By default it is set to <span><strong class="command">gnome-terminal</strong></span> but it can
2257 be any X11 terminal application or terminal multiplexers like screen.
2258 </p></dd><dt><a name="var-TERMCMDRUN"></a>TERMCMDRUN</dt><dd><p>
2259 This command is similar to <em class="glossterm"><a href="#var-TERMCMD" title="TERMCMD">TERMCMD</a></em> however instead of the users shell it runs the command specified by the <em class="glossterm"><a href="#var-SHELLCMDS" title="SHELLCMDS">SHELLCMDS</a></em> variable.
2260 </p></dd></dl></div><div class="glossdiv"><h3 class="title">W</h3><dl><dt><a name="var-WORKDIR"></a>WORKDIR</dt><dd><p>Path to directory in tmp/work/ where package
2261 will be built.</p></dd></dl></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-varlocality"></a>Appendix 7. Reference: Variable Locality (Distro, Machine, Recipe etc.)</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref-varlocality-config-distro">1. Distro Configuration</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-machine">2. Machine Configuration</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-local">3. Local Configuration (local.conf)</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-required">4. Recipe Variables - Required</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-dependencies">5. Recipe Variables - Dependencies</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-paths">6. Recipe Variables - Paths</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-build">7. Recipe Variables - Extra Build Information</a></span></dt></dl></div><p>
2262 Whilst most variables can be used in almost any context (.conf, .bbclass,
2263 .inc or .bb file), variables are often associated with a particular
2264 locality/context. This section describes some common associations.
2265 </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-config-distro"></a>1. Distro Configuration</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="#var-DISTRO"><em class="glossterm"><a href="#var-DISTRO" title="DISTRO">DISTRO</a></em></a></p></li><li><p><a href="#var-DISTRO_NAME"><em class="glossterm"><a href="#var-DISTRO_NAME" title="DISTRO_NAME">DISTRO_NAME</a></em></a></p></li><li><p><a href="#var-DISTRO_VERSION"><em class="glossterm"><a href="#var-DISTRO_VERSION" title="DISTRO_VERSION">DISTRO_VERSION</a></em></a></p></li><li><p><a href="#var-MAINTAINER"><em class="glossterm"><a href="#var-MAINTAINER" title="MAINTAINER">MAINTAINER</a></em></a></p></li><li><p><a href="#var-PACKAGE_CLASSES"><em class="glossterm"><a href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></em></a></p></li><li><p><a href="#var-TARGET_OS"><em class="glossterm"><a href="#var-TARGET_OS" title="TARGET_OS">TARGET_OS</a></em></a></p></li><li><p><a href="#var-TARGET_FPU"><em class="glossterm"><a href="#var-TARGET_FPU" title="TARGET_FPU">TARGET_FPU</a></em></a></p></li><li><p><a href="#var-POKYMODE"><em class="glossterm"><a href="#var-POKYMODE" title="POKYMODE">POKYMODE</a></em></a></p></li><li><p><a href="#var-POKYLIBC"><em class="glossterm"><a href="#var-POKYLIBC" title="POKYLIBC">POKYLIBC</a></em></a></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-config-machine"></a>2. Machine Configuration</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="#var-TARGET_ARCH"><em class="glossterm"><a href="#var-TARGET_ARCH" title="TARGET_ARCH">TARGET_ARCH</a></em></a></p></li><li><p><a href="#var-SERIAL_CONSOLE"><em class="glossterm"><a href="#var-SERIAL_CONSOLE" title="SERIAL_CONSOLE">SERIAL_CONSOLE</a></em></a></p></li><li><p><a href="#var-PACKAGE_EXTRA_ARCHS"><em class="glossterm"><a href="#var-PACKAGE_EXTRA_ARCHS" title="PACKAGE_EXTRA_ARCHS">PACKAGE_EXTRA_ARCHS</a></em></a></p></li><li><p><a href="#var-IMAGE_FSTYPES"><em class="glossterm"><a href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a></em></a></p></li><li><p><a href="#var-ROOT_FLASH_SIZE"><em class="glossterm"><a href="#var-ROOT_FLASH_SIZE" title="ROOT_FLASH_SIZE">ROOT_FLASH_SIZE</a></em></a></p></li><li><p><a href="#var-MACHINE_FEATURES"><em class="glossterm"><a href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></em></a></p></li><li><p><a href="#var-MACHINE_EXTRA_RDEPENDS"><em class="glossterm"><a href="#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS</a></em></a></p></li><li><p><a href="#var-MACHINE_EXTRA_RRECOMMENDS"><em class="glossterm"><a href="#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMNEDS">MACHINE_EXTRA_RRECOMMENDS</a></em></a></p></li><li><p><a href="#var-MACHINE_ESSENTIAL_RDEPENDS"><em class="glossterm"><a href="#var-MACHINE_ESSENTIAL_RDEPENDS" title="MACHINE_ESSENTIAL_RDEPENDS">MACHINE_ESSENTIAL_RDEPENDS</a></em></a></p></li><li><p><a href="#var-MACHINE_ESSENTIAL_RRECOMMENDS"><em class="glossterm"><a href="#var-MACHINE_ESSENTIAL_RRECOMMENDS" title="MACHINE_ESSENTIAL_RRECOOMENDS">MACHINE_ESSENTIAL_RRECOMMENDS</a></em></a></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-config-local"></a>3. Local Configuration (local.conf)</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="#var-DISTRO"><em class="glossterm"><a href="#var-DISTRO" title="DISTRO">DISTRO</a></em></a></p></li><li><p><a href="#var-MACHINE"><em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a></em></a></p></li><li><p><a href="#var-DL_DIR"><em class="glossterm"><a href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></em></a></p></li><li><p><a href="#var-BBFILES"><em class="glossterm"><a href="#var-BBFILES" title="BBFILES">BBFILES</a></em></a></p></li><li><p><a href="#var-IMAGE_FEATURES"><em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em></a></p></li><li><p><a href="#var-PACKAGE_CLASSES"><em class="glossterm"><a href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></em></a></p></li><li><p><a href="#var-BB_NUMBER_THREADS"><em class="glossterm"><a href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a></em></a></p></li><li><p><a href="#var-BBINCLUDELOGS"><em class="glossterm"><a href="#var-BBINCLUDELOGS" title="BBINCLUDELOGS">BBINCLUDELOGS</a></em></a></p></li><li><p><a href="#var-CVS_TARBALL_STASH"><em class="glossterm"><a href="#var-CVS_TARBALL_STASH" title="CVS_TARBALL_STASH">CVS_TARBALL_STASH</a></em></a></p></li><li><p><a href="#var-ENABLE_BINARY_LOCALE_GENERATION"><em class="glossterm"><a href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">ENABLE_BINARY_LOCALE_GENERATION</a></em></a></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-recipe-required"></a>4. Recipe Variables - Required</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><em class="glossterm"><a href="#var-DESCRIPTION" title="DESCRIPTION">DESCRIPTION</a></em></p></li><li><p><em class="glossterm"><a href="#var-LICENSE" title="LICENSE">LICENSE</a></em></p></li><li><p><em class="glossterm"><a href="#var-SECTION" title="SECTION">SECTION</a></em></p></li><li><p><em class="glossterm"><a href="#var-HOMEPAGE" title="HOMEPAGE">HOMEPAGE</a></em></p></li><li><p><em class="glossterm"><a href="#var-AUTHOR" title="AUTHOR">AUTHOR</a></em></p></li><li><p><em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-recipe-dependencies"></a>5. Recipe Variables - Dependencies</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><em class="glossterm"><a href="#var-DEPENDS" title="DEPENDS">DEPENDS</a></em></p></li><li><p><em class="glossterm"><a href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></em></p></li><li><p><em class="glossterm"><a href="#var-RRECOMMENDS" title="RRECOMMENDS">RRECOMMENDS</a></em></p></li><li><p><em class="glossterm"><a href="#var-RCONFLICTS" title="RCONFLICTS">RCONFLICTS</a></em></p></li><li><p><em class="glossterm"><a href="#var-RREPLACES" title="RREPLACES">RREPLACES</a></em></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-recipe-paths"></a>6. Recipe Variables - Paths</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em></p></li><li><p><em class="glossterm"><a href="#var-S" title="S">S</a></em></p></li><li><p><em class="glossterm"><a href="#var-FILES" title="FILES">FILES</a></em></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-recipe-build"></a>7. Recipe Variables - Extra Build Information</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><em class="glossterm"><a href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a></em></p></li><li><p><em class="glossterm"><a href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a></em></p></li><li><p><em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></em></p></li><li><p><em class="glossterm"><a href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></em></p></li></ul></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="faq"></a>Appendix 8. FAQ</h2></div></div></div><div class="qandaset"><dl><dt>8.1. <a href="#id1089074">
2266 How does Poky differ from OpenEmbedded?
2267 </a></dt><dt>8.2. <a href="#id1089095">
2268 How can you claim Poky is stable?
2269 </a></dt><dt>8.3. <a href="#id1089122">
2270 How do I get support for my board added to Poky?
2271 </a></dt><dt>8.4. <a href="#id1089143">
2272 Are there any products running poky ?
2273 </a></dt><dt>8.5. <a href="#id1089157">
2274 What is the Poky output ?
2275 </a></dt><dt>8.6. <a href="#id1089167">
2276 How do I add my package to Poky?
2277 </a></dt><dt>8.7. <a href="#id1089176">
2278 Do I have to reflash my entire board with a new poky image when recompiling a package?
2279 </a></dt><dt>8.8. <a href="#id1089187">
2280 What is GNOME Mobile? What's the difference between GNOME Mobile and GNOME?
2281 </a></dt><dt>8.9. <a href="#id1089203">
2282 How do I make Poky work in RHEL/CentOS?
2283 </a></dt><dt>8.10. <a href="#id1089270">
2284 I see lots of 404 responses for files on http://folks.o-hand.com/~richard/poky/sources/*. Is something wrong?
2285 </a></dt><dt>8.11. <a href="#id1089285">
2286 I have a machine specific data in a package for one machine only but the package is
2287 being marked as machine specific in all cases, how do I stop it?
2288 </a></dt></dl><table border="0" summary="Q and A Set"><col align="left" width="1%"><tbody><tr class="question"><td align="left" valign="top"><a name="id1089074"></a><a name="id1089075"></a><b>8.1.</b></td><td align="left" valign="top"><p>
2289 How does Poky differ from <a href="http://www.openembedded.org/" target="_top">OpenEmbedded</a>?
2290 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2291 Poky is a derivative of <a href="http://www.openembedded.org/" target="_top">OpenEmbedded</a>, a stable,
2292 smaller subset focused on the GNOME Mobile environment. Development
2293 in Poky is closely tied to OpenEmbedded with features being merged
2294 regularly between the two for mutual benefit.
2295 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089095"></a><a name="id1089096"></a><b>8.2.</b></td><td align="left" valign="top"><p>
2296 How can you claim Poky is stable?
2297 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2298 There are three areas that help with stability;
2299
2300 </p><div class="itemizedlist"><ul type="disc"><li><p>
2301 We keep Poky small and focused - around 650 packages compared to over 5000 for full OE
2302 </p></li><li><p>
2303 We only support hardware that we have access to for testing
2304 </p></li><li><p>
2305 We have a Buildbot which provides continuous build and integration tests
2306 </p></li></ul></div><p>
2307 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089122"></a><a name="id1089123"></a><b>8.3.</b></td><td align="left" valign="top"><p>
2308 How do I get support for my board added to Poky?
2309 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2310 There are two main ways to get a board supported in Poky;
2311 </p><div class="itemizedlist"><ul type="disc"><li><p>
2312 Send us the board if we don't have it yet
2313 </p></li><li><p>
2314 Send us bitbake recipes if you have them (see the Poky handbook to find out how to create recipes)
2315 </p></li></ul></div><p>
2316 Usually if it's not a completely exotic board then adding support in Poky should be fairly straightforward.
2317 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089143"></a><a name="id1089144"></a><b>8.4.</b></td><td align="left" valign="top"><p>
2318 Are there any products running poky ?
2319 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2320 The <a href="http://vernier.com/labquest/" target="_top">Vernier Labquest</a> is using Poky (for more about the Labquest see the case study at OpenedHand). There are a number of pre-production devices using Poky and we will announce those as soon as they are released.
2321 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089157"></a><a name="id1089158"></a><b>8.5.</b></td><td align="left" valign="top"><p>
2322 What is the Poky output ?
2323 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2324 The output of a Poky build will depend on how it was started, as the same set of recipes can be used to output various formats. Usually the output is a flashable image ready for the target device.
2325 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089167"></a><a name="id1089168"></a><b>8.6.</b></td><td align="left" valign="top"><p>
2326 How do I add my package to Poky?
2327 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2328 To add a package you need to create a bitbake recipe - see the Poky handbook to find out how to create a recipe.
2329 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089176"></a><a name="id1089177"></a><b>8.7.</b></td><td align="left" valign="top"><p>
2330 Do I have to reflash my entire board with a new poky image when recompiling a package?
2331 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2332 Poky can build packages in various formats, ipkg, Debian package, or RPM. The package can then be upgraded using the package tools on the device, much like on a desktop distribution like Ubuntu or Fedora.
2333 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089187"></a><a name="id1089188"></a><b>8.8.</b></td><td align="left" valign="top"><p>
2334 What is GNOME Mobile? What's the difference between GNOME Mobile and GNOME?
2335 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2336 <a href="http://www.gnome.org/mobile/" target="_top">GNOME Mobile</a> is a subset of the GNOME platform targeted at mobile and embedded devices. The the main difference between GNOME Mobile and standard GNOME is that desktop-orientated libraries have been removed, along with deprecated libraries, creating a much smaller footprint.
2337 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089203"></a><a name="id1089204"></a><b>8.9.</b></td><td align="left" valign="top"><p>
2338 How do I make Poky work in RHEL/CentOS?
2339 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2340 To get Poky working under RHEL/CentOS 5.1 you need to first install some required packages. The standard CentOS packages needed are:
2341 </p><div class="itemizedlist"><ul type="disc"><li><p>
2342 "Development tools" (selected during installation)
2343 </p></li><li><p>
2344 texi2html
2345 </p></li><li><p>
2346 compat-gcc-34
2347 </p></li></ul></div><p>
2348 </p><p>
2349 On top of those the following external packages are needed:
2350 </p><div class="itemizedlist"><ul type="disc"><li><p>
2351 python-sqlite2 from <a href="http://dag.wieers.com/rpm/packages/python-sqlite2/" target="_top">DAG
2352 repository</a>
2353 </p></li><li><p>
2354 help2man from <a href="http://centos.karan.org/el5/extras/testing/i386/RPMS/help2man-1.33.1-2.noarch.rpm" target="_top">Karan
2355 repository</a>
2356 </p></li></ul></div><p>
2357 </p><p>
2358 Once these packages are installed Poky will be able to build standard images however there
2359 may be a problem with QEMU segfaulting. You can either disable the generation of binary
2360 locales by setting <em class="glossterm"><a href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">ENABLE_BINARY_LOCALE_GENERATION</a>
2361 </em> to "0" or remove the linux-2.6-execshield.patch from the kernel and rebuild
2362 it since its that patch which causes the problems with QEMU.
2363 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089270"></a><a name="id1089271"></a><b>8.10.</b></td><td align="left" valign="top"><p>
2364 I see lots of 404 responses for files on http://folks.o-hand.com/~richard/poky/sources/*. Is something wrong?
2365 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2366 Nothing is wrong, Poky will check any configured source mirrors before downloading
2367 from the upstream sources. It does this searching for both source archives and
2368 pre-checked out versions of SCM managed software. This is so in large installations,
2369 it can reduce load on the SCM servers themselves. The address above is one of the
2370 default mirrors configured into standard Poky so if an upstream source disappears,
2371 we can place sources there so builds continue to work.
2372 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089285"></a><a name="id1089286"></a><b>8.11.</b></td><td align="left" valign="top"><p>
2373 I have a machine specific data in a package for one machine only but the package is
2374 being marked as machine specific in all cases, how do I stop it?
2375 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2376 Set <em class="glossterm"><a href="#var-SRC_URI_OVERRIDES_PACKAGE_ARCH" title="SRC_URI_OVERRIDES_PACKAGE_ARCH">SRC_URI_OVERRIDES_PACKAGE_ARCH</a>
2377 </em> = "0" in the .bb file but make sure the package is manually marked as
2378 machine specific in the case that needs it. The code which handles <em class="glossterm"><a href="#var-SRC_URI_OVERRIDES_PACKAGE_ARCH" title="SRC_URI_OVERRIDES_PACKAGE_ARCH">SRC_URI_OVERRIDES_PACKAGE_ARCH</a></em>
2379 is in base.bbclass.
2380 </p></td></tr></tbody></table></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="resources"></a>Appendix 9. Contributing to Poky</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#resources-intro">1. Introduction</a></span></dt><dt><span class="section"><a href="#resources-bugtracker">2. Bugtracker</a></span></dt><dt><span class="section"><a href="#resources-mailinglist">3. Mailing list</a></span></dt><dt><span class="section"><a href="#resources-irc">4. IRC</a></span></dt><dt><span class="section"><a href="#resources-links">5. Links</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-intro"></a>1. Introduction</h2></div></div></div><p>
2381 We're happy for people to experiment with Poky and there are a number of places to
2382 find help if you run into difficulties or find bugs. To find out how to download
2383 source code see the <a href="#intro-getit" title="5. Obtaining Poky">Obtaining Poky</a> section of
2384 the Introduction.
2385 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-bugtracker"></a>2. Bugtracker</h2></div></div></div><p>
2386 Problems with Poky should be reported in the
2387 <a href="http://bugzilla.o-hand.com/" target="_top">bug tracker</a>.
2388 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-mailinglist"></a>3. Mailing list</h2></div></div></div><p>
2389 To subscribe to the mailing list send mail to:
2390 </p><p>
2391 </p><pre class="literallayout">
2392poky+subscribe &lt;at&gt; openedhand &lt;dot&gt; com
2393 </pre><p>
2394 </p><p>
2395 Then follow the simple instructions in subsequent reply. Archives are
2396 available <a href="http://lists.o-hand.com/poky/" target="_top">here</a>.
2397 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-irc"></a>4. IRC</h2></div></div></div><p>
2398 Join #poky on freenode.
2399 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-links"></a>5. Links</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
2400 <a href="http://pokylinux.org" target="_top">The Poky website</a>
2401 </p></li><li><p>
2402 <a href="http://www.openedhand.com/" target="_top">OpenedHand</a> - The
2403 company behind Poky.
2404 </p></li><li><p>
2405 <a href="http://www.openembedded.org/" target="_top">OpenEmbedded</a>
2406 - The upstream generic embedded distribution Poky derives
2407 from (and contributes to).
2408 </p></li><li><p>
2409 <a href="http://developer.berlios.de/projects/bitbake/" target="_top">Bitbake</a>
2410 - The tool used to process Poky metadata.
2411 </p></li><li><p>
2412 <a href="http://bitbake.berlios.de/manual/" target="_top">Bitbake User
2413 Manual</a>
2414 </p></li><li><p>
2415 <a href="http://pimlico-project.org/" target="_top">Pimlico</a> - A
2416 suite of lightweight Personal Information Management (PIM)
2417 applications designed primarily for handheld and mobile
2418 devices.
2419 </p></li><li><p>
2420 <a href="http://fabrice.bellard.free.fr/qemu/" target="_top">QEMU</a>
2421 - An open source machine emulator and virtualizer.
2422 </p></li></ul></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="contact"></a>Appendix 10. OpenedHand Contact Information</h2></div></div></div><div class="literallayout"><p><br>
2423OpenedHand Ltd<br>
2424Unit R, Homesdale Business Center<br>
2425216-218 Homesdale Rd<br>
2426Bromley, BR1 2QZ<br>
2427England<br>
2428+44 (0) 208 819 6559<br>
2429info@openedhand.com</p></div></div><div class="index"><div class="titlepage"><div><div><h2 class="title"><a name="index"></a>Index</h2></div></div></div><div class="index"></div></div></div></body></html>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-03 19:13:23 +0000