325 lines
12 KiB
XML
325 lines
12 KiB
XML
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<chapter id='intro'>
|
|
<title>Introduction</title>
|
|
|
|
<section id='intro-what-is'>
|
|
<title>What is Poky?</title>
|
|
|
|
<para>
|
|
|
|
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 <ulink
|
|
url='http://openembedded.org/'>OpenEmbedded</ulink> but has
|
|
been customised with a particular focus.
|
|
|
|
</para>
|
|
|
|
<para> Poky was setup to:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Provide an open source Linux, X11, Matchbox, GTK+, Pimlico, Clutter, and other <ulink url='http://gnome.org/mobile'>GNOME Mobile</ulink> technologies based full platform build and development tool.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Create a focused, stable, subset of OpenEmbedded that can be easily and reliably built and developed upon.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Fully support a wide range of x86 and ARM hardware and device virtulisation</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<screenshot>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="screenshots/ss-sato.png" format="PNG"/>
|
|
</imageobject>
|
|
<caption>
|
|
<para>The Sato Desktop - A screenshot from a machine running a Poky built image</para>
|
|
</caption>
|
|
</mediaobject>
|
|
</screenshot>
|
|
|
|
|
|
<para>
|
|
|
|
Poky has a growing open source community backed up by commercial support provided by the principle developer and maintainer of Poky, <ulink url="http://o-hand.com/">OpenedHand Ltd</ulink>.
|
|
|
|
</para>
|
|
</section>
|
|
|
|
<section id='intro-manualoverview'>
|
|
<title>Documentation Overview</title>
|
|
|
|
<para>
|
|
The handbook is split into sections covering different aspects of Poky.
|
|
The <link linkend='usingpoky'>'Using Poky' section</link> gives an overview
|
|
of the components that make up Poky followed by information about using and
|
|
debugging the Poky build system. The <link linkend='extendpoky'>'Extending Poky' section</link>
|
|
gives information about how to extend and customise Poky along with advice
|
|
on how to manage these changes. The <link linkend='platdev'>'Platform Development with Poky'
|
|
section</link> 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.
|
|
</para>
|
|
|
|
<para>
|
|
This manual applies to Poky Release 3.1 (Pinky).
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
<section id='intro-requirements'>
|
|
<title>System Requirements</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>On a Debian-based system, you need the following packages installed:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>build-essential</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>python</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>diffstat</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>texinfo</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>texi2html</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>cvs</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>subversion</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>wget</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>gawk</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>help2man</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>bochsbios (only to run qemux86 images)</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
Debian users can add debian.o-hand.com to their APT sources (See
|
|
<ulink url='http://debian.o-hand.com'/>
|
|
for instructions on doing this) and then run <command>
|
|
"apt-get install qemu poky-depends poky-scripts"</command> which will
|
|
automatically install all these dependencies. OpenedHand can also provide
|
|
VMware images with Poky and all dependencies pre-installed if required.
|
|
</para>
|
|
|
|
<para>
|
|
Poky can use a system provided QEMU or build its own depending on how it's
|
|
configured. See the options in <filename>local.conf</filename> for more details.
|
|
</para>
|
|
</section>
|
|
|
|
<section id='intro-quickstart'>
|
|
<title>Quick Start</title>
|
|
|
|
<section id='intro-quickstart-build'>
|
|
<title>Building and Running an Image</title>
|
|
|
|
<para>
|
|
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:
|
|
</para>
|
|
|
|
<para>
|
|
<literallayout class='monospaced'>
|
|
$ 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
|
|
</literallayout>
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
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!
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
To build for other machines see the <glossterm><link
|
|
linkend='var-MACHINE'>MACHINE</link></glossterm> variable in build/conf/local.conf
|
|
which also contains other configuration information. The images/kernels built
|
|
by Poky are placed in the <filename class="directory">tmp/deploy/images</filename>
|
|
directory.
|
|
</para>
|
|
|
|
<para>
|
|
You could also run <command>"poky-qemu zImage-qemuarm.bin poky-image-sato-qemuarm.ext2"
|
|
</command> 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.
|
|
</para>
|
|
<para>
|
|
To setup networking within QEMU see the <link linkend='usingpoky-install-qemu-networking'>
|
|
QEMU/USB networking with IP masquerading</link> section.
|
|
</para>
|
|
|
|
</section>
|
|
<section id='intro-quickstart-qemu'>
|
|
<title>Downloading and Using Prebuilt Images</title>
|
|
|
|
<para>
|
|
Prebuilt images from Poky are also available if you just want to run the system
|
|
under QEMU. To use these you need to:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Add debian.o-hand.com to your APT sources (See
|
|
<ulink url='http://debian.o-hand.com'/> for instructions on doing this)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Install patched QEMU and poky-scripts:</para>
|
|
<para>
|
|
<literallayout class='monospaced'>
|
|
$ apt-get install qemu poky-scripts
|
|
</literallayout>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
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
|
|
<ulink url='http://pokylinux.org/releases/blinky-3.0/'>last release</ulink>
|
|
or from the <ulink url='http://pokylinux.org/autobuild/poky/'>autobuilder</ulink>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Start the image:</para>
|
|
<para>
|
|
<literallayout class='monospaced'>
|
|
$ poky-qemu <kernel> <image>
|
|
</literallayout>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<note><para>
|
|
A patched version of QEMU is required at present. A suitable version is available from
|
|
<ulink url='http://debian.o-hand.com'/>, it can be built
|
|
by poky (bitbake qemu-native) or can be downloaded/built as part of the toolchain/SDK tarballs.
|
|
</para></note>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<section id='intro-getit'>
|
|
<title>Obtaining Poky</title>
|
|
|
|
<section id='intro-getit-releases'>
|
|
<title>Releases</title>
|
|
|
|
<para>Periodically, we make releases of Poky and these are available
|
|
at <ulink url='http://pokylinux.org/releases/'/>.
|
|
These are more stable and tested than the nightly development images.</para>
|
|
</section>
|
|
|
|
<section id='intro-getit-nightly'>
|
|
<title>Nightly Builds</title>
|
|
|
|
<para>
|
|
We make nightly builds of Poky for testing purposes and to make the
|
|
latest developments available. The output from these builds is available
|
|
at <ulink url='http://pokylinux.org/autobuild/'/>
|
|
where the numbers represent the svn revision the builds were made from.
|
|
</para>
|
|
|
|
<para>
|
|
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
|
|
<filename class="directory">/usr/local/poky</filename>) and then enabling the option
|
|
in <filename>local.conf</filename>.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id='intro-getit-dev'>
|
|
<title>Development Checkouts</title>
|
|
|
|
<para>
|
|
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 <ulink url='http://svn.o-hand.com/view/poky/'/>.
|
|
</para>
|
|
|
|
<para>
|
|
'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.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</chapter>
|
|
<!--
|
|
vim: expandtab tw=80 ts=4
|
|
-->
|