diff options
Diffstat (limited to 'documentation/poky-ref-manual/introduction.xml')
-rw-r--r-- | documentation/poky-ref-manual/introduction.xml | 258 |
1 files changed, 32 insertions, 226 deletions
diff --git a/documentation/poky-ref-manual/introduction.xml b/documentation/poky-ref-manual/introduction.xml index 2683d01f22..301086a824 100644 --- a/documentation/poky-ref-manual/introduction.xml +++ b/documentation/poky-ref-manual/introduction.xml | |||
@@ -4,43 +4,39 @@ | |||
4 | <chapter id='intro'> | 4 | <chapter id='intro'> |
5 | <title>Introduction</title> | 5 | <title>Introduction</title> |
6 | 6 | ||
7 | <section id='intro-what-is'> | 7 | <section id='intro-welcome'> |
8 | <title>What is Poky?</title> | 8 | <title>Welcome to Poky!</title> |
9 | 9 | ||
10 | <para> | 10 | <para> |
11 | Poky is the the build tool in Yocto Project. | ||
12 | It is at the heart of Yocto Project. | ||
13 | You use Poky within Yocto Project to build the images (kernel software) for targeted hardware. | ||
14 | </para> | ||
11 | 15 | ||
12 | Poky is an open source platform build tool. It is a complete | 16 | <para> |
13 | software development environment for the creation of Linux | 17 | Before jumping into Poky you should have an understanding of Yokto Project. |
14 | devices. It aids the design, development, building, debugging, | 18 | Be sure you are familiar with the information in the Yocto Project Quick Start. |
15 | simulation and testing of complete modern software stacks | 19 | You can find this documentation on the public <ulink rul='http://yoctoproject.org/'>Yocto Project Website</ulink>. |
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> | 20 | </para> |
21 | </section> | ||
22 | 22 | ||
23 | <para> Poky was setup to:</para> | 23 | <section> |
24 | <title>What is Poky?</title> | ||
24 | 25 | ||
25 | <itemizedlist> | 26 | <para> |
26 | <listitem> | 27 | Poky provides 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 tool within Yocto Project. |
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 | It creates a focused, stable, subset of OpenEmbedded that can be easily and reliably built and developed upon. |
28 | </listitem> | 29 | Poky fully supports a wide range of x86 ARM, MIPS and PowerPC hardware and device virtulisation. |
29 | <listitem> | 30 | </para> |
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 | 31 | ||
37 | <para> | 32 | <para> |
38 | Poky is primarily a platform builder which generates filesystem images | 33 | Poky is primarily a platform builder which generates filesystem images |
39 | based on open source software such as the Kdrive X server, the Matchbox | 34 | 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 | 35 | 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 | 36 | 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 | 37 | machines target QEMU full system emulation(x86, ARM, MIPS and PowerPC) and |
43 | Sharp Zaurus series of devices. Poky's ability to boot inside a QEMU | 38 | real reference boards for each of these architectures. |
39 | Poky's ability to boot inside a QEMU | ||
44 | emulator makes it particularly suitable as a test platform for development | 40 | emulator makes it particularly suitable as a test platform for development |
45 | of embedded software. | 41 | of embedded software. |
46 | </para> | 42 | </para> |
@@ -76,222 +72,32 @@ | |||
76 | 72 | ||
77 | <section id='intro-manualoverview'> | 73 | <section id='intro-manualoverview'> |
78 | <title>Documentation Overview</title> | 74 | <title>Documentation Overview</title> |
79 | |||
80 | <para> | 75 | <para> |
81 | The handbook is split into sections covering different aspects of Poky. | 76 | The Poky User Guide is split into sections covering different aspects of Poky. |
82 | The <link linkend='usingpoky'>'Using Poky' section</link> gives an overview | 77 | The <link linkend='usingpoky'>'Using Poky' section</link> gives an overview of the components that make up Poky followed by information about using Poky and debugging images created in Yocto Project. |
83 | of the components that make up Poky followed by information about using and | 78 | 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. |
84 | debugging the Poky build system. The <link linkend='extendpoky'>'Extending Poky' section</link> | 79 | 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. |
85 | gives information about how to extend and customise Poky along with advice | 80 | The rest of the manual consists of several reference sections each giving details on a specific section of Poky functionality. |
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> | 81 | </para> |
97 | 82 | ||
98 | <para> | 83 | <para> |
99 | This manual applies to Poky Release 3.3 (Green). | 84 | This manual applies to Poky Release 3.3 (Green). |
100 | </para> | 85 | </para> |
101 | |||
102 | </section> | 86 | </section> |
103 | 87 | ||
104 | 88 | ||
105 | <section id='intro-requirements'> | 89 | <section id='intro-requirements'> |
106 | <title>System Requirements</title> | 90 | <title>System Requirements</title> |
107 | |||
108 | <para> | 91 | <para> |
109 | We recommend Debian-based distributions, in particular a recent Ubuntu | 92 | 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 | 93 | release (10.04 or newer), as the host system for Poky. Nothing in Poky is |
111 | distribution specific and | 94 | distribution specific and other distributions will most likely work as long |
112 | other distributions will most likely work as long as the appropriate | 95 | as the appropriate prerequisites are installed - we know of Poky being used |
113 | prerequisites are installed - we know of Poky being used successfully on Redhat, | 96 | successfully on Redhat, SUSE, Gentoo and Slackware host systems. |
114 | SUSE, Gentoo and Slackware host systems. | 97 | For information on what you need to develop images using Yocto Project and Poky |
98 | you should see the Yocto Project Quick Start on the public | ||
99 | <ulink rul='http://yoctoproject.org/'>Yocto Project Website</ulink>. | ||
115 | </para> | 100 | </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 <kernel> <image> | ||
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> | 101 | </section> |
296 | 102 | ||
297 | <section id='intro-getit'> | 103 | <section id='intro-getit'> |