summaryrefslogtreecommitdiffstats
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 @@
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, ARM, MIPS, PowerPC hardware and device virtulisation</para>
34 </listitem>
35 </itemizedlist>
36
37 <para>
38 Poky is primarily a platform builder which generates filesystem images
39 based on open source software such as the Kdrive X server, the Matchbox
40 window manager, the GTK+ toolkit and the D-Bus message bus system. Images
41 for many kinds of devices can be generated, however the standard example
42 machines target QEMU full system emulation(x86, ARM, MIPS and PowerPC) and the ARM based
43 Sharp Zaurus series of devices. Poky's ability to boot inside a QEMU
44 emulator makes it particularly suitable as a test platform for development
45 of embedded software.
46 </para>
47
48 <para>
49 An important component integrated within Poky is Sato, a GNOME Mobile
50 based user interface environment.
51 It is designed to work well with screens at very high DPI and restricted
52 size, such as those often found on smartphones and PDAs. It is coded with
53 focus on efficiency and speed so that it works smoothly on hand-held and
54 other embedded hardware. It will sit neatly on top of any device
55 using the GNOME Mobile stack, providing a well defined user experience.
56 </para>
57
58 <screenshot>
59 <mediaobject>
60 <imageobject>
61 <imagedata fileref="screenshots/ss-sato.png" format="PNG" align='center' scalefit='1' width="100%" contentdepth="100%"/>
62 </imageobject>
63 <caption>
64 <para>The Sato Desktop - A screenshot from a machine running a Poky built image</para>
65 </caption>
66 </mediaobject>
67 </screenshot>
68
69
70 <para>
71
72 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>.
73
74 </para>
75</section>
76
77<section id='intro-manualoverview'>
78 <title>Documentation Overview</title>
79
80 <para>
81 The handbook is split into sections covering different aspects of Poky.
82 The <link linkend='usingpoky'>'Using Poky' section</link> gives an overview
83 of the components that make up Poky followed by information about using and
84 debugging the Poky build system. The <link linkend='extendpoky'>'Extending Poky' section</link>
85 gives information about how to extend and customise Poky along with advice
86 on how to manage these changes.
87 The <link linkend='bsp'>'Board Support Packages (BSP) - Developers Guide' section</link>
88 gives information about how to develop BSP such as the common layout, the
89 software hardware configuration options etc.
90 The <link linkend='platdev'>'Platform Development with Poky'
91 section</link> gives information about interaction between Poky and target
92 hardware for common platform development tasks such as software development,
93 debugging and profiling. The rest of the manual
94 consists of several reference sections each giving details on a specific
95 section of Poky functionality.
96 </para>
97
98 <para>
99 This manual applies to Poky Release 3.3 (Green).
100 </para>
101
102</section>
103
104
105<section id='intro-requirements'>
106 <title>System Requirements</title>
107
108 <para>
109 We recommend Debian-based distributions, in particular a recent Ubuntu
110 release (10.04 or newer), as the host system for Poky. Nothing in Poky is
111 distribution specific and
112 other distributions will most likely work as long as the appropriate
113 prerequisites are installed - we know of Poky being used successfully on Redhat,
114 SUSE, Gentoo and Slackware host systems.
115 </para>
116
117 <para>On a Debian-based system, you need the following packages installed:</para>
118
119 <itemizedlist>
120 <listitem>
121 <para>build-essential</para>
122 </listitem>
123 <listitem>
124 <para>python (version 2.6 or later)</para>
125 </listitem>
126 <listitem>
127 <para>diffstat</para>
128 </listitem>
129 <listitem>
130 <para>texinfo</para>
131 </listitem>
132 <listitem>
133 <para>texi2html</para>
134 </listitem>
135 <listitem>
136 <para>cvs</para>
137 </listitem>
138 <listitem>
139 <para>subversion</para>
140 </listitem>
141 <listitem>
142 <para>wget</para>
143 </listitem>
144 <listitem>
145 <para>gawk</para>
146 </listitem>
147 <listitem>
148 <para>help2man</para>
149 </listitem>
150 <listitem>
151 <para>chrpath</para>
152 </listitem>
153 <listitem>
154 <para>mercurial</para>
155 </listitem>
156 </itemizedlist>
157 <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>
158 <itemizedlist>
159 <listitem>
160 <para>libgl1-mesa-dev</para>
161 </listitem>
162 <listitem>
163 <para>libglu1-mesa-dev</para>
164 </listitem>
165 <listitem>
166 <para>libsdl1.2-dev</para>
167 </listitem>
168 <listitem>
169 <para>bochsbios (only to run qemux86 images)</para>
170 </listitem>
171 </itemizedlist>
172
173 <para>
174 Debian users can add debian.o-hand.com to their APT sources (See
175 <ulink url='http://debian.o-hand.com'/>
176 for instructions on doing this) and then run <command>
177 "apt-get install qemu poky-depends poky-scripts"</command> which will
178 automatically install all these dependencies. Virtualisation images with
179 Poky and all dependencies can also easily be built if required.
180 </para>
181
182 <para>
183 Poky can use a system provided QEMU or build its own depending on how it's
184 configured. See the options in <filename>local.conf</filename> for more details.
185 </para>
186</section>
187
188<section id='intro-quickstart'>
189 <title>Quick Start</title>
190
191 <section id='intro-quickstart-build'>
192 <title>Building and Running an Image</title>
193
194 <para>
195 If you want to try Poky, you can do so in a few commands. The example below
196 checks out the Poky source code, sets up a build environment, builds an
197 image and then runs that image under the QEMU emulator in x86 system emulation mode:
198 </para>
199
200 <para>
201 <literallayout class='monospaced'>
202$ wget http://pokylinux.org/releases/poky-green-3.3.tar.bz2
203$ tar xjvf poky-green-3.3.tar.bz2
204$ cd green-3.3/
205$ source poky-init-build-env
206$ bitbake poky-image-sato
207$ bitbake qemu-native
208$ runqemu qemux86
209</literallayout>
210 </para>
211
212 <note>
213 <para>
214 This process will need Internet access, about 20 GB of disk space
215 available, and you should expect the build to take about 4 - 5 hours since
216 it is building an entire Linux system from source including the toolchain!
217 </para>
218 </note>
219
220 <para>
221 To build for other machines see the <glossterm><link
222 linkend='var-MACHINE'>MACHINE</link></glossterm> variable in build/conf/local.conf.
223 This file contains other useful configuration information and the default version
224 has examples of common setup needs and is worth
225 reading. To take advantage of multiple processor cores to speed up builds for example, set the
226 <glossterm><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm>
227 and <glossterm><link linkend='var-PARALLEL_MAKE'>PARALLEL_MAKE</link></glossterm> variables.
228
229 The images/kernels built by Poky are placed in the <filename class="directory">tmp/deploy/images</filename>
230 directory.
231 </para>
232
233 <para>
234 You could also run <command>"poky-qemu zImage-qemuarm.bin poky-image-sato-qemuarm.ext2"
235 </command> within the images directory if you have the poky-scripts Debian package
236 installed from debian.o-hand.com. This allows the QEMU images to be used standalone
237 outside the Poky build environment.
238 </para>
239 <para>
240 To setup networking within QEMU see the <link linkend='usingpoky-install-qemu-networking'>
241 QEMU/USB networking with IP masquerading</link> section.
242 </para>
243
244 </section>
245 <section id='intro-quickstart-qemu'>
246 <title>Downloading and Using Prebuilt Images</title>
247
248 <para>
249 Prebuilt images from Poky are also available if you just want to run the system
250 under QEMU. To use these you need to:
251 </para>
252
253 <itemizedlist>
254 <listitem>
255 <para>
256 Add debian.o-hand.com to your APT sources (See
257 <ulink url='http://debian.o-hand.com'/> for instructions on doing this)
258 </para>
259 </listitem>
260 <listitem>
261 <para>Install patched QEMU and poky-scripts:</para>
262 <para>
263 <literallayout class='monospaced'>
264$ apt-get install qemu poky-scripts
265</literallayout>
266 </para>
267 </listitem>
268
269 <listitem>
270 <para>
271 Download a Poky QEMU release kernel (*zImage*qemu*.bin) and compressed
272 filesystem image (poky-image-*-qemu*.ext2.bz2) which
273 you'll need to decompress with 'bzip2 -d'. These are available from the
274 <ulink url='http://pokylinux.org/releases/green-3.3/'>last release</ulink>
275 or from the <ulink url='http://autobuilder.pokylinux.org/'>autobuilder</ulink>.
276 </para>
277 </listitem>
278 <listitem>
279 <para>Start the image:</para>
280 <para>
281 <literallayout class='monospaced'>
282$ poky-qemu &lt;kernel&gt; &lt;image&gt;
283</literallayout>
284 </para>
285 </listitem>
286 </itemizedlist>
287
288 <note><para>
289 A patched version of QEMU is required at present. A suitable version is available from
290 <ulink url='http://debian.o-hand.com'/>, it can be built
291 by poky (bitbake qemu-native) or can be downloaded/built as part of the toolchain/SDK tarballs.
292 </para></note>
293
294 </section>
295</section>
296
297<section id='intro-getit'>
298 <title>Obtaining Poky</title>
299
300 <section id='intro-getit-releases'>
301 <title>Releases</title>
302
303 <para>Periodically, we make releases of Poky and these are available
304 at <ulink url='http://pokylinux.org/releases/'/>.
305 These are more stable and tested than the nightly development images.</para>
306 </section>
307
308 <section id='intro-getit-nightly'>
309 <title>Nightly Builds</title>
310
311 <para>
312 We make nightly builds of Poky for testing purposes and to make the
313 latest developments available. The output from these builds is available
314 at <ulink url='http://autobuilder.pokylinux.org/'/>
315 where the numbers increase for each subsequent build and can be used to reference it.
316 </para>
317
318 <para>
319 Automated builds are available for "standard" Poky and for Poky SDKs and toolchains as well
320 as any testing versions we might have such as poky-bleeding. The toolchains can
321 be used either as external standalone toolchains or can be combined with Poky as a
322 prebuilt toolchain to reduce build time. Using the external toolchains is simply a
323 case of untarring the tarball into the root of your system (it only creates files in
324 <filename class="directory">/opt/poky</filename>) and then enabling the option
325 in <filename>local.conf</filename>.
326 </para>
327
328 </section>
329
330 <section id='intro-getit-dev'>
331 <title>Development Checkouts</title>
332
333 <para>
334 Poky is available from our GIT repository located at
335 git://git.pokylinux.org/poky.git; a web interface to the repository
336 can be accessed at <ulink url='http://git.pokylinux.org/'/>.
337 </para>
338
339 <para>
340 The 'master' is where the deveopment work takes place and you should use this if you're
341 after to work with the latest cutting edge developments. It is possible trunk
342 can suffer temporary periods of instability while new features are developed and
343 if this is undesireable we recommend using one of the release branches.
344 </para>
345 </section>
346
347</section>
348
349</chapter>
350<!--
351vim: expandtab tw=80 ts=4
352-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-04-22 20:43:08 +0000