summaryrefslogtreecommitdiffstats
path: root/handbook/usingpoky.xml
diff options
context:
space:
mode:
Diffstat (limited to 'handbook/usingpoky.xml')
-rw-r--r--handbook/usingpoky.xml390
1 files changed, 390 insertions, 0 deletions
diff --git a/handbook/usingpoky.xml b/handbook/usingpoky.xml
new file mode 100644
index 0000000000..c30da0716d
--- /dev/null
+++ b/handbook/usingpoky.xml
@@ -0,0 +1,390 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3<chapter id='usingpoky'>
4<title>Using Poky</title>
5
6 <para>
7 This section gives an overview of the components that make up Poky
8 following by information about running poky builds and dealing with any
9 problems that may arise.
10 </para>
11
12<section id='usingpoky-components'>
13 <title>Poky Overview</title>
14
15 <para>
16 At the core of Poky is the bitbake task executor together with various types of
17 configuration files. This section gives an overview of bitbake and the
18 configuration files, in particular what they are used for, and how they
19 interact.
20 </para>
21
22 <para>
23 Bitbake handles the parsing and execution of the data
24 files. The data itself is of various types; recipes which give
25 details about particular pieces of software, class data which is an
26 abstraction of common build information (e.g. how to build a Linux kernel)
27 and configuration data for machines, policy decisions, etc., which acts as
28 a glue and binds everything together. Bitbake knows how to combine multiple
29 data sources together, each data source being referred to as a <link
30 linkend='usingpoky-changes-collections'>'collection'</link>.
31 </para>
32
33 <para>
34 The <link linkend='ref-structure'>directory structure walkthrough</link>
35 section gives details on the meaning of specific directories but some
36 brief details on the core components follows:
37 </para>
38
39 <section id='usingpoky-components-bitbake'>
40 <title>Bitbake</title>
41
42 <para>
43 Bitbake is the tool at the heart of Poky and is responsible
44 for parsing the metadata, generating a list of tasks from it
45 and then executing them. To see a list of the options it
46 supports look at <command>bitbake --help</command>.
47 </para>
48
49 <para>
50 The most common usage is <command>bitbake packagename</command> where
51 packagename is the name of the package you wish to build
52 (from now on called the target). This often equates to the first part of a .bb
53 filename, so to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you
54 might type <command>bitbake matchbox-desktop</command>.
55 Several different versions of matchbox-desktop might exist and
56 bitbake will choose the one selected by the distribution configuration
57 (more details about how bitbake chooses between different versions
58 and providers is available in the <link linkend='ref-bitbake-providers'>
59 'Preferences and Providers' section</link>). Bitbake will also try to execute any
60 dependent tasks first so before building matchbox-desktop it
61 would build a cross compiler and glibc if not already built.
62 </para>
63
64 </section>
65
66 <section id='usingpoky-components-metadata'>
67 <title>Metadata (Recipes)</title>
68
69 <para>
70 The .bb files are usually referred to as 'recipes'. In general, a
71 recipe contains information about a single piece of software such
72 as where to download the source, any patches that are needed,
73 any special configuration options, how to compile the source files
74 and how to package the compiled output.
75 </para>
76
77 <para>
78 'package' can also used to describe recipes but since the same
79 word is used for the packaged output from Poky (i.e. .ipk or .deb
80 files), this document will avoid it.
81 </para>
82
83 </section>
84
85 <section id='usingpoky-components-classes'>
86 <title>Classes</title>
87
88 <para>
89 Class (.bbclass) files contain information which is useful to share
90 between metadata files. An example is the autotools class which contains
91 the common settings that any application using autotools would use. The
92 <link linkend='ref-classes'>classes reference section</link> gives details
93 on common classes and how to use them.
94 </para>
95 </section>
96
97 <section id='usingpoky-components-configuration'>
98 <title>Configuration</title>
99
100 <para>
101 The configuration (.conf) files define various configuration variables
102 which govern what Poky does. These are split into several areas, such
103 as machine configuration options, distribution configuration options,
104 compiler tuning options, general common configuration and user
105 configuration (local.conf).
106 </para>
107 </section>
108
109</section>
110
111
112
113<section id='usingpoky-build'>
114 <title>Running a Build</title>
115
116 <para>
117 First the Poky build environment needs to be setup using the following command:
118 </para>
119 <para>
120 <literallayout class='monospaced'>
121$ source poky-init-build-env
122</literallayout>
123 </para>
124 <para>
125 Once the Poky build environment is setup, a target can now be built using:
126 </para>
127 <para>
128 <literallayout class='monospaced'>
129$ bitbake &lt;target&gt;
130</literallayout>
131 </para>
132 <para>
133 The target is the name of the recipe you want to build. Common targets are the
134 images (in <filename class="directory">meta/packages/images/</filename>)
135 or the name of a recipe for a specific piece of software like
136 <application>busybox</application>. More details about the standard images
137 are available in the <link linkend='ref-images'>image reference section</link>.
138 </para>
139</section>
140
141<section id='usingpoky-install'>
142 <title>Installing and Using the Result</title>
143
144 <para>
145 Once an image has been built it often needs to be installed. The images/kernels built
146 by Poky are placed in the <filename class="directory">tmp/deploy/images</filename>
147 directory. Running qemux86 and qemuarm images is covered in the <link
148 linkend='intro-quickstart-qemu'>Running an Image</link> section. See your
149 board/machine documentation for information about how to install these images.
150 </para>
151
152 <section id='usingpoky-install-usbnetworking'>
153 <title>USB Networking</title>
154
155 <para>
156 Devices commonly have USB connectivity. To connect to the usbnet interface, on
157 the host machine run:
158 </para>
159 <para>
160 <programlisting>
161modprobe usbnet
162ifconfig usb0 192.168.0.200
163route add 192.168.0.202 usb0
164</programlisting>
165 </para>
166 </section>
167
168 <section id='usingpoky-install-qemu-networking'>
169 <title>QEMU/USB networking with IP masquerading</title>
170
171 <para>
172 On Ubuntu, Debian or similar distributions you can have the network automatically
173 configured. You can also enable masquerading between the QEMU system and the rest
174 of your network. To do this you need to edit <filename>/etc/network/interfaces</filename> to include:
175 </para>
176
177 <para><programlisting>
178allow-hotplug tap0
179iface tap0 inet static
180 address 192.168.7.200
181 netmask 255.255.255.0
182 network 192.168.7.0
183 post-up iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.7.0/24
184 post-up echo 1 > /proc/sys/net/ipv4/ip_forward
185 post-up iptables -P FORWARD ACCEPT
186</programlisting>
187 </para>
188
189 <para>
190 This ensures the tap0 interface will be up everytime you run QEMU
191 and it will have network/internet access.
192 </para>
193
194 <para>
195 Under emulation there are two steps to configure for internet access
196 via tap0. The first step is to configure routing:
197 </para>
198
199 <para><programlisting>
200route add default gw 192.168.7.200 tap0
201</programlisting>
202 </para>
203
204 <para>
205 The second is to configure name resolution which is configured in the
206 <filename>/etc/resolv.conf</filename> file. The simplest solution is
207 to copy it's content from the host machine.
208 </para>
209
210 <para>
211 USB connections to devices can be setup and automated in a similar way.
212 First add the following to
213 <filename>/etc/network/interfaces</filename>:
214 </para>
215
216 <para><programlisting>
217allow-hotplug usb0
218iface usb0 inet static
219 address 192.168.0.200
220 netmask 255.255.255.0
221 network 192.168.0.0
222 post-up iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.0.0/24
223 post-up echo 1 > /proc/sys/net/ipv4/ip_forward
224 post-up iptables -P FORWARD ACCEPT
225</programlisting>
226 </para>
227
228 <para>
229 and then to configure routing on the device you would use:
230 </para>
231
232 <para><programlisting>
233route add default gw 192.168.0.202 usb0
234</programlisting>
235 </para>
236
237 </section>
238</section>
239
240<section id='usingpoky-debugging'>
241 <title>Debugging Build Failures</title>
242
243 <para>
244 The exact method for debugging Poky depends on the nature of the
245 bug(s) and which part of the system they might be from. Standard
246 debugging practises such as comparing to the last
247 known working version and examining the changes, reapplying the
248 changes in steps to identify the one causing the problem etc. are
249 valid for Poky just like any other system. Its impossible to detail
250 every possible potential failure here but there are some general
251 tips to aid debugging:
252 </para>
253
254 <section id='usingpoky-debugging-taskfailures'>
255 <title>Task Failures</title>
256
257 <para>The log file for shell tasks is available in <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
258 For the compile task of busybox 1.01 on the ARM spitz machine, this
259 might be <filename>tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</filename>
260 for example. To see what bitbake ran to generate that log, look at the <filename>run.do_taskname.pid </filename>
261 file in the same directory.
262 </para>
263
264 <para>The output from python tasks is sent directly to the console at present.</para>
265 </section>
266
267 <section id='usingpoky-debugging-taskrunning'>
268 <title>Running specific tasks</title>
269
270 <para> Any given package consists of a set of tasks, in most
271 cases the series is fetch, unpack, patch, configure,
272 compile, install, package, package_write and build. The
273 default task is "build" and any tasks this depends on are
274 built first hence the standard bitbake behaviour. There are
275 some tasks such as devshell which are not part of the
276 default build chain. If you wish to run such a task you can
277 use the "-c" option to bitbake e.g. <command>bitbake
278 matchbox-desktop -c devshell</command>.
279 </para>
280
281 <para>
282 If you wish to rerun a task you can use the force option
283 "-f". A typical usage session might look like: </para>
284
285 <para>
286 <literallayout class='monospaced'>
287% bitbake matchbox-desktop
288[change some source in the WORKDIR for example]
289% bitbake matchbox-desktop -c compile -f
290% bitbake matchbox-desktop</literallayout>
291 </para>
292
293 <para>
294 which would build matchbox-desktop, then recompile it. The
295 final command reruns all tasks after the compile (basically
296 the packaging tasks) since bitbake will notice the the
297 compile has been rerun and hence the other tasks also need
298 to run again.
299 </para>
300
301 <para>
302 You can view a list of tasks in a given package by running
303 the listtasks task e.g. <command>bitbake matchbox-desktop -c
304 listtasks</command>.
305 </para>
306 </section>
307
308 <section id='usingpoky-debugging-dependencies'>
309 <title>Dependency Graphs</title>
310
311 <para>
312 Sometimes it can be hard to see why bitbake wants to build
313 some other packages before a given package you've specified.
314 <command>bitbake -g targetname</command> will create
315 <filename>depends.dot</filename> and
316 <filename>task-depends.dot</filename> files in the current
317 directory. They show
318 which packages and tasks depend on which other packages and
319 tasks and are useful for debugging purposes.
320 </para>
321 </section>
322
323 <section id='usingpoky-debugging-bitbake'>
324 <title>General Bitbake Problems</title>
325
326 <para>
327 Debug output from bitbake can be seen with the "-D" option.
328 The debug output gives more information about what bitbake
329 is doing and/or why. Each -D option increases the logging
330 level, the most common usage being "-DDD".
331 </para>
332
333 <para>
334 The output from <command>bitbake -DDD -v targetname</command> can reveal why
335 a certain version of a package might be chosen, why bitbake
336 picked a certain provider or help in other situations where
337 bitbake does something you're not expecting.
338 </para>
339 </section>
340
341 <section id='usingpoky-debugging-buildfile'>
342 <title>Building with no dependencies</title>
343
344 <para>
345 If you really want to build a specific .bb file, you can use
346 the form <command>bitbake -b somepath/somefile.bb</command>. Note that this
347 will not check the dependencies so this option should only
348 be used when you know its dependencies already exist. You
349 can specify fragments of the filename and bitbake will see
350 if it can find a unique match.
351 </para>
352
353 </section>
354
355 <section id='usingpoky-debugging-variables'>
356 <title>Variables</title>
357
358 <para>
359 The "-e" option will dump the resulting environment for
360 either the configuration (no package specified) or for a
361 specific package when specified with the "-b" option.
362 </para>
363 </section>
364
365 <section id='usingpoky-debugging-others'>
366 <title>Other Tips</title>
367
368 <tip>
369 <para>When adding new packages it is worth keeping an eye open for bad
370 things creeping into compiler commandlines such as references to local
371 system files (<filename>/usr/lib/</filename> or <filename>/usr/include/</filename> etc.).
372 </para>
373 </tip>
374
375 <tip>
376 <para>
377 If you want to remove the psplash boot splashscreen, add "psplash=false"
378 to the kernel commandline and psplash won't load allowing you to see
379 the console. It's also possible to switch out of the splashscreen by
380 switching virtual console (Fn+Left or Fn+Right on a Zaurus).
381 </para>
382 </tip>
383
384 </section>
385</section>
386
387</chapter>
388<!--
389vim: expandtab tw=80 ts=4
390-->