Introduction

What is Poky? Poky is an open source platform build tool. It is a complete software development environment for the creation of Linux devices. It aids the design, development, building, debugging, simulation and testing of complete modern software stacks using Linux, the X Window System and GNOME Mobile based application frameworks. It is based on OpenEmbedded but has been customised with a particular focus. Poky was setup to: Provide an open source Linux, X11, Matchbox, GTK+, Pimlico, Clutter, and other GNOME Mobile technologies based full platform build and development tool. Create a focused, stable, subset of OpenEmbedded that can be easily and reliably built and developed upon. Fully support a wide range of x86 and ARM hardware and device virtulisation Poky is primarily a platform builder which generates filesystem images based on open source software such as the Kdrive X server, the Matchbox window manager, the GTK+ toolkit and the D-Bus message bus system. Images for many kinds of devices can be generated, however the standard example machines target QEMU full system emulation (both x86 and ARM) and the ARM based Sharp Zaurus series of devices. Poky's ability to boot inside a QEMU emulator makes it particularly suitable as a test platform for development of embedded software. An important component integrated within Poky is Sato, a GNOME Mobile based user interface environment. It is designed to work well with screens at very high DPI and restricted size, such as those often found on smartphones and PDAs. It is coded with focus on efficiency and speed so that it works smoothly on hand-held and other embedded hardware. It will sit neatly on top of any device using the GNOME Mobile stack, providing a well defined user experience. The Sato Desktop - A screenshot from a machine running a Poky built image Poky has a growing open source community backed up by commercial support provided by the principle developer and maintainer of Poky, OpenedHand Ltd.

Documentation Overview The handbook is split into sections covering different aspects of Poky. The 'Using Poky' section gives an overview of the components that make up Poky followed by information about using and debugging the Poky build system. The 'Extending Poky' section gives information about how to extend and customise Poky along with advice on how to manage these changes. The 'Platform Development with Poky' section gives information about interaction between Poky and target hardware for common platform development tasks such as software development, debugging and profiling. The rest of the manual consists of several reference sections each giving details on a specific section of Poky functionality. This manual applies to Poky Release 3.1 (Pinky).

System Requirements We recommend Debian-based distributions, in particular a recent Ubuntu release (7.04 or newer), as the host system for Poky. Nothing in Poky is distribution specific and other distributions will most likely work as long as the appropriate prerequisites are installed - we know of Poky being used successfully on Redhat, SUSE, Gentoo and Slackware host systems. On a Debian-based system, you need the following packages installed: build-essential python diffstat texinfo texi2html cvs subversion wget gawk help2man bochsbios (only to run qemux86 images) Debian users can add debian.o-hand.com to their APT sources (See for instructions on doing this) and then run "apt-get install qemu poky-depends poky-scripts" which will automatically install all these dependencies. OpenedHand can also provide VMware images with Poky and all dependencies pre-installed if required. Poky can use a system provided QEMU or build its own depending on how it's configured. See the options in local.conf for more details.

Quick Start

Building and Running an Image If you want to try Poky, you can do so in a few commands. The example below checks out the Poky source code, sets up a build environment, builds an image and then runs that image under the QEMU emulator in ARM system emulation mode: $ wget http://pokylinux.org/releases/pinky-3.1.tar.gz $ tar zxvf pinky-3.1.tar.gz $ cd pinky-3.1/ $ source poky-init-build-env $ bitbake poky-image-sato $ runqemu qemuarm This process will need Internet access, about 3 GB of disk space available, and you should expect the build to take about 4 - 5 hours since it is building an entire Linux system from source including the toolchain! To build for other machines see the MACHINE variable in build/conf/local.conf which also contains other configuration information. The images/kernels built by Poky are placed in the tmp/deploy/images directory. You could also run "poky-qemu zImage-qemuarm.bin poky-image-sato-qemuarm.ext2" within the images directory if you have the poky-scripts Debian package installed from debian.o-hand.com. This allows the QEMU images to be used standalone outside the Poky build environment. To setup networking within QEMU see the QEMU/USB networking with IP masquerading section.

Downloading and Using Prebuilt Images Prebuilt images from Poky are also available if you just want to run the system under QEMU. To use these you need to: Add debian.o-hand.com to your APT sources (See for instructions on doing this) Install patched QEMU and poky-scripts: $ apt-get install qemu poky-scripts Download a Poky QEMU release kernel (*zImage*qemu*.bin) and compressed filesystem image (poky-image-*-qemu*.ext2.bz2) which you'll need to decompress with 'bzip2 -d'. These are available from the last release or from the autobuilder. Start the image: $ poky-qemu <kernel> <image> A patched version of QEMU is required at present. A suitable version is available from , it can be built by poky (bitbake qemu-native) or can be downloaded/built as part of the toolchain/SDK tarballs.

Obtaining Poky

Releases Periodically, we make releases of Poky and these are available at . These are more stable and tested than the nightly development images.

Nightly Builds We make nightly builds of Poky for testing purposes and to make the latest developments available. The output from these builds is available at where the numbers represent the svn revision the builds were made from. Automated builds are available for "standard" Poky and for Poky SDKs and toolchains as well as any testing versions we might have such as poky-bleeding. The toolchains can be used either as external standalone toolchains or can be combined with Poky as a prebuilt toolchain to reduce build time. Using the external toolchains is simply a case of untarring the tarball into the root of your system (it only creates files in /usr/local/poky) and then enabling the option in local.conf.

Development Checkouts Poky is available from our SVN repository located at http://svn.o-hand.com/repos/poky/trunk; a web interface to the repository can be accessed at . 'trunk' is where the deveopment work takes place and you should use this if you're after to work with the latest cutting edge developments. It is possible trunk can suffer temporary periods of instability while new features are developed and if this is undesireable we recommend using one of the release branches.