summaryrefslogtreecommitdiff
path: root/documentation/poky-ref-manual/introduction.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/poky-ref-manual/introduction.xml')
-rw-r--r--documentation/poky-ref-manual/introduction.xml352
1 files changed, 352 insertions, 0 deletions
diff --git a/documentation/poky-ref-manual/introduction.xml b/documentation/poky-ref-manual/introduction.xml
new file mode 100644
index 0000000000..0b407a142a
--- /dev/null
+++ b/documentation/poky-ref-manual/introduction.xml
@@ -0,0 +1,352 @@
+<!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, ARM, MIPS, PowerPC 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(x86, ARM, MIPS and PowerPC) 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" align='center' scalefit='1' width="100%" contentdepth="100%"/>
+ </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 and is also backed up by commercial organisations including <ulink url="http://www.intel.com/">Intel Corporation</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='bsp'>'Board Support Packages (BSP) - Developers Guide' section</link>
+ gives information about how to develop BSP such as the common layout, the
+ software hardware configuration options etc.
+ 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.3 (Green).
+ </para>
+
+</section>
+
+
+<section id='intro-requirements'>
+ <title>System Requirements</title>
+
+ <para>
+ We recommend Debian-based distributions, in particular a recent Ubuntu
+ release (10.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 (version 2.6 or later)</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>chrpath</para>
+ </listitem>
+ <listitem>
+ <para>mercurial</para>
+ </listitem>
+ </itemizedlist>
+ <para>Furthermore if you wish to run an emulated Poky image using <ulink url='http://qemu.org'>QEMU</ulink> (as in the quickstart below) you will need the following packages installed:</para>
+ <itemizedlist>
+ <listitem>
+ <para>libgl1-mesa-dev</para>
+ </listitem>
+ <listitem>
+ <para>libglu1-mesa-dev</para>
+ </listitem>
+ <listitem>
+ <para>libsdl1.2-dev</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. Virtualisation images with
+ Poky and all dependencies can also easily be built 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 x86 system emulation mode:
+ </para>
+
+ <para>
+ <literallayout class='monospaced'>
+$ wget http://pokylinux.org/releases/poky-green-3.3.tar.bz2
+$ tar xjvf poky-green-3.3.tar.bz2
+$ cd green-3.3/
+$ source poky-init-build-env
+$ bitbake poky-image-sato
+$ bitbake qemu-native
+$ runqemu qemux86
+</literallayout>
+ </para>
+
+ <note>
+ <para>
+ This process will need Internet access, about 20 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.
+ This file contains other useful configuration information and the default version
+ has examples of common setup needs and is worth
+ reading. To take advantage of multiple processor cores to speed up builds for example, set the
+ <glossterm><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm>
+ and <glossterm><link linkend='var-PARALLEL_MAKE'>PARALLEL_MAKE</link></glossterm> variables.
+
+ 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/green-3.3/'>last release</ulink>
+ or from the <ulink url='http://autobuilder.pokylinux.org/'>autobuilder</ulink>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Start the image:</para>
+ <para>
+ <literallayout class='monospaced'>
+$ poky-qemu &lt;kernel&gt; &lt;image&gt;
+</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://autobuilder.pokylinux.org/'/>
+ where the numbers increase for each subsequent build and can be used to reference it.
+ </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">/opt/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 GIT repository located at
+ git://git.pokylinux.org/poky.git; a web interface to the repository
+ can be accessed at <ulink url='http://git.pokylinux.org/'/>.
+ </para>
+
+ <para>
+ The 'master' 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
+-->