diff options
Diffstat (limited to 'handbook/introduction.xml')
| -rw-r--r-- | handbook/introduction.xml | 331 |
1 files changed, 331 insertions, 0 deletions
diff --git a/handbook/introduction.xml b/handbook/introduction.xml new file mode 100644 index 0000000000..19a71fe327 --- /dev/null +++ b/handbook/introduction.xml @@ -0,0 +1,331 @@ +<!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><ulink url='http://www.o-hand.com'>OpenedHand</ulink> is the principle developer and maintainer of Poky and uses it to:</para> + + <itemizedlist> + <listitem> + <para>Provide <ulink url='http://www.o-hand.com'>OpenedHand</ulink> with stable R&D platform we can build and develop upon.</para> + </listitem> + <listitem> + <para> + Provide a testbed and showcase for OpenedHand's software products + (such as the <ulink url='http://www.matchbox-project.org/'>Matchbox</ulink>, <ulink url='http://www.clutter-project.org/'>Clutter</ulink> and + <ulink url='http://www.pimlico-project.org/'>Pimlico</ulink> software packages and + Sato, the default user interface in Poky). + </para> + </listitem> + <listitem> + <para>Provide a supported base we can supply to our clients for building and developing their customised platforms.</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> + + <para> + + Poky has a growing open source community backed up by commercial support provided by <ulink url="http://o-hand.com/">OpenedHand</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 +--> |