summaryrefslogtreecommitdiffstats
path: root/handbook/introduction.xml
diff options
context:
space:
mode:
Diffstat (limited to 'handbook/introduction.xml')
-rw-r--r--handbook/introduction.xml331
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 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<chapter id='intro'>
5<title>Introduction</title>
6
7<section id='intro-what-is'>
8 <title>What is Poky?</title>
9
10 <para>
11
12 Poky is an open source platform build tool. It is a complete
13 software development environment for the creation of Linux
14 devices. It aids the design, development, building, debugging,
15 simulation and testing of complete modern software stacks
16 using Linux, the X Window System and GNOME Mobile
17 based application frameworks. It is based on <ulink
18 url='http://openembedded.org/'>OpenEmbedded</ulink> but has
19 been customised with a particular focus.
20
21 </para>
22
23 <para> Poky was setup to:</para>
24
25 <itemizedlist>
26 <listitem>
27 <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>
28 </listitem>
29 <listitem>
30 <para>Create a focused, stable, subset of OpenEmbedded that can be easily and reliably built and developed upon.</para>
31 </listitem>
32 <listitem>
33 <para>Fully support a wide range of x86 and ARM hardware and device virtulisation</para>
34 </listitem>
35 </itemizedlist>
36
37 <para><ulink url='http://www.o-hand.com'>OpenedHand</ulink> is the principle developer and maintainer of Poky and uses it to:</para>
38
39 <itemizedlist>
40 <listitem>
41 <para>Provide <ulink url='http://www.o-hand.com'>OpenedHand</ulink> with stable R&amp;D platform we can build and develop upon.</para>
42 </listitem>
43 <listitem>
44 <para>
45 Provide a testbed and showcase for OpenedHand's software products
46 (such as the <ulink url='http://www.matchbox-project.org/'>Matchbox</ulink>, <ulink url='http://www.clutter-project.org/'>Clutter</ulink> and
47 <ulink url='http://www.pimlico-project.org/'>Pimlico</ulink> software packages and
48 Sato, the default user interface in Poky).
49 </para>
50 </listitem>
51 <listitem>
52 <para>Provide a supported base we can supply to our clients for building and developing their customised platforms.</para>
53 </listitem>
54 </itemizedlist>
55
56 <para>
57 Poky is primarily a platform builder which generates filesystem images
58 based on open source software such as the Kdrive X server, the Matchbox
59 window manager, the GTK+ toolkit and the D-Bus message bus system. Images
60 for many kinds of devices can be generated, however the standard example
61 machines target QEMU full system emulation (both x86 and ARM) and the ARM based
62 Sharp Zaurus series of devices. Poky's ability to boot inside a QEMU
63 emulator makes it particularly suitable as a test platform for development
64 of embedded software.
65 </para>
66
67 <para>
68 An important component integrated within Poky is Sato, a GNOME Mobile
69 based user interface environment.
70 It is designed to work well with screens at very high DPI and restricted
71 size, such as those often found on smartphones and PDAs. It is coded with
72 focus on efficiency and speed so that it works smoothly on hand-held and
73 other embedded hardware. It will sit neatly on top of any device
74 using the GNOME Mobile stack, providing a well defined user experience.
75 </para>
76
77 <para>
78
79 Poky has a growing open source community backed up by commercial support provided by <ulink url="http://o-hand.com/">OpenedHand</ulink>.
80
81 </para>
82</section>
83
84<section id='intro-manualoverview'>
85 <title>Documentation Overview</title>
86
87 <para>
88 The handbook is split into sections covering different aspects of Poky.
89 The <link linkend='usingpoky'>'Using Poky' section</link> gives an overview
90 of the components that make up Poky followed by information about using and
91 debugging the Poky build system. The <link linkend='extendpoky'>'Extending Poky' section</link>
92 gives information about how to extend and customise Poky along with advice
93 on how to manage these changes. The <link linkend='platdev'>'Platform Development with Poky'
94 section</link> gives information about interaction between Poky and target
95 hardware for common platform development tasks such as software development,
96 debugging and profiling. The rest of the manual
97 consists of several reference sections each giving details on a specific
98 section of Poky functionality.
99 </para>
100
101 <para>
102 This manual applies to Poky Release 3.1 (Pinky).
103 </para>
104
105</section>
106
107
108<section id='intro-requirements'>
109 <title>System Requirements</title>
110
111 <para>
112 We recommend Debian-based distributions, in particular a recent Ubuntu
113 release (7.04 or newer), as the host system for Poky. Nothing in Poky is
114 distribution specific and
115 other distributions will most likely work as long as the appropriate
116 prerequisites are installed - we know of Poky being used successfully on Redhat,
117 SUSE, Gentoo and Slackware host systems.
118 </para>
119
120 <para>On a Debian-based system, you need the following packages installed:</para>
121
122 <itemizedlist>
123 <listitem>
124 <para>build-essential</para>
125 </listitem>
126 <listitem>
127 <para>python</para>
128 </listitem>
129 <listitem>
130 <para>diffstat</para>
131 </listitem>
132 <listitem>
133 <para>texinfo</para>
134 </listitem>
135 <listitem>
136 <para>texi2html</para>
137 </listitem>
138 <listitem>
139 <para>cvs</para>
140 </listitem>
141 <listitem>
142 <para>subversion</para>
143 </listitem>
144 <listitem>
145 <para>wget</para>
146 </listitem>
147 <listitem>
148 <para>gawk</para>
149 </listitem>
150 <listitem>
151 <para>help2man</para>
152 </listitem>
153 <listitem>
154 <para>bochsbios (only to run qemux86 images)</para>
155 </listitem>
156 </itemizedlist>
157
158 <para>
159 Debian users can add debian.o-hand.com to their APT sources (See
160 <ulink url='http://debian.o-hand.com'/>
161 for instructions on doing this) and then run <command>
162 "apt-get install qemu poky-depends poky-scripts"</command> which will
163 automatically install all these dependencies. OpenedHand can also provide
164 VMware images with Poky and all dependencies pre-installed if required.
165 </para>
166
167 <para>
168 Poky can use a system provided QEMU or build its own depending on how it's
169 configured. See the options in <filename>local.conf</filename> for more details.
170 </para>
171</section>
172
173<section id='intro-quickstart'>
174 <title>Quick Start</title>
175
176 <section id='intro-quickstart-build'>
177 <title>Building and Running an Image</title>
178
179 <para>
180 If you want to try Poky, you can do so in a few commands. The example below
181 checks out the Poky source code, sets up a build environment, builds an
182 image and then runs that image under the QEMU emulator in ARM system emulation mode:
183 </para>
184
185 <para>
186 <literallayout class='monospaced'>
187$ wget http://pokylinux.org/releases/pinky-3.1.tar.gz
188$ tar zxvf pinky-3.1.tar.gz
189$ cd pinky-3.1/
190$ source poky-init-build-env
191$ bitbake poky-image-sato
192$ runqemu qemuarm
193</literallayout>
194 </para>
195
196 <note>
197 <para>
198 This process will need Internet access, about 3 GB of disk space
199 available, and you should expect the build to take about 4 - 5 hours since
200 it is building an entire Linux system from source including the toolchain!
201 </para>
202 </note>
203
204 <para>
205 To build for other machines see the <glossterm><link
206 linkend='var-MACHINE'>MACHINE</link></glossterm> variable in build/conf/local.conf
207 which also contains other configuration information. The images/kernels built
208 by Poky are placed in the <filename class="directory">tmp/deploy/images</filename>
209 directory.
210 </para>
211
212 <para>
213 You could also run <command>"poky-qemu zImage-qemuarm.bin poky-image-sato-qemuarm.ext2"
214 </command> within the images directory if you have the poky-scripts Debian package
215 installed from debian.o-hand.com. This allows the QEMU images to be used standalone
216 outside the Poky build environment.
217 </para>
218 <para>
219 To setup networking within QEMU see the <link linkend='usingpoky-install-qemu-networking'>
220 QEMU/USB networking with IP masquerading</link> section.
221 </para>
222
223 </section>
224 <section id='intro-quickstart-qemu'>
225 <title>Downloading and Using Prebuilt Images</title>
226
227 <para>
228 Prebuilt images from Poky are also available if you just want to run the system
229 under QEMU. To use these you need to:
230 </para>
231
232 <itemizedlist>
233 <listitem>
234 <para>
235 Add debian.o-hand.com to your APT sources (See
236 <ulink url='http://debian.o-hand.com'/> for instructions on doing this)
237 </para>
238 </listitem>
239 <listitem>
240 <para>Install patched QEMU and poky-scripts:</para>
241 <para>
242 <literallayout class='monospaced'>
243$ apt-get install qemu poky-scripts
244</literallayout>
245 </para>
246 </listitem>
247
248 <listitem>
249 <para>
250 Download a Poky QEMU release kernel (*zImage*qemu*.bin) and compressed
251 filesystem image (poky-image-*-qemu*.ext2.bz2) which
252 you'll need to decompress with 'bzip2 -d'. These are available from the
253 <ulink url='http://pokylinux.org/releases/blinky-3.0/'>last release</ulink>
254 or from the <ulink url='http://pokylinux.org/autobuild/poky/'>autobuilder</ulink>.
255 </para>
256 </listitem>
257 <listitem>
258 <para>Start the image:</para>
259 <para>
260 <literallayout class='monospaced'>
261$ poky-qemu &lt;kernel&gt; &lt;image&gt;
262</literallayout>
263 </para>
264 </listitem>
265 </itemizedlist>
266
267 <note><para>
268 A patched version of QEMU is required at present. A suitable version is available from
269 <ulink url='http://debian.o-hand.com'/>, it can be built
270 by poky (bitbake qemu-native) or can be downloaded/built as part of the toolchain/SDK tarballs.
271 </para></note>
272
273 </section>
274</section>
275
276<section id='intro-getit'>
277 <title>Obtaining Poky</title>
278
279 <section id='intro-getit-releases'>
280 <title>Releases</title>
281
282 <para>Periodically, we make releases of Poky and these are available
283 at <ulink url='http://pokylinux.org/releases/'/>.
284 These are more stable and tested than the nightly development images.</para>
285 </section>
286
287 <section id='intro-getit-nightly'>
288 <title>Nightly Builds</title>
289
290 <para>
291 We make nightly builds of Poky for testing purposes and to make the
292 latest developments available. The output from these builds is available
293 at <ulink url='http://pokylinux.org/autobuild/'/>
294 where the numbers represent the svn revision the builds were made from.
295 </para>
296
297 <para>
298 Automated builds are available for "standard" Poky and for Poky SDKs and toolchains as well
299 as any testing versions we might have such as poky-bleeding. The toolchains can
300 be used either as external standalone toolchains or can be combined with Poky as a
301 prebuilt toolchain to reduce build time. Using the external toolchains is simply a
302 case of untarring the tarball into the root of your system (it only creates files in
303 <filename class="directory">/usr/local/poky</filename>) and then enabling the option
304 in <filename>local.conf</filename>.
305 </para>
306
307 </section>
308
309 <section id='intro-getit-dev'>
310 <title>Development Checkouts</title>
311
312 <para>
313 Poky is available from our SVN repository located at
314 http://svn.o-hand.com/repos/poky/trunk; a web interface to the repository
315 can be accessed at <ulink url='http://svn.o-hand.com/view/poky/'/>.
316 </para>
317
318 <para>
319 'trunk' is where the deveopment work takes place and you should use this if you're
320 after to work with the latest cutting edge developments. It is possible trunk
321 can suffer temporary periods of instability while new features are developed and
322 if this is undesireable we recommend using one of the release branches.
323 </para>
324 </section>
325
326</section>
327
328</chapter>
329<!--
330vim: expandtab tw=80 ts=4
331-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-18 07:17:00 +0000