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 @@ | |||
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&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 <kernel> <image> | ||
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 | <!-- | ||
330 | vim: expandtab tw=80 ts=4 | ||
331 | --> | ||