From 22083287912ebd552e33b79f7c567bc966376d43 Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Fri, 15 Oct 2010 11:55:59 +0100 Subject: handbook: Move into documentation directory Signed-off-by: Richard Purdie --- documentation/poky-ref-manual/introduction.xml | 352 +++++++++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 documentation/poky-ref-manual/introduction.xml (limited to 'documentation/poky-ref-manual/introduction.xml') diff --git a/documentation/poky-ref-manual/introduction.xml b/documentation/poky-ref-manual/introduction.xml new file mode 100644 index 000000000..0b407a142 --- /dev/null +++ b/documentation/poky-ref-manual/introduction.xml @@ -0,0 +1,352 @@ + + + +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, ARM, MIPS, PowerPC 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(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. + + + + 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 and is also backed up by commercial organisations including Intel Corporation. + + +
+ +
+ 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 'Board Support Packages (BSP) - Developers Guide' section + gives information about how to develop BSP such as the common layout, the + software hardware configuration options etc. + 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.3 (Green). + + +
+ + +
+ System Requirements + + + 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. + + + On a Debian-based system, you need the following packages installed: + + + + build-essential + + + python (version 2.6 or later) + + + diffstat + + + texinfo + + + texi2html + + + cvs + + + subversion + + + wget + + + gawk + + + help2man + + + chrpath + + + mercurial + + + Furthermore if you wish to run an emulated Poky image using QEMU (as in the quickstart below) you will need the following packages installed: + + + libgl1-mesa-dev + + + libglu1-mesa-dev + + + libsdl1.2-dev + + + 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. Virtualisation images with + Poky and all dependencies can also easily be built 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 x86 system emulation mode: + + + + +$ 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 + + + + + + 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! + + + + + To build for other machines see the MACHINE 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 + BB_NUMBER_THREADS + and PARALLEL_MAKE variables. + + 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 increase for each subsequent build and can be used to reference it. + + + + 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 + /opt/poky) and then enabling the option + in local.conf. + + +
+ +
+ Development Checkouts + + + 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 . + + + + 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. + +
+ +
+ + + -- cgit v1.2.3