summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRichard Purdie <richard@openedhand.com>2008-02-26 11:31:34 +0000
committerRichard Purdie <richard@openedhand.com>2008-02-26 11:31:34 +0000
commit882e9cd2affb773eec8b1d387ab4e3b5cbdc0994 (patch)
treef023b2ce9abf3b894a81986e0a00e23d77b55e66
parent7197110f46511492a48cd359b3ddf75b60ea47c8 (diff)
downloadpoky-882e9cd2affb773eec8b1d387ab4e3b5cbdc0994.tar.gz
Add Poky handbook
git-svn-id: https://svn.o-hand.com/repos/poky/trunk@3865 311d38ba-8fff-0310-9ca6-ca027cbcb966
Diffstat
-rw-r--r--handbook/ChangeLog29
-rw-r--r--handbook/Makefile22
-rw-r--r--handbook/TODO12
-rw-r--r--handbook/contactus.xml30
-rw-r--r--handbook/development.xml815
-rw-r--r--handbook/examples/hello-autotools/hello_2.3.bb7
-rw-r--r--handbook/examples/hello-single/files/helloworld.c8
-rw-r--r--handbook/examples/hello-single/hello.bb16
-rw-r--r--handbook/examples/libxpm/libxpm_3.5.6.bb13
-rw-r--r--handbook/examples/mtd-makefile/mtd-utils_1.0.0.bb13
-rw-r--r--handbook/extendpoky.xml726
-rw-r--r--handbook/faq.xml234
-rw-r--r--handbook/introduction.xml331
-rw-r--r--handbook/poky-beaver.pngbin0 -> 26252 bytes
-rw-r--r--handbook/poky-doc-tools/AUTHORS0
-rw-r--r--handbook/poky-doc-tools/COPYING0
-rw-r--r--handbook/poky-doc-tools/ChangeLog30
-rw-r--r--handbook/poky-doc-tools/INSTALL236
-rw-r--r--handbook/poky-doc-tools/Makefile.am18
-rw-r--r--handbook/poky-doc-tools/NEWS0
-rw-r--r--handbook/poky-doc-tools/README24
-rwxr-xr-xhandbook/poky-doc-tools/autogen.sh3
-rw-r--r--handbook/poky-doc-tools/common/Makefile.am21
-rw-r--r--handbook/poky-doc-tools/common/Vera.ttfbin0 -> 65932 bytes
-rw-r--r--handbook/poky-doc-tools/common/Vera.xml1
-rw-r--r--handbook/poky-doc-tools/common/VeraMoBd.ttfbin0 -> 49052 bytes
-rw-r--r--handbook/poky-doc-tools/common/VeraMoBd.xml1
-rw-r--r--handbook/poky-doc-tools/common/VeraMono.ttfbin0 -> 49224 bytes
-rw-r--r--handbook/poky-doc-tools/common/VeraMono.xml1
-rw-r--r--handbook/poky-doc-tools/common/draft.pngbin0 -> 24847 bytes
-rw-r--r--handbook/poky-doc-tools/common/fop-config.xml.in33
-rw-r--r--handbook/poky-doc-tools/common/ohand-color.svg150
-rw-r--r--handbook/poky-doc-tools/common/poky-db-pdf.xsl64
-rw-r--r--handbook/poky-doc-tools/common/poky-handbook.pngbin0 -> 32145 bytes
-rw-r--r--handbook/poky-doc-tools/common/poky.svg163
-rw-r--r--handbook/poky-doc-tools/common/titlepage.templates.xml1240
-rw-r--r--handbook/poky-doc-tools/configure.ac27
-rw-r--r--handbook/poky-doc-tools/poky-docbook-to-pdf.in44
-rw-r--r--handbook/poky-handbook.html2429
-rw-r--r--handbook/poky-handbook.pngbin0 -> 17829 bytes
-rw-r--r--handbook/poky-handbook.xml111
-rw-r--r--handbook/poky-logo.svg117
-rw-r--r--handbook/ref-bitbake.xml340
-rw-r--r--handbook/ref-classes.xml460
-rw-r--r--handbook/ref-features.xml302
-rw-r--r--handbook/ref-images.xml69
-rw-r--r--handbook/ref-structure.xml365
-rw-r--r--handbook/ref-variables.xml825
-rw-r--r--handbook/ref-varlocality.xml204
-rw-r--r--handbook/resources.xml92
-rw-r--r--handbook/style.css957
-rw-r--r--handbook/usingpoky.xml390
52 files changed, 10973 insertions, 0 deletions
diff --git a/handbook/ChangeLog b/handbook/ChangeLog
new file mode 100644
index 0000000000..2cff9f9967
--- /dev/null
+++ b/handbook/ChangeLog
@@ -0,0 +1,29 @@
12008-02-15 Matthew Allum <mallum@openedhand.com>
2
3 * introduction.xml:
4 Minor tweaks to 'What is Poky'
5
62008-02-15 Matthew Allum <mallum@openedhand.com>
7
8 * poky-handbook.xml:
9 * poky-handbook.png
10 * poky-beaver.png
11 * poky-logo.svg:
12 * style.css:
13 Add some title images.
14
152008-02-14 Matthew Allum <mallum@openedhand.com>
16
17 * development.xml:
18 remove uri's
19 * style.css:
20 Fix glossary
21
222008-02-06 Matthew Allum <mallum@openedhand.com>
23
24 * Makefile:
25 Add various xslto options for html.
26 * introduction.xml:
27 Remove link in title.
28 * style.css:
29 Add initial version
diff --git a/handbook/Makefile b/handbook/Makefile
new file mode 100644
index 0000000000..ff6cd89d41
--- /dev/null
+++ b/handbook/Makefile
@@ -0,0 +1,22 @@
1all: html pdf
2
3pdf:
4
5 poky-docbook-to-pdf poky-handbook.xml
6# -- old way --
7# dblatex poky-handbook.xml
8
9html:
10# See http://www.sagehill.net/docbookxsl/HtmlOutput.html
11 xsltproc --stringparam html.stylesheet style.css \
12 --stringparam chapter.autolabel 1 \
13 --stringparam appendix.autolabel 1 \
14 --stringparam section.autolabel 1 \
15 -o poky-handbook.html \
16 --xinclude /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl \
17 poky-handbook.xml
18# -- old way --
19# xmlto xhtml-nochunks poky-handbook.xml
20
21validate:
22 xmllint --postvalid --xinclude --noout poky-handbook.xml
diff --git a/handbook/TODO b/handbook/TODO
new file mode 100644
index 0000000000..f3e843b8de
--- /dev/null
+++ b/handbook/TODO
@@ -0,0 +1,12 @@
1Handbook Todo List:
2
3 * Add instructions about using zaurus/openmoko emulation
4 * Add diagrams + oprofile screenshot
5 * Software Deevelopment intro should mention its software development for
6 intended target and could be a different arch etc and thus special case.
7
8Long Term:
9
10 * Expand insane.bbclass documentation to cover tests
11 * Document remaining classes (see list in ref-classes)
12
diff --git a/handbook/contactus.xml b/handbook/contactus.xml
new file mode 100644
index 0000000000..9ebccdec2d
--- /dev/null
+++ b/handbook/contactus.xml
@@ -0,0 +1,30 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='contact'>
5 <title>OpenedHand Contact Information</title>
6
7 <literallayout>
8OpenedHand Ltd
9Unit R, Homesdale Business Center
10216-218 Homesdale Rd
11Bromley, BR1 2QZ
12England
13+44 (0) 208 819 6559
14info@openedhand.com</literallayout>
15
16 <!-- Fop messes this up so we do like above
17 <address>
18 OpenedHand Ltd
19 Unit R, Homesdale Business Center
20 <street>216-218 Homesdale Rd</street>
21 <city>Bromley</city>, <postcode>BR1 2QZ</postcode>
22 <country>England</country>
23 <phone> +44 (0) 208 819 6559</phone>
24 <email>info@openedhand.com</email>
25 </address>
26 -->
27</appendix>
28<!--
29vim: expandtab tw=80 ts=4
30-->
diff --git a/handbook/development.xml b/handbook/development.xml
new file mode 100644
index 0000000000..c56c69ca79
--- /dev/null
+++ b/handbook/development.xml
@@ -0,0 +1,815 @@
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="platdev">
5<title>Platform Development with Poky</title>
6
7<section id="platdev-appdev">
8 <title>Software development</title>
9 <para>
10 Poky supports several methods of software development. These different
11 forms of development are explained below and can be switched
12 between as needed.
13 </para>
14
15 <section id="platdev-appdev-external-sdk">
16 <title>Developing externally using the Poky SDK</title>
17
18 <para>
19 The meta-toolchain and meta-toolchain-sdk targets (<link linkend='ref-images'>see
20 the images section</link>) build tarballs which contain toolchains and
21 libraries suitable for application development outside Poky. These unpack into the
22 <filename class="directory">/usr/local/poky</filename> directory and contain
23 a setup script, e.g.
24 <filename>/usr/local/poky/eabi-glibc/arm/environment-setup</filename> which
25 can be sourced to initialise a suitable environment. After sourcing this, the
26 compiler, QEMU scripts, QEMU binary, a special version of pkgconfig and other
27 useful utilities are added to the PATH. Variables to assist pkgconfig and
28 autotools are also set so that, for example, configure can find pre-generated test
29 results for tests which need target hardware to run.
30 </para>
31
32 <para>
33 Using the toolchain with autotool enabled packages is straightforward, just pass the
34 appropriate host option to configure e.g. "./configure --host=arm-poky-linux-gnueabi".
35 For other projects it is usually a case of ensuring the cross tools are used e.g.
36 CC=arm-poky-linux-gnueabi-gcc and LD=arm-poky-linux-gnueabi-ld.
37 </para>
38 </section>
39
40 <section id="platdev-appdev-qemu">
41 <title>Developing externally in QEMU</title>
42 <para>
43 Running Poky QEMU images is covered in the <link
44 linkend='intro-quickstart-qemu'>Running an Image</link> section.
45 </para>
46 <para>
47 Poky's QEMU images contain a complete native toolchain. This means
48 that applications can be developed within QEMU in the same was as a
49 normal system. Using qemux86 on an x86 machine is fast since the
50 guest and host architectures match, qemuarm is slower but gives
51 faithful emulation of ARM specific issues. To speed things up these
52 images support using distcc to call a cross-compiler outside the
53 emulated system too. If <command>runqemu</command> was used to start
54 QEMU, and distccd is present on the host system, any bitbake cross
55 compiling toolchain available from the build system will automatically
56 be used from within qemu simply by calling distcc
57 (<command>export CC="distcc"</command> can be set in the enviroment).
58 Alterntatively, if a suitable SDK/toolchain is present in
59 <filename class="directory">/usr/local/poky</filename> it will also
60 automatically be used.
61 </para>
62
63 <para>
64 There are several options for connecting into the emulated system.
65 QEMU provides a framebuffer interface which has standard consoles
66 available. There is also a serial connection available which has a
67 console to the system running on it and IP networking as standard.
68 The images have a dropbear ssh server running with the root password
69 disabled allowing standard ssh and scp commands to work. The images
70 also contain an NFS server exporting the guest's root filesystem
71 allowing that to be made available to the host.
72 </para>
73 </section>
74
75 <section id="platdev-appdev-chroot">
76 <title>Developing externally in a chroot</title>
77 <para>
78 If you have a system that matches the architecture of the Poky machine you're using,
79 such as qemux86, you can run binaries directly from the image on the host system
80 using a chroot combined with tools like <ulink url='http://projects.o-hand.com/xephyr'>Xephyr</ulink>.
81 </para>
82 <para>
83 Poky has some scripts to make using its qemux86 images within a chroot easier. To use
84 these you need to install the poky-scripts package or otherwise obtain the
85 <filename>poky-chroot-setup</filename> and <filename>poky-chroot-run</filename> scripts.
86 You also need Xephyr and chrootuid binaries available. To initialize a system use the setup script:
87 </para>
88 <para>
89 <literallayout class='monospaced'>
90# poky-chroot-setup &lt;qemux86-rootfs.tgz&gt; &lt;target-directory&gt;
91</literallayout>
92 </para>
93 <para>
94 which will unpack the specified qemux86 rootfs tarball into the target-directory.
95 You can then start the system with:
96 </para>
97 <para>
98 <literallayout class='monospaced'>
99# poky-chroot-run &lt;target-directory&gt; &lt;command&gt;
100</literallayout>
101 </para>
102 <para>
103 where the target-directory is the place the rootfs was unpacked to and command is
104 an optional command to run. If no command is specified, the system will drop you
105 within a bash shell. A Xephyr window will be displayed containing the emulated
106 system and you may be asked for a password since some of the commands used for
107 bind mounting directories need to be run using sudo.
108 </para>
109 <para>
110 There are limits as to how far the the realism of the chroot environment extends.
111 It is useful for simple development work or quick tests but full system emulation
112 with QEMU offers a much more realistic environment for more complex development
113 tasks. Note that chroot support within Poky is still experimental.
114 </para>
115 </section>
116
117 <section id="platdev-appdev-insitu">
118 <title>Developing in Poky directly</title>
119 <para>
120 Working directly in Poky is a fast and effective development technique.
121 The idea is that you can directly edit files in
122 <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>
123 or the source directory <glossterm><link linkend='var-S'>S</link></glossterm>
124 and then force specific tasks to rerun in order to test the changes.
125 An example session working on the matchbox-desktop package might
126 look like this:
127 </para>
128
129 <para>
130 <literallayout class='monospaced'>
131$ bitbake matchbox-desktop
132$ sh
133$ cd tmp/work/armv5te-poky-linux-gnueabi/matchbox-desktop-2.0+svnr1708-r0/
134$ cd matchbox-desktop-2
135$ vi src/main.c
136$ exit
137$ bitbake matchbox-desktop -c compile -f
138$ bitbake matchbox-desktop
139</literallayout>
140 </para>
141
142 <para>
143 Here, we build the package, change into the work directory for the package,
144 change a file, then recompile the package. Instead of using sh like this,
145 you can also use two different terminals. The risk with working like this
146 is that a command like unpack could wipe out the changes you've made to the
147 work directory so you need to work carefully.
148 </para>
149
150 <para>
151 It is useful when making changes directly to the work directory files to do
152 so using quilt as detailed in the <link linkend='usingpoky-modifying-packages-quilt'>
153 modifying packages with quilt</link> section. The resulting patches can be copied
154 into the recipe directory and used directly in the <glossterm><link
155 linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
156 </para>
157 <para>
158 For a review of the skills used in this section see Sections <link
159 linkend="usingpoky-components-bitbake">2.1.1</link> and <link
160 linkend="usingpoky-debugging-taskrunning">2.4.2</link>.
161 </para>
162
163 </section>
164
165 <section id="platdev-appdev-devshell">
166 <title>Developing with 'devshell'</title>
167
168 <para>
169 When debugging certain commands or even to just edit packages, the
170 'devshell' can be a useful tool. To start it you run a command like:
171 </para>
172
173 <para>
174 <literallayout class='monospaced'>
175$ bitbake matchbox-desktop -c devshell
176</literallayout>
177 </para>
178
179 <para>
180 which will open a terminal with a shell prompt within the Poky
181 environment. This means PATH is setup to include the cross toolchain,
182 the pkgconfig variables are setup to find the right .pc files,
183 configure will be able to find the Poky site files etc. Within this
184 environment, you can run configure or compile command as if they
185 were being run by Poky itself. You are also changed into the
186 source (<glossterm><link linkend='var-S'>S</link></glossterm>)
187 directory automatically. When finished with the shell just exit it
188 or close the terminal window.
189 </para>
190
191 <para>
192 The default shell used by devshell is the gnome-terminal. Other
193 forms of terminal can also be used by setting the <glossterm>
194 <link linkend='var-TERMCMD'>TERMCMD</link></glossterm> and <glossterm>
195 <link linkend='var-TERMCMDRUN'>TERMCMDRUN</link></glossterm> variables
196 in local.conf. For examples of the other options available, see
197 <filename>meta/conf/bitbake.conf</filename>. An external shell is
198 launched rather than opening directly into the original terminal
199 window to make interaction with bitbakes multiple threads easier
200 and also allow a client/server split of bitbake in the future
201 (devshell will still work over X11 forwarding or similar).
202 </para>
203
204 <para>
205 It is worth remembering that inside devshell you need to use the full
206 compiler name such as <command>arm-poky-linux-gnueabi-gcc</command>
207 instead of just <command>gcc</command> and the same applies to other
208 applications from gcc, bintuils, libtool etc. Poky will have setup
209 environmental variables such as CC to assist applications, such as make,
210 find the correct tools.
211 </para>
212
213 </section>
214
215 <section id="platdev-appdev-srcrev">
216 <title>Developing within Poky with an external SCM based package</title>
217
218 <para>
219 If you're working on a recipe which pulls from an external SCM it
220 is possible to have Poky notice new changes added to the
221 SCM and then build the latest version. This only works for SCMs
222 where its possible to get a sensible revision number for changes.
223 Currently it works for svn, git and bzr repositories.
224 </para>
225
226 <para>
227 To enable this behaviour it is simply a case of adding <glossterm>
228 <link linkend='var-SRCREV'>SRCREV</link></glossterm>_pn-<glossterm>
229 <link linkend='var-PN'>PN</link></glossterm> = "${AUTOREV}" to
230 local.conf where <glossterm><link linkend='var-PN'>PN</link></glossterm>
231 is the name of the package for which you want to enable automatic source
232 revision updating.
233 </para>
234 </section>
235
236 <section id="platdev-appdev-external-anjuta">
237 <title>Developing externally using the Anjuta plugin</title>
238
239 <para>
240 An Anjuta IDE plugin exists to make developing software within the Poky framework
241 easier for the application developer. It presents a graphical IDE from which the
242 developer can cross compile an application then deploy and execute the output in a QEMU
243 emulation session. It also supports cross debugging and profiling.
244 </para>
245
246 <para>
247 To use the plugin, a toolchain and SDK built by Poky is required along with Anjuta and the Anjuta
248 plugin. The Poky Anjuta plugin is available from the OpenedHand SVN repository located at
249 http://svn.o-hand.com/repos/anjuta-poky/trunk/anjuta-plugin-sdk/; a web interface
250 to the repository can be accessed at <ulink url='http://svn.o-hand.com/view/anjuta-poky/'/>.
251 See the README file contained in the project for more information
252 about the dependencies and how to get them along with details of
253 the prebuilt packages.
254 </para>
255
256 <section id="platdev-appdev-external-anjuta-setup">
257 <title>Setting up the Anjuta plugin</title>
258
259 <para>Extract the tarball for the toolchain into / as root. The
260 toolchain will be installed into
261 <filename class="directory">/usr/local/poky</filename>.</para>
262
263 <para>To use the plugin, first open or create an existing
264 project. If creating a new project the "C GTK+" project type
265 will allow itself to be cross-compiled. However you should be
266 aware that this uses glade for the UI.</para>
267
268 <para>To activate the plugin go
269 <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>,
270 then choose <guilabel>General</guilabel> from the left hand side. Choose the
271 Installed plugins tab, scroll down to <guilabel>Poky
272 SDK</guilabel> and check the
273 box. The plugin is now activated but first it must be
274 configured.</para> </section>
275
276 <section id="platdev-appdev-external-anjuta-configuration">
277 <title>Configuring the Anjuta plugin</title>
278
279 <para>The configuration options for the SDK can be found by choosing
280 the <guilabel>Poky SDK</guilabel> icon from the left hand side. The following options
281 need to be set:</para>
282
283 <itemizedlist>
284
285 <listitem><para><guilabel>SDK root</guilabel>: this is the root directory of the SDK
286 for an ARM EABI SDK this will be <filename
287 class="directory">/usr/local/poky/eabi-glibc/arm</filename>.
288 This directory will contain directories named like "bin",
289 "include", "var", etc. With the file chooser it is important
290 to enter into the "arm" subdirectory for this
291 example.</para></listitem>
292
293 <listitem><para><guilabel>Toolchain triplet</guilabel>: this is the cross compile
294 triplet, e.g. "arm-poky-linux-gnueabi".</para></listitem>
295
296 <listitem><para><guilabel>Kernel</guilabel>: use the file chooser to select the kernel
297 to use with QEMU</para></listitem>
298
299 <listitem><para><guilabel>Root filesystem</guilabel>: use the file chooser to select
300 the root filesystem image, this should be an image (not a
301 tarball)</para></listitem>
302 </itemizedlist>
303
304 </section>
305
306 <section id="platdev-appdev-external-anjuta-usage">
307 <title>Using the Anjuta plugin</title>
308
309 <para>As an example, cross-compiling a project, deploying it into
310 QEMU and running a debugger against it and then doing a system
311 wide profile.</para>
312
313 <para>Choose <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
314 Configure</guimenuitem></menuchoice> or
315 <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
316 Autogenerate</guimenuitem></menuchoice> to run "configure"
317 (or to run "autogen") for the project. This passes command line
318 arguments to instruct it to cross-compile.</para>
319
320 <para>Next do
321 <menuchoice><guimenu>Build</guimenu><guimenuitem>Build
322 Project</guimenuitem></menuchoice> to build and compile the
323 project. If you have previously built the project in the same
324 tree without using the cross-compiler you may find that your
325 project fails to link. Simply do
326 <menuchoice><guimenu>Build</guimenu><guimenuitem>Clean
327 Project</guimenuitem></menuchoice> to remove the old
328 binaries. You may then try building again.</para>
329
330 <para>Next start QEMU by using
331 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Start
332 QEMU</guimenuitem></menuchoice>, this will start QEMU and
333 will show any error messages in the message view. Once Poky has
334 fully booted within QEMU you may now deploy into it.</para>
335
336 <para>Once built and QEMU is running, choose
337 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Deploy</guimenuitem></menuchoice>,
338 this will install the package into a temporary directory and
339 then copy using rsync over SSH into the target. Progress and
340 messages will be shown in the message view.</para>
341
342 <para>To debug a program installed into onto the target choose
343 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Debug
344 remote</guimenuitem></menuchoice>. This prompts for the
345 local binary to debug and also the command line to run on the
346 target. The command line to run should include the full path to
347 the to binary installed in the target. This will start a
348 gdbserver over SSH on the target and also an instance of a
349 cross-gdb in a local terminal. This will be preloaded to connect
350 to the server and use the <guilabel>SDK root</guilabel> to find
351 symbols. This gdb will connect to the target and load in
352 various libraries and the target program. You should setup any
353 breakpoints or watchpoints now since you might not be able to
354 interrupt the execution later. You may stop
355 the debugger on the target using
356 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Stop
357 debugger</guimenuitem></menuchoice>.</para>
358
359 <para>It is also possible to execute a command in the target over
360 SSH, the appropriate environment will be be set for the
361 execution. Choose
362 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Run
363 remote</guimenuitem></menuchoice> to do this. This will open
364 a terminal with the SSH command inside.</para>
365
366 <para>To do a system wide profile against the system running in
367 QEMU choose
368 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Profile
369 remote</guimenuitem></menuchoice>. This will start up
370 OProfileUI with the appropriate parameters to connect to the
371 server running inside QEMU and will also supply the path to the
372 debug information necessary to get a useful profile.</para>
373
374 </section>
375 </section>
376 </section>
377
378<section id="platdev-gdb-remotedebug">
379 <title>Debugging with GDB Remotely</title>
380
381 <para>
382 <ulink url="http://sourceware.org/gdb/">GDB</ulink> (The GNU Project Debugger)
383 allows you to examine running programs to understand and fix problems and
384 also to perform postmortem style analsys of program crashes. It is available
385 as a package within poky and installed by default in sdk images. It works best
386 when -dbg packages for the application being debugged are installed as the
387 extra symbols give more meaningful output from GDB.
388 </para>
389
390 <para>
391 Sometimes, due to memory or disk space constraints, it is not possible
392 to use GDB directly on the remote target to debug applications. This is
393 due to the fact that
394 GDB needs to load the debugging information and the binaries of the
395 process being debugged. GDB then needs to perform many
396 computations to locate information such as function names, variable
397 names and values, stack traces, etc. even before starting the debugging
398 process. This places load on the target system and can alter the
399 characteristics of the program being debugged.
400 </para>
401 <para>
402 This is where GDBSERVER comes into play as it runs on the remote target
403 and does not load any debugging information from the debugged process.
404 Instead, the debugging information processing is done by a GDB instance
405 running on a distant computer - the host GDB. The host GDB then sends
406 control commands to GDBSERVER to make it stop or start the debugged
407 program, as well as read or write some memory regions of that debugged
408 program. All the debugging information loading and processing as well
409 as the heavy debugging duty is done by the host GDB, giving the
410 GDBSERVER running on the target a chance to remain small and fast.
411 </para>
412 <para>
413 As the host GDB is responsible for loading the debugging information and
414 doing the necessary processing to make actual debugging happen, the
415 user has to make sure it can access the unstripped binaries complete
416 with their debugging information and compiled with no optimisations. The
417 host GDB must also have local access to all the libraries used by the
418 debugged program. On the remote target the binaries can remain stripped
419 as GDBSERVER does not need any debugging information there. However they
420 must also be compiled without optimisation matching the host's binaries.
421 </para>
422
423 <para>
424 The binary being debugged on the remote target machine is hence referred
425 to as the 'inferior' in keeping with GDB documentation and terminology.
426 Further documentation on GDB, is available on
427 <ulink url="http://sourceware.org/gdb/documentation/">on their site</ulink>.
428 </para>
429
430 <section id="platdev-gdb-remotedebug-launch-gdbserver">
431 <title>Launching GDBSERVER on the target</title>
432 <para>
433 First, make sure gdbserver is installed on the target. If not,
434 install the gdbserver package (which needs the libthread-db1
435 package).
436 </para>
437 <para>
438 To launch GDBSERVER on the target and make it ready to "debug" a
439 program located at <emphasis>/path/to/inferior</emphasis>, connect
440 to the target and launch:
441 <programlisting>$ gdbserver localhost:2345 /path/to/inferior</programlisting>
442 After that, gdbserver should be listening on port 2345 for debugging
443 commands coming from a remote GDB process running on the host computer.
444 Communication between the GDBSERVER and the host GDB will be done using
445 TCP. To use other communication protocols please refer to the
446 GDBSERVER documentation.
447 </para>
448 </section>
449
450 <section id="platdev-gdb-remotedebug-launch-gdb">
451 <title>Launching GDB on the host computer</title>
452
453 <para>
454 Running GDB on the host computer takes a number of stages, described in the
455 following sections.
456 </para>
457
458 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
459 <title>Build the cross GDB package</title>
460 <para>
461 A suitable gdb cross binary is required which runs on your host computer but
462 knows about the the ABI of the remote target. This can be obtained from
463 the the Poky toolchain, e.g.
464 <filename>/usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb</filename>
465 which "arm" is the target architecture and "linux-gnueabi" the target ABI.
466 </para>
467
468 <para>
469 Alternatively this can be built directly by Poky. To do this you would build
470 the gdb-cross package so for example you would run:
471 <programlisting>bitbake gdb-cross</programlisting>
472 Once built, the cross gdb binary can be found at
473 <programlisting>tmp/cross/bin/&lt;target-abi&gt;-gdb </programlisting>
474 </para>
475
476 </section>
477 <section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins">
478
479 <title>Making the inferior binaries available</title>
480
481 <para>
482 The inferior binary needs to be available to GDB complete with all debugging
483 symbols in order to get the best possible results along with any libraries
484 the inferior depends on and their debugging symbols. There are a number of
485 ways this can be done.
486 </para>
487
488 <para>
489 Perhaps the easiest is to have an 'sdk' image corresponding to the plain
490 image installed on the device. In the case of 'pky-image-sato',
491 'poky-image-sdk' would contain suitable symbols. The sdk images already
492 have the debugging symbols installed so its just a question expanding the
493 archive to some location and telling GDB where this is.
494 </para>
495
496 <para>
497 Alternatively, poky can build a custom directory of files for a specific
498 debugging purpose by reusing its tmp/rootfs directory, on the host computer
499 in a slightly different way to normal. This directory contains the contents
500 of the last built image. This process assumes the image running on the
501 target was the last image to be built by Poky, the package <emphasis>foo</emphasis>
502 contains the inferior binary to be debugged has been built without without
503 optimisation and has debugging information available.
504 </para>
505 <para>
506 Firstly you want to install the <emphasis>foo</emphasis> package to tmp/rootfs
507 by doing:
508 </para>
509 <programlisting>tmp/staging/i686-linux/usr/bin/ipkg-cl -f \
510tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/ipkg.conf -o \
511tmp/rootfs/ update</programlisting>
512 <para>
513 then,
514 </para>
515 <programlisting>tmp/staging/i686-linux/usr/bin/ipkg-cl -f \
516tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/ipkg.conf \
517-o tmp/rootfs install foo
518
519tmp/staging/i686-linux/usr/bin/ipkg-cl -f \
520tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/ipkg.conf \
521-o tmp/rootfs install foo-dbg</programlisting>
522 <para>
523 which installs the debugging information too.
524 </para>
525
526 </section>
527 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
528
529 <title>Launch the host GDB</title>
530 <para>
531 To launch the host GDB, run the cross gdb binary identified above with
532 the inferior binary specified on the commandline:
533 <programlisting>&lt;target-abi&gt;-gdb rootfs/usr/bin/foo</programlisting>
534 This loads the binary of program <emphasis>foo</emphasis>
535 as well as its debugging information. Once the gdb prompt
536 appears, you must instruct GDB to load all the libraries
537 of the inferior from tmp/rootfs:
538 <programlisting>set solib-absolute-prefix /path/to/tmp/rootfs</programlisting>
539 where <filename>/path/to/tmp/rootfs</filename> must be
540 the absolute path to <filename>tmp/rootfs</filename> or wherever the
541 binaries with debugging information are located.
542 </para>
543 <para>
544 Now, tell GDB to connect to the GDBSERVER running on the remote target:
545 <programlisting>target remote remote-target-ip-address:2345</programlisting>
546 Where remote-target-ip-address is the IP address of the
547 remote target where the GDBSERVER is running. 2345 is the
548 port on which the GDBSERVER is running.
549 </para>
550
551 </section>
552 <section id="platdev-gdb-remotedebug-launch-gdb-using">
553
554 <title>Using the Debugger</title>
555 <para>
556 Debugging can now proceed as normal, as if the debugging were being done on the
557 local machine, for example to tell GDB to break in the <emphasis>main</emphasis>
558 function, for instance:
559 <programlisting>break main</programlisting>
560 and then to tell GDB to "continue" the inferior execution,
561 <programlisting>continue</programlisting>
562 </para>
563 <para>
564 For more information about using GDB please see the
565 project's online documentation at <ulink
566 url="http://sourceware.org/gdb/download/onlinedocs/"/>.
567 </para>
568 </section>
569 </section>
570
571</section>
572
573<section id="platdev-oprofile">
574 <title>Profiling with OProfile</title>
575
576 <para>
577 <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
578 statistical profiler well suited to finding performance
579 bottlenecks in both userspace software and the kernel. It provides
580 answers to questions like "Which functions does my application spend
581 the most time in when doing X?". Poky is well integrated with OProfile
582 to make profiling applications on target hardware straightforward.
583 </para>
584
585 <para>
586 To use OProfile you need an image with OProfile installed. The easiest
587 way to do this is with "tools-profile" in <glossterm><link
588 linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>. You also
589 need debugging symbols to be available on the system where the analysis
590 will take place. This can be achieved with "dbg-pkgs" in <glossterm><link
591 linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> or by
592 installing the appropriate -dbg packages. For
593 successful call graph analysis the binaries must preserve the frame
594 pointer register and hence should be compiled with the
595 "-fno-omit-framepointer" flag. In Poky this can be achieved with
596 <glossterm><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION
597 </link></glossterm> = "-fexpensive-optimizations -fno-omit-framepointer
598 -frename-registers -O2" or by setting <glossterm><link
599 linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></glossterm> = "1" in
600 local.conf (the latter will also add extra debug information making the
601 debug packages large).
602 </para>
603
604 <section id="platdev-oprofile-target">
605 <title>Profiling on the target</title>
606
607 <para>
608 All the profiling work can be performed on the target device. A
609 simple OProfile session might look like:
610 </para>
611
612 <para>
613 <literallayout class='monospaced'>
614# opcontrol --reset
615# opcontrol --start --separate=lib --no-vmlinux -c 5
616[do whatever is being profiled]
617# opcontrol --stop
618$ opreport -cl
619</literallayout>
620 </para>
621
622 <para>
623 Here, the reset command clears any previously profiled data,
624 OProfile is then started. The options used to start OProfile mean
625 dynamic library data is kept separately per application, kernel
626 profiling is disabled and callgraphing is enabled up to 5 levels
627 deep. To profile the kernel, you would specify the
628 <parameter>--vmlinux=/path/to/vmlinux</parameter> option (the vmlinux file is usually in
629 <filename class="directory">/boot/</filename> in Poky and must match the running kernel). The profile is
630 then stopped and the results viewed with opreport with options
631 to see the separate library symbols and callgraph information.
632 </para>
633 <para>
634 Callgraphing means OProfile not only logs infomation about which
635 functions time is being spent in but also which functions
636 called those functions (their parents) and which functions that
637 function calls (its children). The higher the callgraphing depth,
638 the more accurate the results but this also increased the loging
639 overhead so it should be used with caution. On ARM, binaries need
640 to have the frame pointer enabled for callgraphing to work (compile
641 with the gcc option -fno-omit-framepointer).
642 </para>
643 <para>
644 For more information on using OProfile please see the OProfile
645 online documentation at <ulink
646 url="http://oprofile.sourceforge.net/docs/"/>.
647 </para>
648 </section>
649
650 <section id="platdev-oprofile-oprofileui">
651 <title>Using OProfileUI</title>
652
653 <para>
654 A graphical user interface for OProfile is also available. You can
655 either use prebuilt Debian packages from the <ulink
656 url='http://debian.o-hand.com/'>OpenedHand repository</ulink> or
657 download and build from svn at
658 http://svn.o-hand.com/repos/oprofileui/trunk/. If the
659 "tools-profile" image feature is selected, all necessary binaries
660 are installed onto the target device for OProfileUI interaction.
661 </para>
662
663 <para>
664 In order to convert the data in the sample format from the target
665 to the host the <filename>opimport</filename> program is needed.
666 This is not included in standard Debian OProfile packages but an
667 OProfile package with this addition is also available from the <ulink
668 url='http://debian.o-hand.com/'>OpenedHand repository</ulink>.
669 We recommend using OProfile 0.9.3 or greater. Other patches to
670 OProfile may be needed for recent OProfileUI features, but Poky
671 usually includes all needed patches on the target device. Please
672 see the <ulink
673 url='http://svn.o-hand.com/repos/oprofileui/trunk/README'>
674 OProfileUI README</ulink> for up to date information, and the
675 <ulink url="http://labs.o-hand.com/oprofileui">OProfileUI website
676 </ulink> for more information on the OProfileUI project.
677 </para>
678
679 <section id="platdev-oprofile-oprofileui-online">
680 <title>Online mode</title>
681
682 <para>
683 This assumes a working network connection with the target
684 hardware. In this case you just need to run <command>
685 "oprofile-server"</command> on the device. By default it listens
686 on port 4224. This can be changed with the <parameter>--port</parameter> command line
687 option.
688
689 </para>
690
691 <para>
692 The client program is called <command>oprofile-viewer</command>. The
693 UI is relatively straightforward, the key functionality is accessed
694 through the buttons on the toolbar (which are duplicated in the
695 menus.) These buttons are:
696 </para>
697
698 <itemizedlist>
699 <listitem>
700 <para>
701 Connect - connect to the remote host, the IP address or hostname for the
702 target can be supplied here.
703 </para>
704 </listitem>
705 <listitem>
706 <para>
707 Disconnect - disconnect from the target.
708 </para>
709 </listitem>
710 <listitem>
711 <para>
712 Start - start the profiling on the device.
713 </para>
714 </listitem>
715 <listitem>
716 <para>
717 Stop - stop the profiling on the device and download the data to the local
718 host. This will generate the profile and show it in the viewer.
719 </para>
720 </listitem>
721 <listitem>
722 <para>
723 Download - download the data from the target, generate the profile and show it
724 in the viewer.
725 </para>
726 </listitem>
727 <listitem>
728 <para>
729 Reset - reset the sample data on the device. This will remove the sample
730 information that was collected on a previous sampling run. Ensure you do this
731 if you do not want to include old sample information.
732 </para>
733 </listitem>
734 <listitem>
735 <para>
736 Save - save the data downloaded from the target to another directory for later
737 examination.
738 </para>
739 </listitem>
740 <listitem>
741 <para>
742 Open - load data that was previously saved.
743 </para>
744 </listitem>
745 </itemizedlist>
746
747 <para>
748 The behaviour of the client is to download the complete 'profile archive' from
749 the target to the host for processing. This archive is a directory containing
750 the sample data, the object files and the debug information for said object
751 files. This archive is then converted using a script included in this
752 distribution ('oparchconv') that uses 'opimport' to convert the archive from
753 the target to something that can be processed on the host.
754 </para>
755
756 <para>
757 Downloaded archives are kept in /tmp and cleared up when they are no longer in
758 use.
759 </para>
760
761 <para>
762 If you wish to profile into the kernel, this is possible, you just need to ensure
763 a vmlinux file matching the running kernel is available. In Poky this is usually
764 located in /boot/vmlinux-KERNELVERSION, where KERNEL-version is the version of
765 the kernel e.g. 2.6.23. Poky generates separate vmlinux packages for each kernel
766 it builds so it should be a question of just ensuring a matching package is
767 installed (<command> ipkg install kernel-vmlinux</command>. These are automatically
768 installed into development and profiling images alongside OProfile. There is a
769 configuration option within the OProfileUI settings page where the location of
770 the vmlinux file can be entered.
771 </para>
772
773 <para>
774 Waiting for debug symbols to transfer from the device can be slow and it's not
775 always necessary to actually have them on device for OProfile use. All that is
776 needed is a copy of the filesystem with the debug symbols present on the viewer
777 system. The <link linkend='platdev-gdb-remotedebug-launch-gdb'>GDB remote debug
778 section</link> covers how to create such a directory with Poky and the location
779 of this directory can again be specified in the OProfileUI settings dialog. If
780 specified, it will be used where the file checksums match those on the system
781 being profiled.
782 </para>
783 </section>
784 <section id="platdev-oprofile-oprofileui-offline">
785 <title>Offline mode</title>
786
787 <para>
788 If no network access to the target is available an archive for processing in
789 'oprofile-viewer' can be generated with the following set of command.
790 </para>
791
792 <para>
793 <literallayout class='monospaced'>
794# opcontrol --reset
795# opcontrol --start --separate=lib --no-vmlinux -c 5
796[do whatever is being profiled]
797# opcontrol --stop
798# oparchive -o my_archive
799</literallayout>
800 </para>
801
802 <para>
803 Where my_archive is the name of the archive directory where you would like the
804 profile archive to be kept. The directory will be created for you. This can
805 then be copied to another host and loaded using 'oprofile-viewer''s open
806 functionality. The archive will be converted if necessary.
807 </para>
808 </section>
809 </section>
810</section>
811
812</chapter>
813<!--
814vim: expandtab tw=80 ts=4
815-->
diff --git a/handbook/examples/hello-autotools/hello_2.3.bb b/handbook/examples/hello-autotools/hello_2.3.bb
new file mode 100644
index 0000000000..5c5332f731
--- /dev/null
+++ b/handbook/examples/hello-autotools/hello_2.3.bb
@@ -0,0 +1,7 @@
1DESCRIPTION = "GNU Helloworld application"
2SECTION = "examples"
3LICENSE = "GPLv3"
4
5SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2"
6
7inherit autotools
diff --git a/handbook/examples/hello-single/files/helloworld.c b/handbook/examples/hello-single/files/helloworld.c
new file mode 100644
index 0000000000..fc7169b7b8
--- /dev/null
+++ b/handbook/examples/hello-single/files/helloworld.c
@@ -0,0 +1,8 @@
1#include <stdio.h>
2
3int main(void)
4{
5 printf("Hello world!\n");
6
7 return 0;
8}
diff --git a/handbook/examples/hello-single/hello.bb b/handbook/examples/hello-single/hello.bb
new file mode 100644
index 0000000000..d815b1ed73
--- /dev/null
+++ b/handbook/examples/hello-single/hello.bb
@@ -0,0 +1,16 @@
1DESCRIPTION = "Simple helloworld application"
2SECTION = "examples"
3LICENSE = "MIT"
4
5SRC_URI = "file://helloworld.c"
6
7S = "${WORKDIR}"
8
9do_compile() {
10 ${CC} helloworld.c -o helloworld
11}
12
13do_install() {
14 install -d ${D}${bindir}
15 install -m 0755 helloworld ${D}${bindir}
16}
diff --git a/handbook/examples/libxpm/libxpm_3.5.6.bb b/handbook/examples/libxpm/libxpm_3.5.6.bb
new file mode 100644
index 0000000000..2710189b2a
--- /dev/null
+++ b/handbook/examples/libxpm/libxpm_3.5.6.bb
@@ -0,0 +1,13 @@
1require xorg-lib-common.inc
2
3DESCRIPTION = "X11 Pixmap library"
4LICENSE = "X-BSD"
5DEPENDS += "libxext"
6PR = "r2"
7PE = "1"
8
9XORG_PN = "libXpm"
10
11PACKAGES =+ "sxpm cxpm"
12FILES_cxpm = "${bindir}/cxpm"
13FILES_sxpm = "${bindir}/sxpm"
diff --git a/handbook/examples/mtd-makefile/mtd-utils_1.0.0.bb b/handbook/examples/mtd-makefile/mtd-utils_1.0.0.bb
new file mode 100644
index 0000000000..b21dc653af
--- /dev/null
+++ b/handbook/examples/mtd-makefile/mtd-utils_1.0.0.bb
@@ -0,0 +1,13 @@
1DESCRIPTION = "Tools for managing memory technology devices."
2SECTION = "base"
3DEPENDS = "zlib"
4HOMEPAGE = "http://www.linux-mtd.infradead.org/"
5LICENSE = "GPLv2"
6
7SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz"
8
9CFLAGS_prepend = "-I ${S}/include "
10
11do_install() {
12 oe_runmake install DESTDIR=${D}
13}
diff --git a/handbook/extendpoky.xml b/handbook/extendpoky.xml
new file mode 100644
index 0000000000..18a7b66647
--- /dev/null
+++ b/handbook/extendpoky.xml
@@ -0,0 +1,726 @@
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='extendpoky'>
5
6<title>Extending Poky</title>
7
8 <para>
9 This section gives information about how to extend the functionality
10 already present in Poky, documenting standard tasks such as adding new
11 software packages, extending or customising images or porting poky to
12 new hardware (adding a new machine). It also contains advice about how
13 to manage the process of making changes to Poky to achieve best results.
14 </para>
15
16 <section id='usingpoky-extend-addpkg'>
17 <title>Adding a Package</title>
18
19 <para>
20 To add package into Poky you need to write a recipe for it.
21 Writing a recipe means creating a .bb file which sets various
22 variables. The variables
23 useful for recipes are detailed in the <link linkend='ref-varlocality-recipe-required'>
24 recipe reference</link> section along with more detailed information
25 about issues such as recipe naming.
26 </para>
27
28 <para>
29 The simplest way to add a new package is to base it on a similar
30 pre-existing recipe. There are some examples below of how to add
31 standard types of packages:
32 </para>
33
34 <section id='usingpoky-extend-addpkg-singlec'>
35 <title>Single .c File Package (Hello World!)</title>
36
37 <para>
38 To build an application from a single file stored locally requires a
39 recipe which has the file listed in the <glossterm><link
40 linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable. In addition
41 the <function>do_compile</function> and <function>do_install</function>
42 tasks need to be manually written. The <glossterm><link linkend='var-S'>
43 S</link></glossterm> variable defines the directory containing the source
44 code which in this case is set equal to <glossterm><link linkend='var-WORKDIR'>
45 WORKDIR</link></glossterm>, the directory BitBake uses for the build.
46 </para>
47 <programlisting>
48DESCRIPTION = "Simple helloworld application"
49SECTION = "examples"
50LICENSE = "MIT"
51
52SRC_URI = "file://helloworld.c"
53
54S = "${WORKDIR}"
55
56do_compile() {
57 ${CC} helloworld.c -o helloworld
58}
59
60do_install() {
61 install -d ${D}${bindir}
62 install -m 0755 helloworld ${D}${bindir}
63}
64 </programlisting>
65
66 <para>
67 As a result of the build process "helloworld" and "helloworld-dbg"
68 packages will be built.
69 </para>
70 </section>
71
72 <section id='usingpoky-extend-addpkg-autotools'>
73 <title>Autotooled Package</title>
74
75 <para>
76 Applications which use autotools (autoconf, automake)
77 require a recipe which has a source archive listed in
78 <glossterm><link
79 linkend='var-SRC_URI'>SRC_URI</link></glossterm> and
80 <command>inherit autotools</command> to instruct BitBake to use the
81 <filename>autotools.bbclass</filename> which has
82 definitions of all the steps
83 needed to build an autotooled application.
84 The result of the build will be automatically packaged and if
85 the application uses NLS to localise then packages with
86 locale information will be generated (one package per
87 language).
88 </para>
89
90 <programlisting>
91DESCRIPTION = "GNU Helloworld application"
92SECTION = "examples"
93LICENSE = "GPLv2"
94
95SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2"
96
97inherit autotools
98 </programlisting>
99
100 </section>
101
102 <section id='usingpoky-extend-addpkg-makefile'>
103 <title>Makefile-Based Package</title>
104
105 <para>
106 Applications which use GNU make require a recipe which has
107 the source archive listed in <glossterm><link
108 linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
109 Adding a <function>do_compile</function> step
110 is not needed as by default BitBake will start the "make"
111 command to compile the application. If there is a need for
112 additional options to make then they should be stored in the
113 <glossterm><link
114 linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm> variable - BitBake
115 will pass them into the GNU
116 make invocation. A <function>do_install</function> task is required
117 - otherwise BitBake will run an empty <function>do_install</function>
118 task by default.
119 </para>
120
121 <para>
122 Some applications may require extra parameters to be passed to
123 the compiler, for example an additional header path. This can
124 be done buy adding to the <glossterm><link
125 linkend='var-CFLAGS'>CFLAGS</link></glossterm> variable, as in the example below.
126 </para>
127
128 <programlisting>
129DESCRIPTION = "Tools for managing memory technology devices."
130SECTION = "base"
131DEPENDS = "zlib"
132HOMEPAGE = "http://www.linux-mtd.infradead.org/"
133LICENSE = "GPLv2"
134
135SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz"
136
137CFLAGS_prepend = "-I ${S}/include "
138
139do_install() {
140 oe_runmake install DESTDIR=${D}
141}
142 </programlisting>
143
144 </section>
145
146 <section id='usingpoky-extend-addpkg-files'>
147 <title>Controlling packages content</title>
148
149 <para>
150 The variables <glossterm><link
151 linkend='var-PACKAGES'>PACKAGES</link></glossterm> and
152 <glossterm><link linkend='var-FILES'>FILES</link></glossterm> are used to split an
153 application into multiple packages.
154 </para>
155
156 <para>
157 Below the "libXpm" recipe is used as an example. By
158 default the "libXpm" recipe generates one package
159 which contains the library
160 and also a few binaries. The recipe can be adapted to
161 split the binaries into separate packages.
162 </para>
163
164 <programlisting>
165require xorg-lib-common.inc
166
167DESCRIPTION = "X11 Pixmap library"
168LICENSE = "X-BSD"
169DEPENDS += "libxext"
170PE = "1"
171
172XORG_PN = "libXpm"
173
174PACKAGES =+ "sxpm cxpm"
175FILES_cxpm = "${bindir}/cxpm"
176FILES_sxpm = "${bindir}/sxpm"
177 </programlisting>
178
179 <para>
180 In this example we want to ship the "sxpm" and "cxpm" binaries
181 in separate packages. Since "bindir" would be packaged into the
182 main <glossterm><link linkend='var-PN'>PN</link></glossterm>
183 package as standard we prepend the <glossterm><link
184 linkend='var-PACKAGES'>PACKAGES</link></glossterm> variable so
185 additional package names are added to the start of list. The
186 extra <glossterm><link linkend='var-PN'>FILES</link></glossterm>_*
187 variables then contain information to specify which files and
188 directories goes into which package.
189 </para>
190 </section>
191
192 <section id='usingpoky-extend-addpkg-postinstalls'>
193 <title>Post Install Scripts</title>
194
195 <para>
196 To add a post-installation script to a package, add
197 a <function>pkg_postinst_PACKAGENAME()</function>
198 function to the .bb file
199 where PACKAGENAME is the name of the package to attach
200 the postinst script to. A post-installation function has the following structure:
201 </para>
202 <programlisting>
203pkg_postinst_PACKAGENAME () {
204#!/bin/sh -e
205# Commands to carry out
206}
207 </programlisting>
208 <para>
209 The script defined in the post installation function
210 gets called when the rootfs is made. If the script succeeds,
211 the package is marked as installed. If the script fails,
212 the package is marked as unpacked and the script will be
213 executed again on the first boot of the image.
214 </para>
215
216 <para>
217 Sometimes it is necessary that the execution of a post-installation
218 script is delayed until the first boot, because the script
219 needs to be executed the device itself. To delay script execution
220 until boot time, the post-installation function should have the
221 following structure:
222 </para>
223
224 <programlisting>
225pkg_postinst_PACKAGENAME () {
226#!/bin/sh -e
227if [ x"$D" = "x" ]; then
228# Actions to carry out on the device go here
229else
230exit 1
231fi
232}
233 </programlisting>
234
235 <para>
236 The structure above delays execution until first boot
237 because the <glossterm><link
238 linkend='var-D'>D</link></glossterm> variable points
239 to the 'image'
240 directory when the rootfs is being made at build time but
241 is unset when executed on the first boot.
242 </para>
243 </section>
244
245 </section>
246
247 <section id='usingpoky-extend-customimage'>
248 <title>Customising Images</title>
249
250 <para>
251 Poky images can be customised to satisfy
252 particular requirements. Several methods are detailed below
253 along with guidelines of when to use them.
254 </para>
255
256 <section id='usingpoky-extend-customimage-custombb'>
257 <title>Customising Images through a custom image .bb files</title>
258
259 <para>
260 One way to get additional software into an image is by creating a
261 custom image. The recipe will contain two lines:
262 </para>
263
264 <programlisting>
265IMAGE_INSTALL = "task-poky-x11-base package1 package2"
266
267inherit poky-image
268 </programlisting>
269
270 <para>
271 By creating a custom image, a developer has total control
272 over the contents of the image. It is important use
273 the correct names of packages in the <glossterm><link
274 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> variable.
275 The names must be in
276 the OpenEmbedded notation instead of Debian notation, for example
277 "glibc-dev" instead of "libc6-dev" etc.
278 </para>
279
280 <para>
281 The other method of creating a new image is by modifying
282 an existing image. For example if a developer wants to add
283 "strace" into "poky-image-sato" the following recipe can
284 be used:
285 </para>
286
287 <programlisting>
288require poky-image-sato.bb
289
290IMAGE_INSTALL += "strace"
291 </programlisting>
292
293 </section>
294
295 <section id='usingpoky-extend-customimage-customtasks'>
296 <title>Customising Images through custom tasks</title>
297
298 <para>
299 For for complex custom images, the best approach is to create a custom
300 task package which is them used to build the image (or images). A good
301 example of a tasks package is <filename>meta/packages/tasks/task-poky.bb
302 </filename>. The <glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm>
303 variable lists the task packages to build (along with the complimentary
304 -dbg and -dev packages). For each package added,
305 <glossterm><link linkend='var-PACKAGES'>RDEPENDS</link></glossterm> and
306 <glossterm><link linkend='var-PACKAGES'>RRECOMMENDS</link></glossterm>
307 entries can then be added each containing a list of packages the parent
308 task package should contain. An example would be:
309 </para>
310
311 <para>
312 <programlisting>
313DESCRIPTION = "My Custom Tasks"
314
315PACKAGES = "\
316 task-custom-apps \
317 task-custom-apps-dbg \
318 task-custom-apps-dev \
319 task-custom-tools \
320 task-custom-tools-dbg \
321 task-custom-tools-dev \
322 "
323
324RDEPENDS_task-custom-apps = "\
325 dropbear \
326 portmap \
327 psplash"
328
329RDEPENDS_task-custom-tools = "\
330 oprofile \
331 oprofileui-server \
332 lttng-control \
333 lttng-viewer"
334
335RRECOMMENDS_task-custom-tools = "\
336 kernel-module-oprofile"
337</programlisting>
338 </para>
339
340 <para>
341 In this example, two tasks packages are created, task-custom-apps and
342 task-custom-tools with the dependencies and recommended package dependencies
343 listed. To build an image using these task packages, you would then add
344 "task-custom-apps" and/or "task-custom-tools" to <glossterm><link
345 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> or other forms
346 of image dependencies as described in other areas of this section.
347 </para>
348 </section>
349
350 <section id='usingpoky-extend-customimage-imagefeatures'>
351 <title>Customising Images through custom <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm></title>
352
353 <para>
354 Ultimately users may want to add extra image "features" as used by Poky with the
355 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
356 variable. To create these, the best reference is <filename>meta/classes/poky-image.bbclass</filename>
357 which illustrates how poky achieves this. In summary, the file looks at the contents of the
358 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
359 variable and based on this generates the <glossterm><link linkend='var-IMAGE_INSTALL'>
360 IMAGE_INSTALL</link></glossterm> variable automatically. Extra features can be added by
361 extending the class or creating a custom class for use with specialised image .bb files.
362 </para>
363 </section>
364
365 <section id='usingpoky-extend-customimage-localconf'>
366 <title>Customising Images through local.conf</title>
367
368 <para>
369 It is possible to customise image contents by abusing
370 variables used by distribution maintainers in local.conf.
371 This method only allows the addition of packages and
372 is not recommended.
373 </para>
374
375 <para>
376 To add an "strace" package into the image the following is
377 added to local.conf:
378 </para>
379
380 <programlisting>
381DISTRO_EXTRA_RDEPENDS += "strace"
382 </programlisting>
383
384 <para>
385 However, since the <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'>
386 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable is for
387 distribution maintainers this method does not make
388 adding packages as simple as a custom .bb file. Using
389 this method, a few packages will need to be recreated
390 and the the image built.
391 </para>
392 <programlisting>
393bitbake -cclean task-boot task-base task-poky
394bitbake poky-image-sato
395 </programlisting>
396
397 <para>
398 Cleaning task-* packages is required because they use the
399 <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'>
400 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable. There is no need to
401 build them by hand as Poky images depend on the packages they contain so
402 dependencies will be built automatically. For this reason we don't use the
403 "rebuild" task in this case since "rebuild" does not care about
404 dependencies - it only rebuilds the specified package.
405 </para>
406
407 </section>
408
409 </section>
410
411<section id="platdev-newmachine">
412 <title>Porting Poky to a new machine</title>
413 <para>
414 Adding a new machine to Poky is a straightforward process and
415 this section gives an idea of the changes that are needed. This guide is
416 meant to cover adding machines similar to those Poky already supports.
417 Adding a totally new architecture might require gcc/glibc changes as
418 well as updates to the site information and, whilst well within Poky's
419 capabilities, is outside the scope of this section.
420 </para>
421
422 <section id="platdev-newmachine-conffile">
423 <title>Adding the machine configuration file</title>
424 <para>
425 A .conf file needs to be added to conf/machine/ with details of the
426 device being added. The name of the file determines the name Poky will
427 use to reference this machine.
428 </para>
429
430 <para>
431 The most important variables to set in this file are <glossterm>
432 <link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm>
433 (e.g. "arm"), <glossterm><link linkend='var-PREFERRED_PROVIDER'>
434 PREFERRED_PROVIDER</link></glossterm>_virtual/kernel (see below) and
435 <glossterm><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES
436 </link></glossterm> (e.g. "kernel26 apm screen wifi"). Other variables
437 like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE
438 </link></glossterm> (e.g. "115200 ttyS0"), <glossterm>
439 <link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link>
440 </glossterm> (e.g. "zImage") and <glossterm><link linkend='var-IMAGE_FSTYPES'>
441 IMAGE_FSTYPES</link></glossterm> (e.g. "tar.gz jffs2") might also be
442 needed. Full details on what these variables do and the meaning of
443 their contents is available through the links.
444 </para>
445 </section>
446
447 <section id="platdev-newmachine-kernel">
448 <title>Adding a kernel for the machine</title>
449 <para>
450 Poky needs to be able to build a kernel for the machine. You need
451 to either create a new kernel recipe for this machine or extend an
452 existing recipe. There are plenty of kernel examples in the
453 packages/linux directory which can be used as references.
454 </para>
455 <para>
456 If creating a new recipe the "normal" recipe writing rules apply
457 for setting up a <glossterm><link linkend='var-SRC_URI'>SRC_URI
458 </link></glossterm> including any patches and setting <glossterm>
459 <link linkend='var-S'>S</link></glossterm> to point at the source
460 code. You will need to create a configure task which configures the
461 unpacked kernel with a defconfig be that through a "make defconfig"
462 command or more usually though copying in a suitable defconfig and
463 running "make oldconfig". By making use of "inherit kernel" and also
464 maybe some of the linux-*.inc files, most other functionality is
465 centralised and the the defaults of the class normally work well.
466 </para>
467 <para>
468 If extending an existing kernel it is usually a case of adding a
469 suitable defconfig file in a location similar to that used by other
470 machine's defconfig files in a given kernel, possibly listing it in
471 the SRC_URI and adding the machine to the expression in <glossterm>
472 <link linkend='var-COMPATIBLE_MACHINES'>COMPATIBLE_MACHINES</link>
473 </glossterm>.
474 </para>
475 </section>
476
477 <section id="platdev-newmachine-formfactor">
478 <title>Adding a formfactor configuration file</title>
479 <para>
480 A formfactor configuration file provides information about the
481 target hardware on which Poky is running, and that Poky cannot
482 obtain from other sources such as the kernel. Some examples of
483 information contained in a formfactor configuration file include
484 framebuffer orientation, whether or not the system has a keyboard,
485 the positioning of the keyboard in relation to the screen, and
486 screen resolution.
487 </para>
488 <para>
489 Sane defaults should be used in most cases, but if customisation is
490 necessary you need to create a <filename>machconfig</filename> file
491 under <filename>meta/packages/formfactor/files/MACHINENAME/</filename>
492 where <literal>MACHINENAME</literal> is the name for which this infomation
493 applies. For information about the settings available and the defaults, please see
494 <filename>meta/packages/formfactor/files/config</filename>.
495 </para>
496 </section>
497</section>
498
499<section id='usingpoky-changes'>
500 <title>Making and Maintaining Changes</title>
501
502 <para>
503 We recognise that people will want to extend/configure/optimise Poky for
504 their specific uses, especially due to the extreme configurability and
505 flexibility Poky offers. To ensure ease of keeping pace with future
506 changes in Poky we recommend making changes to Poky in a controlled way.
507 </para>
508 <para>
509 Poky supports the idea of <link
510 linkend='usingpoky-changes-collections'>"collections"</link> which when used
511 properly can massively ease future upgrades and allow segregation
512 between the Poky core and a given developer's changes. Some other advice on
513 managing changes to Poky is also given in the following section.
514 </para>
515
516 <section id="usingpoky-changes-collections">
517 <title>Bitbake Collections</title>
518
519 <para>
520 Often, people want to extend Poky either through adding packages
521 or overriding files contained within Poky to add their own
522 functionality. Bitbake has a powerful mechanism called
523 collections which provide a way to handle this which is fully
524 supported and actively encouraged within Poky.
525 </para>
526 <para>
527 In the standard tree, meta-extras is an example of how you can
528 do this. As standard the data in meta-extras is not used on a
529 Poky build but local.conf.sample shows how to enable it:
530 </para>
531 <para>
532 <literallayout class='monospaced'>
533BBFILES := "${OEROOT}/meta/packages/*/*.bb ${OEROOT}/meta-extras/packages/*/*.bb"
534BBFILE_COLLECTIONS = "normal extras"
535BBFILE_PATTERN_normal = "^${OEROOT}/meta/"
536BBFILE_PATTERN_extras = "^${OEROOT}/meta-extras/"
537BBFILE_PRIORITY_normal = "5"
538BBFILE_PRIORITY_extras = "5"</literallayout>
539 </para>
540 <para>
541 As can be seen, the extra recipes are added to BBFILES. The
542 BBFILE_COLLECTIONS variable is then set to contain a list of
543 collection names. The BBFILE_PATTERN variables are regular
544 expressions used to match files from BBFILES into a particular
545 collection in this case by using the base pathname.
546 The BBFILE_PRIORITY variable then assigns the different
547 priorities to the files in different collections. This is useful
548 in situations where the same package might appear in both
549 repositories and allows you to choose which collection should
550 'win'.
551 </para>
552 <para>
553 This works well for recipes. For bbclasses and configuration
554 files, you can use the BBPATH environment variable. In this
555 case, the first file with the matching name found in BBPATH is
556 the one that is used, just like the PATH variable for binaries.
557 </para>
558 </section>
559
560
561 <section id='usingpoky-changes-commits'>
562 <title>Committing Changes</title>
563
564 <para>
565 Modifications to Poky are often managed under some kind of source
566 revision control system. The policy for committing to such systems
567 is important as some simple policy can significantly improve
568 usability. The tips below are based on the policy that OpenedHand
569 uses for commits to Poky.
570 </para>
571
572 <para>
573 It helps to use a consistent style for commit messages when committing
574 changes. We've found a style where the first line of a commit message
575 summarises the change and starts with the name of any package affected
576 work well. Not all changes are to specific packages so the prefix could
577 also be a machine name or class name instead. If a change needs a longer
578 description this should follow the summary.
579 </para>
580
581 <para>
582 Any commit should be self contained in that it should leave the
583 metadata in a consistent state, buildable before and after the
584 commit. This helps ensure the autobuilder test results are valid
585 but is good practice regardless.
586 </para>
587 </section>
588
589 <section id='usingpoky-changes-prbump'>
590 <title>Package Revision Incrementing</title>
591
592 <para>
593 If a committed change will result in changing the package output
594 then the value of the <glossterm><link linkend='var-PR'>PR</link>
595 </glossterm> variable needs to be increased (commonly referred to
596 as 'bumped') as part of that commit. Only integer values are used
597 and <glossterm><link linkend='var-PR'>PR</link></glossterm> =
598 "r0" should not be added into new recipes as this is default value.
599 When upgrading the version of a package (<glossterm><link
600 linkend='var-PV'>PV</link></glossterm>), the <glossterm><link
601 linkend='var-PR'>PR</link></glossterm> variable should be removed.
602 </para>
603
604 <para>
605 The aim is that the package version will only ever increase. If
606 for some reason <glossterm><link linkend='var-PV'>PV</link></glossterm>
607 will change and but not increase, the <glossterm><link
608 linkend='var-PE'>PE</link></glossterm> (Package Epoch) can
609 be increased (it defaults to '0'). The version numbers aim to
610 follow the <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
611 Debian Version Field Policy Guidelines</ulink> which define how
612 versions are compared and hence what "increasing" means.
613 </para>
614
615 <para>
616 There are two reasons for doing this, the first is to ensure that
617 when a developer updates and rebuilds, they get all the changes to
618 the repository and don't have to remember to rebuild any sections.
619 The second is to ensure that target users are able to upgrade their
620 devices via their package manager such as with the <command>
621 ipkg update;ipkg upgrade</command> commands (or similar for
622 dpkg/apt or rpm based systems). The aim is to ensure Poky has
623 upgradable packages in all cases.
624 </para>
625 </section>
626 </section>
627
628 <section id='usingpoky-modifing-packages'>
629 <title>Modifying Package Source Code</title>
630
631 <para>
632 Poky is usually used to build software rather than modifying
633 it. However, there are ways Poky can be used to modify software.
634 </para>
635
636 <para>
637 During building, the sources are available in <glossterm><link
638 linkend='var-WORKDIR'>WORKDIR</link></glossterm> directory.
639 Where exactly this is depends on the type of package and the
640 architecture of target device. For a standard recipe not
641 related to <glossterm><link
642 linkend='var-MACHINE'>MACHINE</link></glossterm> it will be
643 <filename>tmp/work/PACKAGE_ARCH-poky-TARGET_OS/PN-PV-PR/</filename>.
644 Target device dependent packages use <glossterm><link
645 linkend='var-MACHINE'>MACHINE
646 </link></glossterm>
647 instead of <glossterm><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH
648 </link></glossterm>
649 in the directory name.
650 </para>
651
652 <tip>
653 <para>
654 Check the package recipe sets the <glossterm><link
655 linkend='var-S'>S</link></glossterm> variable to something
656 other than standard <filename>WORKDIR/PN-PV/</filename> value.
657 </para>
658 </tip>
659 <para>
660 After building a package, a user can modify the package source code
661 without problem. The easiest way to test changes is by calling the
662 "compile" task:
663 </para>
664
665 <programlisting>
666bitbake --cmd compile --force NAME_OF_PACKAGE
667 </programlisting>
668
669 <para>
670 Other tasks may also be called this way.
671 </para>
672
673 <section id='usingpoky-modifying-packages-quilt'>
674 <title>Modifying Package Source Code with quilt</title>
675
676 <para>
677 By default Poky uses <ulink
678 url='http://savannah.nongnu.org/projects/quilt'>quilt</ulink>
679 to manage patches in <function>do_patch</function> task.
680 It is a powerful tool which can be used to track all
681 modifications done to package sources.
682 </para>
683
684 <para>
685 Before modifying source code it is important to
686 notify quilt so it will track changes into new patch
687 file:
688 <programlisting>
689quilt new NAME-OF-PATCH.patch
690 </programlisting>
691
692 Then add all files which will be modified into that
693 patch:
694 <programlisting>
695quilt add file1 file2 file3
696 </programlisting>
697
698 Now start editing. At the end quilt needs to be used
699 to generate final patch which will contain all
700 modifications:
701 <programlisting>
702quilt refresh
703 </programlisting>
704
705 The resulting patch file can be found in the
706 <filename class="directory">patches/</filename> subdirectory of the source
707 (<glossterm><link linkend='var-S'>S</link></glossterm>) directory. For future builds it
708 should be copied into
709 Poky metadata and added into <glossterm><link
710 linkend='var-SRC_URI'>SRC_URI</link></glossterm> of a recipe:
711 <programlisting>
712SRC_URI += "file://NAME-OF-PATCH.patch;patch=1"
713 </programlisting>
714
715 This also requires a bump of <glossterm><link
716 linkend='var-PR'>PR</link></glossterm> value in the same recipe as we changed resulting packages.
717 </para>
718
719 </section>
720
721</section>
722
723</chapter>
724<!--
725vim: expandtab tw=80 ts=4
726-->
diff --git a/handbook/faq.xml b/handbook/faq.xml
new file mode 100644
index 0000000000..2c227bfc62
--- /dev/null
+++ b/handbook/faq.xml
@@ -0,0 +1,234 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='faq'>
5<title>FAQ</title>
6<qandaset>
7 <qandaentry>
8 <question>
9 <para>
10 How does Poky differ from <ulink url='http://www.openembedded.org/'>OpenEmbedded</ulink>?
11 </para>
12 </question>
13 <answer>
14 <para>
15 Poky is a derivative of <ulink
16 url='http://www.openembedded.org/'>OpenEmbedded</ulink>, a stable,
17 smaller subset focused on the GNOME Mobile environment. Development
18 in Poky is closely tied to OpenEmbedded with features being merged
19 regularly between the two for mutual benefit.
20 </para>
21 </answer>
22 </qandaentry>
23 <qandaentry>
24 <question>
25 <para>
26 How can you claim Poky is stable?
27 </para>
28 </question>
29 <answer>
30 <para>
31 There are three areas that help with stability;
32
33 <itemizedlist>
34 <listitem>
35 <para>
36 We keep Poky small and focused - around 650 packages compared to over 5000 for full OE
37 </para>
38 </listitem>
39 <listitem>
40 <para>
41 We only support hardware that we have access to for testing
42 </para>
43 </listitem>
44 <listitem>
45 <para>
46 We have a Buildbot which provides continuous build and integration tests
47 </para>
48 </listitem>
49 </itemizedlist>
50 </para>
51 </answer>
52 </qandaentry>
53 <qandaentry>
54 <question>
55 <para>
56 How do I get support for my board added to Poky?
57 </para>
58 </question>
59 <answer>
60 <para>
61 There are two main ways to get a board supported in Poky;
62 <itemizedlist>
63 <listitem>
64 <para>
65 Send us the board if we don't have it yet
66 </para>
67 </listitem>
68 <listitem>
69 <para>
70 Send us bitbake recipes if you have them (see the Poky handbook to find out how to create recipes)
71 </para>
72 </listitem>
73 </itemizedlist>
74 Usually if it's not a completely exotic board then adding support in Poky should be fairly straightforward.
75 </para>
76 </answer>
77 </qandaentry>
78 <qandaentry>
79 <question>
80 <para>
81 Are there any products running poky ?
82 </para>
83 </question>
84 <answer>
85 <para>
86 The <ulink url='http://vernier.com/labquest/'>Vernier Labquest</ulink> is using Poky (for more about the Labquest see the case study at OpenedHand). There are a number of pre-production devices using Poky and we will announce those as soon as they are released.
87 </para>
88 </answer>
89 </qandaentry>
90 <qandaentry>
91 <question>
92 <para>
93 What is the Poky output ?
94 </para>
95 </question>
96 <answer>
97 <para>
98 The output of a Poky build will depend on how it was started, as the same set of recipes can be used to output various formats. Usually the output is a flashable image ready for the target device.
99 </para>
100 </answer>
101 </qandaentry>
102 <qandaentry>
103 <question>
104 <para>
105 How do I add my package to Poky?
106 </para>
107 </question>
108 <answer>
109 <para>
110 To add a package you need to create a bitbake recipe - see the Poky handbook to find out how to create a recipe.
111 </para>
112 </answer>
113 </qandaentry>
114 <qandaentry>
115 <question>
116 <para>
117 Do I have to reflash my entire board with a new poky image when recompiling a package?
118 </para>
119 </question>
120 <answer>
121 <para>
122 Poky can build packages in various formats, ipkg, Debian package, or RPM. The package can then be upgraded using the package tools on the device, much like on a desktop distribution like Ubuntu or Fedora.
123 </para>
124 </answer>
125 </qandaentry>
126 <qandaentry>
127 <question>
128 <para>
129 What is GNOME Mobile? What's the difference between GNOME Mobile and GNOME?
130 </para>
131 </question>
132 <answer>
133 <para>
134 <ulink url='http://www.gnome.org/mobile/'>GNOME Mobile</ulink> is a subset of the GNOME platform targeted at mobile and embedded devices. The the main difference between GNOME Mobile and standard GNOME is that desktop-orientated libraries have been removed, along with deprecated libraries, creating a much smaller footprint.
135 </para>
136 </answer>
137 </qandaentry>
138 <qandaentry>
139 <question>
140 <para>
141 How do I make Poky work in RHEL/CentOS?
142 </para>
143 </question>
144 <answer>
145 <para>
146 To get Poky working under RHEL/CentOS 5.1 you need to first install some required packages. The standard CentOS packages needed are:
147 <itemizedlist>
148 <listitem>
149 <para>
150 "Development tools" (selected during installation)
151 </para>
152 </listitem>
153 <listitem>
154 <para>
155 texi2html
156 </para>
157 </listitem>
158 <listitem>
159 <para>
160 compat-gcc-34
161 </para>
162 </listitem>
163 </itemizedlist>
164 </para>
165
166 <para>
167 On top of those the following external packages are needed:
168 <itemizedlist>
169 <listitem>
170 <para>
171 python-sqlite2 from <ulink
172 url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG
173 repository</ulink>
174 </para>
175 </listitem>
176 <listitem>
177 <para>
178 help2man from <ulink
179 url='http://centos.karan.org/el5/extras/testing/i386/RPMS/help2man-1.33.1-2.noarch.rpm'>Karan
180 repository</ulink>
181 </para>
182 </listitem>
183 </itemizedlist>
184 </para>
185
186 <para>
187 Once these packages are installed Poky will be able to build standard images however there
188 may be a problem with QEMU segfaulting. You can either disable the generation of binary
189 locales by setting <glossterm><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
190 </glossterm> to "0" or remove the linux-2.6-execshield.patch from the kernel and rebuild
191 it since its that patch which causes the problems with QEMU.
192 </para>
193 </answer>
194 </qandaentry>
195 <qandaentry>
196 <question>
197 <para>
198 I see lots of 404 responses for files on http://folks.o-hand.com/~richard/poky/sources/*. Is something wrong?
199 </para>
200 </question>
201 <answer>
202 <para>
203 Nothing is wrong, Poky will check any configured source mirrors before downloading
204 from the upstream sources. It does this searching for both source archives and
205 pre-checked out versions of SCM managed software. This is so in large installations,
206 it can reduce load on the SCM servers themselves. The address above is one of the
207 default mirrors configured into standard Poky so if an upstream source disappears,
208 we can place sources there so builds continue to work.
209 </para>
210 </answer>
211 </qandaentry>
212 <qandaentry>
213 <question>
214 <para>
215 I have a machine specific data in a package for one machine only but the package is
216 being marked as machine specific in all cases, how do I stop it?
217 </para>
218 </question>
219 <answer>
220 <para>
221 Set <glossterm><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
222 </glossterm> = "0" in the .bb file but make sure the package is manually marked as
223 machine specific in the case that needs it. The code which handles <glossterm><link
224 linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link></glossterm>
225 is in base.bbclass.
226 </para>
227 </answer>
228 </qandaentry>
229</qandaset>
230</appendix>
231<!--
232vim: expandtab tw=80 ts=4
233-->
234
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-->
diff --git a/handbook/poky-beaver.png b/handbook/poky-beaver.png
new file mode 100644
index 0000000000..9f9e6cf996
--- /dev/null
+++ b/handbook/poky-beaver.png
Binary files differ
diff --git a/handbook/poky-doc-tools/AUTHORS b/handbook/poky-doc-tools/AUTHORS
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/handbook/poky-doc-tools/AUTHORS
diff --git a/handbook/poky-doc-tools/COPYING b/handbook/poky-doc-tools/COPYING
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/handbook/poky-doc-tools/COPYING
diff --git a/handbook/poky-doc-tools/ChangeLog b/handbook/poky-doc-tools/ChangeLog
new file mode 100644
index 0000000000..beee6791ed
--- /dev/null
+++ b/handbook/poky-doc-tools/ChangeLog
@@ -0,0 +1,30 @@
12008-02-15 Matthew Allum <mallum@openedhand.com>
2
3 * common/Makefile.am:
4 * common/poky-handbook.png:
5 Add a PNG image for the manual. Seems our logo SVG
6 is too complex/transparent for PDF
7
82008-02-14 Matthew Allum <mallum@openedhand.com>
9
10 * common/Makefile.am:
11 * common/fop-config.xml.in:
12 * common/poky-db-pdf.xsl:
13 * poky-docbook-to-pdf.in:
14 Font tweakage.
15
162008-01-27 Matthew Allum <mallum@openedhand.com>
17
18 * INSTALL:
19 * Makefile.am:
20 * README:
21 * autogen.sh:
22 * common/Makefile.am:
23 * common/fop-config.xml.in:
24 * common/ohand-color.svg:
25 * common/poky-db-pdf.xsl:
26 * common/poky.svg:
27 * common/titlepage.templates.xml:
28 * configure.ac:
29 * poky-docbook-to-pdf.in:
30 Initial import.
diff --git a/handbook/poky-doc-tools/INSTALL b/handbook/poky-doc-tools/INSTALL
new file mode 100644
index 0000000000..23e5f25d0e
--- /dev/null
+++ b/handbook/poky-doc-tools/INSTALL
@@ -0,0 +1,236 @@
1Installation Instructions
2*************************
3
4Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005 Free
5Software Foundation, Inc.
6
7This file is free documentation; the Free Software Foundation gives
8unlimited permission to copy, distribute and modify it.
9
10Basic Installation
11==================
12
13These are generic installation instructions.
14
15 The `configure' shell script attempts to guess correct values for
16various system-dependent variables used during compilation. It uses
17those values to create a `Makefile' in each directory of the package.
18It may also create one or more `.h' files containing system-dependent
19definitions. Finally, it creates a shell script `config.status' that
20you can run in the future to recreate the current configuration, and a
21file `config.log' containing compiler output (useful mainly for
22debugging `configure').
23
24 It can also use an optional file (typically called `config.cache'
25and enabled with `--cache-file=config.cache' or simply `-C') that saves
26the results of its tests to speed up reconfiguring. (Caching is
27disabled by default to prevent problems with accidental use of stale
28cache files.)
29
30 If you need to do unusual things to compile the package, please try
31to figure out how `configure' could check whether to do them, and mail
32diffs or instructions to the address given in the `README' so they can
33be considered for the next release. If you are using the cache, and at
34some point `config.cache' contains results you don't want to keep, you
35may remove or edit it.
36
37 The file `configure.ac' (or `configure.in') is used to create
38`configure' by a program called `autoconf'. You only need
39`configure.ac' if you want to change it or regenerate `configure' using
40a newer version of `autoconf'.
41
42The simplest way to compile this package is:
43
44 1. `cd' to the directory containing the package's source code and type
45 `./configure' to configure the package for your system. If you're
46 using `csh' on an old version of System V, you might need to type
47 `sh ./configure' instead to prevent `csh' from trying to execute
48 `configure' itself.
49
50 Running `configure' takes awhile. While running, it prints some
51 messages telling which features it is checking for.
52
53 2. Type `make' to compile the package.
54
55 3. Optionally, type `make check' to run any self-tests that come with
56 the package.
57
58 4. Type `make install' to install the programs and any data files and
59 documentation.
60
61 5. You can remove the program binaries and object files from the
62 source code directory by typing `make clean'. To also remove the
63 files that `configure' created (so you can compile the package for
64 a different kind of computer), type `make distclean'. There is
65 also a `make maintainer-clean' target, but that is intended mainly
66 for the package's developers. If you use it, you may have to get
67 all sorts of other programs in order to regenerate files that came
68 with the distribution.
69
70Compilers and Options
71=====================
72
73Some systems require unusual options for compilation or linking that the
74`configure' script does not know about. Run `./configure --help' for
75details on some of the pertinent environment variables.
76
77 You can give `configure' initial values for configuration parameters
78by setting variables in the command line or in the environment. Here
79is an example:
80
81 ./configure CC=c89 CFLAGS=-O2 LIBS=-lposix
82
83 *Note Defining Variables::, for more details.
84
85Compiling For Multiple Architectures
86====================================
87
88You can compile the package for more than one kind of computer at the
89same time, by placing the object files for each architecture in their
90own directory. To do this, you must use a version of `make' that
91supports the `VPATH' variable, such as GNU `make'. `cd' to the
92directory where you want the object files and executables to go and run
93the `configure' script. `configure' automatically checks for the
94source code in the directory that `configure' is in and in `..'.
95
96 If you have to use a `make' that does not support the `VPATH'
97variable, you have to compile the package for one architecture at a
98time in the source code directory. After you have installed the
99package for one architecture, use `make distclean' before reconfiguring
100for another architecture.
101
102Installation Names
103==================
104
105By default, `make install' installs the package's commands under
106`/usr/local/bin', include files under `/usr/local/include', etc. You
107can specify an installation prefix other than `/usr/local' by giving
108`configure' the option `--prefix=PREFIX'.
109
110 You can specify separate installation prefixes for
111architecture-specific files and architecture-independent files. If you
112pass the option `--exec-prefix=PREFIX' to `configure', the package uses
113PREFIX as the prefix for installing programs and libraries.
114Documentation and other data files still use the regular prefix.
115
116 In addition, if you use an unusual directory layout you can give
117options like `--bindir=DIR' to specify different values for particular
118kinds of files. Run `configure --help' for a list of the directories
119you can set and what kinds of files go in them.
120
121 If the package supports it, you can cause programs to be installed
122with an extra prefix or suffix on their names by giving `configure' the
123option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
124
125Optional Features
126=================
127
128Some packages pay attention to `--enable-FEATURE' options to
129`configure', where FEATURE indicates an optional part of the package.
130They may also pay attention to `--with-PACKAGE' options, where PACKAGE
131is something like `gnu-as' or `x' (for the X Window System). The
132`README' should mention any `--enable-' and `--with-' options that the
133package recognizes.
134
135 For packages that use the X Window System, `configure' can usually
136find the X include and library files automatically, but if it doesn't,
137you can use the `configure' options `--x-includes=DIR' and
138`--x-libraries=DIR' to specify their locations.
139
140Specifying the System Type
141==========================
142
143There may be some features `configure' cannot figure out automatically,
144but needs to determine by the type of machine the package will run on.
145Usually, assuming the package is built to be run on the _same_
146architectures, `configure' can figure that out, but if it prints a
147message saying it cannot guess the machine type, give it the
148`--build=TYPE' option. TYPE can either be a short name for the system
149type, such as `sun4', or a canonical name which has the form:
150
151 CPU-COMPANY-SYSTEM
152
153where SYSTEM can have one of these forms:
154
155 OS KERNEL-OS
156
157 See the file `config.sub' for the possible values of each field. If
158`config.sub' isn't included in this package, then this package doesn't
159need to know the machine type.
160
161 If you are _building_ compiler tools for cross-compiling, you should
162use the option `--target=TYPE' to select the type of system they will
163produce code for.
164
165 If you want to _use_ a cross compiler, that generates code for a
166platform different from the build platform, you should specify the
167"host" platform (i.e., that on which the generated programs will
168eventually be run) with `--host=TYPE'.
169
170Sharing Defaults
171================
172
173If you want to set default values for `configure' scripts to share, you
174can create a site shell script called `config.site' that gives default
175values for variables like `CC', `cache_file', and `prefix'.
176`configure' looks for `PREFIX/share/config.site' if it exists, then
177`PREFIX/etc/config.site' if it exists. Or, you can set the
178`CONFIG_SITE' environment variable to the location of the site script.
179A warning: not all `configure' scripts look for a site script.
180
181Defining Variables
182==================
183
184Variables not defined in a site shell script can be set in the
185environment passed to `configure'. However, some packages may run
186configure again during the build, and the customized values of these
187variables may be lost. In order to avoid this problem, you should set
188them in the `configure' command line, using `VAR=value'. For example:
189
190 ./configure CC=/usr/local2/bin/gcc
191
192causes the specified `gcc' to be used as the C compiler (unless it is
193overridden in the site shell script). Here is a another example:
194
195 /bin/bash ./configure CONFIG_SHELL=/bin/bash
196
197Here the `CONFIG_SHELL=/bin/bash' operand causes subsequent
198configuration-related scripts to be executed by `/bin/bash'.
199
200`configure' Invocation
201======================
202
203`configure' recognizes the following options to control how it operates.
204
205`--help'
206`-h'
207 Print a summary of the options to `configure', and exit.
208
209`--version'
210`-V'
211 Print the version of Autoconf used to generate the `configure'
212 script, and exit.
213
214`--cache-file=FILE'
215 Enable the cache: use and save the results of the tests in FILE,
216 traditionally `config.cache'. FILE defaults to `/dev/null' to
217 disable caching.
218
219`--config-cache'
220`-C'
221 Alias for `--cache-file=config.cache'.
222
223`--quiet'
224`--silent'
225`-q'
226 Do not print messages saying which checks are being made. To
227 suppress all normal output, redirect it to `/dev/null' (any error
228 messages will still be shown).
229
230`--srcdir=DIR'
231 Look for the package's source code in directory DIR. Usually
232 `configure' can determine that directory automatically.
233
234`configure' also accepts some other, not widely useful, options. Run
235`configure --help' for more details.
236
diff --git a/handbook/poky-doc-tools/Makefile.am b/handbook/poky-doc-tools/Makefile.am
new file mode 100644
index 0000000000..ca92ae714c
--- /dev/null
+++ b/handbook/poky-doc-tools/Makefile.am
@@ -0,0 +1,18 @@
1SUBDIRS = common
2
3EXTRA_DIST = poky-docbook-to-pdf.in
4
5bin_SCRIPTS = poky-docbook-to-pdf
6
7edit = sed \
8 -e 's,@datadir\@,$(pkgdatadir),g' \
9 -e 's,@prefix\@,$(prefix),g' \
10 -e 's,@version\@,@VERSION@,g'
11
12poky-docbook-to-pdf: poky-docbook-to-pdf.in
13 rm -f poky-docbook-to-pdf
14 $(edit) poky-docbook-to-pdf.in > poky-docbook-to-pdf
15
16clean-local:
17 rm -fr poky-docbook-to-pdf
18 rm -fr poky-pr-docbook-to-pdf \ No newline at end of file
diff --git a/handbook/poky-doc-tools/NEWS b/handbook/poky-doc-tools/NEWS
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/handbook/poky-doc-tools/NEWS
diff --git a/handbook/poky-doc-tools/README b/handbook/poky-doc-tools/README
new file mode 100644
index 0000000000..7f6cb87f07
--- /dev/null
+++ b/handbook/poky-doc-tools/README
@@ -0,0 +1,24 @@
1poky-doc-tools
2==============
3
4Simple tools to wrap fop to create oh branded PDF's from docbook sources.
5(based on OH doc tools)
6
7Dependencies
8============
9
10Sun Java, make sure the java in your path is the *sun* java.
11
12xlstproc, nwalsh style sheets.
13
14FOP, installed - see http://www.sagehill.net/docbookxsl/InstallingAnFO.html.
15Also a 'fop' binary, eg I have;
16
17% cat ~/bin/fop
18#!/bin/sh
19java org.apache.fop.apps.Fop "$@"
20
21
22
23
24
diff --git a/handbook/poky-doc-tools/autogen.sh b/handbook/poky-doc-tools/autogen.sh
new file mode 100755
index 0000000000..5daa935608
--- /dev/null
+++ b/handbook/poky-doc-tools/autogen.sh
@@ -0,0 +1,3 @@
1#! /bin/sh
2autoreconf -v --install || exit 1
3./configure --enable-maintainer-mode --enable-debug "$@"
diff --git a/handbook/poky-doc-tools/common/Makefile.am b/handbook/poky-doc-tools/common/Makefile.am
new file mode 100644
index 0000000000..c6b154b144
--- /dev/null
+++ b/handbook/poky-doc-tools/common/Makefile.am
@@ -0,0 +1,21 @@
1SUPPORT_FILES = VeraMoBd.ttf VeraMoBd.xml \
2 VeraMono.ttf VeraMono.xml \
3 Vera.ttf Vera.xml \
4 draft.png titlepage.templates.xml \
5 poky-db-pdf.xsl poky.svg \
6 ohand-color.svg poky-handbook.png
7
8commondir = $(pkgdatadir)/common
9common_DATA = $(SUPPORT_FILES) fop-config.xml
10
11EXTRA_DIST = $(SUPPORT_FILES) fop-config.xml.in
12
13edit = sed -e 's,@datadir\@,$(pkgdatadir),g'
14
15fop-config.xml: fop-config.xml.in
16 rm -f fop-config.xml
17 $(edit) fop-config.xml.in > fop-config.xml
18
19
20clean-local:
21 rm -fr fop-config.xml \ No newline at end of file
diff --git a/handbook/poky-doc-tools/common/Vera.ttf b/handbook/poky-doc-tools/common/Vera.ttf
new file mode 100644
index 0000000000..58cd6b5e61
--- /dev/null
+++ b/handbook/poky-doc-tools/common/Vera.ttf
Binary files differ
diff --git a/handbook/poky-doc-tools/common/Vera.xml b/handbook/poky-doc-tools/common/Vera.xml
new file mode 100644
index 0000000000..3c82043e35
--- /dev/null
+++ b/handbook/poky-doc-tools/common/Vera.xml
@@ -0,0 +1 @@
<?xml version="1.0" encoding="UTF-8"?><font-metrics type="TYPE0"><font-name>BitstreamVeraSans</font-name><embed/><cap-height>729</cap-height><x-height>546</x-height><ascender>928</ascender><descender>-235</descender><bbox><left>-183</left><bottom>-235</bottom><right>1287</right><top>928</top></bbox><flags>32</flags><stemv>0</stemv><italicangle>0</italicangle><subtype>TYPE0</subtype><multibyte-extras><cid-type>CIDFontType2</cid-type><default-width>0</default-width><bfranges><bf gi="3" ue="126" us="32"/><bf gi="172" ue="160" us="160"/><bf gi="163" ue="161" us="161"/><bf gi="132" ue="163" us="162"/><bf gi="189" ue="164" us="164"/><bf gi="150" ue="165" us="165"/><bf gi="231" ue="166" us="166"/><bf gi="134" ue="167" us="167"/><bf gi="142" ue="168" us="168"/><bf gi="139" ue="169" us="169"/><bf gi="157" ue="170" us="170"/><bf gi="169" ue="171" us="171"/><bf gi="164" ue="172" us="172"/><bf gi="256" ue="173" us="173"/><bf gi="138" ue="174" us="174"/><bf gi="217" ue="175" us="175"/><bf gi="131" ue="176" us="176"/><bf gi="147" ue="177" us="177"/><bf gi="241" ue="179" us="178"/><bf gi="141" ue="180" us="180"/><bf gi="151" ue="181" us="181"/><bf gi="136" ue="182" us="182"/><bf gi="195" ue="183" us="183"/><bf gi="221" ue="184" us="184"/><bf gi="240" ue="185" us="185"/><bf gi="158" ue="186" us="186"/><bf gi="170" ue="187" us="187"/><bf gi="243" ue="190" us="188"/><bf gi="162" ue="191" us="191"/><bf gi="173" ue="192" us="192"/><bf gi="201" ue="193" us="193"/><bf gi="199" ue="194" us="194"/><bf gi="174" ue="195" us="195"/><bf gi="98" ue="197" us="196"/><bf gi="144" ue="198" us="198"/><bf gi="100" ue="199" us="199"/><bf gi="203" ue="200" us="200"/><bf gi="101" ue="201" us="201"/><bf gi="200" ue="202" us="202"/><bf gi="202" ue="203" us="203"/><bf gi="207" ue="204" us="204"/><bf gi="204" ue="207" us="205"/><bf gi="232" ue="208" us="208"/><bf gi="102" ue="209" us="209"/><bf gi="210" ue="210" us="210"/><bf gi="208" ue="212" us="211"/><bf gi="175" ue="213" us="213"/><bf gi="103" ue="214" us="214"/><bf gi="239" ue="215" us="215"/><bf gi="145" ue="216" us="216"/><bf gi="213" ue="217" us="217"/><bf gi="211" ue="219" us="218"/><bf gi="104" ue="220" us="220"/><bf gi="234" ue="221" us="221"/><bf gi="236" ue="222" us="222"/><bf gi="137" ue="223" us="223"/><bf gi="106" ue="224" us="224"/><bf gi="105" ue="225" us="225"/><bf gi="107" ue="226" us="226"/><bf gi="109" ue="227" us="227"/><bf gi="108" ue="228" us="228"/><bf gi="110" ue="229" us="229"/><bf gi="160" ue="230" us="230"/><bf gi="111" ue="231" us="231"/><bf gi="113" ue="232" us="232"/><bf gi="112" ue="233" us="233"/><bf gi="114" ue="235" us="234"/><bf gi="117" ue="236" us="236"/><bf gi="116" ue="237" us="237"/><bf gi="118" ue="239" us="238"/><bf gi="233" ue="240" us="240"/><bf gi="120" ue="241" us="241"/><bf gi="122" ue="242" us="242"/><bf gi="121" ue="243" us="243"/><bf gi="123" ue="244" us="244"/><bf gi="125" ue="245" us="245"/><bf gi="124" ue="246" us="246"/><bf gi="184" ue="247" us="247"/><bf gi="161" ue="248" us="248"/><bf gi="127" ue="249" us="249"/><bf gi="126" ue="250" us="250"/><bf gi="128" ue="252" us="251"/><bf gi="235" ue="253" us="253"/><bf gi="237" ue="254" us="254"/><bf gi="186" ue="255" us="255"/><bf gi="251" ue="263" us="262"/><bf gi="253" ue="269" us="268"/><bf gi="0" ue="270" us="270"/><bf gi="0" ue="271" us="271"/><bf gi="0" ue="272" us="272"/><bf gi="255" ue="273" us="273"/><bf gi="246" ue="287" us="286"/><bf gi="248" ue="304" us="304"/><bf gi="214" ue="305" us="305"/><bf gi="225" ue="322" us="321"/><bf gi="176" ue="339" us="338"/><bf gi="249" ue="351" us="350"/><bf gi="227" ue="353" us="352"/><bf gi="187" ue="376" us="376"/><bf gi="229" ue="382" us="381"/><bf gi="166" ue="402" us="402"/><bf gi="215" ue="710" us="710"/><bf gi="224" ue="711" us="711"/><bf gi="218" ue="730" us="728"/><bf gi="223" ue="731" us="731"/><bf gi="216" ue="732" us="732"/><bf gi="222" ue="733" us="733"/><bf gi="159" ue="937" us="937"/><bf gi="155" ue="960" us="960"/><bf gi="178" ue="8212" us="8211"/><bf gi="0" ue="8213" us="8213"/><bf gi="0" ue="8214" us="8214"/><bf gi="0" ue="8215" us="8215"/><bf gi="182" ue="8217" us="8216"/><bf gi="196" ue="8218" us="8218"/><bf gi="0" ue="8219" us="8219"/><bf gi="180" ue="8221" us="8220"/><bf gi="197" ue="8222" us="8222"/><bf gi="0" ue="8223" us="8223"/><bf gi="130" ue="8224" us="8224"/><bf gi="194" ue="8225" us="8225"/><bf gi="135" ue="8226" us="8226"/><bf gi="0" ue="8227" us="8227"/><bf gi="0" ue="8228" us="8228"/><bf gi="0" ue="8229" us="8229"/><bf gi="171" ue="8230" us="8230"/><bf gi="198" ue="8240" us="8240"/><bf gi="190" ue="8250" us="8249"/><bf gi="258" ue="8364" us="8364"/><bf gi="140" ue="8482" us="8482"/><bf gi="152" ue="8706" us="8706"/><bf gi="0" ue="8707" us="8707"/><bf gi="0" ue="8708" us="8708"/><bf gi="0" ue="8709" us="8709"/><bf gi="168" ue="8710" us="8710"/><bf gi="154" ue="8719" us="8719"/><bf gi="0" ue="8720" us="8720"/><bf gi="153" ue="8721" us="8721"/><bf gi="238" ue="8722" us="8722"/><bf gi="0" ue="8723" us="8723"/><bf gi="0" ue="8724" us="8724"/><bf gi="188" ue="8725" us="8725"/><bf gi="0" ue="8726" us="8726"/><bf gi="0" ue="8727" us="8727"/><bf gi="0" ue="8728" us="8728"/><bf gi="257" ue="8729" us="8729"/><bf gi="165" ue="8730" us="8730"/><bf gi="0" ue="8731" us="8731"/><bf gi="0" ue="8732" us="8732"/><bf gi="0" ue="8733" us="8733"/><bf gi="146" ue="8734" us="8734"/><bf gi="156" ue="8747" us="8747"/><bf gi="167" ue="8776" us="8776"/><bf gi="143" ue="8800" us="8800"/><bf gi="0" ue="8801" us="8801"/><bf gi="0" ue="8802" us="8802"/><bf gi="0" ue="8803" us="8803"/><bf gi="148" ue="8805" us="8804"/><bf gi="185" ue="9674" us="9674"/><bf gi="192" ue="64258" us="64257"/><bf gi="0" ue="65535" us="65535"/></bfranges><cid-widths start-index="0"><wx w="600"/><wx w="0"/><wx w="317"/><wx w="317"/><wx w="400"/><wx w="459"/><wx w="837"/><wx w="636"/><wx w="950"/><wx w="779"/><wx w="274"/><wx w="390"/><wx w="390"/><wx w="500"/><wx w="837"/><wx w="317"/><wx w="360"/><wx w="317"/><wx w="336"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="336"/><wx w="336"/><wx w="837"/><wx w="837"/><wx w="837"/><wx w="530"/><wx w="1000"/><wx w="684"/><wx w="686"/><wx w="698"/><wx w="770"/><wx w="631"/><wx w="575"/><wx w="774"/><wx w="751"/><wx w="294"/><wx w="294"/><wx w="655"/><wx w="557"/><wx w="862"/><wx w="748"/><wx w="787"/><wx w="603"/><wx w="787"/><wx w="694"/><wx w="634"/><wx w="610"/><wx w="731"/><wx w="684"/><wx w="988"/><wx w="685"/><wx w="610"/><wx w="685"/><wx w="390"/><wx w="336"/><wx w="390"/><wx w="837"/><wx w="500"/><wx w="500"/><wx w="612"/><wx w="634"/><wx w="549"/><wx w="634"/><wx w="615"/><wx w="352"/><wx w="634"/><wx w="633"/><wx w="277"/><wx w="277"/><wx w="579"/><wx w="277"/><wx w="974"/><wx w="633"/><wx w="611"/><wx w="634"/><wx w="634"/><wx w="411"/><wx w="520"/><wx w="392"/><wx w="633"/><wx w="591"/><wx w="817"/><wx w="591"/><wx w="591"/><wx w="524"/><wx w="636"/><wx w="336"/><wx w="636"/><wx w="837"/><wx w="684"/><wx w="684"/><wx w="698"/><wx w="631"/><wx w="748"/><wx w="787"/><wx w="731"/><wx w="612"/><wx w="612"/><wx w="612"/><wx w="612"/><wx w="612"/><wx w="612"/><wx w="549"/><wx w="615"/><wx w="615"/><wx w="615"/><wx w="615"/><wx w="277"/><wx w="277"/><wx w="277"/><wx w="277"/><wx w="633"/><wx w="611"/><wx w="611"/><wx w="611"/><wx w="611"/><wx w="611"/><wx w="633"/><wx w="633"/><wx w="633"/><wx w="633"/><wx w="500"/><wx w="500"/><wx w="636"/><wx w="636"/><wx w="500"/><wx w="589"/><wx w="636"/><wx w="629"/><wx w="1000"/><wx w="1000"/><wx w="1000"/><wx w="500"/><wx w="500"/><wx w="837"/><wx w="974"/><wx w="787"/><wx w="833"/><wx w="837"/><wx w="837"/><wx w="837"/><wx w="636"/><wx w="636"/><wx w="517"/><wx w="673"/><wx w="756"/><wx w="588"/><wx w="520"/><wx w="471"/><wx w="471"/><wx w="764"/><wx w="981"/><wx w="611"/><wx w="530"/><wx w="400"/><wx w="837"/><wx w="637"/><wx w="636"/><wx w="837"/><wx w="668"/><wx w="611"/><wx w="611"/><wx w="1000"/><wx w="636"/><wx w="684"/><wx w="684"/><wx w="787"/><wx w="1069"/><wx w="1022"/><wx w="500"/><wx w="1000"/><wx w="518"/><wx w="518"/><wx w="317"/><wx w="317"/><wx w="837"/><wx w="494"/><wx w="591"/><wx w="610"/><wx w="166"/><wx w="636"/><wx w="399"/><wx w="399"/><wx w="629"/><wx w="629"/><wx w="500"/><wx w="317"/><wx w="317"/><wx w="518"/><wx w="1341"/><wx w="684"/><wx w="631"/><wx w="684"/><wx w="631"/><wx w="631"/><wx w="294"/><wx w="294"/><wx w="294"/><wx w="294"/><wx w="787"/><wx w="787"/><wx w="787"/><wx w="731"/><wx w="731"/><wx w="731"/><wx w="277"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="562"/><wx w="284"/><wx w="634"/><wx w="520"/><wx w="685"/><wx w="524"/><wx w="336"/><wx w="774"/><wx w="611"/><wx w="610"/><wx w="591"/><wx w="604"/><wx w="634"/><wx w="837"/><wx w="837"/><wx w="400"/><wx w="400"/><wx w="400"/><wx w="969"/><wx w="969"/><wx w="969"/><wx w="774"/><wx w="634"/><wx w="294"/><wx w="634"/><wx w="520"/><wx w="698"/><wx w="549"/><wx w="698"/><wx w="549"/><wx w="634"/><wx w="360"/><wx w="317"/><wx w="636"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="400"/><wx w="500"/><wx w="500"/></cid-widths></multibyte-extras><kerning kpx1="246"><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="169"/><pair kern="-26" kpx2="197"/><pair kern="-35" kpx2="55"/><pair kern="-49" kpx2="60"/><pair kern="-49" kpx2="187"/><pair kern="-21" kpx2="181"/><pair kern="-17" kpx2="170"/><pair kern="-49" kpx2="234"/></kerning><kerning kpx1="235"><pair kern="-142" kpx2="17"/><pair kern="-17" kpx2="169"/><pair kern="-146" kpx2="197"/><pair kern="-17" kpx2="16"/><pair kern="-72" kpx2="29"/><pair kern="-17" kpx2="170"/></kerning><kerning kpx1="43"><pair kern="-35" kpx2="180"/><pair kern="-17" kpx2="17"/><pair kern="-35" kpx2="197"/><pair kern="-30" kpx2="181"/></kerning><kerning kpx1="16"><pair kern="36" kpx2="246"/><pair kern="-17" kpx2="235"/><pair kern="-21" kpx2="199"/><pair kern="18" kpx2="123"/><pair kern="27" kpx2="208"/><pair kern="-118" kpx2="187"/><pair kern="-49" kpx2="59"/><pair kern="18" kpx2="124"/><pair kern="-21" kpx2="201"/><pair kern="-118" kpx2="60"/><pair kern="36" kpx2="52"/><pair kern="18" kpx2="125"/><pair kern="36" kpx2="42"/><pair kern="-118" kpx2="234"/><pair kern="18" kpx2="122"/><pair kern="27" kpx2="210"/><pair kern="-21" kpx2="36"/><pair kern="18" kpx2="82"/><pair kern="-40" kpx2="58"/><pair kern="-91" kpx2="55"/><pair kern="-17" kpx2="186"/><pair kern="27" kpx2="175"/><pair kern="27" kpx2="50"/><pair kern="27" kpx2="209"/><pair kern="27" kpx2="103"/><pair kern="-21" kpx2="98"/><pair kern="55" kpx2="45"/><pair kern="-21" kpx2="173"/><pair kern="-17" kpx2="92"/><pair kern="-26" kpx2="89"/><pair kern="18" kpx2="121"/><pair kern="-58" kpx2="57"/><pair kern="-35" kpx2="37"/><pair kern="-21" kpx2="174"/></kerning><kerning kpx1="112"><pair kern="-17" kpx2="91"/></kerning><kerning kpx1="123"><pair kern="-72" kpx2="180"/><pair kern="-17" kpx2="17"/><pair kern="-63" kpx2="197"/><pair kern="18" kpx2="16"/><pair kern="-30" kpx2="91"/><pair kern="-35" kpx2="181"/></kerning><kerning kpx1="251"><pair kern="-17" kpx2="169"/><pair kern="-17" kpx2="60"/><pair kern="-17" kpx2="187"/><pair kern="18" kpx2="181"/><pair kern="-17" kpx2="170"/><pair kern="-17" kpx2="234"/></kerning><kerning kpx1="213"><pair kern="-17" kpx2="229"/><pair kern="-17" kpx2="61"/></kerning><kerning kpx1="208"><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="199"/><pair kern="27" kpx2="16"/><pair kern="-54" kpx2="187"/><pair kern="-17" kpx2="98"/><pair kern="-17" kpx2="181"/><pair kern="-63" kpx2="59"/><pair kern="-40" kpx2="17"/><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="169"/><pair kern="-91" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="29"/><pair kern="-17" kpx2="57"/><pair kern="-17" kpx2="174"/><pair kern="-54" kpx2="234"/></kerning><kerning kpx1="187"><pair kern="-114" kpx2="126"/><pair kern="-137" kpx2="107"/><pair kern="-132" kpx2="72"/><pair kern="-77" kpx2="199"/><pair kern="-118" kpx2="16"/><pair kern="-132" kpx2="123"/><pair kern="-132" kpx2="112"/><pair kern="-54" kpx2="251"/><pair kern="-54" kpx2="208"/><pair kern="-132" kpx2="113"/><pair kern="-54" kpx2="180"/><pair kern="-137" kpx2="105"/><pair kern="-114" kpx2="129"/><pair kern="-132" kpx2="124"/><pair kern="-109" kpx2="169"/><pair kern="-77" kpx2="201"/><pair kern="-54" kpx2="253"/><pair kern="-137" kpx2="106"/><pair kern="-132" kpx2="29"/><pair kern="-132" kpx2="125"/><pair kern="-72" kpx2="170"/><pair kern="-132" kpx2="115"/><pair kern="-114" kpx2="88"/><pair kern="-132" kpx2="122"/><pair kern="-54" kpx2="100"/><pair kern="-137" kpx2="68"/><pair kern="-54" kpx2="210"/><pair kern="-77" kpx2="36"/><pair kern="-132" kpx2="82"/><pair kern="-132" kpx2="114"/><pair kern="-54" kpx2="175"/><pair kern="-114" kpx2="127"/><pair kern="-54" kpx2="50"/><pair kern="-54" kpx2="209"/><pair kern="-54" kpx2="103"/><pair kern="-137" kpx2="108"/><pair kern="-77" kpx2="98"/><pair kern="-35" kpx2="76"/><pair kern="-17" kpx2="181"/><pair kern="-202" kpx2="17"/><pair kern="-114" kpx2="128"/><pair kern="-77" kpx2="173"/><pair kern="-137" kpx2="109"/><pair kern="-128" kpx2="197"/><pair kern="-54" kpx2="38"/><pair kern="-132" kpx2="121"/><pair kern="-137" kpx2="110"/><pair kern="-77" kpx2="174"/></kerning><kerning kpx1="113"><pair kern="-17" kpx2="91"/></kerning><kerning kpx1="144"><pair kern="-40" kpx2="180"/><pair kern="-54" kpx2="197"/><pair kern="-44" kpx2="181"/></kerning><kerning kpx1="59"><pair kern="-72" kpx2="100"/><pair kern="-63" kpx2="210"/><pair kern="-17" kpx2="55"/><pair kern="-44" kpx2="114"/><pair kern="-44" kpx2="72"/><pair kern="-63" kpx2="175"/><pair kern="-49" kpx2="16"/><pair kern="-63" kpx2="50"/><pair kern="-63" kpx2="209"/><pair kern="-44" kpx2="112"/><pair kern="-72" kpx2="251"/><pair kern="-63" kpx2="103"/><pair kern="-63" kpx2="208"/><pair kern="-44" kpx2="113"/><pair kern="-40" kpx2="181"/><pair kern="-77" kpx2="180"/><pair kern="-54" kpx2="169"/><pair kern="-21" kpx2="197"/><pair kern="-72" kpx2="38"/><pair kern="-72" kpx2="253"/><pair kern="-44" kpx2="115"/></kerning><kerning kpx1="73"><pair kern="31" kpx2="180"/><pair kern="-17" kpx2="90"/><pair kern="-72" kpx2="17"/><pair kern="-17" kpx2="235"/><pair kern="-35" kpx2="169"/><pair kern="-114" kpx2="197"/><pair kern="-17" kpx2="186"/><pair kern="-17" kpx2="92"/><pair kern="-17" kpx2="87"/><pair kern="-54" kpx2="16"/><pair kern="-35" kpx2="29"/><pair kern="-17" kpx2="170"/></kerning><kerning kpx1="41"><pair kern="-17" kpx2="227"/><pair kern="-54" kpx2="126"/><pair kern="-91" kpx2="107"/><pair kern="-91" kpx2="235"/><pair kern="-54" kpx2="72"/><pair kern="-91" kpx2="199"/><pair kern="-35" kpx2="123"/><pair kern="-54" kpx2="112"/><pair kern="-54" kpx2="113"/><pair kern="-17" kpx2="54"/><pair kern="-21" kpx2="180"/><pair kern="-91" kpx2="105"/><pair kern="-54" kpx2="129"/><pair kern="-35" kpx2="124"/><pair kern="-91" kpx2="201"/><pair kern="-72" kpx2="85"/><pair kern="-91" kpx2="106"/><pair kern="-77" kpx2="29"/><pair kern="-35" kpx2="125"/><pair kern="-54" kpx2="115"/><pair kern="-54" kpx2="88"/><pair kern="-35" kpx2="122"/><pair kern="-91" kpx2="68"/><pair kern="-91" kpx2="36"/><pair kern="-35" kpx2="82"/><pair kern="-91" kpx2="186"/><pair kern="-17" kpx2="55"/><pair kern="-54" kpx2="114"/><pair kern="-54" kpx2="127"/><pair kern="-91" kpx2="108"/><pair kern="-91" kpx2="98"/><pair kern="-72" kpx2="76"/><pair kern="-160" kpx2="17"/><pair kern="-54" kpx2="128"/><pair kern="-91" kpx2="173"/><pair kern="-91" kpx2="109"/><pair kern="-183" kpx2="197"/><pair kern="-91" kpx2="92"/><pair kern="-35" kpx2="121"/><pair kern="-91" kpx2="110"/><pair kern="-91" kpx2="174"/><pair kern="-17" kpx2="249"/></kerning><kerning kpx1="124"><pair kern="-72" kpx2="180"/><pair kern="-17" kpx2="17"/><pair kern="-63" kpx2="197"/><pair kern="18" kpx2="16"/><pair kern="-30" kpx2="91"/><pair kern="-35" kpx2="181"/></kerning><kerning kpx1="169"><pair kern="-17" kpx2="90"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="246"/><pair kern="-17" kpx2="235"/><pair kern="-17" kpx2="58"/><pair kern="-17" kpx2="186"/><pair kern="-54" kpx2="55"/><pair kern="-17" kpx2="251"/><pair kern="-72" kpx2="187"/><pair kern="-17" kpx2="39"/><pair kern="73" kpx2="144"/><pair kern="-17" kpx2="45"/><pair kern="-17" kpx2="92"/><pair kern="-17" kpx2="38"/><pair kern="-72" kpx2="60"/><pair kern="-17" kpx2="89"/><pair kern="-17" kpx2="253"/><pair kern="-54" kpx2="57"/><pair kern="-17" kpx2="37"/><pair kern="-17" kpx2="42"/><pair kern="-72" kpx2="234"/></kerning><kerning kpx1="201"><pair kern="-17" kpx2="246"/><pair kern="-67" kpx2="235"/><pair kern="-21" kpx2="16"/><pair kern="-17" kpx2="112"/><pair kern="-17" kpx2="123"/><pair kern="-17" kpx2="251"/><pair kern="-17" kpx2="113"/><pair kern="-77" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-35" kpx2="73"/><pair kern="-17" kpx2="124"/><pair kern="-35" kpx2="169"/><pair kern="-17" kpx2="252"/><pair kern="-17" kpx2="70"/><pair kern="-77" kpx2="60"/><pair kern="27" kpx2="201"/><pair kern="-17" kpx2="29"/><pair kern="-77" kpx2="234"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="122"/><pair kern="-17" kpx2="210"/><pair kern="-17" kpx2="82"/><pair kern="-54" kpx2="58"/><pair kern="-67" kpx2="186"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="27" kpx2="98"/><pair kern="-123" kpx2="181"/><pair kern="-17" kpx2="17"/><pair kern="-17" kpx2="38"/><pair kern="-17" kpx2="84"/><pair kern="-17" kpx2="121"/><pair kern="-63" kpx2="57"/><pair kern="-17" kpx2="254"/><pair kern="-17" kpx2="87"/><pair kern="-17" kpx2="72"/><pair kern="27" kpx2="199"/><pair kern="-17" kpx2="71"/><pair kern="-128" kpx2="180"/><pair kern="-17" kpx2="253"/><pair kern="-17" kpx2="52"/><pair kern="-17" kpx2="125"/><pair kern="-17" kpx2="42"/><pair kern="-17" kpx2="115"/><pair kern="-40" kpx2="90"/><pair kern="-17" kpx2="111"/><pair kern="27" kpx2="36"/><pair kern="-77" kpx2="55"/><pair kern="-17" kpx2="114"/><pair kern="-17" kpx2="50"/><pair kern="27" kpx2="173"/><pair kern="-67" kpx2="92"/><pair kern="22" kpx2="197"/><pair kern="-58" kpx2="89"/><pair kern="27" kpx2="174"/></kerning><kerning kpx1="60"><pair kern="-114" kpx2="126"/><pair kern="-137" kpx2="107"/><pair kern="-132" kpx2="72"/><pair kern="-77" kpx2="199"/><pair kern="-118" kpx2="16"/><pair kern="-132" kpx2="123"/><pair kern="-132" kpx2="112"/><pair kern="-54" kpx2="251"/><pair kern="-54" kpx2="208"/><pair kern="-132" kpx2="113"/><pair kern="-54" kpx2="180"/><pair kern="-137" kpx2="105"/><pair kern="-114" kpx2="129"/><pair kern="-132" kpx2="124"/><pair kern="-109" kpx2="169"/><pair kern="-77" kpx2="201"/><pair kern="-54" kpx2="253"/><pair kern="-137" kpx2="106"/><pair kern="-132" kpx2="29"/><pair kern="-132" kpx2="125"/><pair kern="-72" kpx2="170"/><pair kern="-132" kpx2="115"/><pair kern="-114" kpx2="88"/><pair kern="-132" kpx2="122"/><pair kern="-54" kpx2="100"/><pair kern="-137" kpx2="68"/><pair kern="-54" kpx2="210"/><pair kern="-77" kpx2="36"/><pair kern="-132" kpx2="82"/><pair kern="-132" kpx2="114"/><pair kern="-54" kpx2="175"/><pair kern="-114" kpx2="127"/><pair kern="-54" kpx2="50"/><pair kern="-54" kpx2="209"/><pair kern="-54" kpx2="103"/><pair kern="-137" kpx2="108"/><pair kern="-77" kpx2="98"/><pair kern="-35" kpx2="76"/><pair kern="-17" kpx2="181"/><pair kern="-202" kpx2="17"/><pair kern="-114" kpx2="128"/><pair kern="-77" kpx2="173"/><pair kern="-137" kpx2="109"/><pair kern="-128" kpx2="197"/><pair kern="-54" kpx2="38"/><pair kern="-132" kpx2="121"/><pair kern="-137" kpx2="110"/><pair kern="-77" kpx2="174"/></kerning><kerning kpx1="85"><pair kern="-21" kpx2="254"/><pair kern="-21" kpx2="72"/><pair kern="-63" kpx2="16"/><pair kern="-21" kpx2="112"/><pair kern="-21" kpx2="123"/><pair kern="-17" kpx2="80"/><pair kern="-21" kpx2="113"/><pair kern="-17" kpx2="71"/><pair kern="-21" kpx2="124"/><pair kern="-35" kpx2="169"/><pair kern="-21" kpx2="252"/><pair kern="-21" kpx2="70"/><pair kern="-17" kpx2="85"/><pair kern="-17" kpx2="29"/><pair kern="-21" kpx2="125"/><pair kern="-21" kpx2="115"/><pair kern="-21" kpx2="111"/><pair kern="-21" kpx2="122"/><pair kern="-21" kpx2="82"/><pair kern="-17" kpx2="75"/><pair kern="-21" kpx2="114"/><pair kern="-26" kpx2="91"/><pair kern="-17" kpx2="81"/><pair kern="41" kpx2="181"/><pair kern="-91" kpx2="17"/><pair kern="-151" kpx2="197"/><pair kern="-17" kpx2="74"/><pair kern="-17" kpx2="84"/><pair kern="-21" kpx2="121"/><pair kern="-17" kpx2="247"/><pair kern="-17" kpx2="120"/></kerning><kerning kpx1="61"><pair kern="-17" kpx2="180"/><pair kern="-17" kpx2="197"/><pair kern="-17" kpx2="16"/><pair kern="-17" kpx2="181"/></kerning><kerning kpx1="234"><pair kern="-114" kpx2="126"/><pair kern="-137" kpx2="107"/><pair kern="-132" kpx2="72"/><pair kern="-77" kpx2="199"/><pair kern="-118" kpx2="16"/><pair kern="-132" kpx2="123"/><pair kern="-132" kpx2="112"/><pair kern="-54" kpx2="251"/><pair kern="-54" kpx2="208"/><pair kern="-132" kpx2="113"/><pair kern="-54" kpx2="180"/><pair kern="-137" kpx2="105"/><pair kern="-114" kpx2="129"/><pair kern="-132" kpx2="124"/><pair kern="-109" kpx2="169"/><pair kern="-77" kpx2="201"/><pair kern="-54" kpx2="253"/><pair kern="-137" kpx2="106"/><pair kern="-132" kpx2="29"/><pair kern="-132" kpx2="125"/><pair kern="-72" kpx2="170"/><pair kern="-132" kpx2="115"/><pair kern="-114" kpx2="88"/><pair kern="-132" kpx2="122"/><pair kern="-54" kpx2="100"/><pair kern="-137" kpx2="68"/><pair kern="-54" kpx2="210"/><pair kern="-77" kpx2="36"/><pair kern="-132" kpx2="82"/><pair kern="-132" kpx2="114"/><pair kern="-54" kpx2="175"/><pair kern="-114" kpx2="127"/><pair kern="-54" kpx2="50"/><pair kern="-54" kpx2="209"/><pair kern="-54" kpx2="103"/><pair kern="-137" kpx2="108"/><pair kern="-77" kpx2="98"/><pair kern="-35" kpx2="76"/><pair kern="-17" kpx2="181"/><pair kern="-202" kpx2="17"/><pair kern="-114" kpx2="128"/><pair kern="-77" kpx2="173"/><pair kern="-137" kpx2="109"/><pair kern="-128" kpx2="197"/><pair kern="-54" kpx2="38"/><pair kern="-132" kpx2="121"/><pair kern="-137" kpx2="110"/><pair kern="-77" kpx2="174"/></kerning><kerning kpx1="100"><pair kern="-17" kpx2="169"/><pair kern="-17" kpx2="60"/><pair kern="-17" kpx2="187"/><pair kern="18" kpx2="181"/><pair kern="-17" kpx2="170"/><pair kern="-17" kpx2="234"/></kerning><kerning kpx1="122"><pair kern="-72" kpx2="180"/><pair kern="-17" kpx2="17"/><pair kern="-63" kpx2="197"/><pair kern="18" kpx2="16"/><pair kern="-30" kpx2="91"/><pair kern="-35" kpx2="181"/></kerning><kerning kpx1="47"><pair kern="-17" kpx2="126"/><pair kern="-91" kpx2="235"/><pair kern="-49" kpx2="104"/><pair kern="-17" kpx2="72"/><pair kern="22" kpx2="199"/><pair kern="-17" kpx2="16"/><pair kern="-17" kpx2="112"/><pair kern="-17" kpx2="123"/><pair kern="-49" kpx2="213"/><pair kern="-35" kpx2="208"/><pair kern="-132" kpx2="187"/><pair kern="-17" kpx2="113"/><pair kern="-202" kpx2="180"/><pair kern="-17" kpx2="129"/><pair kern="-17" kpx2="124"/><pair kern="22" kpx2="201"/><pair kern="-132" kpx2="60"/><pair kern="-49" kpx2="211"/><pair kern="-17" kpx2="125"/><pair kern="-17" kpx2="115"/><pair kern="-132" kpx2="234"/><pair kern="-17" kpx2="88"/><pair kern="-17" kpx2="122"/><pair kern="-35" kpx2="210"/><pair kern="22" kpx2="36"/><pair kern="-17" kpx2="82"/><pair kern="-91" kpx2="58"/><pair kern="-91" kpx2="186"/><pair kern="-137" kpx2="55"/><pair kern="-17" kpx2="114"/><pair kern="-35" kpx2="175"/><pair kern="-17" kpx2="127"/><pair kern="-35" kpx2="50"/><pair kern="-35" kpx2="209"/><pair kern="-35" kpx2="103"/><pair kern="22" kpx2="98"/><pair kern="-262" kpx2="181"/><pair kern="-17" kpx2="128"/><pair kern="22" kpx2="173"/><pair kern="-49" kpx2="212"/><pair kern="-91" kpx2="92"/><pair kern="-17" kpx2="121"/><pair kern="-109" kpx2="57"/><pair kern="22" kpx2="174"/><pair kern="-49" kpx2="56"/></kerning><kerning kpx1="210"><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="199"/><pair kern="27" kpx2="16"/><pair kern="-54" kpx2="187"/><pair kern="-17" kpx2="98"/><pair kern="-17" kpx2="181"/><pair kern="-63" kpx2="59"/><pair kern="-40" kpx2="17"/><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="169"/><pair kern="-91" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="29"/><pair kern="-17" kpx2="57"/><pair kern="-17" kpx2="174"/><pair kern="-54" kpx2="234"/></kerning><kerning kpx1="58"><pair kern="-35" kpx2="126"/><pair kern="-63" kpx2="107"/><pair kern="-17" kpx2="235"/><pair kern="-58" kpx2="72"/><pair kern="-54" kpx2="199"/><pair kern="-40" kpx2="16"/><pair kern="-58" kpx2="112"/><pair kern="-58" kpx2="123"/><pair kern="-58" kpx2="113"/><pair kern="-17" kpx2="180"/><pair kern="-63" kpx2="105"/><pair kern="-35" kpx2="129"/><pair kern="-58" kpx2="124"/><pair kern="-54" kpx2="169"/><pair kern="-54" kpx2="201"/><pair kern="-44" kpx2="85"/><pair kern="-63" kpx2="106"/><pair kern="-58" kpx2="29"/><pair kern="-58" kpx2="125"/><pair kern="-17" kpx2="170"/><pair kern="-58" kpx2="115"/><pair kern="-35" kpx2="88"/><pair kern="-58" kpx2="122"/><pair kern="-63" kpx2="68"/><pair kern="-54" kpx2="36"/><pair kern="-58" kpx2="82"/><pair kern="-17" kpx2="186"/><pair kern="-58" kpx2="114"/><pair kern="-35" kpx2="127"/><pair kern="-63" kpx2="108"/><pair kern="-54" kpx2="98"/><pair kern="-21" kpx2="76"/><pair kern="-114" kpx2="17"/><pair kern="-35" kpx2="128"/><pair kern="-54" kpx2="173"/><pair kern="-63" kpx2="109"/><pair kern="-128" kpx2="197"/><pair kern="-17" kpx2="92"/><pair kern="-58" kpx2="121"/><pair kern="-63" kpx2="110"/><pair kern="-54" kpx2="174"/></kerning><kerning kpx1="82"><pair kern="-72" kpx2="180"/><pair kern="-17" kpx2="17"/><pair kern="-63" kpx2="197"/><pair kern="18" kpx2="16"/><pair kern="-30" kpx2="91"/><pair kern="-35" kpx2="181"/></kerning><kerning kpx1="186"><pair kern="-142" kpx2="17"/><pair kern="-17" kpx2="169"/><pair kern="-146" kpx2="197"/><pair kern="-17" kpx2="16"/><pair kern="-72" kpx2="29"/><pair kern="-17" kpx2="170"/></kerning><kerning kpx1="175"><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="199"/><pair kern="27" kpx2="16"/><pair kern="-54" kpx2="187"/><pair kern="-17" kpx2="98"/><pair kern="-17" kpx2="181"/><pair kern="-63" kpx2="59"/><pair kern="-40" kpx2="17"/><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="169"/><pair kern="-91" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="29"/><pair kern="-17" kpx2="57"/><pair kern="-17" kpx2="174"/><pair kern="-54" kpx2="234"/></kerning><kerning kpx1="209"><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="199"/><pair kern="27" kpx2="16"/><pair kern="-54" kpx2="187"/><pair kern="-17" kpx2="98"/><pair kern="-17" kpx2="181"/><pair kern="-63" kpx2="59"/><pair kern="-40" kpx2="17"/><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="169"/><pair kern="-91" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="29"/><pair kern="-17" kpx2="57"/><pair kern="-17" kpx2="174"/><pair kern="-54" kpx2="234"/></kerning><kerning kpx1="103"><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="199"/><pair kern="27" kpx2="16"/><pair kern="-54" kpx2="187"/><pair kern="-17" kpx2="98"/><pair kern="-17" kpx2="181"/><pair kern="-63" kpx2="59"/><pair kern="-40" kpx2="17"/><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="169"/><pair kern="-91" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="29"/><pair kern="-17" kpx2="57"/><pair kern="-17" kpx2="174"/><pair kern="-54" kpx2="234"/></kerning><kerning kpx1="81"><pair kern="-72" kpx2="180"/><pair kern="-44" kpx2="197"/><pair kern="-54" kpx2="181"/></kerning><kerning kpx1="98"><pair kern="-17" kpx2="246"/><pair kern="-67" kpx2="235"/><pair kern="-21" kpx2="16"/><pair kern="-17" kpx2="112"/><pair kern="-17" kpx2="123"/><pair kern="-17" kpx2="251"/><pair kern="-17" kpx2="113"/><pair kern="-77" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-35" kpx2="73"/><pair kern="-17" kpx2="124"/><pair kern="-35" kpx2="169"/><pair kern="-17" kpx2="252"/><pair kern="-17" kpx2="70"/><pair kern="-77" kpx2="60"/><pair kern="27" kpx2="201"/><pair kern="-17" kpx2="29"/><pair kern="-77" kpx2="234"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="122"/><pair kern="-17" kpx2="210"/><pair kern="-17" kpx2="82"/><pair kern="-54" kpx2="58"/><pair kern="-67" kpx2="186"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="27" kpx2="98"/><pair kern="-123" kpx2="181"/><pair kern="-17" kpx2="17"/><pair kern="-17" kpx2="38"/><pair kern="-17" kpx2="84"/><pair kern="-17" kpx2="121"/><pair kern="-63" kpx2="57"/><pair kern="-17" kpx2="254"/><pair kern="-17" kpx2="87"/><pair kern="-17" kpx2="72"/><pair kern="27" kpx2="199"/><pair kern="-17" kpx2="71"/><pair kern="-128" kpx2="180"/><pair kern="-17" kpx2="253"/><pair kern="-17" kpx2="52"/><pair kern="-17" kpx2="125"/><pair kern="-17" kpx2="42"/><pair kern="-17" kpx2="115"/><pair kern="-40" kpx2="90"/><pair kern="-17" kpx2="111"/><pair kern="27" kpx2="36"/><pair kern="-77" kpx2="55"/><pair kern="-17" kpx2="114"/><pair kern="-17" kpx2="50"/><pair kern="27" kpx2="173"/><pair kern="-67" kpx2="92"/><pair kern="22" kpx2="197"/><pair kern="-58" kpx2="89"/><pair kern="27" kpx2="174"/></kerning><kerning kpx1="212"><pair kern="-17" kpx2="229"/><pair kern="-17" kpx2="61"/></kerning><kerning kpx1="229"><pair kern="-17" kpx2="180"/><pair kern="-17" kpx2="197"/><pair kern="-17" kpx2="16"/><pair kern="-17" kpx2="181"/></kerning><kerning kpx1="38"><pair kern="-17" kpx2="169"/><pair kern="-17" kpx2="60"/><pair kern="-17" kpx2="187"/><pair kern="18" kpx2="181"/><pair kern="-17" kpx2="170"/><pair kern="-17" kpx2="234"/></kerning><kerning kpx1="121"><pair kern="-72" kpx2="180"/><pair kern="-17" kpx2="17"/><pair kern="-63" kpx2="197"/><pair kern="18" kpx2="16"/><pair kern="-30" kpx2="91"/><pair kern="-35" kpx2="181"/></kerning><kerning kpx1="57"><pair kern="-67" kpx2="126"/><pair kern="-77" kpx2="107"/><pair kern="-26" kpx2="235"/><pair kern="-77" kpx2="72"/><pair kern="-63" kpx2="199"/><pair kern="-58" kpx2="16"/><pair kern="-77" kpx2="123"/><pair kern="-77" kpx2="112"/><pair kern="-17" kpx2="208"/><pair kern="-77" kpx2="113"/><pair kern="-77" kpx2="105"/><pair kern="-67" kpx2="129"/><pair kern="-77" kpx2="124"/><pair kern="-86" kpx2="169"/><pair kern="-63" kpx2="201"/><pair kern="-77" kpx2="106"/><pair kern="-81" kpx2="29"/><pair kern="-77" kpx2="125"/><pair kern="-54" kpx2="170"/><pair kern="-77" kpx2="115"/><pair kern="-67" kpx2="88"/><pair kern="-77" kpx2="122"/><pair kern="-77" kpx2="68"/><pair kern="-17" kpx2="210"/><pair kern="-63" kpx2="36"/><pair kern="-77" kpx2="82"/><pair kern="-26" kpx2="186"/><pair kern="-77" kpx2="114"/><pair kern="-17" kpx2="175"/><pair kern="-67" kpx2="127"/><pair kern="-17" kpx2="50"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="-77" kpx2="108"/><pair kern="-63" kpx2="98"/><pair kern="-21" kpx2="76"/><pair kern="-128" kpx2="17"/><pair kern="-67" kpx2="128"/><pair kern="-63" kpx2="173"/><pair kern="-77" kpx2="109"/><pair kern="-137" kpx2="197"/><pair kern="-26" kpx2="92"/><pair kern="-77" kpx2="121"/><pair kern="-77" kpx2="110"/><pair kern="-63" kpx2="174"/></kerning><kerning kpx1="37"><pair kern="-17" kpx2="227"/><pair kern="-17" kpx2="246"/><pair kern="-17" kpx2="251"/><pair kern="-54" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-17" kpx2="54"/><pair kern="-54" kpx2="180"/><pair kern="-30" kpx2="169"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="253"/><pair kern="-17" kpx2="42"/><pair kern="-17" kpx2="170"/><pair kern="-54" kpx2="234"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="210"/><pair kern="-35" kpx2="58"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="50"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="-54" kpx2="181"/><pair kern="-40" kpx2="197"/><pair kern="-17" kpx2="38"/><pair kern="-30" kpx2="57"/><pair kern="-17" kpx2="249"/></kerning><kerning kpx1="120"><pair kern="-72" kpx2="180"/><pair kern="-44" kpx2="197"/><pair kern="-54" kpx2="181"/></kerning><kerning kpx1="249"><pair kern="18" kpx2="173"/><pair kern="18" kpx2="36"/><pair kern="18" kpx2="201"/><pair kern="18" kpx2="199"/><pair kern="18" kpx2="174"/><pair kern="18" kpx2="98"/></kerning><kerning kpx1="227"><pair kern="18" kpx2="173"/><pair kern="18" kpx2="36"/><pair kern="18" kpx2="201"/><pair kern="18" kpx2="199"/><pair kern="18" kpx2="174"/><pair kern="18" kpx2="98"/></kerning><kerning kpx1="51"><pair kern="-17" kpx2="126"/><pair kern="-44" kpx2="107"/><pair kern="-35" kpx2="72"/><pair kern="-63" kpx2="199"/><pair kern="-21" kpx2="16"/><pair kern="-35" kpx2="123"/><pair kern="-35" kpx2="112"/><pair kern="-21" kpx2="187"/><pair kern="-35" kpx2="113"/><pair kern="-17" kpx2="86"/><pair kern="18" kpx2="180"/><pair kern="-44" kpx2="105"/><pair kern="-17" kpx2="129"/><pair kern="-35" kpx2="124"/><pair kern="-17" kpx2="169"/><pair kern="-63" kpx2="201"/><pair kern="-17" kpx2="85"/><pair kern="-21" kpx2="60"/><pair kern="-44" kpx2="106"/><pair kern="-35" kpx2="125"/><pair kern="-35" kpx2="115"/><pair kern="-21" kpx2="234"/><pair kern="-17" kpx2="88"/><pair kern="-35" kpx2="122"/><pair kern="-44" kpx2="68"/><pair kern="-63" kpx2="36"/><pair kern="-35" kpx2="82"/><pair kern="-35" kpx2="114"/><pair kern="-17" kpx2="250"/><pair kern="-17" kpx2="127"/><pair kern="-44" kpx2="108"/><pair kern="-63" kpx2="98"/><pair kern="-17" kpx2="81"/><pair kern="-21" kpx2="76"/><pair kern="18" kpx2="181"/><pair kern="-155" kpx2="17"/><pair kern="-17" kpx2="128"/><pair kern="-63" kpx2="173"/><pair kern="-44" kpx2="109"/><pair kern="-160" kpx2="197"/><pair kern="-35" kpx2="121"/><pair kern="-17" kpx2="228"/><pair kern="-44" kpx2="110"/><pair kern="-63" kpx2="174"/><pair kern="-17" kpx2="120"/></kerning><kerning kpx1="104"><pair kern="-17" kpx2="229"/><pair kern="-17" kpx2="61"/></kerning><kerning kpx1="72"><pair kern="-17" kpx2="91"/></kerning><kerning kpx1="199"><pair kern="-17" kpx2="246"/><pair kern="-67" kpx2="235"/><pair kern="-21" kpx2="16"/><pair kern="-17" kpx2="112"/><pair kern="-17" kpx2="123"/><pair kern="-17" kpx2="251"/><pair kern="-17" kpx2="113"/><pair kern="-77" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-35" kpx2="73"/><pair kern="-17" kpx2="124"/><pair kern="-35" kpx2="169"/><pair kern="-17" kpx2="252"/><pair kern="-17" kpx2="70"/><pair kern="-77" kpx2="60"/><pair kern="27" kpx2="201"/><pair kern="-17" kpx2="29"/><pair kern="-77" kpx2="234"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="122"/><pair kern="-17" kpx2="210"/><pair kern="-17" kpx2="82"/><pair kern="-54" kpx2="58"/><pair kern="-67" kpx2="186"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="27" kpx2="98"/><pair kern="-123" kpx2="181"/><pair kern="-17" kpx2="17"/><pair kern="-17" kpx2="38"/><pair kern="-17" kpx2="84"/><pair kern="-17" kpx2="121"/><pair kern="-63" kpx2="57"/><pair kern="-17" kpx2="254"/><pair kern="-17" kpx2="87"/><pair kern="-17" kpx2="72"/><pair kern="27" kpx2="199"/><pair kern="-17" kpx2="71"/><pair kern="-128" kpx2="180"/><pair kern="-17" kpx2="253"/><pair kern="-17" kpx2="52"/><pair kern="-17" kpx2="125"/><pair kern="-17" kpx2="42"/><pair kern="-17" kpx2="115"/><pair kern="-40" kpx2="90"/><pair kern="-17" kpx2="111"/><pair kern="27" kpx2="36"/><pair kern="-77" kpx2="55"/><pair kern="-17" kpx2="114"/><pair kern="-17" kpx2="50"/><pair kern="27" kpx2="173"/><pair kern="-67" kpx2="92"/><pair kern="22" kpx2="197"/><pair kern="-58" kpx2="89"/><pair kern="27" kpx2="174"/></kerning><kerning kpx1="54"><pair kern="18" kpx2="173"/><pair kern="18" kpx2="36"/><pair kern="18" kpx2="201"/><pair kern="18" kpx2="199"/><pair kern="18" kpx2="174"/><pair kern="18" kpx2="98"/></kerning><kerning kpx1="180"><pair kern="-35" kpx2="235"/><pair kern="-35" kpx2="246"/><pair kern="-30" kpx2="43"/><pair kern="-72" kpx2="123"/><pair kern="-35" kpx2="251"/><pair kern="-35" kpx2="208"/><pair kern="-188" kpx2="144"/><pair kern="-58" kpx2="59"/><pair kern="-35" kpx2="73"/><pair kern="-30" kpx2="41"/><pair kern="-72" kpx2="124"/><pair kern="-54" kpx2="85"/><pair kern="-128" kpx2="201"/><pair kern="-17" kpx2="61"/><pair kern="-35" kpx2="100"/><pair kern="-72" kpx2="122"/><pair kern="-30" kpx2="47"/><pair kern="-35" kpx2="210"/><pair kern="-72" kpx2="82"/><pair kern="-35" kpx2="186"/><pair kern="-35" kpx2="175"/><pair kern="-35" kpx2="209"/><pair kern="-35" kpx2="103"/><pair kern="-128" kpx2="98"/><pair kern="-54" kpx2="81"/><pair kern="-17" kpx2="229"/><pair kern="-35" kpx2="38"/><pair kern="-72" kpx2="121"/><pair kern="-30" kpx2="37"/><pair kern="-54" kpx2="120"/><pair kern="-30" kpx2="51"/><pair kern="-128" kpx2="199"/><pair kern="-30" kpx2="53"/><pair kern="-30" kpx2="137"/><pair kern="-35" kpx2="233"/><pair kern="-35" kpx2="253"/><pair kern="-35" kpx2="52"/><pair kern="-72" kpx2="125"/><pair kern="-35" kpx2="42"/><pair kern="-35" kpx2="90"/><pair kern="-128" kpx2="36"/><pair kern="-35" kpx2="50"/><pair kern="-30" kpx2="39"/><pair kern="-30" kpx2="236"/><pair kern="-30" kpx2="45"/><pair kern="-128" kpx2="173"/><pair kern="-35" kpx2="92"/><pair kern="-35" kpx2="89"/><pair kern="-30" kpx2="46"/><pair kern="-128" kpx2="174"/></kerning><kerning kpx1="53"><pair kern="-21" kpx2="107"/><pair kern="-54" kpx2="235"/><pair kern="-40" kpx2="16"/><pair kern="-44" kpx2="112"/><pair kern="-44" kpx2="123"/><pair kern="-49" kpx2="251"/><pair kern="-44" kpx2="113"/><pair kern="-63" kpx2="187"/><pair kern="-44" kpx2="129"/><pair kern="-44" kpx2="124"/><pair kern="-54" kpx2="169"/><pair kern="-63" kpx2="60"/><pair kern="-40" kpx2="201"/><pair kern="-21" kpx2="106"/><pair kern="-30" kpx2="29"/><pair kern="-63" kpx2="234"/><pair kern="-49" kpx2="100"/><pair kern="-44" kpx2="122"/><pair kern="-21" kpx2="68"/><pair kern="-40" kpx2="58"/><pair kern="-44" kpx2="82"/><pair kern="-54" kpx2="186"/><pair kern="-40" kpx2="98"/><pair kern="-63" kpx2="181"/><pair kern="-35" kpx2="17"/><pair kern="-49" kpx2="38"/><pair kern="-44" kpx2="121"/><pair kern="-54" kpx2="57"/><pair kern="-44" kpx2="126"/><pair kern="-44" kpx2="72"/><pair kern="-40" kpx2="199"/><pair kern="-72" kpx2="180"/><pair kern="-21" kpx2="105"/><pair kern="-49" kpx2="253"/><pair kern="-44" kpx2="125"/><pair kern="-44" kpx2="115"/><pair kern="-17" kpx2="170"/><pair kern="-44" kpx2="88"/><pair kern="-40" kpx2="36"/><pair kern="-44" kpx2="114"/><pair kern="-72" kpx2="55"/><pair kern="-44" kpx2="127"/><pair kern="-21" kpx2="108"/><pair kern="-44" kpx2="128"/><pair kern="-40" kpx2="173"/><pair kern="-21" kpx2="109"/><pair kern="-54" kpx2="92"/><pair kern="-17" kpx2="197"/><pair kern="-21" kpx2="110"/><pair kern="-40" kpx2="174"/></kerning><kerning kpx1="137"><pair kern="-54" kpx2="180"/><pair kern="-40" kpx2="197"/><pair kern="18" kpx2="16"/><pair kern="-54" kpx2="181"/></kerning><kerning kpx1="233"><pair kern="-44" kpx2="180"/><pair kern="-35" kpx2="197"/><pair kern="-54" kpx2="181"/></kerning><kerning kpx1="253"><pair kern="-17" kpx2="169"/><pair kern="-17" kpx2="60"/><pair kern="-17" kpx2="187"/><pair kern="18" kpx2="181"/><pair kern="-17" kpx2="170"/><pair kern="-17" kpx2="234"/></kerning><kerning kpx1="211"><pair kern="-17" kpx2="229"/><pair kern="-17" kpx2="61"/></kerning><kerning kpx1="78"><pair kern="-17" kpx2="107"/><pair kern="-30" kpx2="126"/><pair kern="-35" kpx2="235"/><pair kern="-35" kpx2="72"/><pair kern="-35" kpx2="112"/><pair kern="-35" kpx2="123"/><pair kern="-35" kpx2="113"/><pair kern="-17" kpx2="105"/><pair kern="-30" kpx2="129"/><pair kern="-35" kpx2="124"/><pair kern="-17" kpx2="106"/><pair kern="-35" kpx2="125"/><pair kern="-35" kpx2="115"/><pair kern="-30" kpx2="88"/><pair kern="-35" kpx2="122"/><pair kern="-17" kpx2="68"/><pair kern="-35" kpx2="82"/><pair kern="-35" kpx2="114"/><pair kern="-35" kpx2="186"/><pair kern="-30" kpx2="127"/><pair kern="-17" kpx2="108"/><pair kern="-30" kpx2="128"/><pair kern="-17" kpx2="109"/><pair kern="-35" kpx2="92"/><pair kern="-35" kpx2="121"/><pair kern="-17" kpx2="110"/></kerning><kerning kpx1="52"><pair kern="-21" kpx2="180"/><pair kern="-63" kpx2="197"/><pair kern="27" kpx2="16"/><pair kern="-17" kpx2="181"/></kerning><kerning kpx1="125"><pair kern="-72" kpx2="180"/><pair kern="-17" kpx2="17"/><pair kern="-63" kpx2="197"/><pair kern="18" kpx2="16"/><pair kern="-30" kpx2="91"/><pair kern="-35" kpx2="181"/></kerning><kerning kpx1="42"><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="169"/><pair kern="-26" kpx2="197"/><pair kern="-35" kpx2="55"/><pair kern="-49" kpx2="60"/><pair kern="-49" kpx2="187"/><pair kern="-21" kpx2="181"/><pair kern="-17" kpx2="170"/><pair kern="-49" kpx2="234"/></kerning><kerning kpx1="170"><pair kern="-17" kpx2="235"/><pair kern="-35" kpx2="199"/><pair kern="-17" kpx2="251"/><pair kern="-109" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-54" kpx2="59"/><pair kern="-109" kpx2="60"/><pair kern="-35" kpx2="201"/><pair kern="-17" kpx2="253"/><pair kern="-109" kpx2="234"/><pair kern="-17" kpx2="90"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="210"/><pair kern="-35" kpx2="36"/><pair kern="-54" kpx2="58"/><pair kern="-91" kpx2="55"/><pair kern="-17" kpx2="186"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="50"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="-17" kpx2="39"/><pair kern="-35" kpx2="98"/><pair kern="-17" kpx2="45"/><pair kern="-35" kpx2="173"/><pair kern="-17" kpx2="92"/><pair kern="-17" kpx2="38"/><pair kern="-17" kpx2="89"/><pair kern="-86" kpx2="57"/><pair kern="-35" kpx2="37"/><pair kern="-35" kpx2="174"/></kerning><kerning kpx1="115"><pair kern="-17" kpx2="91"/></kerning><kerning kpx1="90"><pair kern="-91" kpx2="17"/><pair kern="-17" kpx2="169"/><pair kern="-104" kpx2="197"/><pair kern="-54" kpx2="29"/><pair kern="-17" kpx2="170"/></kerning><kerning kpx1="36"><pair kern="-17" kpx2="246"/><pair kern="-67" kpx2="235"/><pair kern="-21" kpx2="16"/><pair kern="-17" kpx2="112"/><pair kern="-17" kpx2="123"/><pair kern="-17" kpx2="251"/><pair kern="-17" kpx2="113"/><pair kern="-77" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-35" kpx2="73"/><pair kern="-17" kpx2="124"/><pair kern="-35" kpx2="169"/><pair kern="-17" kpx2="252"/><pair kern="-17" kpx2="70"/><pair kern="-77" kpx2="60"/><pair kern="27" kpx2="201"/><pair kern="-17" kpx2="29"/><pair kern="-77" kpx2="234"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="122"/><pair kern="-17" kpx2="210"/><pair kern="-17" kpx2="82"/><pair kern="-54" kpx2="58"/><pair kern="-67" kpx2="186"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="27" kpx2="98"/><pair kern="-123" kpx2="181"/><pair kern="-17" kpx2="17"/><pair kern="-17" kpx2="38"/><pair kern="-17" kpx2="84"/><pair kern="-17" kpx2="121"/><pair kern="-63" kpx2="57"/><pair kern="-17" kpx2="254"/><pair kern="-17" kpx2="87"/><pair kern="-17" kpx2="72"/><pair kern="27" kpx2="199"/><pair kern="-17" kpx2="71"/><pair kern="-128" kpx2="180"/><pair kern="-17" kpx2="253"/><pair kern="-17" kpx2="52"/><pair kern="-17" kpx2="125"/><pair kern="-17" kpx2="42"/><pair kern="-17" kpx2="115"/><pair kern="-40" kpx2="90"/><pair kern="-17" kpx2="111"/><pair kern="27" kpx2="36"/><pair kern="-77" kpx2="55"/><pair kern="-17" kpx2="114"/><pair kern="-17" kpx2="50"/><pair kern="27" kpx2="173"/><pair kern="-67" kpx2="92"/><pair kern="22" kpx2="197"/><pair kern="-58" kpx2="89"/><pair kern="27" kpx2="174"/></kerning><kerning kpx1="55"><pair kern="-165" kpx2="107"/><pair kern="-155" kpx2="235"/><pair kern="-91" kpx2="16"/><pair kern="-169" kpx2="112"/><pair kern="-169" kpx2="123"/><pair kern="-58" kpx2="251"/><pair kern="-169" kpx2="113"/><pair kern="-165" kpx2="86"/><pair kern="-151" kpx2="129"/><pair kern="-169" kpx2="124"/><pair kern="-91" kpx2="169"/><pair kern="-169" kpx2="252"/><pair kern="-169" kpx2="70"/><pair kern="-146" kpx2="85"/><pair kern="-77" kpx2="201"/><pair kern="-165" kpx2="106"/><pair kern="-109" kpx2="29"/><pair kern="-58" kpx2="100"/><pair kern="-169" kpx2="122"/><pair kern="-165" kpx2="68"/><pair kern="-169" kpx2="82"/><pair kern="-155" kpx2="186"/><pair kern="-165" kpx2="250"/><pair kern="-77" kpx2="98"/><pair kern="-21" kpx2="181"/><pair kern="-118" kpx2="17"/><pair kern="-58" kpx2="38"/><pair kern="-169" kpx2="121"/><pair kern="-165" kpx2="228"/><pair kern="-169" kpx2="254"/><pair kern="-151" kpx2="126"/><pair kern="-169" kpx2="72"/><pair kern="-77" kpx2="199"/><pair kern="-165" kpx2="105"/><pair kern="-58" kpx2="253"/><pair kern="-169" kpx2="125"/><pair kern="-169" kpx2="115"/><pair kern="-54" kpx2="170"/><pair kern="-151" kpx2="88"/><pair kern="-169" kpx2="111"/><pair kern="-165" kpx2="90"/><pair kern="-77" kpx2="36"/><pair kern="-17" kpx2="55"/><pair kern="-169" kpx2="114"/><pair kern="-151" kpx2="127"/><pair kern="-165" kpx2="108"/><pair kern="-30" kpx2="76"/><pair kern="-151" kpx2="128"/><pair kern="-77" kpx2="173"/><pair kern="-165" kpx2="109"/><pair kern="-155" kpx2="92"/><pair kern="-128" kpx2="197"/><pair kern="-165" kpx2="110"/><pair kern="-77" kpx2="174"/></kerning><kerning kpx1="114"><pair kern="-17" kpx2="91"/></kerning><kerning kpx1="50"><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="199"/><pair kern="27" kpx2="16"/><pair kern="-54" kpx2="187"/><pair kern="-17" kpx2="98"/><pair kern="-17" kpx2="181"/><pair kern="-63" kpx2="59"/><pair kern="-40" kpx2="17"/><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="169"/><pair kern="-91" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="29"/><pair kern="-17" kpx2="57"/><pair kern="-17" kpx2="174"/><pair kern="-54" kpx2="234"/></kerning><kerning kpx1="91"><pair kern="-17" kpx2="254"/><pair kern="-17" kpx2="111"/><pair kern="-30" kpx2="122"/><pair kern="-30" kpx2="82"/><pair kern="-30" kpx2="114"/><pair kern="-30" kpx2="72"/><pair kern="-30" kpx2="112"/><pair kern="-30" kpx2="123"/><pair kern="-30" kpx2="113"/><pair kern="-30" kpx2="124"/><pair kern="-17" kpx2="252"/><pair kern="-17" kpx2="70"/><pair kern="-30" kpx2="121"/><pair kern="-30" kpx2="125"/><pair kern="-30" kpx2="115"/></kerning><kerning kpx1="39"><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="199"/><pair kern="-17" kpx2="98"/><pair kern="-54" kpx2="187"/><pair kern="-26" kpx2="181"/><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="169"/><pair kern="-91" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="57"/><pair kern="-17" kpx2="174"/><pair kern="-17" kpx2="170"/><pair kern="-54" kpx2="234"/></kerning><kerning kpx1="236"><pair kern="-17" kpx2="180"/><pair kern="-72" kpx2="17"/><pair kern="-91" kpx2="197"/><pair kern="-35" kpx2="29"/></kerning><kerning kpx1="45"><pair kern="-35" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="169"/><pair kern="-54" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-17" kpx2="199"/><pair kern="-35" kpx2="16"/><pair kern="-17" kpx2="174"/><pair kern="-17" kpx2="98"/><pair kern="-30" kpx2="181"/><pair kern="-17" kpx2="170"/></kerning><kerning kpx1="173"><pair kern="-17" kpx2="246"/><pair kern="-67" kpx2="235"/><pair kern="-21" kpx2="16"/><pair kern="-17" kpx2="112"/><pair kern="-17" kpx2="123"/><pair kern="-17" kpx2="251"/><pair kern="-17" kpx2="113"/><pair kern="-77" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-35" kpx2="73"/><pair kern="-17" kpx2="124"/><pair kern="-35" kpx2="169"/><pair kern="-17" kpx2="252"/><pair kern="-17" kpx2="70"/><pair kern="-77" kpx2="60"/><pair kern="27" kpx2="201"/><pair kern="-17" kpx2="29"/><pair kern="-77" kpx2="234"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="122"/><pair kern="-17" kpx2="210"/><pair kern="-17" kpx2="82"/><pair kern="-54" kpx2="58"/><pair kern="-67" kpx2="186"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="27" kpx2="98"/><pair kern="-123" kpx2="181"/><pair kern="-17" kpx2="17"/><pair kern="-17" kpx2="38"/><pair kern="-17" kpx2="84"/><pair kern="-17" kpx2="121"/><pair kern="-63" kpx2="57"/><pair kern="-17" kpx2="254"/><pair kern="-17" kpx2="87"/><pair kern="-17" kpx2="72"/><pair kern="27" kpx2="199"/><pair kern="-17" kpx2="71"/><pair kern="-128" kpx2="180"/><pair kern="-17" kpx2="253"/><pair kern="-17" kpx2="52"/><pair kern="-17" kpx2="125"/><pair kern="-17" kpx2="42"/><pair kern="-17" kpx2="115"/><pair kern="-40" kpx2="90"/><pair kern="-17" kpx2="111"/><pair kern="27" kpx2="36"/><pair kern="-77" kpx2="55"/><pair kern="-17" kpx2="114"/><pair kern="-17" kpx2="50"/><pair kern="27" kpx2="173"/><pair kern="-67" kpx2="92"/><pair kern="22" kpx2="197"/><pair kern="-58" kpx2="89"/><pair kern="27" kpx2="174"/></kerning><kerning kpx1="197"><pair kern="-35" kpx2="246"/><pair kern="-54" kpx2="235"/><pair kern="-35" kpx2="43"/><pair kern="-35" kpx2="123"/><pair kern="-54" kpx2="251"/><pair kern="-183" kpx2="187"/><pair kern="-54" kpx2="208"/><pair kern="18" kpx2="144"/><pair kern="-35" kpx2="59"/><pair kern="-17" kpx2="73"/><pair kern="-35" kpx2="41"/><pair kern="-35" kpx2="124"/><pair kern="-35" kpx2="85"/><pair kern="-183" kpx2="60"/><pair kern="18" kpx2="201"/><pair kern="-183" kpx2="234"/><pair kern="-54" kpx2="100"/><pair kern="-35" kpx2="122"/><pair kern="-35" kpx2="47"/><pair kern="-54" kpx2="210"/><pair kern="-35" kpx2="82"/><pair kern="-123" kpx2="58"/><pair kern="-54" kpx2="186"/><pair kern="-54" kpx2="175"/><pair kern="-54" kpx2="209"/><pair kern="-54" kpx2="103"/><pair kern="-35" kpx2="81"/><pair kern="18" kpx2="98"/><pair kern="-54" kpx2="38"/><pair kern="-35" kpx2="121"/><pair kern="-183" kpx2="57"/><pair kern="-35" kpx2="37"/><pair kern="-35" kpx2="120"/><pair kern="-35" kpx2="51"/><pair kern="18" kpx2="199"/><pair kern="-35" kpx2="53"/><pair kern="-35" kpx2="137"/><pair kern="-35" kpx2="233"/><pair kern="-54" kpx2="253"/><pair kern="-54" kpx2="52"/><pair kern="-35" kpx2="125"/><pair kern="-35" kpx2="42"/><pair kern="-95" kpx2="90"/><pair kern="18" kpx2="36"/><pair kern="-137" kpx2="55"/><pair kern="-54" kpx2="50"/><pair kern="-35" kpx2="39"/><pair kern="-35" kpx2="236"/><pair kern="22" kpx2="45"/><pair kern="18" kpx2="173"/><pair kern="-54" kpx2="92"/><pair kern="-114" kpx2="89"/><pair kern="-35" kpx2="46"/><pair kern="18" kpx2="174"/></kerning><kerning kpx1="92"><pair kern="-142" kpx2="17"/><pair kern="-17" kpx2="169"/><pair kern="-146" kpx2="197"/><pair kern="-17" kpx2="16"/><pair kern="-72" kpx2="29"/><pair kern="-17" kpx2="170"/></kerning><kerning kpx1="89"><pair kern="-77" kpx2="17"/><pair kern="-17" kpx2="169"/><pair kern="-132" kpx2="197"/><pair kern="-26" kpx2="16"/><pair kern="-54" kpx2="29"/><pair kern="-17" kpx2="181"/><pair kern="-17" kpx2="170"/></kerning><kerning kpx1="46"><pair kern="-17" kpx2="107"/><pair kern="-72" kpx2="235"/><pair kern="-104" kpx2="16"/><pair kern="-49" kpx2="112"/><pair kern="-49" kpx2="123"/><pair kern="-54" kpx2="251"/><pair kern="-26" kpx2="213"/><pair kern="-49" kpx2="113"/><pair kern="-35" kpx2="187"/><pair kern="-54" kpx2="208"/><pair kern="-49" kpx2="129"/><pair kern="-49" kpx2="124"/><pair kern="-63" kpx2="169"/><pair kern="-35" kpx2="60"/><pair kern="-17" kpx2="201"/><pair kern="-17" kpx2="106"/><pair kern="-35" kpx2="234"/><pair kern="-54" kpx2="100"/><pair kern="-49" kpx2="122"/><pair kern="-17" kpx2="68"/><pair kern="-54" kpx2="210"/><pair kern="-35" kpx2="58"/><pair kern="-49" kpx2="82"/><pair kern="-72" kpx2="186"/><pair kern="-54" kpx2="175"/><pair kern="-54" kpx2="209"/><pair kern="-54" kpx2="103"/><pair kern="-17" kpx2="98"/><pair kern="-30" kpx2="181"/><pair kern="-26" kpx2="212"/><pair kern="-54" kpx2="38"/><pair kern="-49" kpx2="121"/><pair kern="-49" kpx2="126"/><pair kern="-26" kpx2="104"/><pair kern="-49" kpx2="72"/><pair kern="-17" kpx2="199"/><pair kern="-30" kpx2="180"/><pair kern="-17" kpx2="105"/><pair kern="-54" kpx2="253"/><pair kern="-26" kpx2="211"/><pair kern="-49" kpx2="125"/><pair kern="-49" kpx2="115"/><pair kern="-49" kpx2="88"/><pair kern="-17" kpx2="36"/><pair kern="-77" kpx2="55"/><pair kern="-49" kpx2="114"/><pair kern="-54" kpx2="50"/><pair kern="-49" kpx2="127"/><pair kern="-17" kpx2="108"/><pair kern="-49" kpx2="128"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="109"/><pair kern="-72" kpx2="92"/><pair kern="-17" kpx2="110"/><pair kern="-17" kpx2="174"/><pair kern="-26" kpx2="56"/></kerning><kerning kpx1="174"><pair kern="-17" kpx2="246"/><pair kern="-67" kpx2="235"/><pair kern="-21" kpx2="16"/><pair kern="-17" kpx2="112"/><pair kern="-17" kpx2="123"/><pair kern="-17" kpx2="251"/><pair kern="-17" kpx2="113"/><pair kern="-77" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-35" kpx2="73"/><pair kern="-17" kpx2="124"/><pair kern="-35" kpx2="169"/><pair kern="-17" kpx2="252"/><pair kern="-17" kpx2="70"/><pair kern="-77" kpx2="60"/><pair kern="27" kpx2="201"/><pair kern="-17" kpx2="29"/><pair kern="-77" kpx2="234"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="122"/><pair kern="-17" kpx2="210"/><pair kern="-17" kpx2="82"/><pair kern="-54" kpx2="58"/><pair kern="-67" kpx2="186"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="27" kpx2="98"/><pair kern="-123" kpx2="181"/><pair kern="-17" kpx2="17"/><pair kern="-17" kpx2="38"/><pair kern="-17" kpx2="84"/><pair kern="-17" kpx2="121"/><pair kern="-63" kpx2="57"/><pair kern="-17" kpx2="254"/><pair kern="-17" kpx2="87"/><pair kern="-17" kpx2="72"/><pair kern="27" kpx2="199"/><pair kern="-17" kpx2="71"/><pair kern="-128" kpx2="180"/><pair kern="-17" kpx2="253"/><pair kern="-17" kpx2="52"/><pair kern="-17" kpx2="125"/><pair kern="-17" kpx2="42"/><pair kern="-17" kpx2="115"/><pair kern="-40" kpx2="90"/><pair kern="-17" kpx2="111"/><pair kern="27" kpx2="36"/><pair kern="-77" kpx2="55"/><pair kern="-17" kpx2="114"/><pair kern="-17" kpx2="50"/><pair kern="27" kpx2="173"/><pair kern="-67" kpx2="92"/><pair kern="22" kpx2="197"/><pair kern="-58" kpx2="89"/><pair kern="27" kpx2="174"/></kerning><kerning kpx1="56"><pair kern="-17" kpx2="229"/><pair kern="-17" kpx2="61"/></kerning></font-metrics> \ No newline at end of file
diff --git a/handbook/poky-doc-tools/common/VeraMoBd.ttf b/handbook/poky-doc-tools/common/VeraMoBd.ttf
new file mode 100644
index 0000000000..9be6547ed6
--- /dev/null
+++ b/handbook/poky-doc-tools/common/VeraMoBd.ttf
Binary files differ
diff --git a/handbook/poky-doc-tools/common/VeraMoBd.xml b/handbook/poky-doc-tools/common/VeraMoBd.xml
new file mode 100644
index 0000000000..78c9207502
--- /dev/null
+++ b/handbook/poky-doc-tools/common/VeraMoBd.xml
@@ -0,0 +1 @@
<?xml version="1.0" encoding="UTF-8"?><font-metrics type="TRUETYPE"><font-name>BitstreamVeraSansMono,Bold</font-name><embed/><cap-height>729</cap-height><x-height>546</x-height><ascender>928</ascender><descender>-235</descender><bbox><left>-19</left><bottom>-235</bottom><right>605</right><top>928</top></bbox><flags>34</flags><stemv>0</stemv><italicangle>0</italicangle><subtype>TRUETYPE</subtype><singlebyte-extras><encoding>WinAnsiEncoding</encoding><first-char>0</first-char><last-char>255</last-char><widths><char idx="0" wdt="602"/><char idx="1" wdt="602"/><char idx="2" wdt="602"/><char idx="3" wdt="602"/><char idx="4" wdt="602"/><char idx="5" wdt="602"/><char idx="6" wdt="602"/><char idx="7" wdt="602"/><char idx="8" wdt="602"/><char idx="9" wdt="602"/><char idx="10" wdt="602"/><char idx="11" wdt="602"/><char idx="12" wdt="602"/><char idx="13" wdt="602"/><char idx="14" wdt="602"/><char idx="15" wdt="602"/><char idx="16" wdt="602"/><char idx="17" wdt="602"/><char idx="18" wdt="602"/><char idx="19" wdt="602"/><char idx="20" wdt="602"/><char idx="21" wdt="602"/><char idx="22" wdt="602"/><char idx="23" wdt="602"/><char idx="24" wdt="602"/><char idx="25" wdt="602"/><char idx="26" wdt="602"/><char idx="27" wdt="602"/><char idx="28" wdt="602"/><char idx="29" wdt="602"/><char idx="30" wdt="602"/><char idx="31" wdt="602"/><char idx="32" wdt="602"/><char idx="33" wdt="602"/><char idx="34" wdt="602"/><char idx="35" wdt="602"/><char idx="36" wdt="602"/><char idx="37" wdt="602"/><char idx="38" wdt="602"/><char idx="39" wdt="602"/><char idx="40" wdt="602"/><char idx="41" wdt="602"/><char idx="42" wdt="602"/><char idx="43" wdt="602"/><char idx="44" wdt="602"/><char idx="45" wdt="602"/><char idx="46" wdt="602"/><char idx="47" wdt="602"/><char idx="48" wdt="602"/><char idx="49" wdt="602"/><char idx="50" wdt="602"/><char idx="51" wdt="602"/><char idx="52" wdt="602"/><char idx="53" wdt="602"/><char idx="54" wdt="602"/><char idx="55" wdt="602"/><char idx="56" wdt="602"/><char idx="57" wdt="602"/><char idx="58" wdt="602"/><char idx="59" wdt="602"/><char idx="60" wdt="602"/><char idx="61" wdt="602"/><char idx="62" wdt="602"/><char idx="63" wdt="602"/><char idx="64" wdt="602"/><char idx="65" wdt="602"/><char idx="66" wdt="602"/><char idx="67" wdt="602"/><char idx="68" wdt="602"/><char idx="69" wdt="602"/><char idx="70" wdt="602"/><char idx="71" wdt="602"/><char idx="72" wdt="602"/><char idx="73" wdt="602"/><char idx="74" wdt="602"/><char idx="75" wdt="602"/><char idx="76" wdt="602"/><char idx="77" wdt="602"/><char idx="78" wdt="602"/><char idx="79" wdt="602"/><char idx="80" wdt="602"/><char idx="81" wdt="602"/><char idx="82" wdt="602"/><char idx="83" wdt="602"/><char idx="84" wdt="602"/><char idx="85" wdt="602"/><char idx="86" wdt="602"/><char idx="87" wdt="602"/><char idx="88" wdt="602"/><char idx="89" wdt="602"/><char idx="90" wdt="602"/><char idx="91" wdt="602"/><char idx="92" wdt="602"/><char idx="93" wdt="602"/><char idx="94" wdt="602"/><char idx="95" wdt="602"/><char idx="96" wdt="602"/><char idx="97" wdt="602"/><char idx="98" wdt="602"/><char idx="99" wdt="602"/><char idx="100" wdt="602"/><char idx="101" wdt="602"/><char idx="102" wdt="602"/><char idx="103" wdt="602"/><char idx="104" wdt="602"/><char idx="105" wdt="602"/><char idx="106" wdt="602"/><char idx="107" wdt="602"/><char idx="108" wdt="602"/><char idx="109" wdt="602"/><char idx="110" wdt="602"/><char idx="111" wdt="602"/><char idx="112" wdt="602"/><char idx="113" wdt="602"/><char idx="114" wdt="602"/><char idx="115" wdt="602"/><char idx="116" wdt="602"/><char idx="117" wdt="602"/><char idx="118" wdt="602"/><char idx="119" wdt="602"/><char idx="120" wdt="602"/><char idx="121" wdt="602"/><char idx="122" wdt="602"/><char idx="123" wdt="602"/><char idx="124" wdt="602"/><char idx="125" wdt="602"/><char idx="126" wdt="602"/><char idx="127" wdt="602"/><char idx="128" wdt="602"/><char idx="129" wdt="602"/><char idx="130" wdt="602"/><char idx="131" wdt="602"/><char idx="132" wdt="602"/><char idx="133" wdt="602"/><char idx="134" wdt="602"/><char idx="135" wdt="602"/><char idx="136" wdt="602"/><char idx="137" wdt="602"/><char idx="138" wdt="602"/><char idx="139" wdt="602"/><char idx="140" wdt="602"/><char idx="141" wdt="602"/><char idx="142" wdt="602"/><char idx="143" wdt="602"/><char idx="144" wdt="602"/><char idx="145" wdt="602"/><char idx="146" wdt="602"/><char idx="147" wdt="602"/><char idx="148" wdt="602"/><char idx="149" wdt="602"/><char idx="150" wdt="602"/><char idx="151" wdt="602"/><char idx="152" wdt="602"/><char idx="153" wdt="602"/><char idx="154" wdt="602"/><char idx="155" wdt="602"/><char idx="156" wdt="602"/><char idx="157" wdt="602"/><char idx="158" wdt="602"/><char idx="159" wdt="602"/><char idx="160" wdt="602"/><char idx="161" wdt="602"/><char idx="162" wdt="602"/><char idx="163" wdt="602"/><char idx="164" wdt="602"/><char idx="165" wdt="602"/><char idx="166" wdt="602"/><char idx="167" wdt="602"/><char idx="168" wdt="602"/><char idx="169" wdt="602"/><char idx="170" wdt="602"/><char idx="171" wdt="602"/><char idx="172" wdt="602"/><char idx="173" wdt="602"/><char idx="174" wdt="602"/><char idx="175" wdt="602"/><char idx="176" wdt="602"/><char idx="177" wdt="602"/><char idx="178" wdt="602"/><char idx="179" wdt="602"/><char idx="180" wdt="602"/><char idx="181" wdt="602"/><char idx="182" wdt="602"/><char idx="183" wdt="602"/><char idx="184" wdt="602"/><char idx="185" wdt="602"/><char idx="186" wdt="602"/><char idx="187" wdt="602"/><char idx="188" wdt="602"/><char idx="189" wdt="602"/><char idx="190" wdt="602"/><char idx="191" wdt="602"/><char idx="192" wdt="602"/><char idx="193" wdt="602"/><char idx="194" wdt="602"/><char idx="195" wdt="602"/><char idx="196" wdt="602"/><char idx="197" wdt="602"/><char idx="198" wdt="602"/><char idx="199" wdt="602"/><char idx="200" wdt="602"/><char idx="201" wdt="602"/><char idx="202" wdt="602"/><char idx="203" wdt="602"/><char idx="204" wdt="602"/><char idx="205" wdt="602"/><char idx="206" wdt="602"/><char idx="207" wdt="602"/><char idx="208" wdt="602"/><char idx="209" wdt="602"/><char idx="210" wdt="602"/><char idx="211" wdt="602"/><char idx="212" wdt="602"/><char idx="213" wdt="602"/><char idx="214" wdt="602"/><char idx="215" wdt="602"/><char idx="216" wdt="602"/><char idx="217" wdt="602"/><char idx="218" wdt="602"/><char idx="219" wdt="602"/><char idx="220" wdt="602"/><char idx="221" wdt="602"/><char idx="222" wdt="602"/><char idx="223" wdt="602"/><char idx="224" wdt="602"/><char idx="225" wdt="602"/><char idx="226" wdt="602"/><char idx="227" wdt="602"/><char idx="228" wdt="602"/><char idx="229" wdt="602"/><char idx="230" wdt="602"/><char idx="231" wdt="602"/><char idx="232" wdt="602"/><char idx="233" wdt="602"/><char idx="234" wdt="602"/><char idx="235" wdt="602"/><char idx="236" wdt="602"/><char idx="237" wdt="602"/><char idx="238" wdt="602"/><char idx="239" wdt="602"/><char idx="240" wdt="602"/><char idx="241" wdt="602"/><char idx="242" wdt="602"/><char idx="243" wdt="602"/><char idx="244" wdt="602"/><char idx="245" wdt="602"/><char idx="246" wdt="602"/><char idx="247" wdt="602"/><char idx="248" wdt="602"/><char idx="249" wdt="602"/><char idx="250" wdt="602"/><char idx="251" wdt="602"/><char idx="252" wdt="602"/><char idx="253" wdt="602"/><char idx="254" wdt="602"/><char idx="255" wdt="602"/></widths></singlebyte-extras></font-metrics> \ No newline at end of file
diff --git a/handbook/poky-doc-tools/common/VeraMono.ttf b/handbook/poky-doc-tools/common/VeraMono.ttf
new file mode 100644
index 0000000000..139f0b4311
--- /dev/null
+++ b/handbook/poky-doc-tools/common/VeraMono.ttf
Binary files differ
diff --git a/handbook/poky-doc-tools/common/VeraMono.xml b/handbook/poky-doc-tools/common/VeraMono.xml
new file mode 100644
index 0000000000..61607b453a
--- /dev/null
+++ b/handbook/poky-doc-tools/common/VeraMono.xml
@@ -0,0 +1 @@
<?xml version="1.0" encoding="UTF-8"?><font-metrics type="TRUETYPE"><font-name>BitstreamVeraSansMono</font-name><embed/><cap-height>729</cap-height><x-height>546</x-height><ascender>928</ascender><descender>-235</descender><bbox><left>-4</left><bottom>-235</bottom><right>605</right><top>928</top></bbox><flags>34</flags><stemv>0</stemv><italicangle>0</italicangle><subtype>TRUETYPE</subtype><singlebyte-extras><encoding>WinAnsiEncoding</encoding><first-char>0</first-char><last-char>255</last-char><widths><char idx="0" wdt="602"/><char idx="1" wdt="602"/><char idx="2" wdt="602"/><char idx="3" wdt="602"/><char idx="4" wdt="602"/><char idx="5" wdt="602"/><char idx="6" wdt="602"/><char idx="7" wdt="602"/><char idx="8" wdt="602"/><char idx="9" wdt="602"/><char idx="10" wdt="602"/><char idx="11" wdt="602"/><char idx="12" wdt="602"/><char idx="13" wdt="602"/><char idx="14" wdt="602"/><char idx="15" wdt="602"/><char idx="16" wdt="602"/><char idx="17" wdt="602"/><char idx="18" wdt="602"/><char idx="19" wdt="602"/><char idx="20" wdt="602"/><char idx="21" wdt="602"/><char idx="22" wdt="602"/><char idx="23" wdt="602"/><char idx="24" wdt="602"/><char idx="25" wdt="602"/><char idx="26" wdt="602"/><char idx="27" wdt="602"/><char idx="28" wdt="602"/><char idx="29" wdt="602"/><char idx="30" wdt="602"/><char idx="31" wdt="602"/><char idx="32" wdt="602"/><char idx="33" wdt="602"/><char idx="34" wdt="602"/><char idx="35" wdt="602"/><char idx="36" wdt="602"/><char idx="37" wdt="602"/><char idx="38" wdt="602"/><char idx="39" wdt="602"/><char idx="40" wdt="602"/><char idx="41" wdt="602"/><char idx="42" wdt="602"/><char idx="43" wdt="602"/><char idx="44" wdt="602"/><char idx="45" wdt="602"/><char idx="46" wdt="602"/><char idx="47" wdt="602"/><char idx="48" wdt="602"/><char idx="49" wdt="602"/><char idx="50" wdt="602"/><char idx="51" wdt="602"/><char idx="52" wdt="602"/><char idx="53" wdt="602"/><char idx="54" wdt="602"/><char idx="55" wdt="602"/><char idx="56" wdt="602"/><char idx="57" wdt="602"/><char idx="58" wdt="602"/><char idx="59" wdt="602"/><char idx="60" wdt="602"/><char idx="61" wdt="602"/><char idx="62" wdt="602"/><char idx="63" wdt="602"/><char idx="64" wdt="602"/><char idx="65" wdt="602"/><char idx="66" wdt="602"/><char idx="67" wdt="602"/><char idx="68" wdt="602"/><char idx="69" wdt="602"/><char idx="70" wdt="602"/><char idx="71" wdt="602"/><char idx="72" wdt="602"/><char idx="73" wdt="602"/><char idx="74" wdt="602"/><char idx="75" wdt="602"/><char idx="76" wdt="602"/><char idx="77" wdt="602"/><char idx="78" wdt="602"/><char idx="79" wdt="602"/><char idx="80" wdt="602"/><char idx="81" wdt="602"/><char idx="82" wdt="602"/><char idx="83" wdt="602"/><char idx="84" wdt="602"/><char idx="85" wdt="602"/><char idx="86" wdt="602"/><char idx="87" wdt="602"/><char idx="88" wdt="602"/><char idx="89" wdt="602"/><char idx="90" wdt="602"/><char idx="91" wdt="602"/><char idx="92" wdt="602"/><char idx="93" wdt="602"/><char idx="94" wdt="602"/><char idx="95" wdt="602"/><char idx="96" wdt="602"/><char idx="97" wdt="602"/><char idx="98" wdt="602"/><char idx="99" wdt="602"/><char idx="100" wdt="602"/><char idx="101" wdt="602"/><char idx="102" wdt="602"/><char idx="103" wdt="602"/><char idx="104" wdt="602"/><char idx="105" wdt="602"/><char idx="106" wdt="602"/><char idx="107" wdt="602"/><char idx="108" wdt="602"/><char idx="109" wdt="602"/><char idx="110" wdt="602"/><char idx="111" wdt="602"/><char idx="112" wdt="602"/><char idx="113" wdt="602"/><char idx="114" wdt="602"/><char idx="115" wdt="602"/><char idx="116" wdt="602"/><char idx="117" wdt="602"/><char idx="118" wdt="602"/><char idx="119" wdt="602"/><char idx="120" wdt="602"/><char idx="121" wdt="602"/><char idx="122" wdt="602"/><char idx="123" wdt="602"/><char idx="124" wdt="602"/><char idx="125" wdt="602"/><char idx="126" wdt="602"/><char idx="127" wdt="602"/><char idx="128" wdt="602"/><char idx="129" wdt="602"/><char idx="130" wdt="602"/><char idx="131" wdt="602"/><char idx="132" wdt="602"/><char idx="133" wdt="602"/><char idx="134" wdt="602"/><char idx="135" wdt="602"/><char idx="136" wdt="602"/><char idx="137" wdt="602"/><char idx="138" wdt="602"/><char idx="139" wdt="602"/><char idx="140" wdt="602"/><char idx="141" wdt="602"/><char idx="142" wdt="602"/><char idx="143" wdt="602"/><char idx="144" wdt="602"/><char idx="145" wdt="602"/><char idx="146" wdt="602"/><char idx="147" wdt="602"/><char idx="148" wdt="602"/><char idx="149" wdt="602"/><char idx="150" wdt="602"/><char idx="151" wdt="602"/><char idx="152" wdt="602"/><char idx="153" wdt="602"/><char idx="154" wdt="602"/><char idx="155" wdt="602"/><char idx="156" wdt="602"/><char idx="157" wdt="602"/><char idx="158" wdt="602"/><char idx="159" wdt="602"/><char idx="160" wdt="602"/><char idx="161" wdt="602"/><char idx="162" wdt="602"/><char idx="163" wdt="602"/><char idx="164" wdt="602"/><char idx="165" wdt="602"/><char idx="166" wdt="602"/><char idx="167" wdt="602"/><char idx="168" wdt="602"/><char idx="169" wdt="602"/><char idx="170" wdt="602"/><char idx="171" wdt="602"/><char idx="172" wdt="602"/><char idx="173" wdt="602"/><char idx="174" wdt="602"/><char idx="175" wdt="602"/><char idx="176" wdt="602"/><char idx="177" wdt="602"/><char idx="178" wdt="602"/><char idx="179" wdt="602"/><char idx="180" wdt="602"/><char idx="181" wdt="602"/><char idx="182" wdt="602"/><char idx="183" wdt="602"/><char idx="184" wdt="602"/><char idx="185" wdt="602"/><char idx="186" wdt="602"/><char idx="187" wdt="602"/><char idx="188" wdt="602"/><char idx="189" wdt="602"/><char idx="190" wdt="602"/><char idx="191" wdt="602"/><char idx="192" wdt="602"/><char idx="193" wdt="602"/><char idx="194" wdt="602"/><char idx="195" wdt="602"/><char idx="196" wdt="602"/><char idx="197" wdt="602"/><char idx="198" wdt="602"/><char idx="199" wdt="602"/><char idx="200" wdt="602"/><char idx="201" wdt="602"/><char idx="202" wdt="602"/><char idx="203" wdt="602"/><char idx="204" wdt="602"/><char idx="205" wdt="602"/><char idx="206" wdt="602"/><char idx="207" wdt="602"/><char idx="208" wdt="602"/><char idx="209" wdt="602"/><char idx="210" wdt="602"/><char idx="211" wdt="602"/><char idx="212" wdt="602"/><char idx="213" wdt="602"/><char idx="214" wdt="602"/><char idx="215" wdt="602"/><char idx="216" wdt="602"/><char idx="217" wdt="602"/><char idx="218" wdt="602"/><char idx="219" wdt="602"/><char idx="220" wdt="602"/><char idx="221" wdt="602"/><char idx="222" wdt="602"/><char idx="223" wdt="602"/><char idx="224" wdt="602"/><char idx="225" wdt="602"/><char idx="226" wdt="602"/><char idx="227" wdt="602"/><char idx="228" wdt="602"/><char idx="229" wdt="602"/><char idx="230" wdt="602"/><char idx="231" wdt="602"/><char idx="232" wdt="602"/><char idx="233" wdt="602"/><char idx="234" wdt="602"/><char idx="235" wdt="602"/><char idx="236" wdt="602"/><char idx="237" wdt="602"/><char idx="238" wdt="602"/><char idx="239" wdt="602"/><char idx="240" wdt="602"/><char idx="241" wdt="602"/><char idx="242" wdt="602"/><char idx="243" wdt="602"/><char idx="244" wdt="602"/><char idx="245" wdt="602"/><char idx="246" wdt="602"/><char idx="247" wdt="602"/><char idx="248" wdt="602"/><char idx="249" wdt="602"/><char idx="250" wdt="602"/><char idx="251" wdt="602"/><char idx="252" wdt="602"/><char idx="253" wdt="602"/><char idx="254" wdt="602"/><char idx="255" wdt="602"/></widths></singlebyte-extras></font-metrics> \ No newline at end of file
diff --git a/handbook/poky-doc-tools/common/draft.png b/handbook/poky-doc-tools/common/draft.png
new file mode 100644
index 0000000000..53051a9ddd
--- /dev/null
+++ b/handbook/poky-doc-tools/common/draft.png
Binary files differ
diff --git a/handbook/poky-doc-tools/common/fop-config.xml.in b/handbook/poky-doc-tools/common/fop-config.xml.in
new file mode 100644
index 0000000000..649ccb566f
--- /dev/null
+++ b/handbook/poky-doc-tools/common/fop-config.xml.in
@@ -0,0 +1,33 @@
1<configuration>
2 <entry>
3 <!--
4 Set the baseDir so common/openedhand.svg references in plans still
5 work ok. Note, relative file references to current dir should still work.
6 -->
7 <key>baseDir</key>
8 <value>@datadir@</value>
9 </entry>
10 <fonts>
11 <font metrics-file="@datadir@/common/VeraMono.xml"
12 kerning="yes"
13 embed-file="@datadir@/common/VeraMono.ttf">
14 <font-triplet name="veramono" style="normal" weight="normal"/>
15 </font>
16
17 <font metrics-file="@datadir@/common/VeraMoBd.xml"
18 kerning="yes"
19 embed-file="@datadir@/common/VeraMoBd.ttf">
20 <font-triplet name="veramono" style="normal" weight="bold"/>
21 </font>
22
23 <font metrics-file="@datadir@/common/Vera.xml"
24 kerning="yes"
25 embed-file="@datadir@/common/Vera.ttf">
26 <font-triplet name="verasans" style="normal" weight="normal"/>
27 <font-triplet name="verasans" style="normal" weight="bold"/>
28 <font-triplet name="verasans" style="italic" weight="normal"/>
29 <font-triplet name="verasans" style="italic" weight="bold"/>
30 </font>
31
32 </fonts>
33</configuration> \ No newline at end of file
diff --git a/handbook/poky-doc-tools/common/ohand-color.svg b/handbook/poky-doc-tools/common/ohand-color.svg
new file mode 100644
index 0000000000..e42ff9c6fc
--- /dev/null
+++ b/handbook/poky-doc-tools/common/ohand-color.svg
@@ -0,0 +1,150 @@
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2<!-- Created with Inkscape (http://www.inkscape.org/) -->
3<svg
4 xmlns:dc="http://purl.org/dc/elements/1.1/"
5 xmlns:cc="http://web.resource.org/cc/"
6 xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
7 xmlns:svg="http://www.w3.org/2000/svg"
8 xmlns="http://www.w3.org/2000/svg"
9 xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
10 xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
11 width="141.17999"
12 height="55.34"
13 id="svg2207"
14 sodipodi:version="0.32"
15 inkscape:version="0.45"
16 version="1.0"
17 sodipodi:docname="ohand-color.svg"
18 inkscape:output_extension="org.inkscape.output.svg.inkscape"
19 sodipodi:docbase="/home/mallum/Projects/admin/oh-doc-tools/common"
20 sodipodi:modified="true">
21 <defs
22 id="defs3" />
23 <sodipodi:namedview
24 id="base"
25 pagecolor="#ffffff"
26 bordercolor="#666666"
27 borderopacity="1.0"
28 inkscape:pageopacity="0.0"
29 inkscape:pageshadow="2"
30 inkscape:zoom="1.2"
31 inkscape:cx="160"
32 inkscape:cy="146.21189"
33 inkscape:document-units="mm"
34 inkscape:current-layer="layer1"
35 height="55.34px"
36 width="141.18px"
37 inkscape:window-width="772"
38 inkscape:window-height="581"
39 inkscape:window-x="5"
40 inkscape:window-y="48" />
41 <metadata
42 id="metadata2211">
43 <rdf:RDF>
44 <cc:Work
45 rdf:about="">
46 <dc:format>image/svg+xml</dc:format>
47 <dc:type
48 rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
49 </cc:Work>
50 </rdf:RDF>
51 </metadata>
52 <g
53 inkscape:label="Layer 1"
54 inkscape:groupmode="layer"
55 id="layer1">
56 <g
57 id="g2094"
58 style="fill:#6d6d70;fill-opacity:1"
59 inkscape:export-filename="/home/mallum/Desktop/g2126.png"
60 inkscape:export-xdpi="312.71841"
61 inkscape:export-ydpi="312.71841"
62 transform="matrix(0.5954767,0,0,0.5954767,31.793058,-18.471052)">
63 <g
64 id="g19"
65 style="fill:#6d6d70;fill-opacity:1">
66 <path
67 style="fill:#6d6d70;fill-opacity:1"
68 id="path21"
69 d="M 48.693,50.633 C 40.282,50.633 33.439,57.477 33.439,65.888 L 33.439,81.142 L 41.066,81.142 L 41.066,65.888 C 41.066,61.684 44.486,58.261 48.692,58.261 C 52.897,58.261 56.32,61.684 56.32,65.888 C 56.32,70.093 52.897,73.516 48.692,73.516 C 45.677,73.516 43.065,71.756 41.828,69.211 L 41.828,79.504 C 43.892,80.549 46.224,81.142 48.692,81.142 C 57.103,81.142 63.947,74.3 63.947,65.888 C 63.948,57.477 57.104,50.633 48.693,50.633 z " />
70 </g>
71 <path
72 style="fill:#6d6d70;fill-opacity:1"
73 id="path23"
74 d="M 18.486,50.557 C 26.942,50.557 33.819,57.435 33.819,65.888 C 33.819,74.344 26.942,81.223 18.486,81.223 C 10.032,81.223 3.152,74.344 3.152,65.888 C 3.152,57.435 10.032,50.557 18.486,50.557 z M 18.486,73.556 C 22.713,73.556 26.153,70.118 26.153,65.888 C 26.153,61.661 22.713,58.222 18.486,58.222 C 14.258,58.222 10.819,61.661 10.819,65.888 C 10.82,70.117 14.259,73.556 18.486,73.556 z " />
75 <path
76 style="fill:#6d6d70;fill-opacity:1"
77 id="path25"
78 d="M 94.074,107.465 L 94.074,96.016 C 94.074,87.605 87.233,80.763 78.822,80.763 C 70.41,80.763 63.567,87.605 63.567,96.016 C 63.567,104.427 70.41,111.269 78.822,111.269 C 81.289,111.269 83.621,110.676 85.685,109.631 L 85.685,99.339 C 84.448,101.885 81.836,103.644 78.822,103.644 C 74.615,103.644 71.194,100.221 71.194,96.016 C 71.194,91.81 74.615,88.388 78.822,88.388 C 83.026,88.388 86.448,91.81 86.448,96.016 L 86.448,107.456 C 86.448,109.562 88.156,111.268 90.262,111.268 C 92.364,111.269 94.068,109.566 94.074,107.465 z " />
79 <path
80 style="fill:#6d6d70;fill-opacity:1"
81 id="path27"
82 d="M 124.197,95.814 C 124.088,87.496 117.293,80.762 108.949,80.762 C 100.59,80.762 93.783,87.52 93.697,95.856 L 93.693,95.856 L 93.695,107.456 C 93.695,109.562 95.402,111.268 97.509,111.268 C 99.611,111.268 101.316,109.566 101.321,107.464 L 101.321,95.994 L 101.321,95.994 C 101.333,91.798 104.747,88.388 108.948,88.388 C 113.147,88.388 116.563,91.798 116.575,95.994 L 116.575,107.456 C 116.575,109.562 118.282,111.268 120.387,111.268 C 122.492,111.268 124.201,109.562 124.201,107.456 L 124.201,95.814 L 124.197,95.814 z " />
83 <path
84 style="fill:#6d6d70;fill-opacity:1"
85 id="path29"
86 d="M 63.946,96.005 L 63.946,95.854 L 63.943,95.854 L 63.943,95.815 L 63.942,95.815 C 63.833,87.497 57.037,80.761 48.693,80.761 C 48.682,80.761 48.671,80.763 48.658,80.763 C 48.382,80.763 48.107,80.772 47.833,80.786 C 47.75,80.791 47.668,80.799 47.586,80.806 C 47.378,80.822 47.172,80.838 46.968,80.862 C 46.884,80.873 46.801,80.882 46.719,80.893 C 46.508,80.92 46.298,80.952 46.091,80.987 C 46.024,80.999 45.958,81.01 45.891,81.024 C 45.649,81.068 45.406,81.119 45.168,81.175 C 45.14,81.183 45.112,81.189 45.085,81.195 C 43.656,81.542 42.306,82.092 41.065,82.812 L 41.065,80.761 L 33.438,80.761 L 33.438,95.857 L 33.435,95.857 L 33.435,107.457 C 33.435,109.563 35.142,111.269 37.248,111.269 C 39.093,111.269 40.632,109.958 40.984,108.217 C 41.036,107.963 41.065,107.702 41.065,107.435 L 41.065,95.873 C 41.086,94.732 41.357,93.65 41.828,92.685 L 41.828,92.693 C 42.598,91.106 43.905,89.824 45.511,89.085 C 45.519,89.08 45.529,89.076 45.536,89.073 C 45.849,88.928 46.174,88.807 46.508,88.707 C 46.523,88.704 46.536,88.699 46.55,88.696 C 46.699,88.651 46.85,88.614 47.004,88.576 C 47.025,88.575 47.046,88.567 47.069,88.562 C 47.234,88.527 47.402,88.495 47.572,88.469 C 47.586,88.468 47.6,88.466 47.615,88.463 C 47.763,88.443 47.916,88.427 48.067,88.415 C 48.106,88.41 48.145,88.407 48.186,88.404 C 48.352,88.393 48.52,88.386 48.691,88.386 C 52.888,88.387 56.304,91.797 56.316,95.992 L 56.316,107.454 C 56.316,109.56 58.023,111.266 60.13,111.266 C 61.976,111.266 63.516,109.954 63.867,108.211 C 63.919,107.963 63.946,107.706 63.946,107.442 L 63.946,96.024 C 63.946,96.021 63.947,96.018 63.947,96.015 C 63.948,96.011 63.946,96.008 63.946,96.005 z " />
87 <path
88 style="fill:#6d6d70;fill-opacity:1"
89 id="path31"
90 d="M 180.644,50.633 C 178.539,50.633 176.832,52.341 176.832,54.447 L 176.832,65.887 C 176.832,70.092 173.41,73.513 169.203,73.513 C 164.998,73.513 161.576,70.092 161.576,65.887 C 161.576,61.683 164.998,58.26 169.203,58.26 C 172.219,58.26 174.83,60.019 176.068,62.565 L 176.068,52.271 C 174.004,51.225 171.673,50.632 169.203,50.632 C 160.793,50.632 153.951,57.476 153.951,65.887 C 153.951,74.298 160.793,81.141 169.203,81.141 C 177.615,81.141 184.459,74.298 184.459,65.887 L 184.459,54.447 C 184.458,52.341 182.751,50.633 180.644,50.633 z " />
91 <path
92 style="fill:#6d6d70;fill-opacity:1"
93 id="path33"
94 d="M 124.203,77.339 L 124.203,65.687 L 124.197,65.687 C 124.088,57.371 117.293,50.633 108.949,50.633 C 100.592,50.633 93.783,57.393 93.697,65.731 L 93.695,65.731 L 93.695,65.877 C 93.695,65.882 93.693,65.885 93.693,65.888 C 93.693,65.891 93.695,65.896 93.695,65.899 L 93.695,77.33 C 93.695,79.435 95.402,81.142 97.509,81.142 C 99.614,81.142 101.321,79.435 101.321,77.33 L 101.321,65.868 C 101.333,61.672 104.747,58.261 108.948,58.261 C 113.147,58.261 116.563,61.672 116.575,65.868 L 116.575,65.868 L 116.575,77.329 C 116.575,79.434 118.282,81.141 120.389,81.141 C 122.492,81.142 124.197,79.44 124.203,77.339 z " />
95 <path
96 style="fill:#6d6d70;fill-opacity:1"
97 id="path35"
98 d="M 150.517,80.761 C 148.41,80.761 146.703,82.469 146.703,84.575 L 146.703,96.015 C 146.703,100.22 143.283,103.643 139.076,103.643 C 134.871,103.643 131.449,100.22 131.449,96.015 C 131.449,91.808 134.871,88.387 139.076,88.387 C 142.092,88.387 144.703,90.145 145.941,92.692 L 145.941,82.397 C 143.875,81.353 141.545,80.76 139.076,80.76 C 130.666,80.76 123.822,87.604 123.822,96.015 C 123.822,104.426 130.666,111.268 139.076,111.268 C 147.486,111.268 154.33,104.426 154.33,96.015 L 154.33,84.575 C 154.33,82.469 152.623,80.761 150.517,80.761 z " />
99 <path
100 style="fill:#6d6d70;fill-opacity:1"
101 id="path37"
102 d="M 82.625,77.345 C 82.625,75.247 80.923,73.547 78.826,73.547 L 78.826,81.142 C 80.922,81.142 82.625,79.442 82.625,77.345 z " />
103 <path
104 style="fill:#6d6d70;fill-opacity:1"
105 id="path39"
106 d="M 90.252,69.685 C 92.35,69.685 94.048,67.987 94.048,65.888 L 86.453,65.888 C 86.453,67.986 88.154,69.685 90.252,69.685 z " />
107 <path
108 style="fill:#6d6d70;fill-opacity:1"
109 id="path41"
110 d="M 93.832,77.329 C 93.832,75.223 92.125,73.516 90.018,73.516 L 78.825,73.516 C 74.619,73.516 71.199,70.093 71.199,65.888 C 71.199,61.684 74.619,58.261 78.825,58.261 C 83.032,58.261 86.453,61.684 86.453,65.888 C 86.453,68.904 84.694,71.514 82.149,72.752 L 92.442,72.752 C 93.488,70.689 94.08,68.356 94.08,65.888 C 94.08,57.477 87.237,50.633 78.826,50.633 C 70.415,50.633 63.571,57.477 63.571,65.888 C 63.571,74.3 70.415,81.142 78.826,81.142 L 90.018,81.142 C 92.125,81.142 93.832,79.435 93.832,77.329 z " />
111 <path
112 style="fill:#6d6d70;fill-opacity:1"
113 id="path43"
114 d="M 142.869,77.345 C 142.869,75.247 141.168,73.547 139.07,73.547 L 139.07,81.142 C 141.167,81.142 142.869,79.442 142.869,77.345 z " />
115 <path
116 style="fill:#6d6d70;fill-opacity:1"
117 id="path45"
118 d="M 150.496,69.685 C 152.594,69.685 154.293,67.987 154.293,65.888 L 146.699,65.888 C 146.699,67.986 148.398,69.685 150.496,69.685 z " />
119 <path
120 style="fill:#6d6d70;fill-opacity:1"
121 id="path47"
122 d="M 154.076,77.329 C 154.076,75.223 152.367,73.516 150.262,73.516 L 139.07,73.516 C 134.865,73.516 131.443,70.093 131.443,65.888 C 131.443,61.684 134.865,58.261 139.07,58.261 C 143.275,58.261 146.699,61.684 146.699,65.888 C 146.699,68.904 144.939,71.514 142.392,72.752 L 152.687,72.752 C 153.73,70.689 154.324,68.356 154.324,65.888 C 154.324,57.477 147.48,50.633 139.07,50.633 C 130.66,50.633 123.816,57.477 123.816,65.888 C 123.816,74.3 130.66,81.142 139.07,81.142 L 150.261,81.142 C 152.367,81.142 154.076,79.435 154.076,77.329 z " />
123 </g>
124 <g
125 id="g2126"
126 transform="matrix(0.7679564,0,0,0.7679564,-66.520631,11.42903)"
127 inkscape:export-xdpi="312.71841"
128 inkscape:export-ydpi="312.71841"
129 style="fill:#35992a;fill-opacity:1">
130 <g
131 transform="translate(86.33975,4.23985e-2)"
132 style="fill:#35992a;fill-opacity:1"
133 id="g2114">
134 <g
135 style="fill:#35992a;fill-opacity:1"
136 id="g2116">
137 <path
138 id="path2118"
139 transform="translate(-86.33975,-4.239934e-2)"
140 d="M 89.96875,0.03125 C 87.962748,0.031250001 86.34375,1.6815001 86.34375,3.6875 L 86.34375,17.71875 L 86.34375,19.6875 L 86.34375,28.90625 C 86.343752,39.06825 94.61925,47.34375 104.78125,47.34375 L 113.375,47.34375 L 123.1875,47.34375 L 127.15625,47.34375 C 129.16325,47.343749 130.8125,45.72475 130.8125,43.71875 C 130.8125,41.71275 129.16325,40.09375 127.15625,40.09375 L 123.1875,40.09375 L 123.1875,19.6875 L 123.1875,14.65625 L 123.1875,3.6875 C 123.1875,1.6815 121.5675,0.03125 119.5625,0.03125 C 117.5555,0.031250001 115.9375,1.6815001 115.9375,3.6875 L 115.9375,14.28125 C 115.1185,13.65425 114.26275,13.109 113.34375,12.625 L 113.34375,3.6875 C 113.34475,1.6815 111.6925,0.03125 109.6875,0.03125 C 107.6825,0.031250001 106.0625,1.6815001 106.0625,3.6875 L 106.0625,10.5625 C 105.6305,10.5325 105.22025,10.5 104.78125,10.5 C 104.34125,10.5 103.90075,10.5325 103.46875,10.5625 L 103.46875,3.6875 C 103.46975,1.6815 101.84975,0.03125 99.84375,0.03125 C 97.837749,0.031250001 96.21875,1.6815001 96.21875,3.6875 L 96.21875,12.625 C 95.299754,13.109 94.41375,13.65425 93.59375,14.28125 L 93.59375,3.6875 C 93.59475,1.6815 91.97475,0.03125 89.96875,0.03125 z M 104.78125,14.34375 C 112.80825,14.34375 119.3125,20.87925 119.3125,28.90625 C 119.3125,36.93325 112.80825,43.46875 104.78125,43.46875 C 96.754254,43.46875 90.21875,36.93425 90.21875,28.90625 C 90.218752,20.87825 96.753253,14.34375 104.78125,14.34375 z "
141 style="fill:#35992a;fill-opacity:1" />
142 </g>
143 </g>
144 <path
145 style="fill:#35992a;fill-opacity:1"
146 id="path2122"
147 d="M 112.04875,28.913399 C 112.04875,24.899399 108.78275,21.634399 104.76975,21.634399 C 100.75675,21.634399 97.490753,24.900399 97.490753,28.913399 C 97.490753,32.926399 100.75675,36.192399 104.76975,36.192399 C 108.78275,36.192399 112.04875,32.927399 112.04875,28.913399 z " />
148 </g>
149 </g>
150</svg>
diff --git a/handbook/poky-doc-tools/common/poky-db-pdf.xsl b/handbook/poky-doc-tools/common/poky-db-pdf.xsl
new file mode 100644
index 0000000000..d1452eb0bb
--- /dev/null
+++ b/handbook/poky-doc-tools/common/poky-db-pdf.xsl
@@ -0,0 +1,64 @@
1<?xml version='1.0'?>
2<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
3
4 <xsl:import href="file:///usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl"/>
5
6 <!-- check project-plan.sh for how this is generated, needed to tweak
7 the cover page
8 -->
9 <xsl:include href="/tmp/titlepage.xsl"/>
10
11 <!-- To force a page break in document, i.e per section add a
12 <?hard-pagebreak?> tag.
13 -->
14 <xsl:template match="processing-instruction('hard-pagebreak')">
15 <fo:block break-before='page' />
16 </xsl:template>
17
18 <!--Fix for defualt indent getting TOC all wierd..
19 See http://sources.redhat.com/ml/docbook-apps/2005-q1/msg00455.html
20 FIXME: must be a better fix
21 -->
22 <xsl:param name="body.start.indent" select="'0'"/>
23 <!--<xsl:param name="title.margin.left" select="'0'"/>-->
24
25 <!-- stop long-ish header titles getting wrapped -->
26 <xsl:param name="header.column.widths">1 10 1</xsl:param>
27
28 <!-- customise headers and footers a little -->
29
30 <xsl:template name="head.sep.rule">
31 <xsl:if test="$header.rule != 0">
32 <xsl:attribute name="border-bottom-width">0.5pt</xsl:attribute>
33 <xsl:attribute name="border-bottom-style">solid</xsl:attribute>
34 <xsl:attribute name="border-bottom-color">#cccccc</xsl:attribute>
35 </xsl:if>
36 </xsl:template>
37
38 <xsl:template name="foot.sep.rule">
39 <xsl:if test="$footer.rule != 0">
40 <xsl:attribute name="border-top-width">0.5pt</xsl:attribute>
41 <xsl:attribute name="border-top-style">solid</xsl:attribute>
42 <xsl:attribute name="border-top-color">#cccccc</xsl:attribute>
43 </xsl:if>
44 </xsl:template>
45
46 <xsl:attribute-set name="header.content.properties">
47 <xsl:attribute name="color">#cccccc</xsl:attribute>
48 </xsl:attribute-set>
49
50 <xsl:attribute-set name="footer.content.properties">
51 <xsl:attribute name="color">#cccccc</xsl:attribute>
52 </xsl:attribute-set>
53
54
55 <!-- general settings -->
56
57 <xsl:param name="fop.extensions" select="1"></xsl:param>
58 <xsl:param name="paper.type" select="'A4'"></xsl:param>
59 <xsl:param name="section.autolabel" select="1"></xsl:param>
60 <xsl:param name="body.font.family" select="'verasans'"></xsl:param>
61 <xsl:param name="title.font.family" select="'verasans'"></xsl:param>
62 <xsl:param name="monospace.font.family" select="'veramono'"></xsl:param>
63
64</xsl:stylesheet>
diff --git a/handbook/poky-doc-tools/common/poky-handbook.png b/handbook/poky-doc-tools/common/poky-handbook.png
new file mode 100644
index 0000000000..2085edb467
--- /dev/null
+++ b/handbook/poky-doc-tools/common/poky-handbook.png
Binary files differ
diff --git a/handbook/poky-doc-tools/common/poky.svg b/handbook/poky-doc-tools/common/poky.svg
new file mode 100644
index 0000000000..a4ea5e2f45
--- /dev/null
+++ b/handbook/poky-doc-tools/common/poky.svg
@@ -0,0 +1,163 @@
1<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2<!-- Created with Inkscape (http://www.inkscape.org/) -->
3<svg
4 xmlns:svg="http://www.w3.org/2000/svg"
5 xmlns="http://www.w3.org/2000/svg"
6 version="1.0"
7 width="158.56076"
8 height="79.284424"
9 viewBox="-40.981 -92.592 300 300"
10 id="svg2"
11 xml:space="preserve">
12<defs
13 id="defs4">
14</defs>
15<path
16 d="M -36.585379,54.412576 L -36.585379,54.421305 L -36.582469,54.421305 L -36.582469,54.243829 C -36.57956,54.302018 -36.585379,54.357297 -36.585379,54.412576 z "
17 style="fill:#6ac7bd"
18 id="path6" />
19<g
20 transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
21 style="opacity:0.65"
22 id="g8">
23 <g
24 id="g10">
25 <path
26 d="M 24.482,23.998 L 24.482,23.995 C 10.961,23.994 0,34.955 0,48.476 L 0.001,48.479 L 0.001,48.482 C 0.003,62.001 10.962,72.96 24.482,72.96 L 24.482,72.96 L 0,72.96 L 0,97.442 L 0.003,97.442 C 13.523,97.44 24.482,86.48 24.482,72.961 L 24.485,72.961 C 38.005,72.959 48.963,62 48.963,48.479 L 48.963,48.476 C 48.962,34.957 38.001,23.998 24.482,23.998 z M 24.482,50.928 C 23.13,50.928 22.034,49.832 22.034,48.48 C 22.034,47.128 23.13,46.032 24.482,46.032 C 25.834,46.032 26.93,47.128 26.93,48.48 C 26.93,49.832 25.834,50.928 24.482,50.928 z "
27 style="fill:#ef412a"
28 id="path12" />
29 </g>
30</g>
31<g
32 transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
33 style="opacity:0.65"
34 id="g14">
35 <g
36 id="g16">
37 <path
38 d="M 119.96,48.842 C 120.024,47.548 121.086,46.516 122.397,46.516 C 123.707,46.516 124.768,47.548 124.833,48.843 C 137.211,47.62 146.879,37.181 146.879,24.483 L 122.397,24.483 C 122.396,10.961 111.435,0 97.915,0 L 97.915,24.485 C 97.917,37.183 107.584,47.619 119.96,48.842 z M 124.833,49.084 C 124.769,50.379 123.707,51.411 122.397,51.411 L 122.396,51.411 L 122.396,73.444 L 146.878,73.444 L 146.878,73.441 C 146.876,60.745 137.208,50.308 124.833,49.084 z M 119.949,48.963 L 97.915,48.963 L 97.915,73.442 L 97.915,73.442 C 110.613,73.442 121.052,63.774 122.275,51.399 C 120.981,51.334 119.949,50.274 119.949,48.963 z "
39 style="fill:#a9c542"
40 id="path18" />
41 </g>
42</g>
43<g
44 transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
45 style="opacity:0.65"
46 id="g20">
47 <g
48 id="g22">
49 <path
50 d="M 168.912,48.967 C 168.912,47.656 169.945,46.596 171.24,46.531 C 170.018,34.152 159.579,24.482 146.879,24.482 L 146.879,48.963 C 146.879,62.484 157.84,73.444 171.361,73.444 L 171.361,51.414 C 170.007,51.415 168.912,50.319 168.912,48.967 z M 195.841,48.978 C 195.841,48.973 195.842,48.969 195.842,48.964 L 195.842,24.482 L 195.838,24.482 C 183.14,24.484 172.702,34.154 171.482,46.531 C 172.776,46.595 173.808,47.656 173.808,48.967 C 173.808,50.278 172.776,51.339 171.481,51.403 C 172.679,63.59 182.814,73.146 195.244,73.445 L 171.361,73.445 L 171.361,97.927 L 171.364,97.927 C 184.879,97.925 195.834,86.973 195.842,73.46 L 195.844,73.46 L 195.844,48.979 L 195.841,48.978 z M 195.832,48.964 L 195.842,48.964 L 195.842,48.978 L 195.832,48.964 z "
51 style="fill:#f9c759"
52 id="path24" />
53 </g>
54</g>
55<g
56 transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
57 style="opacity:0.65"
58 id="g26">
59 <g
60 id="g28">
61 <path
62 d="M 70.994,48.479 L 48.962,48.479 L 48.962,48.481 L 70.995,48.481 C 70.995,48.481 70.994,48.48 70.994,48.479 z M 73.44,24.001 L 73.437,24.001 L 73.437,46.032 C 73.439,46.032 73.44,46.032 73.442,46.032 C 74.794,46.032 75.89,47.128 75.89,48.48 C 75.89,49.832 74.794,50.928 73.442,50.928 C 72.091,50.928 70.996,49.834 70.994,48.483 L 48.958,48.483 L 48.958,48.486 C 48.96,62.005 59.919,72.964 73.437,72.964 C 86.955,72.964 97.914,62.005 97.916,48.486 L 97.916,48.483 C 97.916,34.963 86.958,24.003 73.44,24.001 z "
63 style="fill:#6ac7bd"
64 id="path30" />
65 </g>
66</g>
67<g
68 transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
69 style="opacity:0.65"
70 id="g32">
71 <g
72 id="g34">
73 <path
74 d="M 24.482,23.998 L 24.482,23.995 C 10.961,23.994 0,34.955 0,48.476 L 22.034,48.476 C 22.036,47.125 23.131,46.031 24.482,46.031 C 25.834,46.031 26.93,47.127 26.93,48.479 C 26.93,49.831 25.834,50.927 24.482,50.927 L 24.482,72.937 C 24.469,59.427 13.514,48.479 0,48.479 L 0,72.96 L 24.481,72.96 L 24.481,72.96 L 0,72.96 L 0,97.442 L 0.003,97.442 C 13.523,97.44 24.482,86.48 24.482,72.961 L 24.485,72.961 C 38.005,72.959 48.963,62 48.963,48.479 L 48.963,48.476 C 48.962,34.957 38.001,23.998 24.482,23.998 z "
75 style="fill:#ef412a"
76 id="path36" />
77 </g>
78</g>
79<g
80 transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
81 style="opacity:0.65"
82 id="g38">
83 <g
84 id="g40">
85 <path
86 d="M 122.397,46.516 C 123.707,46.516 124.768,47.548 124.833,48.843 C 137.211,47.62 146.879,37.181 146.879,24.483 L 122.397,24.483 L 122.397,46.516 L 122.397,46.516 z M 97.915,0 L 97.915,24.482 L 122.396,24.482 C 122.396,10.961 111.435,0 97.915,0 z M 122.275,46.528 C 121.052,34.151 110.613,24.482 97.914,24.482 L 97.914,48.964 L 97.914,48.964 L 97.914,73.443 L 97.914,73.443 C 110.612,73.443 121.051,63.775 122.274,51.4 C 120.98,51.335 119.948,50.275 119.948,48.964 C 119.949,47.653 120.98,46.593 122.275,46.528 z M 124.833,49.084 C 124.769,50.379 123.707,51.411 122.397,51.411 L 122.396,51.411 L 122.396,73.444 L 146.878,73.444 L 146.878,73.441 C 146.876,60.745 137.208,50.308 124.833,49.084 z "
87 style="fill:#a9c542"
88 id="path42" />
89 </g>
90</g>
91<g
92 transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
93 style="opacity:0.65"
94 id="g44">
95 <g
96 id="g46">
97 <path
98 d="M 173.795,49.1 C 173.724,50.389 172.666,51.415 171.36,51.415 C 170.006,51.415 168.911,50.319 168.911,48.967 C 168.911,47.656 169.944,46.596 171.239,46.531 C 170.017,34.152 159.578,24.482 146.878,24.482 L 146.878,48.963 C 146.878,62.484 157.839,73.444 171.36,73.444 L 171.36,97.926 L 171.363,97.926 C 184.878,97.924 195.833,86.972 195.841,73.459 L 195.842,73.459 L 195.842,73.443 L 195.841,73.443 C 195.833,60.753 186.167,50.322 173.795,49.1 z M 195.838,24.482 C 183.14,24.484 172.702,34.154 171.482,46.531 C 172.775,46.595 173.806,47.655 173.808,48.964 L 195.841,48.964 L 195.841,48.979 C 195.841,48.974 195.842,48.969 195.842,48.964 L 195.842,24.482 L 195.838,24.482 z "
99 style="fill:#f9c759"
100 id="path48" />
101 </g>
102</g>
103<g
104 transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
105 style="opacity:0.65"
106 id="g50">
107 <g
108 id="g52">
109 <path
110 d="M 71.007,48.347 C 71.075,47.105 72.062,46.117 73.304,46.046 C 72.509,38.02 67.85,31.133 61.201,27.284 C 57.601,25.2 53.424,24 48.965,24 L 48.962,24 C 48.962,28.46 50.161,32.638 52.245,36.24 C 56.093,42.891 62.98,47.552 71.007,48.347 z M 48.962,48.418 C 48.962,48.438 48.961,48.456 48.961,48.476 L 48.961,48.479 L 48.962,48.479 L 48.962,48.418 z M 70.995,48.482 C 70.995,48.481 70.995,48.481 70.995,48.48 L 48.962,48.48 L 48.962,48.482 L 70.995,48.482 z M 73.44,24.001 L 73.437,24.001 L 73.437,46.032 C 73.439,46.032 73.44,46.032 73.442,46.032 C 74.794,46.032 75.89,47.128 75.89,48.48 C 75.89,49.832 74.794,50.928 73.442,50.928 C 72.091,50.928 70.996,49.834 70.994,48.483 L 48.958,48.483 L 48.958,48.486 C 48.96,62.005 59.919,72.964 73.437,72.964 C 86.955,72.964 97.914,62.005 97.916,48.486 L 97.916,48.483 C 97.916,34.963 86.958,24.003 73.44,24.001 z "
111 style="fill:#6ac7bd"
112 id="path54" />
113 </g>
114</g>
115<g
116 transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
117 style="opacity:0.65"
118 id="g56">
119 <g
120 id="g58">
121 <path
122 d="M 24.482,23.998 L 24.482,23.995 C 10.961,23.994 0,34.955 0,48.476 L 22.034,48.476 C 22.036,47.125 23.131,46.031 24.482,46.031 C 25.834,46.031 26.93,47.127 26.93,48.479 C 26.93,49.831 25.834,50.927 24.482,50.927 C 23.171,50.927 22.11,49.894 22.046,48.6 C 9.669,49.824 0.001,60.262 0.001,72.96 L 0,72.96 L 0,97.442 L 0.003,97.442 C 13.523,97.44 24.482,86.48 24.482,72.961 L 24.485,72.961 C 38.005,72.959 48.963,62 48.963,48.479 L 48.963,48.476 C 48.962,34.957 38.001,23.998 24.482,23.998 z "
123 style="fill:#ef412a"
124 id="path60" />
125 </g>
126</g>
127<g
128 transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
129 style="opacity:0.65"
130 id="g62">
131 <g
132 id="g64">
133 <path
134 d="M 119.949,48.963 C 119.949,47.611 121.045,46.515 122.397,46.515 C 123.707,46.515 124.768,47.547 124.833,48.842 C 137.211,47.619 146.879,37.18 146.879,24.482 L 122.397,24.482 C 122.396,10.961 111.435,0 97.915,0 L 97.915,24.482 L 122.394,24.482 C 108.874,24.484 97.916,35.444 97.916,48.963 L 97.916,48.963 L 97.916,73.442 L 97.916,73.442 C 110.614,73.442 121.053,63.774 122.276,51.399 C 120.981,51.334 119.949,50.274 119.949,48.963 z M 124.833,49.084 C 124.769,50.379 123.707,51.411 122.397,51.411 L 122.396,51.411 L 122.396,73.444 L 146.878,73.444 L 146.878,73.441 C 146.876,60.745 137.208,50.308 124.833,49.084 z "
135 style="fill:#a9c542"
136 id="path66" />
137 </g>
138</g>
139<g
140 transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
141 style="opacity:0.65"
142 id="g68">
143 <g
144 id="g70">
145 <path
146 d="M 195.841,48.979 L 195.835,48.964 L 195.841,48.964 L 195.841,48.979 C 195.841,48.974 195.842,48.969 195.842,48.964 L 195.842,24.482 L 195.838,24.482 C 183.14,24.484 172.702,34.154 171.482,46.531 C 172.776,46.595 173.808,47.656 173.808,48.967 C 173.808,50.319 172.712,51.415 171.361,51.415 C 170.007,51.415 168.912,50.319 168.912,48.967 C 168.912,47.656 169.945,46.596 171.24,46.531 C 170.018,34.152 159.579,24.482 146.879,24.482 L 146.879,48.963 C 146.879,62.484 157.84,73.444 171.361,73.444 L 171.361,97.926 L 171.364,97.926 C 184.883,97.924 195.843,86.963 195.843,73.444 L 171.959,73.444 C 185.203,73.126 195.841,62.299 195.841,48.979 z "
147 style="fill:#f9c759"
148 id="path72" />
149 </g>
150</g>
151<g
152 transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
153 style="opacity:0.65"
154 id="g74">
155 <g
156 id="g76">
157 <path
158 d="M 73.44,24.001 L 73.437,24.001 C 59.919,24.003 48.96,34.959 48.958,48.476 L 48.958,48.479 L 48.961,48.479 L 48.961,48.481 L 48.957,48.482 L 48.957,48.485 C 48.959,62.004 59.918,72.963 73.436,72.963 C 86.954,72.963 97.913,62.004 97.915,48.485 L 97.915,48.482 C 97.916,34.963 86.958,24.003 73.44,24.001 z M 73.442,50.928 C 72.09,50.928 70.994,49.832 70.994,48.48 C 70.994,47.128 72.09,46.032 73.442,46.032 C 74.794,46.032 75.89,47.128 75.89,48.48 C 75.89,49.832 74.794,50.928 73.442,50.928 z "
159 style="fill:#6ac7bd"
160 id="path78" />
161 </g>
162</g>
163</svg> \ No newline at end of file
diff --git a/handbook/poky-doc-tools/common/titlepage.templates.xml b/handbook/poky-doc-tools/common/titlepage.templates.xml
new file mode 100644
index 0000000000..ff640fa5f2
--- /dev/null
+++ b/handbook/poky-doc-tools/common/titlepage.templates.xml
@@ -0,0 +1,1240 @@
1<!DOCTYPE t:templates [
2<!ENTITY hsize0 "10pt">
3<!ENTITY hsize1 "12pt">
4<!ENTITY hsize2 "14.4pt">
5<!ENTITY hsize3 "17.28pt">
6<!ENTITY hsize4 "20.736pt">
7<!ENTITY hsize5 "24.8832pt">
8<!ENTITY hsize0space "7.5pt"> <!-- 0.75 * hsize0 -->
9<!ENTITY hsize1space "9pt"> <!-- 0.75 * hsize1 -->
10<!ENTITY hsize2space "10.8pt"> <!-- 0.75 * hsize2 -->
11<!ENTITY hsize3space "12.96pt"> <!-- 0.75 * hsize3 -->
12<!ENTITY hsize4space "15.552pt"> <!-- 0.75 * hsize4 -->
13<!ENTITY hsize5space "18.6624pt"> <!-- 0.75 * hsize5 -->
14]>
15<t:templates xmlns:t="http://nwalsh.com/docbook/xsl/template/1.0"
16 xmlns:param="http://nwalsh.com/docbook/xsl/template/1.0/param"
17 xmlns:fo="http://www.w3.org/1999/XSL/Format"
18 xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
19
20<!-- ********************************************************************
21 $Id: titlepage.templates.xml,v 1.23 2003/12/16 00:30:49 bobstayton Exp $
22 ********************************************************************
23
24 This file is part of the DocBook XSL Stylesheet distribution.
25 See ../README or http://docbook.sf.net/ for copyright
26 and other information.
27
28 ******************************************************************** -->
29
30<!-- ==================================================================== -->
31
32<t:titlepage t:element="article" t:wrapper="fo:block"
33 font-family="{$title.fontset}">
34
35 <t:titlepage-content t:side="recto"
36 text-align="center">
37
38 <mediaobject/>
39
40 <title t:named-template="component.title"
41 param:node="ancestor-or-self::article[1]"
42 keep-with-next="always"
43 font-size="&hsize5;"
44 font-weight="bold"/>
45
46 <subtitle param:node="ancestor-or-self::article[1]"
47 keep-with-next="always"
48 font-size="&hsize3;"
49 font-weight="bold"
50 space-after="0.8em"/>
51
52 <corpauthor space-before="0.5em"
53 font-size="&hsize3;"/>
54 <authorgroup space-before="0.5em"
55 font-size="&hsize2;"/>
56 <author space-before="0.5em"
57 font-size="&hsize2;"
58 space-after="0.8em"/>
59
60 <email font-size="&hsize2;"/>
61
62 <othercredit space-before="0.5em"/>
63 <releaseinfo space-before="0.5em"/>
64 <copyright space-before="0.5em"/>
65 <legalnotice text-align="start"
66 margin-left="0.5in"
67 margin-right="0.5in"
68 font-family="{$body.fontset}"/>
69 <pubdate space-before="0.5em"/>
70 <para></para>
71 <revision space-before="0.5em"/>
72 <revhistory space-before="0.5em"/>
73 <abstract space-before="0.5em"
74 text-align="start"
75 margin-left="0.5in"
76 margin-right="0.5in"
77 font-family="{$body.fontset}"/>
78
79 <para></para>
80 </t:titlepage-content>
81
82 <t:titlepage-content t:side="verso">
83 </t:titlepage-content>
84
85 <t:titlepage-separator>
86 </t:titlepage-separator>
87
88 <t:titlepage-before t:side="recto">
89 </t:titlepage-before>
90
91 <t:titlepage-before t:side="verso">
92 </t:titlepage-before>
93</t:titlepage>
94
95<!-- ==================================================================== -->
96
97<t:titlepage t:element="set" t:wrapper="fo:block">
98 <t:titlepage-content t:side="recto">
99 <title
100 t:named-template="division.title"
101 param:node="ancestor-or-self::set[1]"
102 text-align="center"
103 font-size="&hsize5;"
104 space-before="&hsize5space;"
105 font-weight="bold"
106 font-family="{$title.fontset}"/>
107 <subtitle
108 font-family="{$title.fontset}"
109 text-align="center"/>
110 <corpauthor/>
111 <authorgroup/>
112 <author/>
113 <othercredit/>
114 <releaseinfo/>
115 <copyright/>
116 <legalnotice/>
117 <pubdate/>
118 <revision/>
119 <revhistory/>
120 <abstract/>
121 </t:titlepage-content>
122
123 <t:titlepage-content t:side="verso">
124 </t:titlepage-content>
125
126 <t:titlepage-separator>
127 </t:titlepage-separator>
128
129 <t:titlepage-before t:side="recto">
130 </t:titlepage-before>
131
132 <t:titlepage-before t:side="verso">
133 </t:titlepage-before>
134</t:titlepage>
135
136<!-- ==================================================================== -->
137
138 <t:titlepage t:element="book" t:wrapper="fo:block">
139 <t:titlepage-content t:side="recto">
140
141 <mediaobject/>
142
143 <title
144 t:named-template="division.title"
145 param:node="ancestor-or-self::book[1]"
146 text-align="center"
147 font-size="&hsize5;"
148 space-before="&hsize5space;"
149 font-weight="bold"
150 font-family="{$title.fontset}"/>
151 <subtitle
152 text-align="center"
153 font-size="&hsize4;"
154 space-before="&hsize4space;"
155 font-family="{$title.fontset}"/>
156 <corpauthor font-size="&hsize3;"
157 keep-with-next="always"
158 space-before="2in"/>
159 <authorgroup space-before="2in"/>
160 <author font-size="&hsize3;"
161 space-before="&hsize2space;"
162 keep-with-next="always"/>
163 </t:titlepage-content>
164
165 <t:titlepage-content t:side="verso">
166 <title
167 t:named-template="book.verso.title"
168 font-size="&hsize2;"
169 font-weight="bold"
170 font-family="{$title.fontset}"/>
171 <corpauthor/>
172 <authorgroup t:named-template="verso.authorgroup"/>
173 <author/>
174 <othercredit/>
175 <pubdate space-before="1em"/>
176 <copyright/>
177 <abstract/>
178 <legalnotice font-size="8pt"/>
179 </t:titlepage-content>
180
181 <t:titlepage-separator>
182 <fo:block break-after="page"/>
183 </t:titlepage-separator>
184
185 <t:titlepage-before t:side="recto">
186 </t:titlepage-before>
187
188 <t:titlepage-before t:side="verso">
189 <fo:block break-after="page"/>
190 </t:titlepage-before>
191</t:titlepage>
192
193<!-- ==================================================================== -->
194
195<t:titlepage t:element="part" t:wrapper="fo:block">
196 <t:titlepage-content t:side="recto">
197 <title
198 t:named-template="division.title"
199 param:node="ancestor-or-self::part[1]"
200 text-align="center"
201 font-size="&hsize5;"
202 space-before="&hsize5space;"
203 font-weight="bold"
204 font-family="{$title.fontset}"/>
205 <subtitle
206 text-align="center"
207 font-size="&hsize4;"
208 space-before="&hsize4space;"
209 font-weight='bold'
210 font-style='italic'
211 font-family="{$title.fontset}"/>
212 </t:titlepage-content>
213
214 <t:titlepage-content t:side="verso">
215 </t:titlepage-content>
216
217 <t:titlepage-separator>
218 </t:titlepage-separator>
219
220 <t:titlepage-before t:side="recto">
221 </t:titlepage-before>
222
223 <t:titlepage-before t:side="verso">
224 </t:titlepage-before>
225</t:titlepage>
226
227<t:titlepage t:element="partintro" t:wrapper="fo:block">
228 <t:titlepage-content t:side="recto">
229 <title
230 text-align="center"
231 font-size="&hsize5;"
232 font-weight="bold"
233 space-before="1em"
234 font-family="{$title.fontset}"/>
235 <subtitle
236 text-align="center"
237 font-size="&hsize2;"
238 font-weight="bold"
239 font-style="italic"
240 font-family="{$title.fontset}"/>
241 <corpauthor/>
242 <authorgroup/>
243 <author/>
244 <othercredit/>
245 <releaseinfo/>
246 <copyright/>
247 <legalnotice/>
248 <pubdate/>
249 <revision/>
250 <revhistory/>
251 <abstract/>
252 </t:titlepage-content>
253
254 <t:titlepage-content t:side="verso">
255 </t:titlepage-content>
256
257 <t:titlepage-separator>
258 </t:titlepage-separator>
259
260 <t:titlepage-before t:side="recto">
261 </t:titlepage-before>
262
263 <t:titlepage-before t:side="verso">
264 </t:titlepage-before>
265</t:titlepage>
266
267<!-- ==================================================================== -->
268
269<t:titlepage t:element="reference" t:wrapper="fo:block">
270 <t:titlepage-content t:side="recto">
271 <title
272 t:named-template="division.title"
273 param:node="ancestor-or-self::reference[1]"
274 text-align="center"
275 font-size="&hsize5;"
276 space-before="&hsize5space;"
277 font-weight="bold"
278 font-family="{$title.fontset}"/>
279 <subtitle
280 font-family="{$title.fontset}"
281 text-align="center"/>
282 <corpauthor/>
283 <authorgroup/>
284 <author/>
285 <othercredit/>
286 <releaseinfo/>
287 <copyright/>
288 <legalnotice/>
289 <pubdate/>
290 <revision/>
291 <revhistory/>
292 <abstract/>
293 </t:titlepage-content>
294
295 <t:titlepage-content t:side="verso">
296 </t:titlepage-content>
297
298 <t:titlepage-separator>
299 </t:titlepage-separator>
300
301 <t:titlepage-before t:side="recto">
302 </t:titlepage-before>
303
304 <t:titlepage-before t:side="verso">
305 </t:titlepage-before>
306</t:titlepage>
307
308<!-- ==================================================================== -->
309
310<t:titlepage t:element="refsynopsisdiv" t:wrapper="fo:block">
311 <t:titlepage-content t:side="recto">
312 <title
313 font-family="{$title.fontset}"/>
314 </t:titlepage-content>
315
316 <t:titlepage-content t:side="verso">
317 </t:titlepage-content>
318
319 <t:titlepage-separator>
320 </t:titlepage-separator>
321
322 <t:titlepage-before t:side="recto">
323 </t:titlepage-before>
324
325 <t:titlepage-before t:side="verso">
326 </t:titlepage-before>
327</t:titlepage>
328
329<!-- ==================================================================== -->
330
331<t:titlepage t:element="refsection" t:wrapper="fo:block">
332 <t:titlepage-content t:side="recto">
333 <title
334 font-family="{$title.fontset}"/>
335 </t:titlepage-content>
336
337 <t:titlepage-content t:side="verso">
338 </t:titlepage-content>
339
340 <t:titlepage-separator>
341 </t:titlepage-separator>
342
343 <t:titlepage-before t:side="recto">
344 </t:titlepage-before>
345
346 <t:titlepage-before t:side="verso">
347 </t:titlepage-before>
348</t:titlepage>
349
350<!-- ==================================================================== -->
351
352<t:titlepage t:element="refsect1" t:wrapper="fo:block">
353 <t:titlepage-content t:side="recto">
354 <title
355 font-family="{$title.fontset}"/>
356 </t:titlepage-content>
357
358 <t:titlepage-content t:side="verso">
359 </t:titlepage-content>
360
361 <t:titlepage-separator>
362 </t:titlepage-separator>
363
364 <t:titlepage-before t:side="recto">
365 </t:titlepage-before>
366
367 <t:titlepage-before t:side="verso">
368 </t:titlepage-before>
369</t:titlepage>
370
371<!-- ==================================================================== -->
372
373<t:titlepage t:element="refsect2" t:wrapper="fo:block">
374 <t:titlepage-content t:side="recto">
375 <title
376 font-family="{$title.fontset}"/>
377 </t:titlepage-content>
378
379 <t:titlepage-content t:side="verso">
380 </t:titlepage-content>
381
382 <t:titlepage-separator>
383 </t:titlepage-separator>
384
385 <t:titlepage-before t:side="recto">
386 </t:titlepage-before>
387
388 <t:titlepage-before t:side="verso">
389 </t:titlepage-before>
390</t:titlepage>
391
392<!-- ==================================================================== -->
393
394<t:titlepage t:element="refsect3" t:wrapper="fo:block">
395 <t:titlepage-content t:side="recto">
396 <title
397 font-family="{$title.fontset}"/>
398 </t:titlepage-content>
399
400 <t:titlepage-content t:side="verso">
401 </t:titlepage-content>
402
403 <t:titlepage-separator>
404 </t:titlepage-separator>
405
406 <t:titlepage-before t:side="recto">
407 </t:titlepage-before>
408
409 <t:titlepage-before t:side="verso">
410 </t:titlepage-before>
411</t:titlepage>
412
413<!-- ==================================================================== -->
414
415 <t:titlepage t:element="dedication" t:wrapper="fo:block">
416 <t:titlepage-content t:side="recto">
417 <title
418 t:force="1"
419 t:named-template="component.title"
420 param:node="ancestor-or-self::dedication[1]"
421 margin-left="{$title.margin.left}"
422 font-size="&hsize5;"
423 font-family="{$title.fontset}"
424 font-weight="bold"/>
425 <subtitle
426 font-family="{$title.fontset}"/>
427 </t:titlepage-content>
428
429 <t:titlepage-content t:side="verso">
430 </t:titlepage-content>
431
432 <t:titlepage-separator>
433 </t:titlepage-separator>
434
435 <t:titlepage-before t:side="recto">
436 </t:titlepage-before>
437
438 <t:titlepage-before t:side="verso">
439 </t:titlepage-before>
440</t:titlepage>
441
442<!-- ==================================================================== -->
443
444 <t:titlepage t:element="preface" t:wrapper="fo:block">
445 <t:titlepage-content t:side="recto">
446 <title
447 t:force="1"
448 t:named-template="component.title"
449 param:node="ancestor-or-self::preface[1]"
450 margin-left="{$title.margin.left}"
451 font-size="&hsize5;"
452 font-family="{$title.fontset}"
453 font-weight="bold"/>
454 <subtitle
455 font-family="{$title.fontset}"/>
456 <corpauthor/>
457 <authorgroup/>
458 <author/>
459 <othercredit/>
460 <releaseinfo/>
461 <copyright/>
462 <legalnotice/>
463 <pubdate/>
464 <revision/>
465 <revhistory/>
466 <abstract/>
467 </t:titlepage-content>
468
469 <t:titlepage-content t:side="verso">
470 </t:titlepage-content>
471
472 <t:titlepage-separator>
473 </t:titlepage-separator>
474
475 <t:titlepage-before t:side="recto">
476 </t:titlepage-before>
477
478 <t:titlepage-before t:side="verso">
479 </t:titlepage-before>
480</t:titlepage>
481
482<!-- ==================================================================== -->
483
484 <t:titlepage t:element="chapter" t:wrapper="fo:block"
485 font-family="{$title.fontset}">
486 <t:titlepage-content t:side="recto" margin-left="{$title.margin.left}">
487 <title t:named-template="component.title"
488 param:node="ancestor-or-self::chapter[1]"
489 font-size="&hsize5;"
490 font-weight="bold"/>
491
492 <subtitle space-before="0.5em"
493 font-style="italic"
494 font-size="&hsize2;"
495 font-weight="bold"/>
496
497 <corpauthor space-before="0.5em"
498 space-after="0.5em"
499 font-size="&hsize2;"/>
500
501 <authorgroup space-before="0.5em"
502 space-after="0.5em"
503 font-size="&hsize2;"/>
504
505 <author space-before="0.5em"
506 space-after="0.5em"
507 font-size="&hsize2;"/>
508
509 <othercredit/>
510 <releaseinfo/>
511 <copyright/>
512 <legalnotice/>
513 <pubdate/>
514 <revision/>
515 <revhistory/>
516 <abstract/>
517 </t:titlepage-content>
518
519 <t:titlepage-content t:side="verso">
520 </t:titlepage-content>
521
522 <t:titlepage-separator>
523 </t:titlepage-separator>
524
525 <t:titlepage-before t:side="recto">
526 </t:titlepage-before>
527
528 <t:titlepage-before t:side="verso">
529 </t:titlepage-before>
530</t:titlepage>
531
532<!-- ==================================================================== -->
533
534 <t:titlepage t:element="appendix" t:wrapper="fo:block">
535 <t:titlepage-content t:side="recto">
536 <title
537 t:named-template="component.title"
538 param:node="ancestor-or-self::appendix[1]"
539 margin-left="{$title.margin.left}"
540 font-size="&hsize5;"
541 font-weight="bold"
542 font-family="{$title.fontset}"/>
543 <subtitle
544 font-family="{$title.fontset}"/>
545 <corpauthor/>
546 <authorgroup/>
547 <author/>
548 <othercredit/>
549 <releaseinfo/>
550 <copyright/>
551 <legalnotice/>
552 <pubdate/>
553 <revision/>
554 <revhistory/>
555 <abstract/>
556 </t:titlepage-content>
557
558 <t:titlepage-content t:side="verso">
559 </t:titlepage-content>
560
561 <t:titlepage-separator>
562 </t:titlepage-separator>
563
564 <t:titlepage-before t:side="recto">
565 </t:titlepage-before>
566
567 <t:titlepage-before t:side="verso">
568 </t:titlepage-before>
569</t:titlepage>
570
571<!-- ==================================================================== -->
572
573<t:titlepage t:element="section" t:wrapper="fo:block">
574 <t:titlepage-content t:side="recto">
575 <title
576 margin-left="{$title.margin.left}"
577 font-family="{$title.fontset}"/>
578 <subtitle
579 font-family="{$title.fontset}"/>
580 <corpauthor/>
581 <authorgroup/>
582 <author/>
583 <othercredit/>
584 <releaseinfo/>
585 <copyright/>
586 <legalnotice/>
587 <pubdate/>
588 <revision/>
589 <revhistory/>
590 <abstract/>
591 </t:titlepage-content>
592
593 <t:titlepage-content t:side="verso">
594 </t:titlepage-content>
595
596 <t:titlepage-separator>
597 </t:titlepage-separator>
598
599 <t:titlepage-before t:side="recto">
600 </t:titlepage-before>
601
602 <t:titlepage-before t:side="verso">
603 </t:titlepage-before>
604</t:titlepage>
605
606<t:titlepage t:element="sect1" t:wrapper="fo:block">
607 <t:titlepage-content t:side="recto">
608 <title
609 margin-left="{$title.margin.left}"
610 font-family="{$title.fontset}"/>
611 <subtitle
612 font-family="{$title.fontset}"/>
613 <corpauthor/>
614 <authorgroup/>
615 <author/>
616 <othercredit/>
617 <releaseinfo/>
618 <copyright/>
619 <legalnotice/>
620 <pubdate/>
621 <revision/>
622 <revhistory/>
623 <abstract/>
624 </t:titlepage-content>
625
626 <t:titlepage-content t:side="verso">
627 </t:titlepage-content>
628
629 <t:titlepage-separator>
630 </t:titlepage-separator>
631
632 <t:titlepage-before t:side="recto">
633 </t:titlepage-before>
634
635 <t:titlepage-before t:side="verso">
636 </t:titlepage-before>
637</t:titlepage>
638
639<t:titlepage t:element="sect2" t:wrapper="fo:block">
640 <t:titlepage-content t:side="recto">
641 <title
642 margin-left="{$title.margin.left}"
643 font-family="{$title.fontset}"/>
644 <subtitle
645 font-family="{$title.fontset}"/>
646 <corpauthor/>
647 <authorgroup/>
648 <author/>
649 <othercredit/>
650 <releaseinfo/>
651 <copyright/>
652 <legalnotice/>
653 <pubdate/>
654 <revision/>
655 <revhistory/>
656 <abstract/>
657 </t:titlepage-content>
658
659 <t:titlepage-content t:side="verso">
660 </t:titlepage-content>
661
662 <t:titlepage-separator>
663 </t:titlepage-separator>
664
665 <t:titlepage-before t:side="recto">
666 </t:titlepage-before>
667
668 <t:titlepage-before t:side="verso">
669 </t:titlepage-before>
670</t:titlepage>
671
672<t:titlepage t:element="sect3" t:wrapper="fo:block">
673 <t:titlepage-content t:side="recto">
674 <title
675 margin-left="{$title.margin.left}"
676 font-family="{$title.fontset}"/>
677 <subtitle
678 font-family="{$title.fontset}"/>
679 <corpauthor/>
680 <authorgroup/>
681 <author/>
682 <othercredit/>
683 <releaseinfo/>
684 <copyright/>
685 <legalnotice/>
686 <pubdate/>
687 <revision/>
688 <revhistory/>
689 <abstract/>
690 </t:titlepage-content>
691
692 <t:titlepage-content t:side="verso">
693 </t:titlepage-content>
694
695 <t:titlepage-separator>
696 </t:titlepage-separator>
697
698 <t:titlepage-before t:side="recto">
699 </t:titlepage-before>
700
701 <t:titlepage-before t:side="verso">
702 </t:titlepage-before>
703</t:titlepage>
704
705<t:titlepage t:element="sect4" t:wrapper="fo:block">
706 <t:titlepage-content t:side="recto">
707 <title
708 margin-left="{$title.margin.left}"
709 font-family="{$title.fontset}"/>
710 <subtitle
711 font-family="{$title.fontset}"/>
712 <corpauthor/>
713 <authorgroup/>
714 <author/>
715 <othercredit/>
716 <releaseinfo/>
717 <copyright/>
718 <legalnotice/>
719 <pubdate/>
720 <revision/>
721 <revhistory/>
722 <abstract/>
723 </t:titlepage-content>
724
725 <t:titlepage-content t:side="verso">
726 </t:titlepage-content>
727
728 <t:titlepage-separator>
729 </t:titlepage-separator>
730
731 <t:titlepage-before t:side="recto">
732 </t:titlepage-before>
733
734 <t:titlepage-before t:side="verso">
735 </t:titlepage-before>
736</t:titlepage>
737
738<t:titlepage t:element="sect5" t:wrapper="fo:block">
739 <t:titlepage-content t:side="recto">
740 <title
741 margin-left="{$title.margin.left}"
742 font-family="{$title.fontset}"/>
743 <subtitle
744 font-family="{$title.fontset}"/>
745 <corpauthor/>
746 <authorgroup/>
747 <author/>
748 <othercredit/>
749 <releaseinfo/>
750 <copyright/>
751 <legalnotice/>
752 <pubdate/>
753 <revision/>
754 <revhistory/>
755 <abstract/>
756 </t:titlepage-content>
757
758 <t:titlepage-content t:side="verso">
759 </t:titlepage-content>
760
761 <t:titlepage-separator>
762 </t:titlepage-separator>
763
764 <t:titlepage-before t:side="recto">
765 </t:titlepage-before>
766
767 <t:titlepage-before t:side="verso">
768 </t:titlepage-before>
769</t:titlepage>
770
771<t:titlepage t:element="simplesect" t:wrapper="fo:block">
772 <t:titlepage-content t:side="recto">
773 <title
774 margin-left="{$title.margin.left}"
775 font-family="{$title.fontset}"/>
776 <subtitle
777 font-family="{$title.fontset}"/>
778 <corpauthor/>
779 <authorgroup/>
780 <author/>
781 <othercredit/>
782 <releaseinfo/>
783 <copyright/>
784 <legalnotice/>
785 <pubdate/>
786 <revision/>
787 <revhistory/>
788 <abstract/>
789 </t:titlepage-content>
790
791 <t:titlepage-content t:side="verso">
792 </t:titlepage-content>
793
794 <t:titlepage-separator>
795 </t:titlepage-separator>
796
797 <t:titlepage-before t:side="recto">
798 </t:titlepage-before>
799
800 <t:titlepage-before t:side="verso">
801 </t:titlepage-before>
802</t:titlepage>
803
804<!-- ==================================================================== -->
805
806 <t:titlepage t:element="bibliography" t:wrapper="fo:block">
807 <t:titlepage-content t:side="recto">
808 <title
809 t:force="1"
810 t:named-template="component.title"
811 param:node="ancestor-or-self::bibliography[1]"
812 margin-left="{$title.margin.left}"
813 font-size="&hsize5;"
814 font-family="{$title.fontset}"
815 font-weight="bold"/>
816 <subtitle
817 font-family="{$title.fontset}"/>
818 </t:titlepage-content>
819
820 <t:titlepage-content t:side="verso">
821 </t:titlepage-content>
822
823 <t:titlepage-separator>
824 </t:titlepage-separator>
825
826 <t:titlepage-before t:side="recto">
827 </t:titlepage-before>
828
829 <t:titlepage-before t:side="verso">
830 </t:titlepage-before>
831 </t:titlepage>
832
833<!-- ==================================================================== -->
834
835 <t:titlepage t:element="bibliodiv" t:wrapper="fo:block">
836 <t:titlepage-content t:side="recto">
837 <title t:named-template="component.title"
838 param:node="ancestor-or-self::bibliodiv[1]"
839 margin-left="{$title.margin.left}"
840 font-size="&hsize4;"
841 font-family="{$title.fontset}"
842 font-weight="bold"/>
843 <subtitle
844 font-family="{$title.fontset}"/>
845 </t:titlepage-content>
846
847 <t:titlepage-content t:side="verso">
848 </t:titlepage-content>
849
850 <t:titlepage-separator>
851 </t:titlepage-separator>
852
853 <t:titlepage-before t:side="recto">
854 </t:titlepage-before>
855
856 <t:titlepage-before t:side="verso">
857 </t:titlepage-before>
858 </t:titlepage>
859
860<!-- ==================================================================== -->
861
862 <t:titlepage t:element="glossary" t:wrapper="fo:block">
863 <t:titlepage-content t:side="recto">
864 <title
865 t:force="1"
866 t:named-template="component.title"
867 param:node="ancestor-or-self::glossary[1]"
868 margin-left="{$title.margin.left}"
869 font-size="&hsize5;"
870 font-family="{$title.fontset}"
871 font-weight="bold"/>
872 <subtitle
873 font-family="{$title.fontset}"/>
874 </t:titlepage-content>
875
876 <t:titlepage-content t:side="verso">
877 </t:titlepage-content>
878
879 <t:titlepage-separator>
880 </t:titlepage-separator>
881
882 <t:titlepage-before t:side="recto">
883 </t:titlepage-before>
884
885 <t:titlepage-before t:side="verso">
886 </t:titlepage-before>
887 </t:titlepage>
888
889<!-- ==================================================================== -->
890
891 <t:titlepage t:element="glossdiv" t:wrapper="fo:block">
892 <t:titlepage-content t:side="recto">
893 <title t:named-template="component.title"
894 param:node="ancestor-or-self::glossdiv[1]"
895 margin-left="{$title.margin.left}"
896 font-size="&hsize4;"
897 font-family="{$title.fontset}"
898 font-weight="bold"/>
899 <subtitle
900 font-family="{$title.fontset}"/>
901 </t:titlepage-content>
902
903 <t:titlepage-content t:side="verso">
904 </t:titlepage-content>
905
906 <t:titlepage-separator>
907 </t:titlepage-separator>
908
909 <t:titlepage-before t:side="recto">
910 </t:titlepage-before>
911
912 <t:titlepage-before t:side="verso">
913 </t:titlepage-before>
914 </t:titlepage>
915
916<!-- ==================================================================== -->
917
918 <t:titlepage t:element="index" t:wrapper="fo:block">
919 <t:titlepage-content t:side="recto">
920 <title
921 t:force="1"
922 t:named-template="component.title"
923 param:node="ancestor-or-self::index[1]"
924 param:pagewide="1"
925 margin-left="0pt"
926 font-size="&hsize5;"
927 font-family="{$title.fontset}"
928 font-weight="bold"/>
929 <subtitle
930 font-family="{$title.fontset}"/>
931 </t:titlepage-content>
932
933 <t:titlepage-content t:side="verso">
934 </t:titlepage-content>
935
936 <t:titlepage-separator>
937 </t:titlepage-separator>
938
939 <t:titlepage-before t:side="recto">
940 </t:titlepage-before>
941
942 <t:titlepage-before t:side="verso">
943 </t:titlepage-before>
944 </t:titlepage>
945
946<!-- ==================================================================== -->
947
948 <!-- The indexdiv.title template is used so that manual and -->
949 <!-- automatically generated indexdiv titles get the same -->
950 <!-- formatting. -->
951
952 <t:titlepage t:element="indexdiv" t:wrapper="fo:block">
953 <t:titlepage-content t:side="recto">
954 <title t:force="1"
955 t:named-template="indexdiv.title"
956 param:title="title"/>
957 <subtitle
958 font-family="{$title.fontset}"/>
959 </t:titlepage-content>
960
961 <t:titlepage-content t:side="verso">
962 </t:titlepage-content>
963
964 <t:titlepage-separator>
965 </t:titlepage-separator>
966
967 <t:titlepage-before t:side="recto">
968 </t:titlepage-before>
969
970 <t:titlepage-before t:side="verso">
971 </t:titlepage-before>
972 </t:titlepage>
973
974<!-- ==================================================================== -->
975
976 <t:titlepage t:element="setindex" t:wrapper="fo:block">
977 <t:titlepage-content t:side="recto">
978 <title
979 t:force="1"
980 t:named-template="component.title"
981 param:node="ancestor-or-self::setindex[1]"
982 param:pagewide="1"
983 margin-left="0pt"
984 font-size="&hsize5;"
985 font-family="{$title.fontset}"
986 font-weight="bold"/>
987 <subtitle
988 font-family="{$title.fontset}"/>
989 </t:titlepage-content>
990
991 <t:titlepage-content t:side="verso">
992 </t:titlepage-content>
993
994 <t:titlepage-separator>
995 </t:titlepage-separator>
996
997 <t:titlepage-before t:side="recto">
998 </t:titlepage-before>
999
1000 <t:titlepage-before t:side="verso">
1001 </t:titlepage-before>
1002 </t:titlepage>
1003
1004<!-- ==================================================================== -->
1005
1006 <t:titlepage t:element="colophon" t:wrapper="fo:block">
1007 <t:titlepage-content t:side="recto">
1008 <title
1009 t:force="1"
1010 t:named-template="component.title"
1011 param:node="ancestor-or-self::colophon[1]"
1012 margin-left="{$title.margin.left}"
1013 font-size="&hsize5;"
1014 font-family="{$title.fontset}"
1015 font-weight="bold"/>
1016 <subtitle
1017 font-family="{$title.fontset}"/>
1018 </t:titlepage-content>
1019
1020 <t:titlepage-content t:side="verso">
1021 </t:titlepage-content>
1022
1023 <t:titlepage-separator>
1024 </t:titlepage-separator>
1025
1026 <t:titlepage-before t:side="recto">
1027 </t:titlepage-before>
1028
1029 <t:titlepage-before t:side="verso">
1030 </t:titlepage-before>
1031</t:titlepage>
1032
1033<!-- ==================================================================== -->
1034
1035 <t:titlepage t:element="table.of.contents" t:wrapper="fo:block">
1036 <t:titlepage-content t:side="recto">
1037 <title
1038 t:force="1"
1039 t:named-template="gentext"
1040 param:key="'TableofContents'"
1041 space-before.minimum="1em"
1042 space-before.optimum="1.5em"
1043 space-before.maximum="2em"
1044 space-after="0.5em"
1045 margin-left="{$title.margin.left}"
1046 font-size="&hsize3;"
1047 font-weight="bold"
1048 font-family="{$title.fontset}"/>
1049 </t:titlepage-content>
1050
1051 <t:titlepage-content t:side="verso">
1052 </t:titlepage-content>
1053
1054 <t:titlepage-separator>
1055 </t:titlepage-separator>
1056
1057 <t:titlepage-before t:side="recto">
1058 </t:titlepage-before>
1059
1060 <t:titlepage-before t:side="verso">
1061 </t:titlepage-before>
1062 </t:titlepage>
1063
1064 <t:titlepage t:element="list.of.tables" t:wrapper="fo:block">
1065 <t:titlepage-content t:side="recto">
1066 <title
1067 t:force="1"
1068 t:named-template="gentext"
1069 param:key="'ListofTables'"
1070 space-before.minimum="1em"
1071 space-before.optimum="1.5em"
1072 space-before.maximum="2em"
1073 space-after="0.5em"
1074 margin-left="{$title.margin.left}"
1075 font-size="&hsize3;"
1076 font-weight="bold"
1077 font-family="{$title.fontset}"/>
1078 </t:titlepage-content>
1079
1080 <t:titlepage-content t:side="verso">
1081 </t:titlepage-content>
1082
1083 <t:titlepage-separator>
1084 </t:titlepage-separator>
1085
1086 <t:titlepage-before t:side="recto">
1087 </t:titlepage-before>
1088
1089 <t:titlepage-before t:side="verso">
1090 </t:titlepage-before>
1091 </t:titlepage>
1092
1093 <t:titlepage t:element="list.of.figures" t:wrapper="fo:block">
1094 <t:titlepage-content t:side="recto">
1095 <title
1096 t:force="1"
1097 t:named-template="gentext"
1098 param:key="'ListofFigures'"
1099 space-before.minimum="1em"
1100 space-before.optimum="1.5em"
1101 space-before.maximum="2em"
1102 space-after="0.5em"
1103 margin-left="{$title.margin.left}"
1104 font-size="&hsize3;"
1105 font-weight="bold"
1106 font-family="{$title.fontset}"/>
1107 </t:titlepage-content>
1108
1109 <t:titlepage-content t:side="verso">
1110 </t:titlepage-content>
1111
1112 <t:titlepage-separator>
1113 </t:titlepage-separator>
1114
1115 <t:titlepage-before t:side="recto">
1116 </t:titlepage-before>
1117
1118 <t:titlepage-before t:side="verso">
1119 </t:titlepage-before>
1120 </t:titlepage>
1121
1122 <t:titlepage t:element="list.of.examples" t:wrapper="fo:block">
1123 <t:titlepage-content t:side="recto">
1124 <title
1125 t:force="1"
1126 t:named-template="gentext"
1127 param:key="'ListofExamples'"
1128 space-before.minimum="1em"
1129 space-before.optimum="1.5em"
1130 space-before.maximum="2em"
1131 space-after="0.5em"
1132 margin-left="{$title.margin.left}"
1133 font-size="&hsize3;"
1134 font-weight="bold"
1135 font-family="{$title.fontset}"/>
1136 </t:titlepage-content>
1137
1138 <t:titlepage-content t:side="verso">
1139 </t:titlepage-content>
1140
1141 <t:titlepage-separator>
1142 </t:titlepage-separator>
1143
1144 <t:titlepage-before t:side="recto">
1145 </t:titlepage-before>
1146
1147 <t:titlepage-before t:side="verso">
1148 </t:titlepage-before>
1149 </t:titlepage>
1150
1151 <t:titlepage t:element="list.of.equations" t:wrapper="fo:block">
1152 <t:titlepage-content t:side="recto">
1153 <title
1154 t:force="1"
1155 t:named-template="gentext"
1156 param:key="'ListofEquations'"
1157 space-before.minimum="1em"
1158 space-before.optimum="1.5em"
1159 space-before.maximum="2em"
1160 space-after="0.5em"
1161 margin-left="{$title.margin.left}"
1162 font-size="&hsize3;"
1163 font-weight="bold"
1164 font-family="{$title.fontset}"/>
1165 </t:titlepage-content>
1166
1167 <t:titlepage-content t:side="verso">
1168 </t:titlepage-content>
1169
1170 <t:titlepage-separator>
1171 </t:titlepage-separator>
1172
1173 <t:titlepage-before t:side="recto">
1174 </t:titlepage-before>
1175
1176 <t:titlepage-before t:side="verso">
1177 </t:titlepage-before>
1178 </t:titlepage>
1179
1180 <t:titlepage t:element="list.of.procedures" t:wrapper="fo:block">
1181 <t:titlepage-content t:side="recto">
1182 <title
1183 t:force="1"
1184 t:named-template="gentext"
1185 param:key="'ListofProcedures'"
1186 space-before.minimum="1em"
1187 space-before.optimum="1.5em"
1188 space-before.maximum="2em"
1189 space-after="0.5em"
1190 margin-left="{$title.margin.left}"
1191 font-size="&hsize3;"
1192 font-weight="bold"
1193 font-family="{$title.fontset}"/>
1194 </t:titlepage-content>
1195
1196 <t:titlepage-content t:side="verso">
1197 </t:titlepage-content>
1198
1199 <t:titlepage-separator>
1200 </t:titlepage-separator>
1201
1202 <t:titlepage-before t:side="recto">
1203 </t:titlepage-before>
1204
1205 <t:titlepage-before t:side="verso">
1206 </t:titlepage-before>
1207 </t:titlepage>
1208
1209 <t:titlepage t:element="list.of.unknowns" t:wrapper="fo:block">
1210 <t:titlepage-content t:side="recto">
1211 <title
1212 t:force="1"
1213 t:named-template="gentext"
1214 param:key="'ListofUnknown'"
1215 space-before.minimum="1em"
1216 space-before.optimum="1.5em"
1217 space-before.maximum="2em"
1218 space-after="0.5em"
1219 margin-left="{$title.margin.left}"
1220 font-size="&hsize3;"
1221 font-weight="bold"
1222 font-family="{$title.fontset}"/>
1223 </t:titlepage-content>
1224
1225 <t:titlepage-content t:side="verso">
1226 </t:titlepage-content>
1227
1228 <t:titlepage-separator>
1229 </t:titlepage-separator>
1230
1231 <t:titlepage-before t:side="recto">
1232 </t:titlepage-before>
1233
1234 <t:titlepage-before t:side="verso">
1235 </t:titlepage-before>
1236 </t:titlepage>
1237
1238<!-- ==================================================================== -->
1239
1240</t:templates>
diff --git a/handbook/poky-doc-tools/configure.ac b/handbook/poky-doc-tools/configure.ac
new file mode 100644
index 0000000000..0d15c8198c
--- /dev/null
+++ b/handbook/poky-doc-tools/configure.ac
@@ -0,0 +1,27 @@
1AC_PREREQ(2.53)
2AC_INIT(poky-doc-tools, 0.1, http://o-hand.com)
3AM_INIT_AUTOMAKE()
4
5AC_PATH_PROG(HAVE_XSLTPROC, xsltproc, no)
6if test x$HAVE_XSLTPROC = xno; then
7 AC_MSG_ERROR([Required xsltproc program not found])
8fi
9
10AC_PATH_PROG(HAVE_FOP, fop, no)
11if test x$HAVE_FOP = xno; then
12 AC_MSG_ERROR([Required fop program not found])
13fi
14
15AC_CHECK_FILE([/usr/share/xml/docbook/stylesheet/nwalsh/template/titlepage.xsl],HAVE_NWALSH="yes", HAVE_NWALSH="no")
16if test x$HAVE_FOP = xno; then
17 AC_MSG_ERROR([Required 'nwalsh' docbook stylesheets not found])
18fi
19
20AC_OUTPUT([
21Makefile
22common/Makefile
23])
24
25echo "
26 == poky-doc-tools $VERSION configured successfully. ==
27" \ No newline at end of file
diff --git a/handbook/poky-doc-tools/poky-docbook-to-pdf.in b/handbook/poky-doc-tools/poky-docbook-to-pdf.in
new file mode 100644
index 0000000000..cc999ab995
--- /dev/null
+++ b/handbook/poky-doc-tools/poky-docbook-to-pdf.in
@@ -0,0 +1,44 @@
1#!/bin/sh
2
3if [ -z "$1" ]; then
4 echo "usage: [-v] $0 <docbook file>"
5 echo
6 echo "*NOTE* you need xsltproc, fop and nwalsh docbook stylesheets"
7 echo " installed for this to work!"
8 echo
9 exit 0
10fi
11
12if [ "$1" = "-v" ]; then
13 echo "Version @version@"
14 exit 1
15fi
16
17BASENAME=`basename $1 .xml` || exit 1
18FO="$BASENAME.fo"
19PDF="$BASENAME.pdf"
20
21xsltproc -o /tmp/titlepage.xsl \
22 --xinclude \
23 /usr/share/xml/docbook/stylesheet/nwalsh/template/titlepage.xsl \
24 @datadir@/common/titlepage.templates.xml || exit 1
25
26xsltproc --xinclude \
27 --stringparam hyphenate false \
28 --stringparam formal.title.placement "figure after" \
29 --stringparam ulink.show 1 \
30 --stringparam body.font.master 9 \
31 --stringparam title.font.master 11 \
32 --stringparam draft.watermark.image "@datadir@/common/draft.png" \
33 --output $FO \
34 @datadir@/common/poky-db-pdf.xsl \
35 $1 || exit 1
36
37fop -c @datadir@/common/fop-config.xml -fo $FO -pdf $PDF || exit 1
38
39rm -f $FO
40rm -f /tmp/titlepage.xsl
41
42echo
43echo " #### Success! $PDF ready. ####"
44echo \ No newline at end of file
diff --git a/handbook/poky-handbook.html b/handbook/poky-handbook.html
new file mode 100644
index 0000000000..abc32354dd
--- /dev/null
+++ b/handbook/poky-handbook.html
@@ -0,0 +1,2429 @@
1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Poky Handbook</title><link rel="stylesheet" href="style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="poky-handbook"></a>Poky Handbook</h1></div><div><h2 class="subtitle">Hitchhiker's Guide to Poky</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Richard</span> <span class="surname">Purdie</span></h3><div class="affiliation"><span class="orgname">OpenedHand Ltd<br></span></div><code class="email">&lt;<a href="mailto:richard@openedhand.com">richard@openedhand.com</a>&gt;</code></div><div class="author"><h3 class="author"><span class="firstname">Tomas</span> <span class="surname">Frydrych</span></h3><div class="affiliation"><span class="orgname">OpenedHand Ltd<br></span></div><code class="email">&lt;<a href="mailto:tf@openedhand.com">tf@openedhand.com</a>&gt;</code></div><div class="author"><h3 class="author"><span class="firstname">Marcin</span> <span class="surname">Juszkiewicz</span></h3><div class="affiliation"><span class="orgname">OpenedHand Ltd<br></span></div><code class="email">&lt;<a href="mailto:hrw@openedhand.com">hrw@openedhand.com</a>&gt;</code></div><div class="author"><h3 class="author"><span class="firstname">Dodji</span> <span class="surname">Seketeli</span></h3><div class="affiliation"><span class="orgname">OpenedHand Ltd<br></span></div><code class="email">&lt;<a href="mailto:dodji@openedhand.com">dodji@openedhand.com</a>&gt;</code></div></div></div><div><p class="copyright">Copyright © 2007 OpenedHand Limited</p></div><div><div class="legalnotice"><a name="id1081631"></a><p>
2 Permission is granted to copy, distribute and/or modify this document under
3 the terms of the <a href="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/" target="_top">Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England &amp; Wales</a> as published by Creative Commons.
4 </p></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision 3.1</td><td align="left">15 Feburary 2008</td></tr><tr><td align="left" colspan="2">Poky 3.1 (Pinky) Documentation Release</td></tr></table></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#intro">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-what-is">1. What is Poky?</a></span></dt><dt><span class="section"><a href="#intro-manualoverview">2. Documentation Overview</a></span></dt><dt><span class="section"><a href="#intro-requirements">3. System Requirements</a></span></dt><dt><span class="section"><a href="#intro-quickstart">4. Quick Start</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-quickstart-build">4.1. Building and Running an Image</a></span></dt><dt><span class="section"><a href="#intro-quickstart-qemu">4.2. Downloading and Using Prebuilt Images</a></span></dt></dl></dd><dt><span class="section"><a href="#intro-getit">5. Obtaining Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-getit-releases">5.1. Releases</a></span></dt><dt><span class="section"><a href="#intro-getit-nightly">5.2. Nightly Builds</a></span></dt><dt><span class="section"><a href="#intro-getit-dev">5.3. Development Checkouts</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#usingpoky">2. Using Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components">1. Poky Overview</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">1.1. Bitbake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">1.3. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">1.4. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-build">2. Running a Build</a></span></dt><dt><span class="section"><a href="#usingpoky-install">3. Installing and Using the Result</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-install-usbnetworking">3.1. USB Networking</a></span></dt><dt><span class="section"><a href="#usingpoky-install-qemu-networking">3.2. QEMU/USB networking with IP masquerading</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-debugging">4. Debugging Build Failures</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-debugging-taskfailures">4.1. Task Failures</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-taskrunning">4.2. Running specific tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-dependencies">4.3. Dependency Graphs</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-bitbake">4.4. General Bitbake Problems</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-buildfile">4.5. Building with no dependencies</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-variables">4.6. Variables</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-others">4.7. Other Tips</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#extendpoky">3. Extending Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-addpkg">1. Adding a Package</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-addpkg-singlec">1.1. Single .c File Package (Hello World!)</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-autotools">1.2. Autotooled Package</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-makefile">1.3. Makefile-Based Package</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-files">1.4. Controlling packages content</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-postinstalls">1.5. Post Install Scripts</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-extend-customimage">2. Customising Images</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-customimage-custombb">2.1. Customising Images through a custom image .bb files</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-customtasks">2.2. Customising Images through custom tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-imagefeatures">2.3. Customising Images through custom IMAGE_FEATURES</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-localconf">2.4. Customising Images through local.conf</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-newmachine">3. Porting Poky to a new machine</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-newmachine-conffile">3.1. Adding the machine configuration file</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-kernel">3.2. Adding a kernel for the machine</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-formfactor">3.3. Adding a formfactor configuration file</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-changes">4. Making and Maintaining Changes</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-changes-collections">4.1. Bitbake Collections</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-commits">4.2. Committing Changes</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-prbump">4.3. Package Revision Incrementing</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-modifing-packages">5. Modifying Package Source Code</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-modifying-packages-quilt">5.1. Modifying Package Source Code with quilt</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#platdev">4. Platform Development with Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-appdev">1. Software development</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-appdev-external-anjuta">1.1. Developing externally using the Anjuta Plugin</a></span></dt><dt><span class="section"><a href="#platdev-appdev-external-sdk">1.2. Developing externally using the Poky SDK</a></span></dt><dt><span class="section"><a href="#platdev-appdev-qemu">1.3. Developing externally in QEMU</a></span></dt><dt><span class="section"><a href="#platdev-appdev-chroot">1.4. Developing externally in a chroot</a></span></dt><dt><span class="section"><a href="#platdev-appdev-insitu">1.5. Developing in Poky directly</a></span></dt><dt><span class="section"><a href="#platdev-appdev-devshell">1.6. Developing with 'devshell'</a></span></dt><dt><span class="section"><a href="#platdev-appdev-srcrev">1.7. Developing within Poky with an external SCM based package</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-gdb-remotedebug">2. Debugging with GDB Remotely</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdbserver">2.1. Launching GDBSERVER on the target</a></span></dt><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdb">2.2. Launching GDB on the host computer</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-oprofile">3. Profiling with OProfile</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-oprofile-target">3.1. Profiling on the target</a></span></dt><dt><span class="section"><a href="#platdev-oprofile-oprofileui">3.2. Using OProfileUI</a></span></dt></dl></dd></dl></dd><dt><span class="appendix"><a href="#ref-structure">1. Reference: Directory Structure</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core">1. Top level core components</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core-bitbake">1.1. <code class="filename">bitbake/</code></a></span></dt><dt><span class="section"><a href="#structure-core-build">1.2. <code class="filename">build/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta">1.3. <code class="filename">meta/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-extras">1.4. <code class="filename">meta-extras/</code></a></span></dt><dt><span class="section"><a href="#structure-core-scripts">1.5. <code class="filename">scripts/</code></a></span></dt><dt><span class="section"><a href="#structure-core-sources">1.6. <code class="filename">sources/</code></a></span></dt><dt><span class="section"><a href="#structure-core-script">1.7. <code class="filename">poky-init-build-env</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-build">2. <code class="filename">build/</code> - The Build Directory</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-build-conf-local.conf">2.1. <code class="filename">build/conf/local.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp">2.2. <code class="filename">build/tmp/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cache">2.3. <code class="filename">build/tmp/cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cross">2.4. <code class="filename">build/tmp/cross/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy">2.5. <code class="filename">build/tmp/deploy/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-deb">2.6. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-images">2.7. <code class="filename">build/tmp/deploy/images/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-ipk">2.8. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-rootfs">2.9. <code class="filename">build/tmp/rootfs/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-staging">2.10. <code class="filename">build/tmp/staging/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-stamps">2.11. <code class="filename">build/tmp/stamps/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-work">2.12. <code class="filename">build/tmp/work/</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-meta">3. <code class="filename">meta/</code> - The Metadata</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-meta-classes">3.1. <code class="filename">meta/classes/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf">3.2. <code class="filename">meta/conf/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-machine">3.3. <code class="filename">meta/conf/machine/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-distro">3.4. <code class="filename">meta/conf/distro/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-packages">3.5. <code class="filename">meta/packages/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-site">3.6. <code class="filename">meta/site/</code></a></span></dt></dl></dd></dl></dd><dt><span class="appendix"><a href="#ref-bitbake">2. Reference: Bitbake</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-bitbake-parsing">1. Parsing</a></span></dt><dt><span class="section"><a href="#ref-bitbake-providers">2. Preferences and Providers</a></span></dt><dt><span class="section"><a href="#ref-bitbake-dependencies">3. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-bitbake-tasklist">4. The Task List</a></span></dt><dt><span class="section"><a href="#ref-bitbake-runtask">5. Running a Task</a></span></dt><dt><span class="section"><a href="#ref-bitbake-commandline">6. Commandline</a></span></dt><dt><span class="section"><a href="#ref-bitbake-fetchers">7. Fetchers</a></span></dt></dl></dd><dt><span class="appendix"><a href="#ref-classes">3. Reference: Classes</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-classes-base">1. The base class - <code class="filename">base.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-autotools">2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-alternatives">3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-rc.d">4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-binconfig">5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-debian">6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-pkgconfig">7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-src-distribute">8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-perl">9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-distutils">10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-devshell">11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-package">12. Packaging - <code class="filename">package*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-kernel">13. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-image">14. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-sanity">15. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-insane">16. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-siteinfo">17. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-others">18. Other Classes</a></span></dt></dl></dd><dt><span class="appendix"><a href="#ref-images">4. Reference: Images</a></span></dt><dt><span class="appendix"><a href="#ref-features">5. Reference: Features</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-features-distro">1. Distro</a></span></dt><dt><span class="section"><a href="#ref-features-machine">2. Machine</a></span></dt><dt><span class="section"><a href="#ref-features-image">3. Reference: Images</a></span></dt></dl></dd><dt><span class="appendix"><a href="#ref-variables-glos">6. Reference: Variables Glossary</a></span></dt><dd><dl><dt><span class="glossary"><a href="#ref-variables-glossary">Glossary</a></span></dt></dl></dd><dt><span class="appendix"><a href="#ref-varlocality">7. Reference: Variable Locality (Distro, Machine, Recipe etc.)</a></span></dt><dd><dl><dt><span class="section"><a href="#ref-varlocality-config-distro">1. Distro Configuration</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-machine">2. Machine Configuration</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-local">3. Local Configuration (local.conf)</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-required">4. Recipe Variables - Required</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-dependencies">5. Recipe Variables - Dependencies</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-paths">6. Recipe Variables - Paths</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-build">7. Recipe Variables - Extra Build Information</a></span></dt></dl></dd><dt><span class="appendix"><a href="#faq">8. FAQ</a></span></dt><dt><span class="appendix"><a href="#resources">9. Contributing to Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#resources-intro">1. Introduction</a></span></dt><dt><span class="section"><a href="#resources-bugtracker">2. Bugtracker</a></span></dt><dt><span class="section"><a href="#resources-mailinglist">3. Mailing list</a></span></dt><dt><span class="section"><a href="#resources-irc">4. IRC</a></span></dt><dt><span class="section"><a href="#resources-links">5. Links</a></span></dt></dl></dd><dt><span class="appendix"><a href="#contact">10. OpenedHand Contact Information</a></span></dt><dt><span class="index"><a href="#index">Index</a></span></dt></dl></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="intro"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#intro-what-is">1. What is Poky?</a></span></dt><dt><span class="section"><a href="#intro-manualoverview">2. Documentation Overview</a></span></dt><dt><span class="section"><a href="#intro-requirements">3. System Requirements</a></span></dt><dt><span class="section"><a href="#intro-quickstart">4. Quick Start</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-quickstart-build">4.1. Building and Running an Image</a></span></dt><dt><span class="section"><a href="#intro-quickstart-qemu">4.2. Downloading and Using Prebuilt Images</a></span></dt></dl></dd><dt><span class="section"><a href="#intro-getit">5. Obtaining Poky</a></span></dt><dd><dl><dt><span class="section"><a href="#intro-getit-releases">5.1. Releases</a></span></dt><dt><span class="section"><a href="#intro-getit-nightly">5.2. Nightly Builds</a></span></dt><dt><span class="section"><a href="#intro-getit-dev">5.3. Development Checkouts</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-what-is"></a>1. What is Poky?</h2></div></div></div><p>
5 Poky is an open source platform build tool. It is a complete software
6 development environment for the creation of Linux devices. It aids the
7 design, development, building, debugging, simulation and testing of
8 complete modern software stacks using Linux, the X Window System and
9 GNOME Mobile based application frameworks. It is based on
10 <a href="http://openembedded.org/" target="_top">OpenEmbedded</a>
11 but has been customised with a particular focus.
12 </p><p> Poky was setup to:</p><div class="itemizedlist"><ul type="disc"><li><p>Provide an open source Linux, X11, Matchbox, GTK+, <a href="http://gnome.org/mobile" target="_top">GNOME Mobile</a> platform.</p></li><li><p>Create a focused, stable, subset of OpenEmbedded that can be easily and reliably built and developed upon.</p></li><li><p>Fully support a wide range of x86 and ARM hardware</p></li></ul></div><p><a href="http://www.o-hand.com" target="_top">OpenedHand</a> is the principle developer and maintainer of Poky and uses it to:</p><div class="itemizedlist"><ul type="disc"><li><p>Provide <a href="http://www.o-hand.com" target="_top">OpenedHand</a> with stable R&amp;D platform we can build and develop upon.</p></li><li><p>
13 Demonstrate the skills available within <a href="http://www.o-hand.com" target="_top">
14 OpenedHand</a> and provide a showcase for our software products
15 (such as the <a href="http://www.matchbox-project.org/" target="_top">Matchbox</a> and
16 <a href="http://www.pimlico-project.org/" target="_top">Pimlico</a> software packages and
17 Sato, the default user interface in Poky).
18 </p></li><li><p>Provide a base we can supply to our clients for building and developing their customised platforms.</p></li></ul></div><p>
19 Poky is primarily a platform builder which generates filesystem images
20 based on open source software such as the Kdrive X server, the Matchbox
21 window manager, the GTK+ toolkit and the D-Bus message bus system. Images
22 for many kinds of devices can be generated, however the standard example
23 machines target QEMU system emulation (both x86 and ARM) and the ARM based
24 Sharp Zaurus series of devices. Poky's ability to boot inside a QEMU
25 emulator makes it particularly suitable as a test platform for development
26 of embedded software.
27 </p><p>
28 An important component integrated within Poky is Sato, a GNOME Mobile
29 based user interface environment.
30 It is designed to work well with screens at very high DPI and restricted
31 size, such as those often found on smartphones and PDAs. It is coded with
32 focus on efficiency and speed so that it works smoothly on hand-held and
33 other embedded hardware. It will sit neatly on top of any device
34 using the GNOME Mobile stack, providing a well defined user experience.
35 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-manualoverview"></a>2. Documentation Overview</h2></div></div></div><p>
36 The handbook is split into sections covering different aspects of Poky.
37 The <a href="#usingpoky" title="Chapter 2. Using Poky">'Using Poky' section</a> gives an overview
38 of the components that make up Poky followed by information about using and
39 debugging the Poky build system. The <a href="#extendpoky" title="Chapter 3. Extending Poky">'Extending Poky' section</a>
40 gives information about how to extend and customise Poky along with advice
41 on how to manage these changes. The <a href="#platdev" title="Chapter 4. Platform Development with Poky">'Platform Development with Poky'
42 section</a> gives information about interaction between Poky and target
43 hardware for common platform development tasks such as software development,
44 debugging and profiling. The rest of the manual
45 consists of several reference sections each giving details on a specific
46 section of Poky functionality.
47 </p><p>
48 This manual applies to Poky Release 3.1 (Pinky).
49 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-requirements"></a>3. System Requirements</h2></div></div></div><p>
50 We recommend Debian-based distributions, in particular a recent Ubuntu
51 release (7.04 or newer), as the host system for Poky. Nothing in Poky is
52 distribution specific and
53 other distributions will most likely work as long as the appropriate
54 prerequisites are installed - we know of Poky being used successfully on Redhat,
55 SUSE, Gentoo and Slackware host systems.
56 </p><p>On a Debian-based system, you need the following packages installed:</p><div class="itemizedlist"><ul type="disc"><li><p>build-essential</p></li><li><p>python</p></li><li><p>diffstat</p></li><li><p>texinfo</p></li><li><p>texi2html</p></li><li><p>cvs</p></li><li><p>subversion</p></li><li><p>wget</p></li><li><p>gawk</p></li><li><p>help2man</p></li><li><p>bochsbios (only to run qemux86 images)</p></li></ul></div><p>
57 Debian users can add debian.o-hand.com to their APT sources (See
58 <a href="http://debian.o-hand.com" target="_top">http://debian.o-hand.com</a>
59 for instructions on doing this) and then run <span><strong class="command">
60 "apt-get install qemu poky-depends poky-scripts"</strong></span> which will
61 automatically install all these dependencies. OpenedHand can also provide
62 VMware images with Poky and all dependencies pre-installed if required.
63 </p><p>
64 Poky can use a system provided QEMU or build its own depending on how it's
65 configured. See the options in <code class="filename">local.conf</code> for more details.
66 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-quickstart"></a>4. Quick Start</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-quickstart-build"></a>4.1. Building and Running an Image</h3></div></div></div><p>
67 If you want to try Poky, you can do so in a few commands. The example below
68 checks out the Poky source code, sets up a build environment, builds an
69 image and then runs that image under the QEMU emulator in ARM system emulation mode:
70 </p><p>
71 </p><pre class="literallayout">
72$ wget http://pokylinux.org/releases/pinky-3.1.tar.gz
73$ tar zxvf pinky-3.1.tar.gz
74$ cd pinky-3.1/
75$ source poky-init-build-env
76$ bitbake poky-image-sato
77$ runqemu qemuarm
78</pre><p>
79 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
80 This process will need Internet access, about 3 GB of disk space
81 available, and you should expect the build to take about 4 - 5 hours since
82 it is building an entire Linux system from source including the toolchain!
83 </p></div><p>
84 To build for other machines see the <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a></em> variable in build/conf/local.conf
85 which also contains other configuration information. The images/kernels built
86 by Poky are placed in the <code class="filename">tmp/deploy/images</code>
87 directory.
88 </p><p>
89 You could also run <span><strong class="command">"poky-qemu zImage-qemuarm.bin poky-image-sato-qemuarm.ext2"
90 </strong></span> within the images directory if you have the poky-scripts Debian package
91 installed from debian.o-hand.com. This allows the QEMU images to be used standalone
92 outside the Poky build environment.
93 </p><p>
94 To setup networking within QEMU see the <a href="#usingpoky-install-qemu-networking" title="3.2. QEMU/USB networking with IP masquerading">
95 QEMU/USB networking with IP masquerading</a> section.
96 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-quickstart-qemu"></a>4.2. Downloading and Using Prebuilt Images</h3></div></div></div><p>
97 Prebuilt images from Poky are also available if you just want to run the system
98 under QEMU. To use these you need to:
99 </p><div class="itemizedlist"><ul type="disc"><li><p>
100 Add debian.o-hand.com to your APT sources (See
101 <a href="http://debian.o-hand.com" target="_top">http://debian.o-hand.com</a> for instructions on doing this)
102 </p></li><li><p>Install patched QEMU and poky-scripts:</p><p>
103 </p><pre class="literallayout">
104$ apt-get install qemu poky-scripts
105</pre><p>
106 </p></li><li><p>
107 Download a Poky QEMU release kernel (*zImage*qemu*.bin) and compressed
108 filesystem image (poky-image-*-qemu*.ext2.bz2) which
109 you'll need to decompress with 'bzip2 -d'. These are available from the
110 <a href="http://pokylinux.org/releases/blinky-3.0/" target="_top">last release</a>
111 or from the <a href="http://pokylinux.org/autobuild/poky/" target="_top">autobuilder</a>.
112 </p></li><li><p>Start the image:</p><p>
113 </p><pre class="literallayout">
114$ poky-qemu &lt;kernel&gt; &lt;image&gt;
115</pre><p>
116 </p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
117 A patched version of QEMU is required at present. A suitable version is available from
118 <a href="http://debian.o-hand.com" target="_top">http://debian.o-hand.com</a>, it can be built
119 by poky (bitbake qemu-native) or can be downloaded/built as part of the toolchain/SDK tarballs.
120 </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="intro-getit"></a>5. Obtaining Poky</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-getit-releases"></a>5.1. Releases</h3></div></div></div><p>Periodically, we make releases of Poky and these are available
121 at <a href="http://pokylinux.org/releases/" target="_top">http://pokylinux.org/releases/</a>.
122 These are more stable and tested than the nightly development images.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-getit-nightly"></a>5.2. Nightly Builds</h3></div></div></div><p>
123 We make nightly builds of Poky for testing purposes and to make the
124 latest developments available. The output from these builds is available
125 at <a href="http://pokylinux.org/autobuild/" target="_top">http://pokylinux.org/autobuild/</a>
126 where the numbers represent the svn revision the builds were made from.
127 </p><p>
128 Automated builds are available for "standard" Poky and for Poky SDKs and toolchains as well
129 as any testing versions we might have such as poky-bleeding. The toolchains can
130 be used either as external standalone toolchains or can be combined with Poky as a
131 prebuilt toolchain to reduce build time. Using the external toolchains is simply a
132 case of untarring the tarball into the root of your system (it only creates files in
133 <code class="filename">/usr/local/poky</code>) and then enabling the option
134 in <code class="filename">local.conf</code>.
135 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="intro-getit-dev"></a>5.3. Development Checkouts</h3></div></div></div><p>
136 Poky is available from our SVN repository located at
137 http://svn.o-hand.com/repos/poky/trunk; a web interface to the repository
138 can be accessed at <a href="http://svn.o-hand.com/view/poky/" target="_top">http://svn.o-hand.com/view/poky/</a>.
139 </p><p>
140 'trunk' is where the deveopment work takes place and you should use this if you're
141 after to work with the latest cutting edge developments. It is possible trunk
142 can suffer temporary periods of instability while new features are developed and
143 if this is undesireable we recommend using one of the release branches.
144 </p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="usingpoky"></a>Chapter 2. Using Poky</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#usingpoky-components">1. Poky Overview</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-components-bitbake">1.1. Bitbake</a></span></dt><dt><span class="section"><a href="#usingpoky-components-metadata">1.2. Metadata (Recipes)</a></span></dt><dt><span class="section"><a href="#usingpoky-components-classes">1.3. Classes</a></span></dt><dt><span class="section"><a href="#usingpoky-components-configuration">1.4. Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-build">2. Running a Build</a></span></dt><dt><span class="section"><a href="#usingpoky-install">3. Installing and Using the Result</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-install-usbnetworking">3.1. USB Networking</a></span></dt><dt><span class="section"><a href="#usingpoky-install-qemu-networking">3.2. QEMU/USB networking with IP masquerading</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-debugging">4. Debugging Build Failures</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-debugging-taskfailures">4.1. Task Failures</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-taskrunning">4.2. Running specific tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-dependencies">4.3. Dependency Graphs</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-bitbake">4.4. General Bitbake Problems</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-buildfile">4.5. Building with no dependencies</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-variables">4.6. Variables</a></span></dt><dt><span class="section"><a href="#usingpoky-debugging-others">4.7. Other Tips</a></span></dt></dl></dd></dl></div><p>
145 This section gives an overview of the components that make up Poky
146 following by information about running poky builds and dealing with any
147 problems that may arise.
148 </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-components"></a>1. Poky Overview</h2></div></div></div><p>
149 At the core of Poky is the bitbake task executor together with various types of
150 configuration files. This section gives an overview of bitbake and the
151 configuration files, in particular what they are used for, and how they
152 interact.
153 </p><p>
154 Bitbake handles the parsing and execution of the data
155 files. The data itself is of various types; recipes which give
156 details about particular pieces of software, class data which is an
157 abstraction of common build information (e.g. how to build a Linux kernel)
158 and configuration data for machines, policy decisions, etc., which acts as
159 a glue and binds everything together. Bitbake knows how to combine multiple
160 data sources together, each data source being referred to as a <a href="#usingpoky-changes-collections" title="4.1. Bitbake Collections">'collection'</a>.
161 </p><p>
162 The <a href="#ref-structure" title="Appendix 1. Reference: Directory Structure">directory structure walkthrough</a>
163 section gives details on the meaning of specific directories but some
164 brief details on the core components follows:
165 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-components-bitbake"></a>1.1. Bitbake</h3></div></div></div><p>
166 Bitbake is the tool at the heart of Poky and is responsible
167 for parsing the metadata, generating a list of tasks from it
168 and then executing them. To see a list of the options it
169 supports look at <span><strong class="command">bitbake --help</strong></span>.
170 </p><p>
171 The most common usage is <span><strong class="command">bitbake packagename</strong></span> where
172 packagename is the name of the package you wish to build
173 (from now on called the target). This often equates to the first part of a .bb
174 filename, so to run the <code class="filename">matchbox-desktop_1.2.3.bb</code> file, you
175 might type <span><strong class="command">bitbake matchbox-desktop</strong></span>.
176 Several different versions of matchbox-desktop might exist and
177 bitbake will choose the one selected by the distribution configuration
178 (more details about how bitbake chooses between different versions
179 and providers is available in the <a href="#ref-bitbake-providers" title="2. Preferences and Providers">
180 'Preferences and Providers' section</a>). Bitbake will also try to execute any
181 dependent tasks first so before building matchbox-desktop it
182 would build a cross compiler and glibc if not already built.
183 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-components-metadata"></a>1.2. Metadata (Recipes)</h3></div></div></div><p>
184 The .bb files are usually referred to as 'recipes'. In general, a
185 recipe contains information about a single piece of software such
186 as where to download the source, any patches that are needed,
187 any special configuration options, how to compile the source files
188 and how to package the compiled output.
189 </p><p>
190 'package' can also used to describe recipes but since the same
191 word is used for the packaged output from Poky (i.e. .ipk or .deb
192 files), this document will avoid it.
193 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-components-classes"></a>1.3. Classes</h3></div></div></div><p>
194 Class (.bbclass) files contain information which is useful to share
195 between metadata files. An example is the autotools class which contains
196 the common settings that any application using autotools would use. The
197 <a href="#ref-classes" title="Appendix 3. Reference: Classes">classes reference section</a> gives details
198 on common classes and how to use them.
199 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-components-configuration"></a>1.4. Configuration</h3></div></div></div><p>
200 The configuration (.conf) files define various configuration variables
201 which govern what Poky does. These are split into several areas, such
202 as machine configuration options, distribution configuration options,
203 compiler tuning options, general common configuration and user
204 configuration (local.conf).
205 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-build"></a>2. Running a Build</h2></div></div></div><p>
206 First the Poky build environment needs to be setup using the following command:
207 </p><p>
208 </p><pre class="literallayout">
209$ source poky-init-build-env
210</pre><p>
211 </p><p>
212 Once the Poky build environment is setup, a target can now be built using:
213 </p><p>
214 </p><pre class="literallayout">
215$ bitbake &lt;target&gt;
216</pre><p>
217 </p><p>
218 The target is the name of the recipe you want to build. Common targets are the
219 images (in <code class="filename">meta/packages/images/</code>)
220 or the name of a recipe for a specific piece of software like
221 <span class="application">busybox</span>. More details about the standard images
222 are available in the <a href="#ref-images" title="Appendix 4. Reference: Images">image reference section</a>.
223 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-install"></a>3. Installing and Using the Result</h2></div></div></div><p>
224 Once an image has been built it often needs to be installed. The images/kernels built
225 by Poky are placed in the <code class="filename">tmp/deploy/images</code>
226 directory. Running qemux86 and qemuarm images is covered in the <a href="#intro-quickstart-qemu" title="4.2. Downloading and Using Prebuilt Images">Running an Image</a> section. See your
227 board/machine documentation for information about how to install these images.
228 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-install-usbnetworking"></a>3.1. USB Networking</h3></div></div></div><p>
229 Devices commonly have USB connectivity. To connect to the usbnet interface, on
230 the host machine run:
231 </p><p>
232 </p><pre class="programlisting">
233modprobe usbnet
234ifconfig usb0 192.168.0.200
235route add 192.168.0.202 usb0
236</pre><p>
237 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-install-qemu-networking"></a>3.2. QEMU/USB networking with IP masquerading</h3></div></div></div><p>
238 On Ubuntu, Debian or similar distributions you can have the network automatically
239 configured. You can also enable masquerading between the QEMU system and the rest
240 of your network. To do this you need to edit <code class="filename">/etc/network/interfaces</code> to include:
241 </p><pre class="programlisting">
242allow-hotplug tap0
243iface tap0 inet static
244 address 192.168.7.200
245 netmask 255.255.255.0
246 network 192.168.7.0
247 post-up iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.7.0/24
248 post-up echo 1 &gt; /proc/sys/net/ipv4/ip_forward
249 post-up iptables -P FORWARD ACCEPT
250</pre><p>
251 </p><p>
252 This ensures the tap0 interface will be up everytime you run QEMU
253 and it will have network/internet access.
254 </p><p>
255 Under emulation there are two steps to configure for internet access
256 via tap0. The first step is to configure routing:
257 </p><pre class="programlisting">
258route add default gw 192.168.7.200 tap0
259</pre><p>
260 </p><p>
261 The second is to configure name resolution which is configured in the
262 <code class="filename">/etc/resolv.conf</code> file. The simplest solution is
263 to copy it's content from the host machine.
264 </p><p>
265 USB connections to devices can be setup and automated in a similar way.
266 First add the following to
267 <code class="filename">/etc/network/interfaces</code>:
268 </p><pre class="programlisting">
269allow-hotplug usb0
270iface usb0 inet static
271 address 192.168.0.200
272 netmask 255.255.255.0
273 network 192.168.0.0
274 post-up iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.0.0/24
275 post-up echo 1 &gt; /proc/sys/net/ipv4/ip_forward
276 post-up iptables -P FORWARD ACCEPT
277</pre><p>
278 </p><p>
279 and then to configure routing on the device you would use:
280 </p><pre class="programlisting">
281route add default gw 192.168.0.202 usb0
282</pre><p>
283 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-debugging"></a>4. Debugging Build Failures</h2></div></div></div><p>
284 The exact method for debugging Poky depends on the nature of the
285 bug(s) and which part of the system they might be from. Standard
286 debugging practises such as comparing to the last
287 known working version and examining the changes, reapplying the
288 changes in steps to identify the one causing the problem etc. are
289 valid for Poky just like any other system. Its impossible to detail
290 every possible potential failure here but there are some general
291 tips to aid debugging:
292 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-taskfailures"></a>4.1. Task Failures</h3></div></div></div><p>The log file for shell tasks is available in <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>.
293 For the compile task of busybox 1.01 on the ARM spitz machine, this
294 might be <code class="filename">tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</code>
295 for example. To see what bitbake ran to generate that log, look at the <code class="filename">run.do_taskname.pid </code>
296 file in the same directory.
297 </p><p>The output from python tasks is sent directly to the console at present.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-taskrunning"></a>4.2. Running specific tasks</h3></div></div></div><p> Any given package consists of a set of tasks, in most
298 cases the series is fetch, unpack, patch, configure,
299 compile, install, package, package_write and build. The
300 default task is "build" and any tasks this depends on are
301 built first hence the standard bitbake behaviour. There are
302 some tasks such as devshell which are not part of the
303 default build chain. If you wish to run such a task you can
304 use the "-c" option to bitbake e.g. <span><strong class="command">bitbake
305 matchbox-desktop -c devshell</strong></span>.
306 </p><p>
307 If you wish to rerun a task you can use the force option
308 "-f". A typical usage session might look like: </p><p>
309 </p><pre class="literallayout">
310% bitbake matchbox-desktop
311[change some source in the WORKDIR for example]
312% bitbake matchbox-desktop -c compile -f
313% bitbake matchbox-desktop</pre><p>
314 </p><p>
315 which would build matchbox-desktop, then recompile it. The
316 final command reruns all tasks after the compile (basically
317 the packaging tasks) since bitbake will notice the the
318 compile has been rerun and hence the other tasks also need
319 to run again.
320 </p><p>
321 You can view a list of tasks in a given package by running
322 the listtasks task e.g. <span><strong class="command">bitbake matchbox-desktop -c
323 listtasks</strong></span>.
324 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-dependencies"></a>4.3. Dependency Graphs</h3></div></div></div><p>
325 Sometimes it can be hard to see why bitbake wants to build
326 some other packages before a given package you've specified.
327 <span><strong class="command">bitbake -g targetname</strong></span> will create
328 <code class="filename">depends.dot</code> and
329 <code class="filename">task-depends.dot</code> files in the current
330 directory. They show
331 which packages and tasks depend on which other packages and
332 tasks and are useful for debugging purposes.
333 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-bitbake"></a>4.4. General Bitbake Problems</h3></div></div></div><p>
334 Debug output from bitbake can be seen with the "-D" option.
335 The debug output gives more information about what bitbake
336 is doing and/or why. Each -D option increases the logging
337 level, the most common usage being "-DDD".
338 </p><p>
339 The output from <span><strong class="command">bitbake -DDD -v targetname</strong></span> can reveal why
340 a certain version of a package might be chosen, why bitbake
341 picked a certain provider or help in other situations where
342 bitbake does something you're not expecting.
343 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-buildfile"></a>4.5. Building with no dependencies</h3></div></div></div><p>
344 If you really want to build a specific .bb file, you can use
345 the form <span><strong class="command">bitbake -b somepath/somefile.bb</strong></span>. Note that this
346 will not check the dependencies so this option should only
347 be used when you know its dependencies already exist. You
348 can specify fragments of the filename and bitbake will see
349 if it can find a unique match.
350 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-variables"></a>4.6. Variables</h3></div></div></div><p>
351 The "-e" option will dump the resulting environment for
352 either the configuration (no package specified) or for a
353 specific package when specified with the "-b" option.
354 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-debugging-others"></a>4.7. Other Tips</h3></div></div></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>When adding new packages it is worth keeping an eye open for bad
355 things creeping into compiler commandlines such as references to local
356 system files (<code class="filename">/usr/lib/</code> or <code class="filename">/usr/include/</code> etc.).
357 </p></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
358 If you want to remove the psplash boot splashscreen, add "psplash=false"
359 to the kernel commandline and psplash won't load allowing you to see
360 the console. It's also possible to switch out of the splashscreen by
361 switching virtual console (Fn+Left or Fn+Right on a Zaurus).
362 </p></div></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="extendpoky"></a>Chapter 3. Extending Poky</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#usingpoky-extend-addpkg">1. Adding a Package</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-addpkg-singlec">1.1. Single .c File Package (Hello World!)</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-autotools">1.2. Autotooled Package</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-makefile">1.3. Makefile-Based Package</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-files">1.4. Controlling packages content</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-addpkg-postinstalls">1.5. Post Install Scripts</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-extend-customimage">2. Customising Images</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-extend-customimage-custombb">2.1. Customising Images through a custom image .bb files</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-customtasks">2.2. Customising Images through custom tasks</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-imagefeatures">2.3. Customising Images through custom IMAGE_FEATURES</a></span></dt><dt><span class="section"><a href="#usingpoky-extend-customimage-localconf">2.4. Customising Images through local.conf</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-newmachine">3. Porting Poky to a new machine</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-newmachine-conffile">3.1. Adding the machine configuration file</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-kernel">3.2. Adding a kernel for the machine</a></span></dt><dt><span class="section"><a href="#platdev-newmachine-formfactor">3.3. Adding a formfactor configuration file</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-changes">4. Making and Maintaining Changes</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-changes-collections">4.1. Bitbake Collections</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-commits">4.2. Committing Changes</a></span></dt><dt><span class="section"><a href="#usingpoky-changes-prbump">4.3. Package Revision Incrementing</a></span></dt></dl></dd><dt><span class="section"><a href="#usingpoky-modifing-packages">5. Modifying Package Source Code</a></span></dt><dd><dl><dt><span class="section"><a href="#usingpoky-modifying-packages-quilt">5.1. Modifying Package Source Code with quilt</a></span></dt></dl></dd></dl></div><p>
363 This section gives information about how to extend the functionality
364 already present in Poky, documenting standard tasks such as adding new
365 software packages, extending or customising images or porting poky to
366 new hardware (adding a new machine). It also contains advice about how
367 to manage the process of making changes to Poky to achieve best results.
368 </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-extend-addpkg"></a>1. Adding a Package</h2></div></div></div><p>
369 To add package into Poky you need to write a recipe for it.
370 Writing a recipe means creating a .bb file which sets various
371 variables. The variables
372 useful for recipes are detailed in the <a href="#ref-varlocality-recipe-required" title="4. Recipe Variables - Required">
373 recipe reference</a> section along with more detailed information
374 about issues such as recipe naming.
375 </p><p>
376 The simplest way to add a new package is to base it on a similar
377 pre-existing recipe. There are some examples below of how to add
378 standard types of packages:
379 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-singlec"></a>1.1. Single .c File Package (Hello World!)</h3></div></div></div><p>
380 To build an application from a single file stored locally requires a
381 recipe which has the file listed in the <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em> variable. In addition
382 the <code class="function">do_compile</code> and <code class="function">do_install</code>
383 tasks need to be manually written. The <em class="glossterm"><a href="#var-S" title="S">
384 S</a></em> variable defines the directory containing the source
385 code which in this case is set equal to <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">
386 WORKDIR</a></em>, the directory BitBake uses for the build.
387 </p><pre class="programlisting">
388DESCRIPTION = "Simple helloworld application"
389SECTION = "examples"
390LICENSE = "MIT"
391
392SRC_URI = "file://helloworld.c"
393
394S = "${WORKDIR}"
395
396do_compile() {
397 ${CC} helloworld.c -o helloworld
398}
399
400do_install() {
401 install -d ${D}${bindir}
402 install -m 0755 helloworld ${D}${bindir}
403}
404 </pre><p>
405 As a result of the build process "helloworld" and "helloworld-dbg"
406 packages will be built.
407 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-autotools"></a>1.2. Autotooled Package</h3></div></div></div><p>
408 Applications which use autotools (autoconf, automake)
409 require a recipe which has a source archive listed in
410 <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em> and
411 <span><strong class="command">inherit autotools</strong></span> to instruct BitBake to use the
412 <code class="filename">autotools.bbclass</code> which has
413 definitions of all the steps
414 needed to build an autotooled application.
415 The result of the build will be automatically packaged and if
416 the application uses NLS to localise then packages with
417 locale information will be generated (one package per
418 language).
419 </p><pre class="programlisting">
420DESCRIPTION = "GNU Helloworld application"
421SECTION = "examples"
422LICENSE = "GPLv2"
423
424SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2"
425
426inherit autotools
427 </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-makefile"></a>1.3. Makefile-Based Package</h3></div></div></div><p>
428 Applications which use GNU make require a recipe which has
429 the source archive listed in <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em>.
430 Adding a <code class="function">do_compile</code> step
431 is not needed as by default BitBake will start the "make"
432 command to compile the application. If there is a need for
433 additional options to make then they should be stored in the
434 <em class="glossterm"><a href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a></em> variable - BitBake
435 will pass them into the GNU
436 make invocation. A <code class="function">do_install</code> task is required
437 - otherwise BitBake will run an empty <code class="function">do_install</code>
438 task by default.
439 </p><p>
440 Some applications may require extra parameters to be passed to
441 the compiler, for example an additional header path. This can
442 be done buy adding to the <em class="glossterm"><a href="#var-CFLAGS" title="CFLAGS">CFLAGS</a></em> variable, as in the example below.
443 </p><pre class="programlisting">
444DESCRIPTION = "Tools for managing memory technology devices."
445SECTION = "base"
446DEPENDS = "zlib"
447HOMEPAGE = "http://www.linux-mtd.infradead.org/"
448LICENSE = "GPLv2"
449
450SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz"
451
452CFLAGS_prepend = "-I ${S}/include "
453
454do_install() {
455 oe_runmake install DESTDIR=${D}
456}
457 </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-files"></a>1.4. Controlling packages content</h3></div></div></div><p>
458 The variables <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></em> and
459 <em class="glossterm"><a href="#var-FILES" title="FILES">FILES</a></em> are used to split an
460 application into multiple packages.
461 </p><p>
462 Below the "libXpm" recipe is used as an example. By
463 default the "libXpm" recipe generates one package
464 which contains the library
465 and also a few binaries. The recipe can be adapted to
466 split the binaries into separate packages.
467 </p><pre class="programlisting">
468require xorg-lib-common.inc
469
470DESCRIPTION = "X11 Pixmap library"
471LICENSE = "X-BSD"
472DEPENDS += "libxext"
473PE = "1"
474
475XORG_PN = "libXpm"
476
477PACKAGES =+ "sxpm cxpm"
478FILES_cxpm = "${bindir}/cxpm"
479FILES_sxpm = "${bindir}/sxpm"
480 </pre><p>
481 In this example we want to ship the "sxpm" and "cxpm" binaries
482 in separate packages. Since "bindir" would be packaged into the
483 main <em class="glossterm"><a href="#var-PN" title="PN">PN</a></em>
484 package as standard we prepend the <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></em> variable so
485 additional package names are added to the start of list. The
486 extra <em class="glossterm"><a href="#var-PN" title="PN">FILES</a></em>_*
487 variables then contain information to specify which files and
488 directories goes into which package.
489 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-addpkg-postinstalls"></a>1.5. Post Install Scripts</h3></div></div></div><p>
490 To add a post-installation script to a package, add
491 a <code class="function">pkg_postinst_PACKAGENAME()</code>
492 function to the .bb file
493 where PACKAGENAME is the name of the package to attach
494 the postinst script to. A post-installation function has the following structure:
495 </p><pre class="programlisting">
496pkg_postinst_PACKAGENAME () {
497#!/bin/sh -e
498# Commands to carry out
499}
500 </pre><p>
501 The script defined in the post installation function
502 gets called when the rootfs is made. If the script succeeds,
503 the package is marked as installed. If the script fails,
504 the package is marked as unpacked and the script will be
505 executed again on the first boot of the image.
506 </p><p>
507 Sometimes it is necessary that the execution of a post-installation
508 script is delayed until the first boot, because the script
509 needs to be executed the device itself. To delay script execution
510 until boot time, the post-installation function should have the
511 following structure:
512 </p><pre class="programlisting">
513pkg_postinst_PACKAGENAME () {
514#!/bin/sh -e
515if [ x"$D" = "x" ]; then
516# Actions to carry out on the device go here
517else
518exit 1
519fi
520}
521 </pre><p>
522 The structure above delays execution until first boot
523 because the <em class="glossterm"><a href="#var-D" title="D">D</a></em> variable points
524 to the 'image'
525 directory when the rootfs is being made at build time but
526 is unset when executed on the first boot.
527 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-extend-customimage"></a>2. Customising Images</h2></div></div></div><p>
528 Poky images can be customised to satisfy
529 particular requirements. Several methods are detailed below
530 along with guidelines of when to use them.
531 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-customimage-custombb"></a>2.1. Customising Images through a custom image .bb files</h3></div></div></div><p>
532 One way to get additional software into an image is by creating a
533 custom image. The recipe will contain two lines:
534 </p><pre class="programlisting">
535IMAGE_INSTALL = "task-poky-x11-base package1 package2"
536
537inherit poky-image
538 </pre><p>
539 By creating a custom image, a developer has total control
540 over the contents of the image. It is important use
541 the correct names of packages in the <em class="glossterm"><a href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></em> variable.
542 The names must be in
543 the OpenEmbedded notation instead of Debian notation, for example
544 "glibc-dev" instead of "libc6-dev" etc.
545 </p><p>
546 The other method of creating a new image is by modifying
547 an existing image. For example if a developer wants to add
548 "strace" into "poky-image-sato" the following recipe can
549 be used:
550 </p><pre class="programlisting">
551require poky-image-sato.bb
552
553IMAGE_INSTALL += "strace"
554 </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-customimage-customtasks"></a>2.2. Customising Images through custom tasks</h3></div></div></div><p>
555 For for complex custom images, the best approach is to create a custom
556 task package which is them used to build the image (or images). A good
557 example of a tasks package is <code class="filename">meta/packages/tasks/task-poky.bb
558 </code>. The <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></em>
559 variable lists the task packages to build (along with the complimentary
560 -dbg and -dev packages). For each package added,
561 <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">RDEPENDS</a></em> and
562 <em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">RRECOMMENDS</a></em>
563 entries can then be added each containing a list of packages the parent
564 task package should contain. An example would be:
565 </p><p>
566 </p><pre class="programlisting">
567DESCRIPTION = "My Custom Tasks"
568
569PACKAGES = "\
570 task-custom-apps \
571 task-custom-apps-dbg \
572 task-custom-apps-dev \
573 task-custom-tools \
574 task-custom-tools-dbg \
575 task-custom-tools-dev \
576 "
577
578RDEPENDS_task-custom-apps = "\
579 dropbear \
580 portmap \
581 psplash"
582
583RDEPENDS_task-custom-tools = "\
584 oprofile \
585 oprofileui-server \
586 lttng-control \
587 lttng-viewer"
588
589RRECOMMENDS_task-custom-tools = "\
590 kernel-module-oprofile"
591</pre><p>
592 </p><p>
593 In this example, two tasks packages are created, task-custom-apps and
594 task-custom-tools with the dependencies and recommended package dependencies
595 listed. To build an image using these task packages, you would then add
596 "task-custom-apps" and/or "task-custom-tools" to <em class="glossterm"><a href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></em> or other forms
597 of image dependencies as described in other areas of this section.
598 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-customimage-imagefeatures"></a>2.3. Customising Images through custom <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em></h3></div></div></div><p>
599 Ultimately users may want to add extra image "features" as used by Poky with the
600 <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em>
601 variable. To create these, the best reference is <code class="filename">meta/classes/poky-image.bbclass</code>
602 which illustrates how poky achieves this. In summary, the file looks at the contents of the
603 <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em>
604 variable and based on this generates the <em class="glossterm"><a href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">
605 IMAGE_INSTALL</a></em> variable automatically. Extra features can be added by
606 extending the class or creating a custom class for use with specialised image .bb files.
607 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-extend-customimage-localconf"></a>2.4. Customising Images through local.conf</h3></div></div></div><p>
608 It is possible to customise image contents by abusing
609 variables used by distribution maintainers in local.conf.
610 This method only allows the addition of packages and
611 is not recommended.
612 </p><p>
613 To add an "strace" package into the image the following is
614 added to local.conf:
615 </p><pre class="programlisting">
616DISTRO_EXTRA_RDEPENDS += "strace"
617 </pre><p>
618 However, since the <em class="glossterm"><a href="#var-DISTRO_EXTRA_RDEPENDS" title="DISTRO_EXTRA_RDEPENDS">
619 DISTRO_EXTRA_RDEPENDS</a></em> variable is for
620 distribution maintainers this method does not make
621 adding packages as simple as a custom .bb file. Using
622 this method, a few packages will need to be recreated
623 and the the image built.
624 </p><pre class="programlisting">
625bitbake -cclean task-boot task-base task-poky
626bitbake poky-image-sato
627 </pre><p>
628 Cleaning task-* packages is required because they use the
629 <em class="glossterm"><a href="#var-DISTRO_EXTRA_RDEPENDS" title="DISTRO_EXTRA_RDEPENDS">
630 DISTRO_EXTRA_RDEPENDS</a></em> variable. There is no need to
631 build them by hand as Poky images depend on the packages they contain so
632 dependencies will be built automatically. For this reason we don't use the
633 "rebuild" task in this case since "rebuild" does not care about
634 dependencies - it only rebuilds the specified package.
635 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="platdev-newmachine"></a>3. Porting Poky to a new machine</h2></div></div></div><p>
636 Adding a new machine to Poky is a straightforward process and
637 this section gives an idea of the changes that are needed. This guide is
638 meant to cover adding machines similar to those Poky already supports.
639 Adding a totally new architecture might require gcc/glibc changes as
640 well as updates to the site information and, whilst well within Poky's
641 capabilities, is outside the scope of this section.
642 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-newmachine-conffile"></a>3.1. Adding the machine configuration file</h3></div></div></div><p>
643 A .conf file needs to be added to conf/machine/ with details of the
644 device being added. The name of the file determines the name Poky will
645 use to reference this machine.
646 </p><p>
647 The most important variables to set in this file are <em class="glossterm">
648 <a href="#var-TARGET_ARCH" title="TARGET_ARCH">TARGET_ARCH</a></em>
649 (e.g. "arm"), <em class="glossterm"><a href="#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">
650 PREFERRED_PROVIDER</a></em>_virtual/kernel (see below) and
651 <em class="glossterm"><a href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES
652 </a></em> (e.g. "kernel26 apm screen wifi"). Other variables
653 like <em class="glossterm"><a href="#var-SERIAL_CONSOLE" title="SERIAL_CONSOLE">SERIAL_CONSOLE
654 </a></em> (e.g. "115200 ttyS0"), <em class="glossterm">
655 <a href="#var-KERNEL_IMAGETYPE" title="KERNEL_IMAGETYPE">KERNEL_IMAGETYPE</a>
656 </em> (e.g. "zImage") and <em class="glossterm"><a href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">
657 IMAGE_FSTYPES</a></em> (e.g. "tar.gz jffs2") might also be
658 needed. Full details on what these variables do and the meaning of
659 their contents is available through the links.
660 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-newmachine-kernel"></a>3.2. Adding a kernel for the machine</h3></div></div></div><p>
661 Poky needs to be able to build a kernel for the machine. You need
662 to either create a new kernel recipe for this machine or extend an
663 existing recipe. There are plenty of kernel examples in the
664 packages/linux directory which can be used as references.
665 </p><p>
666 If creating a new recipe the "normal" recipe writing rules apply
667 for setting up a <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI
668 </a></em> including any patches and setting <em class="glossterm">
669 <a href="#var-S" title="S">S</a></em> to point at the source
670 code. You will need to create a configure task which configures the
671 unpacked kernel with a defconfig be that through a "make defconfig"
672 command or more usually though copying in a suitable defconfig and
673 running "make oldconfig". By making use of "inherit kernel" and also
674 maybe some of the linux-*.inc files, most other functionality is
675 centralised and the the defaults of the class normally work well.
676 </p><p>
677 If extending an existing kernel it is usually a case of adding a
678 suitable defconfig file in a location similar to that used by other
679 machine's defconfig files in a given kernel, possibly listing it in
680 the SRC_URI and adding the machine to the expression in <em class="glossterm">
681 <a href="#var-COMPATIBLE_MACHINES" title="COMPATIBLE_MACHINES">COMPATIBLE_MACHINES</a>
682 </em>.
683 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-newmachine-formfactor"></a>3.3. Adding a formfactor configuration file</h3></div></div></div><p>
684 A formfactor configuration file provides information about the
685 target hardware on which Poky is running, and that Poky cannot
686 obtain from other sources such as the kernel. Some examples of
687 information contained in a formfactor configuration file include
688 framebuffer orientation, whether or not the system has a keyboard,
689 the positioning of the keyboard in relation to the screen, and
690 screen resolution.
691 </p><p>
692 Sane defaults should be used in most cases, but if customisation is
693 necessary you need to create a <code class="filename">machconfig</code> file
694 under <code class="filename">meta/packages/formfactor/files/MACHINENAME/</code>
695 where <code class="literal">MACHINENAME</code> is the name for which this infomation
696 applies. For information about the settings available and the defaults, please see
697 <code class="filename">meta/packages/formfactor/files/config</code>.
698 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-changes"></a>4. Making and Maintaining Changes</h2></div></div></div><p>
699 We recognise that people will want to extend/configure/optimise Poky for
700 their specific uses, especially due to the extreme configurability and
701 flexibility Poky offers. To ensure ease of keeping pace with future
702 changes in Poky we recommend making changes to Poky in a controlled way.
703 </p><p>
704 Poky supports the idea of <a href="#usingpoky-changes-collections" title="4.1. Bitbake Collections">"collections"</a> which when used
705 properly can massively ease future upgrades and allow segregation
706 between the Poky core and a given developer's changes. Some other advice on
707 managing changes to Poky is also given in the following section.
708 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-changes-collections"></a>4.1. Bitbake Collections</h3></div></div></div><p>
709 Often, people want to extend Poky either through adding packages
710 or overriding files contained within Poky to add their own
711 functionality. Bitbake has a powerful mechanism called
712 collections which provide a way to handle this which is fully
713 supported and actively encouraged within Poky.
714 </p><p>
715 In the standard tree, meta-extras is an example of how you can
716 do this. As standard the data in meta-extras is not used on a
717 Poky build but local.conf.sample shows how to enable it:
718 </p><p>
719 </p><pre class="literallayout">
720BBFILES := "${OEROOT}/meta/packages/*/*.bb ${OEROOT}/meta-extras/packages/*/*.bb"
721BBFILE_COLLECTIONS = "normal extras"
722BBFILE_PATTERN_normal = "^${OEROOT}/meta/"
723BBFILE_PATTERN_extras = "^${OEROOT}/meta-extras/"
724BBFILE_PRIORITY_normal = "5"
725BBFILE_PRIORITY_extras = "5"</pre><p>
726 </p><p>
727 As can be seen, the extra recipes are added to BBFILES. The
728 BBFILE_COLLECTIONS variable is then set to contain a list of
729 collection names. The BBFILE_PATTERN variables are regular
730 expressions used to match files from BBFILES into a particular
731 collection in this case by using the base pathname.
732 The BBFILE_PRIORITY variable then assigns the different
733 priorities to the files in different collections. This is useful
734 in situations where the same package might appear in both
735 repositories and allows you to choose which collection should
736 'win'.
737 </p><p>
738 This works well for recipes. For bbclasses and configuration
739 files, you can use the BBPATH environment variable. In this
740 case, the first file with the matching name found in BBPATH is
741 the one that is used, just like the PATH variable for binaries.
742 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-changes-commits"></a>4.2. Committing Changes</h3></div></div></div><p>
743 Modifications to Poky are often managed under some kind of source
744 revision control system. The policy for committing to such systems
745 is important as some simple policy can significantly improve
746 usability. The tips below are based on the policy that OpenedHand
747 uses for commits to Poky.
748 </p><p>
749 It helps to use a consistent style for commit messages when committing
750 changes. We've found a style where the first line of a commit message
751 summarises the change and starts with the name of any package affected
752 work well. Not all changes are to specific packages so the prefix could
753 also be a machine name or class name instead. If a change needs a longer
754 description this should follow the summary.
755 </p><p>
756 Any commit should be self contained in that it should leave the
757 metadata in a consistent state, buildable before and after the
758 commit. This helps ensure the autobuilder test results are valid
759 but is good practice regardless.
760 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-changes-prbump"></a>4.3. Package Revision Incrementing</h3></div></div></div><p>
761 If a committed change will result in changing the package output
762 then the value of the <em class="glossterm"><a href="#var-PR" title="PR">PR</a>
763 </em> variable needs to be increased (commonly referred to
764 as 'bumped') as part of that commit. Only integer values are used
765 and <em class="glossterm"><a href="#var-PR" title="PR">PR</a></em> =
766 "r0" should not be added into new recipes as this is default value.
767 When upgrading the version of a package (<em class="glossterm"><a href="#var-PV" title="PV">PV</a></em>), the <em class="glossterm"><a href="#var-PR" title="PR">PR</a></em> variable should be removed.
768 </p><p>
769 The aim is that the package version will only ever increase. If
770 for some reason <em class="glossterm"><a href="#var-PV" title="PV">PV</a></em>
771 will change and but not increase, the <em class="glossterm"><a href="#var-PE" title="PE">PE</a></em> (Package Epoch) can
772 be increased (it defaults to '0'). The version numbers aim to
773 follow the <a href="http://www.debian.org/doc/debian-policy/ch-controlfields.html" target="_top">
774 Debian Version Field Policy Guidelines</a> which define how
775 versions are compared and hence what "increasing" means.
776 </p><p>
777 There are two reasons for doing this, the first is to ensure that
778 when a developer updates and rebuilds, they get all the changes to
779 the repository and don't have to remember to rebuild any sections.
780 The second is to ensure that target users are able to upgrade their
781 devices via their package manager such as with the <span><strong class="command">
782 ipkg update;ipkg upgrade</strong></span> commands (or similar for
783 dpkg/apt or rpm based systems). The aim is to ensure Poky has
784 upgradable packages in all cases.
785 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="usingpoky-modifing-packages"></a>5. Modifying Package Source Code</h2></div></div></div><p>
786 Poky is usually used to build software rather than modifying
787 it. However, there are ways Poky can be used to modify software.
788 </p><p>
789 During building, the sources are available in <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em> directory.
790 Where exactly this is depends on the type of package and the
791 architecture of target device. For a standard recipe not
792 related to <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a></em> it will be
793 <code class="filename">tmp/work/PACKAGE_ARCH-poky-TARGET_OS/PN-PV-PR/</code>.
794 Target device dependent packages use <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE
795 </a></em>
796 instead of <em class="glossterm"><a href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH
797 </a></em>
798 in the directory name.
799 </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
800 Check the package recipe sets the <em class="glossterm"><a href="#var-S" title="S">S</a></em> variable to something
801 other than standard <code class="filename">WORKDIR/PN-PV/</code> value.
802 </p></div><p>
803 After building a package, a user can modify the package source code
804 without problem. The easiest way to test changes is by calling the
805 "compile" task:
806 </p><pre class="programlisting">
807bitbake --cmd compile --force NAME_OF_PACKAGE
808 </pre><p>
809 Other tasks may also be called this way.
810 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="usingpoky-modifying-packages-quilt"></a>5.1. Modifying Package Source Code with quilt</h3></div></div></div><p>
811 By default Poky uses <a href="http://savannah.nongnu.org/projects/quilt" target="_top">quilt</a>
812 to manage patches in <code class="function">do_patch</code> task.
813 It is a powerful tool which can be used to track all
814 modifications done to package sources.
815 </p><p>
816 Before modifying source code it is important to
817 notify quilt so it will track changes into new patch
818 file:
819 </p><pre class="programlisting">
820quilt new NAME-OF-PATCH.patch
821 </pre><p>
822
823 Then add all files which will be modified into that
824 patch:
825 </p><pre class="programlisting">
826quilt add file1 file2 file3
827 </pre><p>
828
829 Now start editing. At the end quilt needs to be used
830 to generate final patch which will contain all
831 modifications:
832 </p><pre class="programlisting">
833quilt refresh
834 </pre><p>
835
836 The resulting patch file can be found in the
837 <code class="filename">patches/</code> subdirectory of the source
838 (<em class="glossterm"><a href="#var-S" title="S">S</a></em>) directory. For future builds it
839 should be copied into
840 Poky metadata and added into <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em> of a recipe:
841 </p><pre class="programlisting">
842SRC_URI += "file://NAME-OF-PATCH.patch;patch=1"
843 </pre><p>
844
845 This also requires a bump of <em class="glossterm"><a href="#var-PR" title="PR">PR</a></em> value in the same recipe as we changed resulting packages.
846 </p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="platdev"></a>Chapter 4. Platform Development with Poky</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#platdev-appdev">1. Software development</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-appdev-external-anjuta">1.1. Developing externally using the Anjuta Plugin</a></span></dt><dt><span class="section"><a href="#platdev-appdev-external-sdk">1.2. Developing externally using the Poky SDK</a></span></dt><dt><span class="section"><a href="#platdev-appdev-qemu">1.3. Developing externally in QEMU</a></span></dt><dt><span class="section"><a href="#platdev-appdev-chroot">1.4. Developing externally in a chroot</a></span></dt><dt><span class="section"><a href="#platdev-appdev-insitu">1.5. Developing in Poky directly</a></span></dt><dt><span class="section"><a href="#platdev-appdev-devshell">1.6. Developing with 'devshell'</a></span></dt><dt><span class="section"><a href="#platdev-appdev-srcrev">1.7. Developing within Poky with an external SCM based package</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-gdb-remotedebug">2. Debugging with GDB Remotely</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdbserver">2.1. Launching GDBSERVER on the target</a></span></dt><dt><span class="section"><a href="#platdev-gdb-remotedebug-launch-gdb">2.2. Launching GDB on the host computer</a></span></dt></dl></dd><dt><span class="section"><a href="#platdev-oprofile">3. Profiling with OProfile</a></span></dt><dd><dl><dt><span class="section"><a href="#platdev-oprofile-target">3.1. Profiling on the target</a></span></dt><dt><span class="section"><a href="#platdev-oprofile-oprofileui">3.2. Using OProfileUI</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="platdev-appdev"></a>1. Software development</h2></div></div></div><p>
847 Poky supports several methods of software development. These different
848 forms of development are explained below and can be switched
849 between as needed.
850 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-external-anjuta"></a>1.1. Developing externally using the Anjuta Plugin</h3></div></div></div><p>
851 An Anjuta IDE plugin exists to make developing software within the Poky framework
852 easier for the application developer. It presents a graphical IDE from which the
853 developer can cross compile an application then deploy and execute the output in a QEMU
854 emulation session. It also supports cross debugging and profiling.
855 </p><p>
856 To use the plugin, a toolchain and SDK built by Poky is required along with Anjuta and the Anjuta
857 plugin. The Poky Anjuta plugin is available from the OpenedHand SVN repository located at
858 http://svn.o-hand.com/repos/anjuta-poky/trunk/anjuta-plugin-sdk/; a web interface
859 to the repository can be accessed at <a href="http://svn.o-hand.com/view/anjuta-poky/" target="_top">http://svn.o-hand.com/view/anjuta-poky/</a>.
860 See the README file contained in the project for more information.
861 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-external-sdk"></a>1.2. Developing externally using the Poky SDK</h3></div></div></div><p>
862 The meta-toolchain and meta-toolchain-sdk targets (<a href="#ref-images" title="Appendix 4. Reference: Images">see
863 the images section</a>) build tarballs which contain toolchains and
864 libraries suitable for application development outside Poky. These unpack into the
865 <code class="filename">/usr/local/poky</code> directory and contain
866 a setup script, e.g.
867 <code class="filename">/usr/local/poky/eabi-glibc/arm/environment-setup</code> which
868 can be sourced to initialise a suitable environment. After sourcing this, the
869 compiler, QEMU scripts, QEMU binary, a special version of pkgconfig and other
870 useful utilities are added to the PATH. Variables to assist pkgconfig and
871 autotools are also set so that, for example, configure can find pre-generated test
872 results for tests which need target hardware to run.
873 </p><p>
874 Using the toolchain with autotool enabled packages is straightforward, just pass the
875 appropriate host option to configure e.g. "./configure --host=arm-poky-linux-gnueabi".
876 For other projects it is usually a case of ensuring the cross tools are used e.g.
877 CC=arm-poky-linux-gnueabi-gcc and LD=arm-poky-linux-gnueabi-ld.
878 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-qemu"></a>1.3. Developing externally in QEMU</h3></div></div></div><p>
879 Running Poky QEMU images is covered in the <a href="#intro-quickstart-qemu" title="4.2. Downloading and Using Prebuilt Images">Running an Image</a> section.
880 </p><p>
881 Poky's QEMU images contain a complete native toolchain. This means
882 that applications can be developed within QEMU in the same was as a
883 normal system. Using qemux86 on an x86 machine is fast since the
884 guest and host architectures match, qemuarm is slower but gives
885 faithful emulation of ARM specific issues. To speed things up these
886 images support using distcc to call a cross-compiler outside the
887 emulated system too. If <span><strong class="command">runqemu</strong></span> was used to start
888 QEMU, and distccd is present on the host system, any bitbake cross
889 compiling toolchain available from the build system will automatically
890 be used from within qemu simply by calling distcc
891 (<span><strong class="command">export CC="distcc"</strong></span> can be set in the enviroment).
892 Alterntatively, if a suitable SDK/toolchain is present in
893 <code class="filename">/usr/local/poky</code> it will also
894 automatically be used.
895 </p><p>
896 There are several options for connecting into the emulated system.
897 QEMU provides a framebuffer interface which has standard consoles
898 available. There is also a serial connection available which has a
899 console to the system running on it and IP networking as standard.
900 The images have a dropbear ssh server running with the root password
901 disabled allowing standard ssh and scp commands to work. The images
902 also contain an NFS server exporting the guest's root filesystem
903 allowing that to be made available to the host.
904 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-chroot"></a>1.4. Developing externally in a chroot</h3></div></div></div><p>
905 If you have a system that matches the architecture of the Poky machine you're using,
906 such as qemux86, you can run binaries directly from the image on the host system
907 using a chroot combined with tools like <a href="http://projects.o-hand.com/xephyr" target="_top">Xephyr</a>.
908 </p><p>
909 Poky has some scripts to make using its qemux86 images within a chroot easier. To use
910 these you need to install the poky-scripts package or otherwise obtain the
911 <code class="filename">poky-chroot-setup</code> and <code class="filename">poky-chroot-run</code> scripts.
912 You also need Xephyr and chrootuid binaries available. To initialize a system use the setup script:
913 </p><p>
914 </p><pre class="literallayout">
915# poky-chroot-setup &lt;qemux86-rootfs.tgz&gt; &lt;target-directory&gt;
916</pre><p>
917 </p><p>
918 which will unpack the specified qemux86 rootfs tarball into the target-directory.
919 You can then start the system with:
920 </p><p>
921 </p><pre class="literallayout">
922# poky-chroot-run &lt;target-directory&gt; &lt;command&gt;
923</pre><p>
924 </p><p>
925 where the target-directory is the place the rootfs was unpacked to and command is
926 an optional command to run. If no command is specified, the system will drop you
927 within a bash shell. A Xephyr window will be displayed containing the emulated
928 system and you may be asked for a password since some of the commands used for
929 bind mounting directories need to be run using sudo.
930 </p><p>
931 There are limits as to how far the the realism of the chroot environment extends.
932 It is useful for simple development work or quick tests but full system emulation
933 with QEMU offers a much more realistic environment for more complex development
934 tasks. Note that chroot support within Poky is still experimental.
935 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-insitu"></a>1.5. Developing in Poky directly</h3></div></div></div><p>
936 Working directly in Poky is a fast and effective development technique.
937 The idea is that you can directly edit files in
938 <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em>
939 or the source directory <em class="glossterm"><a href="#var-S" title="S">S</a></em>
940 and then force specific tasks to rerun in order to test the changes.
941 An example session working on the matchbox-desktop package might
942 look like this:
943 </p><p>
944 </p><pre class="literallayout">
945$ bitbake matchbox-desktop
946$ sh
947$ cd tmp/work/armv5te-poky-linux-gnueabi/matchbox-desktop-2.0+svnr1708-r0/
948$ cd matchbox-desktop-2
949$ vi src/main.c
950$ exit
951$ bitbake matchbox-desktop -c compile -f
952$ bitbake matchbox-desktop
953</pre><p>
954 </p><p>
955 Here, we build the package, change into the work directory for the package,
956 change a file, then recompile the package. Instead of using sh like this,
957 you can also use two different terminals. The risk with working like this
958 is that a command like unpack could wipe out the changes you've made to the
959 work directory so you need to work carefully.
960 </p><p>
961 It is useful when making changes directly to the work directory files to do
962 so using quilt as detailed in the <a href="#usingpoky-modifying-packages-quilt" title="5.1. Modifying Package Source Code with quilt">
963 modifying packages with quilt</a> section. The resulting patches can be copied
964 into the recipe directory and used directly in the <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em>.
965 </p><p>
966 For a review of the skills used in this section see Sections <a href="#usingpoky-components-bitbake" title="1.1. Bitbake">2.1.1</a> and <a href="#usingpoky-debugging-taskrunning" title="4.2. Running specific tasks">2.4.2</a>.
967 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-devshell"></a>1.6. Developing with 'devshell'</h3></div></div></div><p>
968 When debugging certain commands or even to just edit packages, the
969 'devshell' can be a useful tool. To start it you run a command like:
970 </p><p>
971 </p><pre class="literallayout">
972$ bitbake matchbox-desktop -c devshell
973</pre><p>
974 </p><p>
975 which will open a terminal with a shell prompt within the Poky
976 environment. This means PATH is setup to include the cross toolchain,
977 the pkgconfig variables are setup to find the right .pc files,
978 configure will be able to find the Poky site files etc. Within this
979 environment, you can run configure or compile command as if they
980 were being run by Poky itself. You are also changed into the
981 source (<em class="glossterm"><a href="#var-S" title="S">S</a></em>)
982 directory automatically. When finished with the shell just exit it
983 or close the terminal window.
984 </p><p>
985 The default shell used by devshell is the gnome-terminal. Other
986 forms of terminal can also be used by setting the <em class="glossterm">
987 <a href="#var-TERMCMD" title="TERMCMD">TERMCMD</a></em> and <em class="glossterm">
988 <a href="#var-TERMCMDRUN" title="TERMCMDRUN">TERMCMDRUN</a></em> variables
989 in local.conf. For examples of the other options available, see
990 <code class="filename">meta/conf/bitbake.conf</code>. An external shell is
991 launched rather than opening directly into the original terminal
992 window to make interaction with bitbakes multiple threads easier
993 and also allow a client/server split of bitbake in the future
994 (devshell will still work over X11 forwarding or similar).
995 </p><p>
996 It is worth remembering that inside devshell you need to use the full
997 compiler name such as <span><strong class="command">arm-poky-linux-gnueabi-gcc</strong></span>
998 instead of just <span><strong class="command">gcc</strong></span> and the same applies to other
999 applications from gcc, bintuils, libtool etc. Poky will have setup
1000 environmental variables such as CC to assist applications, such as make,
1001 find the correct tools.
1002 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-appdev-srcrev"></a>1.7. Developing within Poky with an external SCM based package</h3></div></div></div><p>
1003 If you're working on a recipe which pulls from an external SCM it
1004 is possible to have Poky notice new changes added to the
1005 SCM and then build the latest version. This only works for SCMs
1006 where its possible to get a sensible revision number for changes.
1007 Currently it works for svn, git and bzr repositories.
1008 </p><p>
1009 To enable this behaviour it is simply a case of adding <em class="glossterm">
1010 <a href="#var-SRCREV" title="SRCREV">SRCREV</a></em>_pn-<em class="glossterm">
1011 <a href="#var-PN" title="PN">PN</a></em> = "${AUTOREV}" to
1012 local.conf where <em class="glossterm"><a href="#var-PN" title="PN">PN</a></em>
1013 is the name of the package for which you want to enable automatic source
1014 revision updating.
1015 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="platdev-gdb-remotedebug"></a>2. Debugging with GDB Remotely</h2></div></div></div><p>
1016 <a href="http://sourceware.org/gdb/" target="_top">GDB</a> (The GNU Project Debugger)
1017 allows you to examine running programs to understand and fix problems and
1018 also to perform postmortem style analsys of program crashes. It is available
1019 as a package within poky and installed by default in sdk images. It works best
1020 when -dbg packages for the application being debugged are installed as the
1021 extra symbols give more meaningful output from GDB.
1022 </p><p>
1023 Sometimes, due to memory or disk space constraints, it is not possible
1024 to use GDB directly on the remote target to debug applications. This is
1025 due to the fact that
1026 GDB needs to load the debugging information and the binaries of the
1027 process being debugged. GDB then needs to perform many
1028 computations to locate information such as function names, variable
1029 names and values, stack traces, etc. even before starting the debugging
1030 process. This places load on the target system and can alter the
1031 characteristics of the program being debugged.
1032 </p><p>
1033 This is where GDBSERVER comes into play as it runs on the remote target
1034 and does not load any debugging information from the debugged process.
1035 Instead, the debugging information processing is done by a GDB instance
1036 running on a distant computer - the host GDB. The host GDB then sends
1037 control commands to GDBSERVER to make it stop or start the debugged
1038 program, as well as read or write some memory regions of that debugged
1039 program. All the debugging information loading and processing as well
1040 as the heavy debugging duty is done by the host GDB, giving the
1041 GDBSERVER running on the target a chance to remain small and fast.
1042 </p><p>
1043 As the host GDB is responsible for loading the debugging information and
1044 doing the necessary processing to make actual debugging happen, the
1045 user has to make sure it can access the unstripped binaries complete
1046 with their debugging information and compiled with no optimisations. The
1047 host GDB must also have local access to all the libraries used by the
1048 debugged program. On the remote target the binaries can remain stripped
1049 as GDBSERVER does not need any debugging information there. However they
1050 must also be compiled without optimisation matching the host's binaries.
1051 </p><p>
1052 The binary being debugged on the remote target machine is hence referred
1053 to as the 'inferior' in keeping with GDB documentation and terminology.
1054 Further documentation on GDB, is available on
1055 <a href="http://sourceware.org/gdb/documentation/" target="_top">on their site</a>.
1056 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-gdb-remotedebug-launch-gdbserver"></a>2.1. Launching GDBSERVER on the target</h3></div></div></div><p>
1057 First, make sure gdbserver is installed on the target. If not,
1058 install the gdbserver package (which needs the libthread-db1
1059 package).
1060 </p><p>
1061 To launch GDBSERVER on the target and make it ready to "debug" a
1062 program located at <span class="emphasis"><em>/path/to/inferior</em></span>, connect
1063 to the target and launch:
1064 </p><pre class="programlisting">$ gdbserver localhost:2345 /path/to/inferior</pre><p>
1065 After that, gdbserver should be listening on port 2345 for debugging
1066 commands coming from a remote GDB process running on the host computer.
1067 Communication between the GDBSERVER and the host GDB will be done using
1068 TCP. To use other communication protocols please refer to the
1069 GDBSERVER documentation.
1070 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-gdb-remotedebug-launch-gdb"></a>2.2. Launching GDB on the host computer</h3></div></div></div><p>
1071 Running GDB on the host computer takes a number of stages, described in the
1072 following sections.
1073 </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-gdb-remotedebug-launch-gdb-buildcross"></a>2.2.1. Build the cross GDB package</h4></div></div></div><p>
1074 A suitable gdb cross binary is required which runs on your host computer but
1075 knows about the the ABI of the remote target. This can be obtained from
1076 the the Poky toolchain, e.g.
1077 <code class="filename">/usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb</code>
1078 which "arm" is the target architecture and "linux-gnueabi" the target ABI.
1079 </p><p>
1080 Alternatively this can be built directly by Poky. To do this you would build
1081 the gdb-cross package so for example you would run:
1082 </p><pre class="programlisting">bitbake gdb-cross</pre><p>
1083 Once built, the cross gdb binary can be found at
1084 </p><pre class="programlisting">tmp/cross/bin/&lt;target-abi&gt;-gdb </pre><p>
1085 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-gdb-remotedebug-launch-gdb-inferiorbins"></a>2.2.2. Making the inferior binaries available</h4></div></div></div><p>
1086 The inferior binary needs to be available to GDB complete with all debugging
1087 symbols in order to get the best possible results along with any libraries
1088 the inferior depends on and their debugging symbols. There are a number of
1089 ways this can be done.
1090 </p><p>
1091 Perhaps the easiest is to have an 'sdk' image corresponding to the plain
1092 image installed on the device. In the case of 'pky-image-sato',
1093 'poky-image-sdk' would contain suitable symbols. The sdk images already
1094 have the debugging symbols installed so its just a question expanding the
1095 archive to some location and telling GDB where this is.
1096 </p><p>
1097 Alternatively, poky can build a custom directory of files for a specific
1098 debugging purpose by reusing its tmp/rootfs directory, on the host computer
1099 in a slightly different way to normal. This directory contains the contents
1100 of the last built image. This process assumes the image running on the
1101 target was the last image to be built by Poky, the package <span class="emphasis"><em>foo</em></span>
1102 contains the inferior binary to be debugged has been built without without
1103 optimisation and has debugging information available.
1104 </p><p>
1105 Firstly you want to install the <span class="emphasis"><em>foo</em></span> package to tmp/rootfs
1106 by doing:
1107 </p><pre class="programlisting">tmp/staging/i686-linux/usr/bin/ipkg-cl -f \
1108tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/ipkg.conf -o \
1109tmp/rootfs/ update</pre><p>
1110 then,
1111 </p><pre class="programlisting">tmp/staging/i686-linux/usr/bin/ipkg-cl -f \
1112tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/ipkg.conf \
1113-o tmp/rootfs install foo
1114
1115tmp/staging/i686-linux/usr/bin/ipkg-cl -f \
1116tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/temp/ipkg.conf \
1117-o tmp/rootfs install foo-dbg</pre><p>
1118 which installs the debugging information too.
1119 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-gdb-remotedebug-launch-gdb-launchhost"></a>2.2.3. Launch the host GDB</h4></div></div></div><p>
1120 To launch the host GDB, run the cross gdb binary identified above with
1121 the inferior binary specified on the commandline:
1122 </p><pre class="programlisting">&lt;target-abi&gt;-gdb rootfs/usr/bin/foo</pre><p>
1123 This loads the binary of program <span class="emphasis"><em>foo</em></span>
1124 as well as its debugging information. Once the gdb prompt
1125 appears, you must instruct GDB to load all the libraries
1126 of the inferior from tmp/rootfs:
1127 </p><pre class="programlisting">set solib-absolute-prefix /path/to/tmp/rootfs</pre><p>
1128 where <code class="filename">/path/to/tmp/rootfs</code> must be
1129 the absolute path to <code class="filename">tmp/rootfs</code> or wherever the
1130 binaries with debugging information are located.
1131 </p><p>
1132 Now, tell GDB to connect to the GDBSERVER running on the remote target:
1133 </p><pre class="programlisting">target remote remote-target-ip-address:2345</pre><p>
1134 Where remote-target-ip-address is the IP address of the
1135 remote target where the GDBSERVER is running. 2345 is the
1136 port on which the GDBSERVER is running.
1137 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-gdb-remotedebug-launch-gdb-using"></a>2.2.4. Using the Debugger</h4></div></div></div><p>
1138 Debugging can now proceed as normal, as if the debugging were being done on the
1139 local machine, for example to tell GDB to break in the <span class="emphasis"><em>main</em></span>
1140 function, for instance:
1141 </p><pre class="programlisting">break main</pre><p>
1142 and then to tell GDB to "continue" the inferior execution,
1143 </p><pre class="programlisting">continue</pre><p>
1144 </p><p>
1145 For more information about using GDB please see the
1146 project's online documentation at <a href="http://sourceware.org/gdb/download/onlinedocs/" target="_top">http://sourceware.org/gdb/download/onlinedocs/</a>.
1147 </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="platdev-oprofile"></a>3. Profiling with OProfile</h2></div></div></div><p>
1148 <a href="http://oprofile.sourceforge.net/" target="_top">OProfile</a> is a
1149 statistical profiler well suited to finding performance
1150 bottlenecks in both userspace software and the kernel. It provides
1151 answers to questions like "Which functions does my application spend
1152 the most time in when doing X?". Poky is well integrated with OProfile
1153 to make profiling applications on target hardware straightforward.
1154 </p><p>
1155 To use OProfile you need an image with OProfile installed. The easiest
1156 way to do this is with "tools-profile" in <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em>. You also
1157 need debugging symbols to be available on the system where the analysis
1158 will take place. This can be achieved with "dbg-pkgs" in <em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em> or by
1159 installing the appropriate -dbg packages. For
1160 successful call graph analysis the binaries must preserve the frame
1161 pointer register and hence should be compiled with the
1162 "-fno-omit-framepointer" flag. In Poky this can be achieved with
1163 <em class="glossterm"><a href="#var-SELECTED_OPTIMIZATION" title="SELECTED_OPTIMIZATION">SELECTED_OPTIMIZATION
1164 </a></em> = "-fexpensive-optimizations -fno-omit-framepointer
1165 -frename-registers -O2" or by setting <em class="glossterm"><a href="#var-DEBUG_BUILD" title="DEBUG_BUILD">DEBUG_BUILD</a></em> = "1" in
1166 local.conf (the latter will also add extra debug information making the
1167 debug packages large).
1168 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-oprofile-target"></a>3.1. Profiling on the target</h3></div></div></div><p>
1169 All the profiling work can be performed on the target device. A
1170 simple OProfile session might look like:
1171 </p><p>
1172 </p><pre class="literallayout">
1173# opcontrol --reset
1174# opcontrol --start --separate=lib --no-vmlinux -c 5
1175[do whatever is being profiled]
1176# opcontrol --stop
1177$ opreport -cl
1178</pre><p>
1179 </p><p>
1180 Here, the reset command clears any previously profiled data,
1181 OProfile is then started. The options used to start OProfile mean
1182 dynamic library data is kept separately per application, kernel
1183 profiling is disabled and callgraphing is enabled up to 5 levels
1184 deep. To profile the kernel, you would specify the
1185 <em class="parameter"><code>--vmlinux=/path/to/vmlinux</code></em> option (the vmlinux file is usually in
1186 <code class="filename">/boot/</code> in Poky and must match the running kernel). The profile is
1187 then stopped and the results viewed with opreport with options
1188 to see the separate library symbols and callgraph information.
1189 </p><p>
1190 Callgraphing means OProfile not only logs infomation about which
1191 functions time is being spent in but also which functions
1192 called those functions (their parents) and which functions that
1193 function calls (its children). The higher the callgraphing depth,
1194 the more accurate the results but this also increased the loging
1195 overhead so it should be used with caution. On ARM, binaries need
1196 to have the frame pointer enabled for callgraphing to work (compile
1197 with the gcc option -fno-omit-framepointer).
1198 </p><p>
1199 For more information on using OProfile please see the OProfile
1200 online documentation at <a href="http://oprofile.sourceforge.net/docs/" target="_top">http://oprofile.sourceforge.net/docs/</a>.
1201 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="platdev-oprofile-oprofileui"></a>3.2. Using OProfileUI</h3></div></div></div><p>
1202 A graphical user interface for OProfile is also available. You can
1203 either use prebuilt Debian packages from the <a href="http://debian.o-hand.com/" target="_top">OpenedHand repository</a> or
1204 download and build from svn at
1205 http://svn.o-hand.com/repos/oprofileui/trunk/. If the
1206 "tools-profile" image feature is selected, all necessary binaries
1207 are installed onto the target device for OProfileUI interaction.
1208 </p><p>
1209 In order to convert the data in the sample format from the target
1210 to the host the <code class="filename">opimport</code> program is needed.
1211 This is not included in standard Debian OProfile packages but an
1212 OProfile package with this addition is also available from the <a href="http://debian.o-hand.com/" target="_top">OpenedHand repository</a>.
1213 We recommend using OProfile 0.9.3 or greater. Other patches to
1214 OProfile may be needed for recent OProfileUI features, but Poky
1215 usually includes all needed patches on the target device. Please
1216 see the <a href="http://svn.o-hand.com/repos/oprofileui/trunk/README" target="_top">
1217 OProfileUI README</a> for up to date information, and the
1218 <a href="http://labs.o-hand.com/oprofileui" target="_top">OProfileUI website
1219 </a> for more information on the OProfileUI project.
1220 </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-oprofile-oprofileui-online"></a>3.2.1. Online mode</h4></div></div></div><p>
1221 This assumes a working network connection with the target
1222 hardware. In this case you just need to run <span><strong class="command">
1223 "oprofile-server"</strong></span> on the device. By default it listens
1224 on port 4224. This can be changed with the <em class="parameter"><code>--port</code></em> command line
1225 option.
1226
1227 </p><p>
1228 The client program is called <span><strong class="command">oprofile-viewer</strong></span>. The
1229 UI is relatively straightforward, the key functionality is accessed
1230 through the buttons on the toolbar (which are duplicated in the
1231 menus.) These buttons are:
1232 </p><div class="itemizedlist"><ul type="disc"><li><p>
1233 Connect - connect to the remote host, the IP address or hostname for the
1234 target can be supplied here.
1235 </p></li><li><p>
1236 Disconnect - disconnect from the target.
1237 </p></li><li><p>
1238 Start - start the profiling on the device.
1239 </p></li><li><p>
1240 Stop - stop the profiling on the device and download the data to the local
1241 host. This will generate the profile and show it in the viewer.
1242 </p></li><li><p>
1243 Download - download the data from the target, generate the profile and show it
1244 in the viewer.
1245 </p></li><li><p>
1246 Reset - reset the sample data on the device. This will remove the sample
1247 information that was collected on a previous sampling run. Ensure you do this
1248 if you do not want to include old sample information.
1249 </p></li><li><p>
1250 Save - save the data downloaded from the target to another directory for later
1251 examination.
1252 </p></li><li><p>
1253 Open - load data that was previously saved.
1254 </p></li></ul></div><p>
1255 The behaviour of the client is to download the complete 'profile archive' from
1256 the target to the host for processing. This archive is a directory containing
1257 the sample data, the object files and the debug information for said object
1258 files. This archive is then converted using a script included in this
1259 distribution ('oparchconv') that uses 'opimport' to convert the archive from
1260 the target to something that can be processed on the host.
1261 </p><p>
1262 Downloaded archives are kept in /tmp and cleared up when they are no longer in
1263 use.
1264 </p><p>
1265 If you wish to profile into the kernel, this is possible, you just need to ensure
1266 a vmlinux file matching the running kernel is available. In Poky this is usually
1267 located in /boot/vmlinux-KERNELVERSION, where KERNEL-version is the version of
1268 the kernel e.g. 2.6.23. Poky generates separate vmlinux packages for each kernel
1269 it builds so it should be a question of just ensuring a matching package is
1270 installed (<span><strong class="command"> ipkg install kernel-vmlinux</strong></span>. These are automatically
1271 installed into development and profiling images alongside OProfile. There is a
1272 configuration option within the OProfileUI settings page where the location of
1273 the vmlinux file can be entered.
1274 </p><p>
1275 Waiting for debug symbols to transfer from the device can be slow and it's not
1276 always necessary to actually have them on device for OProfile use. All that is
1277 needed is a copy of the filesystem with the debug symbols present on the viewer
1278 system. The <a href="#platdev-gdb-remotedebug-launch-gdb" title="2.2. Launching GDB on the host computer">GDB remote debug
1279 section</a> covers how to create such a directory with Poky and the location
1280 of this directory can again be specified in the OProfileUI settings dialog. If
1281 specified, it will be used where the file checksums match those on the system
1282 being profiled.
1283 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="platdev-oprofile-oprofileui-offline"></a>3.2.2. Offline mode</h4></div></div></div><p>
1284 If no network access to the target is available an archive for processing in
1285 'oprofile-viewer' can be generated with the following set of command.
1286 </p><p>
1287 </p><pre class="literallayout">
1288# opcontrol --reset
1289# opcontrol --start --separate=lib --no-vmlinux -c 5
1290[do whatever is being profiled]
1291# opcontrol --stop
1292# oparchive -o my_archive
1293</pre><p>
1294 </p><p>
1295 Where my_archive is the name of the archive directory where you would like the
1296 profile archive to be kept. The directory will be created for you. This can
1297 then be copied to another host and loaded using 'oprofile-viewer''s open
1298 functionality. The archive will be converted if necessary.
1299 </p></div></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-structure"></a>Appendix 1. Reference: Directory Structure</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#structure-core">1. Top level core components</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-core-bitbake">1.1. <code class="filename">bitbake/</code></a></span></dt><dt><span class="section"><a href="#structure-core-build">1.2. <code class="filename">build/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta">1.3. <code class="filename">meta/</code></a></span></dt><dt><span class="section"><a href="#structure-core-meta-extras">1.4. <code class="filename">meta-extras/</code></a></span></dt><dt><span class="section"><a href="#structure-core-scripts">1.5. <code class="filename">scripts/</code></a></span></dt><dt><span class="section"><a href="#structure-core-sources">1.6. <code class="filename">sources/</code></a></span></dt><dt><span class="section"><a href="#structure-core-script">1.7. <code class="filename">poky-init-build-env</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-build">2. <code class="filename">build/</code> - The Build Directory</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-build-conf-local.conf">2.1. <code class="filename">build/conf/local.conf</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp">2.2. <code class="filename">build/tmp/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cache">2.3. <code class="filename">build/tmp/cache/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-cross">2.4. <code class="filename">build/tmp/cross/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy">2.5. <code class="filename">build/tmp/deploy/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-deb">2.6. <code class="filename">build/tmp/deploy/deb/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-images">2.7. <code class="filename">build/tmp/deploy/images/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-deploy-ipk">2.8. <code class="filename">build/tmp/deploy/ipk/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-rootfs">2.9. <code class="filename">build/tmp/rootfs/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-staging">2.10. <code class="filename">build/tmp/staging/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-stamps">2.11. <code class="filename">build/tmp/stamps/</code></a></span></dt><dt><span class="section"><a href="#structure-build-tmp-work">2.12. <code class="filename">build/tmp/work/</code></a></span></dt></dl></dd><dt><span class="section"><a href="#structure-meta">3. <code class="filename">meta/</code> - The Metadata</a></span></dt><dd><dl><dt><span class="section"><a href="#structure-meta-classes">3.1. <code class="filename">meta/classes/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf">3.2. <code class="filename">meta/conf/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-machine">3.3. <code class="filename">meta/conf/machine/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-conf-distro">3.4. <code class="filename">meta/conf/distro/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-packages">3.5. <code class="filename">meta/packages/</code></a></span></dt><dt><span class="section"><a href="#structure-meta-site">3.6. <code class="filename">meta/site/</code></a></span></dt></dl></dd></dl></div><p>
1300 Poky consists of several components and understanding what these are
1301 and where they're located is one of the keys to using it. This section walks
1302 through the Poky directory structure giving information about the various
1303 files and directories.
1304</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="structure-core"></a>1. Top level core components</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-bitbake"></a>1.1. <code class="filename">bitbake/</code></h3></div></div></div><p>
1305 A copy of BitBake is included within Poky for ease of use, and should
1306 usually match the current BitBake stable release from the BitBake project.
1307 Bitbake, a metadata interpreter, reads the Poky metadata and runs the tasks
1308 defined in the Poky metadata. Failures are usually from the metadata, not
1309 BitBake itself, so most users don't need to worry about BitBake. The
1310 <code class="filename">bitbake/bin/</code> directory is placed
1311 into the PATH environment variable by the <a href="#structure-core-script" title="1.7. poky-init-build-env">poky-init-build-env</a> script.
1312 </p><p>
1313 For more information on BitBake please see the BitBake project site at
1314 <a href="http://bitbake.berlios.de/" target="_top">http://bitbake.berlios.de/</a>
1315 and the BitBake on-line manual at <a href="http://bitbake.berlios.de/manual/" target="_top">http://bitbake.berlios.de/manual/</a>.
1316 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-build"></a>1.2. <code class="filename">build/</code></h3></div></div></div><p>
1317 This directory contains user configuration files and the output
1318 from Poky.
1319 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-meta"></a>1.3. <code class="filename">meta/</code></h3></div></div></div><p>
1320 This directory contains the core metadata, a key part of Poky. Within this
1321 directory there are definitions of the machines, the Poky distribution
1322 and the packages that make up a given system.
1323 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-meta-extras"></a>1.4. <code class="filename">meta-extras/</code></h3></div></div></div><p>
1324 This directory is similar to <code class="filename">meta/</code>,
1325 and contains some extra metadata not included in standard Poky. These are
1326 disabled by default, and are not supported as part of Poky.
1327 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-scripts"></a>1.5. <code class="filename">scripts/</code></h3></div></div></div><p>
1328 This directory contains various integration scripts which implement
1329 extra functionality in the Poky environment, such as the QEMU
1330 scripts. This directory is appended to the PATH environment variable by the
1331 <a href="#structure-core-script" title="1.7. poky-init-build-env">poky-init-build-env</a> script.
1332 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-sources"></a>1.6. <code class="filename">sources/</code></h3></div></div></div><p>
1333 While not part of a checkout, Poky will create this directory as
1334 part of any build. Any downloads are placed in this directory (as
1335 specified by the <em class="glossterm"><a href="#var-DL_DIR" title="DL_DIR">DL_DIR</a>
1336 </em> variable). This directory can be shared between Poky
1337 builds to save downloading files multiple times. SCM checkouts are
1338 also stored here as e.g. <code class="filename">sources/svn/
1339 </code>, <code class="filename">sources/cvs/</code> or
1340 <code class="filename">sources/git/</code> and the
1341 sources directory may contain archives of checkouts for various
1342 revisions or dates.
1343 </p><p>
1344 It's worth noting that BitBake creates <code class="filename">.md5
1345 </code> stamp files for downloads. It uses these to mark downloads as
1346 complete as well as for checksum and access accounting purposes. If you add
1347 a file manually to the directory, you need to touch the corresponding
1348 <code class="filename">.md5</code> file too.
1349 </p><p>
1350 This location can be overridden by setting <em class="glossterm"><a href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></em> in <code class="filename">local.conf
1351 </code>. This directory can be shared between builds and even between
1352 machines via NFS, so downloads are only made once, speeding up builds.
1353 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-core-script"></a>1.7. <code class="filename">poky-init-build-env</code></h3></div></div></div><p>
1354 This script is used to setup the Poky build environment. Sourcing this file in
1355 a shell makes changes to PATH and sets other core BitBake variables based on the
1356 current working directory. You need to use this before running Poky commands.
1357 Internally it uses scripts within the <code class="filename">scripts/
1358 </code> directory to do the bulk of the work.
1359 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="structure-build"></a>2. <code class="filename">build/</code> - The Build Directory</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-conf-local.conf"></a>2.1. <code class="filename">build/conf/local.conf</code></h3></div></div></div><p>
1360 This file contains all the local user configuration of Poky. If there
1361 is no <code class="filename">local.conf</code> present, it is created from
1362 <code class="filename">local.conf.sample</code>. The <code class="filename">local.conf</code>
1363 file contains documentation on the various configuration options. Any
1364 variable set here overrides any variable set elsewhere within Poky unless
1365 that variable is hardcoded within Poky (e.g. by using '=' instead of '?=').
1366 Some variables are hardcoded for various reasons but these variables are
1367 relatively rare.
1368 </p><p>
1369 Edit this file to set the <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a></em> for which you want to build, which package types you
1370 wish to use (PACKAGE_CLASSES) or where downloaded files should go
1371 (<em class="glossterm"><a href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></em>).
1372 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp"></a>2.2. <code class="filename">build/tmp/</code></h3></div></div></div><p>
1373 This is created by BitBake if it doesn't exist and is where all the Poky output
1374 is placed. To clean Poky and start a build from scratch (other than downloads),
1375 you can wipe this directory. The <code class="filename">tmp/
1376 </code> directory has some important sub-components detailed below.
1377 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-cache"></a>2.3. <code class="filename">build/tmp/cache/</code></h3></div></div></div><p>
1378 When BitBake parses the metadata it creates a cache file of the result which can
1379 be used when subsequently running commands. These are stored here on
1380 a per machine basis.
1381 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-cross"></a>2.4. <code class="filename">build/tmp/cross/</code></h3></div></div></div><p>
1382 The cross compiler when generated is placed into this directory and those
1383 beneath it.
1384 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-deploy"></a>2.5. <code class="filename">build/tmp/deploy/</code></h3></div></div></div><p>Any 'end result' output from Poky is placed under here.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-deploy-deb"></a>2.6. <code class="filename">build/tmp/deploy/deb/</code></h3></div></div></div><p>
1385 Any .deb packages emitted by Poky are placed here, sorted into feeds for
1386 different architecture types.
1387 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-deploy-images"></a>2.7. <code class="filename">build/tmp/deploy/images/</code></h3></div></div></div><p>
1388 Complete filesystem images are placed here. If you want to flash the resulting
1389 image from a build onto a device, look here for them.
1390 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-deploy-ipk"></a>2.8. <code class="filename">build/tmp/deploy/ipk/</code></h3></div></div></div><p>Any resulting .ipk packages emitted by Poky are placed here.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-rootfs"></a>2.9. <code class="filename">build/tmp/rootfs/</code></h3></div></div></div><p>
1391 This is a temporary scratch area used when creating filesystem images. It is run
1392 under fakeroot and is not useful once that fakeroot session has ended as
1393 information is lost. It is left around since it is still useful in debugging
1394 image creation problems.
1395 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-staging"></a>2.10. <code class="filename">build/tmp/staging/</code></h3></div></div></div><p>
1396 Any package needing to share output with other packages does so within staging.
1397 This means it contains any shared header files and any shared libraries amongst
1398 other data. It is subdivided by architecture so multiple builds can run within
1399 the one build directory.
1400 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-stamps"></a>2.11. <code class="filename">build/tmp/stamps/</code></h3></div></div></div><p>
1401 This is used by BitBake for accounting purposes to keep track of which tasks
1402 have been run and when. It is also subdivided by architecture. The files are
1403 empty and the important information is the filenames and timestamps.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-build-tmp-work"></a>2.12. <code class="filename">build/tmp/work/</code></h3></div></div></div><p>
1404 This directory contains various subdirectories for each architecture, and each package built by BitBake has its own work directory under the appropriate architecture subdirectory. All tasks are executed from this work directory. As an example, the source for a particular package will be unpacked, patched, configured and compiled all within its own work directory.
1405 </p><p>
1406 It is worth considering the structure of a typical work directory. An
1407 example is the linux-rp kernel, version 2.6.20 r7 on the machine spitz
1408 built within Poky. For this package a work directory of <code class="filename">tmp/work/spitz-poky-linux-gnueabi/linux-rp-2.6.20-r7/
1409 </code>, referred to as <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR
1410 </a></em>, is created. Within this directory, the source is
1411 unpacked to linux-2.6.20 and then patched by quilt (see <a href="#usingpoky-modifying-packages-quilt" title="5.1. Modifying Package Source Code with quilt">Section 3.5.1</a>).
1412 Within the <code class="filename">linux-2.6.20</code> directory,
1413 standard Quilt directories <code class="filename">linux-2.6.20/patches</code>
1414 and <code class="filename">linux-2.6.20/.pc</code> are created,
1415 and standard quilt commands can be used.
1416 </p><p>
1417 There are other directories generated within <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em>. The most important
1418 is <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em><code class="filename">/temp/</code> which has log files for each
1419 task (<code class="filename">log.do_*.pid</code>) and the scripts BitBake runs for
1420 each task (<code class="filename">run.do_*.pid</code>). The <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em><code class="filename">/image/</code> directory is where <span><strong class="command">make
1421 install</strong></span> places its output which is then split into subpackages
1422 within <em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em><code class="filename">/install/</code>.
1423 </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="structure-meta"></a>3. <code class="filename">meta/</code> - The Metadata</h2></div></div></div><p>
1424 As mentioned previously, this is the core of Poky. It has several
1425 important subdivisions:
1426 </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-classes"></a>3.1. <code class="filename">meta/classes/</code></h3></div></div></div><p>
1427 Contains the <code class="filename">*.bbclass</code> files. Class
1428 files are used to abstract common code allowing it to be reused by multiple
1429 packages. The <code class="filename">base.bbclass</code> file is inherited by every
1430 package. Examples of other important classes are
1431 <code class="filename">autotools.bbclass</code> that in theory allows any
1432 Autotool-enabled package to work with Poky with minimal effort, or
1433 <code class="filename">kernel.bbclass</code> that contains common code and functions
1434 for working with the linux kernel. Functions like image generation or
1435 packaging also have their specific class files (<code class="filename">image.bbclass
1436 </code>, <code class="filename">rootfs_*.bbclass</code> and
1437 <code class="filename">package*.bbclass</code>).
1438 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-conf"></a>3.2. <code class="filename">meta/conf/</code></h3></div></div></div><p>
1439 This is the core set of configuration files which start from
1440 <code class="filename">bitbake.conf</code> and from which all other configuration
1441 files are included (see the includes at the end of the file, even
1442 <code class="filename">local.conf</code> is loaded from there!). While
1443 <code class="filename">bitbake.conf</code> sets up the defaults, these can often be
1444 overridden by user (<code class="filename">local.conf</code>), machine or
1445 distribution configuration files.
1446 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-conf-machine"></a>3.3. <code class="filename">meta/conf/machine/</code></h3></div></div></div><p>
1447 Contains all the machine configuration files. If you set MACHINE="spitz", the
1448 end result is Poky looking for a <code class="filename">spitz.conf</code> file in this directory. The includes
1449 directory contains various data common to multiple machines. If you want to add
1450 support for a new machine to Poky, this is the directory to look in.
1451 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-conf-distro"></a>3.4. <code class="filename">meta/conf/distro/</code></h3></div></div></div><p>
1452 Any distribution specific configuration is controlled from here. OpenEmbedded
1453 supports multiple distributions of which Poky is one. Poky only contains the
1454 Poky distribution so poky.conf is the main file here. This includes the
1455 versions and SRCDATES for applications which are configured here. An example of
1456 an alternative configuration is poky-bleeding.conf although this mainly inherits
1457 its configuration from Poky itself.
1458 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-packages"></a>3.5. <code class="filename">meta/packages/</code></h3></div></div></div><p>
1459 Each application (package) Poky can build has an associated .bb file which are
1460 all stored under this directory. Poky finds them through the BBFILES variable
1461 which defaults to packages/*/*.bb. Adding a new piece of software to Poky
1462 consists of adding the appropriate .bb file. The .bb files from OpenEmbedded
1463 upstream are usually compatible although they are not supported.
1464 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="structure-meta-site"></a>3.6. <code class="filename">meta/site/</code></h3></div></div></div><p>
1465 Certain autoconf test results cannot be determined when cross compiling since it
1466 can't run tests on a live system. This directory therefore contains a list of
1467 cached results for various architectures which is passed to autoconf.
1468 </p></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-bitbake"></a>Appendix 2. Reference: Bitbake</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref-bitbake-parsing">1. Parsing</a></span></dt><dt><span class="section"><a href="#ref-bitbake-providers">2. Preferences and Providers</a></span></dt><dt><span class="section"><a href="#ref-bitbake-dependencies">3. Dependencies</a></span></dt><dt><span class="section"><a href="#ref-bitbake-tasklist">4. The Task List</a></span></dt><dt><span class="section"><a href="#ref-bitbake-runtask">5. Running a Task</a></span></dt><dt><span class="section"><a href="#ref-bitbake-commandline">6. Commandline</a></span></dt><dt><span class="section"><a href="#ref-bitbake-fetchers">7. Fetchers</a></span></dt></dl></div><p>
1469 Bitbake a program written in Python which interprets the metadata
1470 that makes up Poky. At some point, people wonder what actually happens
1471 when you type <span><strong class="command">bitbake poky-image-sato</strong></span>. This section
1472 aims to give an overview of what happens behind the scenes from a
1473 BitBake perspective.
1474 </p><p>
1475 It is worth noting that bitbake aims to be a generic "task" executor
1476 capable of handling complex dependency relationships. As such it has no
1477 real knowledge of what the tasks its executing actually do. It just
1478 considers a list of tasks with dependencies and handles metadata
1479 consisting of variables in a certain format which get passed to the
1480 tasks.
1481 </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-parsing"></a>1. Parsing</h2></div></div></div><p>
1482 The first thing BitBake does is work out its configuration by
1483 looking for a file called <code class="filename">bitbake.conf</code>.
1484 Bitbake searches through the <code class="varname">BBPATH</code> environment
1485 variable looking for a <code class="filename">conf/</code>
1486 directory containing a <code class="filename">bitbake.conf</code> file and
1487 adds the first <code class="filename">bitbake.conf</code> file found in
1488 <code class="varname">BBPATH</code> (similar to the PATH environment variable).
1489 For Poky, <code class="filename">bitbake.conf</code> is found in <code class="filename">meta/conf/</code>.
1490 </p><p>
1491 In Poky, <code class="filename">bitbake.conf</code> lists other configuration
1492 files to include from a <code class="filename">conf/</code>
1493 directory below the directories listed in <code class="varname">BBPATH</code>.
1494 In general the most important configuration file from a user's perspective
1495 is <code class="filename">local.conf</code>, which contains a users customized
1496 settings for Poky. Other notable configuration files are the distribution
1497 configuration file (set by the <em class="glossterm"><a href="#var-DISTRO" title="DISTRO">
1498 DISTRO</a></em> variable) and the machine configuration file
1499 (set by the <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a>
1500 </em> variable). The <em class="glossterm"><a href="#var-DISTRO" title="DISTRO">
1501 DISTRO</a></em> and <em class="glossterm"><a href="#var-MACHINE" title="MACHINE">
1502 MACHINE</a></em> environment variables are both usually set in
1503 the <code class="filename">local.conf</code> file. Valid distribution
1504 configuration files are available in the <code class="filename">
1505 meta/conf/distro/</code> directory and valid machine configuration
1506 files in the <code class="filename">meta/conf/machine/</code>
1507 directory. Within the <code class="filename">
1508 meta/conf/machine/include/</code> directory are various <code class="filename">
1509 tune-*.inc</code> configuration files which provide common
1510 "tuning" settings specific to and shared between particular
1511 architectures and machines.
1512 </p><p>
1513 After the parsing of the configuration files some standard classes
1514 are included. In particular, <code class="filename">base.bbclass</code> is
1515 always included, as will any other classes
1516 specified in the configuration using the <em class="glossterm"><a href="#var-INHERIT" title="INHERIT">INHERIT</a></em>
1517 variable. Class files are searched for in a classes subdirectory
1518 under the paths in <code class="varname">BBPATH</code> in the same way as
1519 configuration files.
1520 </p><p>
1521 After the parsing of the configuration files is complete, the
1522 variable <em class="glossterm"><a href="#var-BBFILES" title="BBFILES">BBFILES</a></em>
1523 is set, usually in
1524 <code class="filename">local.conf</code>, and defines the list of places to search for
1525 <code class="filename">.bb</code> files. By
1526 default this specifies the <code class="filename">meta/packages/
1527 </code> directory within Poky, but other directories such as
1528 <code class="filename">meta-extras/</code> can be included
1529 too. If multiple directories are specified a system referred to as
1530 <a href="#usingpoky-changes-collections" title="4.1. Bitbake Collections">"collections"</a> is used to
1531 determine which files have priority.
1532 </p><p>
1533 Bitbake parses each <code class="filename">.bb</code> file in
1534 <em class="glossterm"><a href="#var-BBFILES" title="BBFILES">BBFILES</a></em> and
1535 stores the values of various variables. In summary, for each
1536 <code class="filename">.bb</code>
1537 file the configuration + base class of variables are set, followed
1538 by the data in the <code class="filename">.bb</code> file
1539 itself, followed by any inherit commands that
1540 <code class="filename">.bb</code> file might contain.
1541 </p><p>
1542 Parsing <code class="filename">.bb</code> files is a time
1543 consuming process, so a cache is kept to speed up subsequent parsing.
1544 This cache is invalid if the timestamp of the <code class="filename">.bb</code>
1545 file itself has changed, or if the timestamps of any of the include,
1546 configuration or class files the <code class="filename">.bb</code>
1547 file depends on have changed.
1548 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-providers"></a>2. Preferences and Providers</h2></div></div></div><p>
1549 Once all the <code class="filename">.bb</code> files have been
1550 parsed, BitBake will proceed to build "poky-image-sato" (or whatever was
1551 specified on the commandline) and looks for providers of that target.
1552 Once a provider is selected, BitBake resolves all the dependencies for
1553 the target. In the case of "poky-image-sato", it would lead to
1554 <code class="filename">task-oh.bb</code> and <code class="filename">task-base.bb</code>
1555 which in turn would lead to packages like <span class="application">Contacts</span>,
1556 <span class="application">Dates</span>, <span class="application">BusyBox</span>
1557 and these in turn depend on glibc and the toolchain.
1558 </p><p>
1559 Sometimes a target might have multiple providers and a common example
1560 is "virtual/kernel" that is provided by each kernel package. Each machine
1561 will often elect the best provider of its kernel with a line like the
1562 following in the machine configuration file:
1563 </p><pre class="programlisting"><em class="glossterm"><a href="#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">PREFERRED_PROVIDER</a></em>_virtual/kernel = "linux-rp"</pre><p>
1564 The default <em class="glossterm"><a href="#var-PREFERRED_PROVIDER" title="PREFERRED_PROVIDER">
1565 PREFERRED_PROVIDER</a></em> is the provider with the same name as
1566 the target.
1567 </p><p>
1568 Understanding how providers are chosen is complicated by the fact
1569 multiple versions might be present. Bitbake defaults to the highest
1570 version of a provider by default. Version comparisons are made using
1571 the same method as Debian. The <em class="glossterm"><a href="#var-PREFERRED_VERSION" title="PREFERRED_VERSION">PREFERRED_VERSION</a></em>
1572 variable can be used to specify a particular version
1573 (usually in the distro configuration) but the order can
1574 also be influenced by the <em class="glossterm"><a href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></em>
1575 variable. By default files
1576 have a preference of "0". Setting the
1577 <em class="glossterm"><a href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></em> to "-1" will
1578 make a package unlikely to be used unless it was explicitly referenced and
1579 "1" makes it likely the package will be used.
1580 <em class="glossterm"><a href="#var-PREFERRED_VERSION" title="PREFERRED_VERSION">PREFERRED_VERSION</a></em> overrides
1581 any default preference. <em class="glossterm"><a href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></em>
1582 is often used to mark more
1583 experimental new versions of packages until they've undergone sufficient
1584 testing to be considered stable.
1585 </p><p>
1586 The end result is that internally, BitBake has now built a list of
1587 providers for each target it needs in order of priority.
1588 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-dependencies"></a>3. Dependencies</h2></div></div></div><p>
1589 Each target BitBake builds consists of multiple tasks (e.g. fetch,
1590 unpack, patch, configure, compile etc.). For best performance on
1591 multi-core systems, BitBake considers each task as an independent
1592 entity with a set of dependencies. There are many variables that
1593 are used to signify these dependencies and more information can be found
1594 found about these in the <a href="http://bitbake.berlios.de/manual/" target="_top">
1595 BitBake manual</a>. At a basic level it is sufficient to know
1596 that BitBake uses the <em class="glossterm"><a href="#var-DEPENDS" title="DEPENDS">DEPENDS</a></em> and
1597 <em class="glossterm"><a href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></em> variables when
1598 calculating dependencies and descriptions of these variables are
1599 available through the links.
1600 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-tasklist"></a>4. The Task List</h2></div></div></div><p>
1601 Based on the generated list of providers and the dependency information,
1602 BitBake can now calculate exactly which tasks it needs to run and in what
1603 order. The build now starts with BitBake forking off threads up to
1604 the limit set in the <em class="glossterm"><a href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a></em> variable
1605 as long there are tasks ready to run, i.e. tasks with all their
1606 dependencies met.
1607 </p><p>
1608 As each task completes, a timestamp is written to the directory
1609 specified by the <em class="glossterm"><a href="#var-STAMPS" title="STAMPS">STAMPS</a></em> variable (usually
1610 <code class="filename">build/tmp/stamps/*/</code>). On
1611 subsequent runs, BitBake looks at the <em class="glossterm"><a href="#var-STAMPS" title="STAMPS">STAMPS</a></em>
1612 directory and will not rerun
1613 tasks its already completed unless a timestamp is found to be invalid.
1614 Currently, invalid timestamps are only considered on a per <code class="filename">.bb</code> file basis so if for example the configure stamp has a timestamp greater than the
1615 compile timestamp for a given target the compile task would rerun but this
1616 has no effect on other providers depending on that target. This could
1617 change or become configurable in future versions of BitBake. Some tasks
1618 are marked as "nostamp" tasks which means no timestamp file will be written
1619 and the task will always rerun.
1620 </p><p>Once all the tasks have been completed BitBake exits.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-runtask"></a>5. Running a Task</h2></div></div></div><p>
1621 It's worth noting what BitBake does to run a task. A task can either
1622 be a shell task or a python task. For shell tasks, BitBake writes a
1623 shell script to <code class="filename">${WORKDIR}/temp/run.do_taskname.pid</code>
1624 and then executes the script. The generated
1625 shell script contains all the exported variables, and the shell functions
1626 with all variables expanded. Output from the shell script is
1627 sent to the file <code class="filename">${WORKDIR}/temp/log.do_taskname.pid</code>.
1628 Looking at the
1629 expanded shell functions in the run file and the output in the log files
1630 is a useful debugging technique.
1631 </p><p>
1632 Python functions are executed internally to BitBake itself and
1633 logging goes to the controlling terminal. Future versions of BitBake will
1634 write the functions to files in a similar way to shell functions and
1635 logging will also go to the log files in a similar way.
1636 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-commandline"></a>6. Commandline</h2></div></div></div><p>
1637 To quote from "bitbake --help":
1638 </p><pre class="screen">Usage: bitbake [options] [package ...]
1639
1640Executes the specified task (default is 'build') for a given set of BitBake files.
1641It expects that BBFILES is defined, which is a space separated list of files to
1642be executed. BBFILES does support wildcards.
1643Default BBFILES are the .bb files in the current directory.
1644
1645Options:
1646 --version show program's version number and exit
1647 -h, --help show this help message and exit
1648 -b BUILDFILE, --buildfile=BUILDFILE
1649 execute the task against this .bb file, rather than a
1650 package from BBFILES.
1651 -k, --continue continue as much as possible after an error. While the
1652 target that failed, and those that depend on it,
1653 cannot be remade, the other dependencies of these
1654 targets can be processed all the same.
1655 -f, --force force run of specified cmd, regardless of stamp status
1656 -i, --interactive drop into the interactive mode also called the BitBake
1657 shell.
1658 -c CMD, --cmd=CMD Specify task to execute. Note that this only executes
1659 the specified task for the providee and the packages
1660 it depends on, i.e. 'compile' does not implicitly call
1661 stage for the dependencies (IOW: use only if you know
1662 what you are doing). Depending on the base.bbclass a
1663 listtasks tasks is defined and will show available
1664 tasks
1665 -r FILE, --read=FILE read the specified file before bitbake.conf
1666 -v, --verbose output more chit-chat to the terminal
1667 -D, --debug Increase the debug level. You can specify this more
1668 than once.
1669 -n, --dry-run don't execute, just go through the motions
1670 -p, --parse-only quit after parsing the BB files (developers only)
1671 -d, --disable-psyco disable using the psyco just-in-time compiler (not
1672 recommended)
1673 -s, --show-versions show current and preferred versions of all packages
1674 -e, --environment show the global or per-package environment (this is
1675 what used to be bbread)
1676 -g, --graphviz emit the dependency trees of the specified packages in
1677 the dot syntax
1678 -I IGNORED_DOT_DEPS, --ignore-deps=IGNORED_DOT_DEPS
1679 Stop processing at the given list of dependencies when
1680 generating dependency graphs. This can help to make
1681 the graph more appealing
1682 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
1683 Show debug logging for the specified logging domains
1684 -P, --profile profile the command and print a report</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-bitbake-fetchers"></a>7. Fetchers</h2></div></div></div><p>
1685 As well as the containing the parsing and task/dependency handling
1686 code, bitbake also contains a set of "fetcher" modules which allow
1687 fetching of source code from various types of sources. Example
1688 sources might be from disk with the metadata, from websites, from
1689 remote shell accounts or from SCM systems like cvs/subversion/git.
1690 </p><p>
1691 The fetchers are usually triggered by entries in
1692 <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em>. Information about the
1693 options and formats of entries for specific fetchers can be found in the
1694 <a href="http://bitbake.berlios.de/manual/" target="_top">BitBake manual</a>.
1695 </p><p>
1696 One useful feature for certain SCM fetchers is the ability to
1697 "auto-update" when the upstream SCM changes version. Since this
1698 requires certain functionality from the SCM only certain systems
1699 support it, currently Subversion, Bazaar and to a limited extent, Git. It
1700 works using the <em class="glossterm"><a href="#var-SRCREV" title="SRCREV">SRCREV</a>
1701 </em> variable. See the <a href="#platdev-appdev-srcrev" title="1.7. Developing within Poky with an external SCM based package">
1702 developing with an external SCM based project</a> section for more
1703 information.
1704 </p></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-classes"></a>Appendix 3. Reference: Classes</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref-classes-base">1. The base class - <code class="filename">base.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-autotools">2. Autotooled Packages - <code class="filename">autotools.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-alternatives">3. Alternatives - <code class="filename">update-alternatives.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-update-rc.d">4. Initscripts - <code class="filename">update-rc.d.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-binconfig">5. Binary config scripts - <code class="filename">binconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-debian">6. Debian renaming - <code class="filename">debian.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-pkgconfig">7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-src-distribute">8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-perl">9. Perl modules - <code class="filename">cpan.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-distutils">10. Python extensions - <code class="filename">distutils.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-devshell">11. Developer Shell - <code class="filename">devshell.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-package">12. Packaging - <code class="filename">package*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-kernel">13. Building kernels - <code class="filename">kernel.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-image">14. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-sanity">15. Host System sanity checks - <code class="filename">sanity.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-insane">16. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-siteinfo">17. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></a></span></dt><dt><span class="section"><a href="#ref-classes-others">18. Other Classes</a></span></dt></dl></div><p>
1705 Class files are used to abstract common functionality and share it amongst multiple
1706 <code class="filename">.bb</code> files. Any metadata usually found in a
1707 <code class="filename">.bb</code> file can also be placed in a class
1708 file. Class files are identified by the extension
1709 <code class="filename">.bbclass</code> and are usually placed
1710 in a <code class="filename">classes/</code> directory beneath the
1711 <code class="filename">meta/</code> directory or the <code class="filename">build/</code> directory in the same way as <code class="filename">.conf</code> files in the <code class="filename">conf</code> directory. Class files are searched for
1712 in BBPATH in the same was as <code class="filename">.conf</code> files too.
1713</p><p>
1714 In most cases inheriting the class is enough to enable its features, although
1715 for some classes you may need to set variables and/or override some of the
1716 default behaviour.
1717</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-base"></a>1. The base class - <code class="filename">base.bbclass</code></h2></div></div></div><p>
1718 The base class is special in that every <code class="filename">.bb</code>
1719 file inherits it automatically. It contains definitions of standard basic
1720 tasks such as fetching, unpacking, configuring (empty by default), compiling
1721 (runs any Makefile present), installing (empty by default) and packaging
1722 (empty by default). These are often overridden or extended by other classes
1723 such as <code class="filename">autotools.bbclass</code> or
1724 <code class="filename">package.bbclass</code>. The class contains some commonly
1725 some commonly used functions such as <code class="function">oe_libinstall</code>
1726 and <code class="function">oe_runmake</code>. The end of the class file has a
1727 list of standard mirrors for software projects for use by the fetcher code.
1728 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-autotools"></a>2. Autotooled Packages - <code class="filename">autotools.bbclass</code></h2></div></div></div><p>
1729 Autotools (autoconf, automake, libtool) brings standardisation and this
1730 class aims to define a set of tasks (configure, compile etc.) that will
1731 work for all autotooled packages. It should usualy be enough to define
1732 a few standard variables as documented in the <a href="#usingpoky-extend-addpkg-autotools" title="1.2. Autotooled Package">simple autotools
1733 example</a> section and then simply "inherit autotools". This class
1734 can also work with software that emulates autotools.
1735 </p><p>
1736 Its useful to have some idea of the tasks this class defines work and
1737 what they do behind the scenes.
1738 </p><div class="itemizedlist"><ul type="disc"><li><p>
1739 'do_configure' regenearates the configure script and
1740 then launches it with a standard set of arguments used during
1741 cross-compilation. Additional parameters can be passed to
1742 <span><strong class="command">configure</strong></span> through the <em class="glossterm"><a href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a></em> variable.
1743 </p></li><li><p>
1744 'do_compile' runs <span><strong class="command">make</strong></span> with arguments specifying
1745 the compiler and linker. Additional arguments can be passed through
1746 the <em class="glossterm"><a href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a>
1747 </em> variable.
1748 </p></li><li><p>
1749 'do_install' runs <span><strong class="command">make install</strong></span> passing a DESTDIR
1750 option taking its value from the standard <em class="glossterm"><a href="#var-DESTDIR" title="DESTDIR">DESTDIR</a></em> variable.
1751 </p></li></ul></div><p>
1752 By default the class does not stage headers and libraries so
1753 the recipe author needs to add their own <code class="function">do_stage()</code>
1754 task. For typical recipes the following example code will usually be
1755 enough:
1756 </p><pre class="programlisting">
1757do_stage() {
1758autotools_stage_all
1759}</pre><p>
1760 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-update-alternatives"></a>3. Alternatives - <code class="filename">update-alternatives.bbclass</code></h2></div></div></div><p>
1761 Several programs can fulfill the same or similar function and
1762 they can be installed with the same name. For example the <span><strong class="command">ar</strong></span>
1763 command is available from the "busybox", "binutils" and "elfutils" packages.
1764 This class handles the renaming of the binaries so multiple packages
1765 can be installed which would otherwise conflict and yet the
1766 <span><strong class="command">ar</strong></span> command still works regardless of which are installed
1767 or subsequently removed. It renames the conflicting binary in each package
1768 and symlinks the highest priority binary during installation or removal
1769 of packages.
1770
1771 Four variables control this class:
1772 </p><div class="variablelist"><dl><dt><span class="term">ALTERNATIVE_NAME</span></dt><dd><p>
1773 Name of binary which will be replaced (<span><strong class="command">ar</strong></span> in this example)
1774 </p></dd><dt><span class="term">ALTERNATIVE_LINK</span></dt><dd><p>
1775 Path to resulting binary ("/bin/ar" in this example)
1776 </p></dd><dt><span class="term">ALTERNATIVE_PATH</span></dt><dd><p>
1777 Path to real binary ("/usr/bin/ar.binutils" in this example)
1778 </p></dd><dt><span class="term">ALTERNATIVE_PRIORITY</span></dt><dd><p>
1779 Priority of binary, the version with the most features should have the highest priority
1780 </p></dd></dl></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-update-rc.d"></a>4. Initscripts - <code class="filename">update-rc.d.bbclass</code></h2></div></div></div><p>
1781 This class uses update-rc.d to safely install an initscript on behalf of
1782 the package. Details such as making sure the initscript is stopped before
1783 a package is removed and started when the package is installed are taken
1784 care of. Three variables control this class,
1785 <a href="#var-INITSCRIPT_PACKAGES" title="INITSCRIPT_PACKAGES">INITSCRIPT_PACKAGES</a>,
1786 <a href="#var-INITSCRIPT_NAME" title="INITSCRIPT_NAME">INITSCRIPT_NAME</a> and
1787 <a href="#var-INITSCRIPT_PARAMS" title="INITSCRIPT_PARAMS">INITSCRIPT_PARAMS</a>. See the
1788 links for details.
1789 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-binconfig"></a>5. Binary config scripts - <code class="filename">binconfig.bbclass</code></h2></div></div></div><p>
1790 Before pkg-config became widespread, libraries shipped shell
1791 scripts to give information about the libraries and include paths needed
1792 to build software (usually named 'LIBNAME-config'). This class assists
1793 any recipe using such scripts.
1794 </p><p>
1795 During staging Bitbake installs such scripts into the <code class="filename">staging/</code> directory. It also changes all
1796 paths to point into the <code class="filename">staging/</code>
1797 directory so all builds which use the script will use the correct
1798 directories for the cross compiling layout.
1799 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-debian"></a>6. Debian renaming - <code class="filename">debian.bbclass</code></h2></div></div></div><p>
1800 This class renames packages so that they follow the Debian naming
1801 policy, i.e. 'glibc' becomes 'libc6' and 'glibc-devel' becomes
1802 'libc6-dev'.
1803 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-pkgconfig"></a>7. Pkg-config - <code class="filename">pkgconfig.bbclass</code></h2></div></div></div><p>
1804 Pkg-config brought standardisation and this class aims to make its
1805 integration smooth for all libraries which make use of it.
1806 </p><p>
1807 During staging Bitbake installs pkg-config data into the <code class="filename">staging/</code> directory. By making use of
1808 sysroot functionality within pkgconfig this class no longer has to
1809 manipulate the files.
1810 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-src-distribute"></a>8. Distribution of sources - <code class="filename">src_distribute_local.bbclass</code></h2></div></div></div><p>
1811 Many software licenses require providing the sources for compiled
1812 binaries. To simplify this process two classes were created:
1813 <code class="filename">src_distribute.bbclass</code> and
1814 <code class="filename">src_distribute_local.bbclass</code>.
1815 </p><p>
1816 Result of their work are <code class="filename">tmp/deploy/source/</code>
1817 subdirs with sources sorted by <em class="glossterm"><a href="#var-LICENSE" title="LICENSE">LICENSE</a>
1818 </em> field. If recipe lists few licenses (or has entries like "Bitstream Vera") source archive is put in each
1819 license dir.
1820 </p><p>
1821 Src_distribute_local class has three modes of operating:
1822 </p><div class="itemizedlist"><ul type="disc"><li><p>copy - copies the files to the distribute dir</p></li><li><p>symlink - symlinks the files to the distribute dir</p></li><li><p>move+symlink - moves the files into distribute dir, and symlinks them back</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-perl"></a>9. Perl modules - <code class="filename">cpan.bbclass</code></h2></div></div></div><p>
1823 Recipes for Perl modules are simple - usually needs only
1824 pointing to source archive and inheriting of proper bbclass.
1825 Building is split into two methods dependly on method used by
1826 module authors.
1827 </p><p>
1828 Modules which use old Makefile.PL based build system require
1829 using of <code class="filename">cpan.bbclass</code> in their recipes.
1830 </p><p>
1831 Modules which use Build.PL based build system require
1832 using of <code class="filename">cpan_build.bbclass</code> in their recipes.
1833 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-distutils"></a>10. Python extensions - <code class="filename">distutils.bbclass</code></h2></div></div></div><p>
1834 Recipes for Python extensions are simple - usually needs only
1835 pointing to source archive and inheriting of proper bbclass.
1836 Building is split into two methods dependly on method used by
1837 module authors.
1838 </p><p>
1839 Extensions which use autotools based build system require using
1840 of autotools and distutils-base bbclasses in their recipes.
1841 </p><p>
1842 Extensions which use distutils build system require using
1843 of <code class="filename">distutils.bbclass</code> in their recipes.
1844 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-devshell"></a>11. Developer Shell - <code class="filename">devshell.bbclass</code></h2></div></div></div><p>
1845 This class adds the devshell task. Its usually up to distribution policy
1846 to include this class (Poky does). See the <a href="#platdev-appdev-devshell" title="1.6. Developing with 'devshell'">developing with 'devshell' section</a>
1847 for more information about using devshell.
1848 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-package"></a>12. Packaging - <code class="filename">package*.bbclass</code></h2></div></div></div><p>
1849 The packaging classes add support for generating packages from the output
1850 from builds. The core generic functionality is in
1851 <code class="filename">package.bbclass</code>, code specific to particular package
1852 types is contained in various sub classes such as
1853 <code class="filename">package_deb.bbclass</code> and <code class="filename">package_ipk.bbclass</code>.
1854 Most users will
1855 want one or more of these classes and this is controlled by the <em class="glossterm">
1856 <a href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></em>
1857 variable. The first class listed in this variable will be used for image
1858 generation. Since images are generated from packages a packaging class is
1859 needed to enable image generation.
1860 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-kernel"></a>13. Building kernels - <code class="filename">kernel.bbclass</code></h2></div></div></div><p>
1861 This class handle building of Linux kernels and the class contains code to know how to build both 2.4 and 2.6 kernel trees. All needed headers are
1862 staged into <em class="glossterm"><a href="#var-STAGING_KERNEL_DIR" title="STAGING_KERNEL_DIR">STAGING_KERNEL_DIR</a></em>
1863 directory to allow building of out-of-tree modules using <code class="filename">module.bbclass</code>.
1864 </p><p>
1865 The means that each kerel module built is packaged separately and inter-modules dependencies are
1866 created by parsing the <span><strong class="command">modinfo</strong></span> output. If all modules are
1867 required then installing "kernel-modules" package will install all
1868 packages with modules and various other kernel packages such as "kernel-vmlinux" are also generated.
1869 </p><p>
1870 Various other classes are used by the kernel and module classes internally including
1871 <code class="filename">kernel-arch.bbclass</code>, <code class="filename">module_strip.bbclass</code>,
1872 <code class="filename">module-base.bbclass</code> and <code class="filename">linux-kernel-base.bbclass</code>.
1873 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-image"></a>14. Creating images - <code class="filename">image.bbclass</code> and <code class="filename">rootfs*.bbclass</code></h2></div></div></div><p>
1874 Those classes add support for creating images in many formats. First the
1875 rootfs is created from packages by one of the <code class="filename">rootfs_*.bbclass</code>
1876 files (depending on package format used) and then image is created.
1877
1878 The <em class="glossterm"><a href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a></em>
1879 variable controls which types of image to generate.
1880
1881 The list of packages to install into the image is controlled by the
1882 <em class="glossterm"><a href="#var-IMAGE_INSTALL" title="IMAGE_INSTALL">IMAGE_INSTALL</a></em>
1883 variable.
1884 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-sanity"></a>15. Host System sanity checks - <code class="filename">sanity.bbclass</code></h2></div></div></div><p>
1885 This class checks prerequisite software is present to try and identify
1886 and notify the user of problems which will affect their build. It also
1887 performs basic checks of the users configuration from local.conf to
1888 prevent common mistakes and resulting build failures. Its usually up to
1889 distribution policy to include this class (Poky does).
1890 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-insane"></a>16. Generated output quality assurance checks - <code class="filename">insane.bbclass</code></h2></div></div></div><p>
1891 This class adds a step to package generation which sanity checks the
1892 packages generated by Poky. There are an ever increasing range of checks
1893 this makes, checking for common problems which break builds/packages/images,
1894 see the bbclass file for more information. Its usually up to distribution
1895 policy to include this class (Poky doesn't at the time of writing but plans
1896 to soon).
1897 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-siteinfo"></a>17. Autotools configuration data cache - <code class="filename">siteinfo.bbclass</code></h2></div></div></div><p>
1898 Autotools can require tests which have to execute on the target hardware.
1899 Since this isn't possible in general when cross compiling, siteinfo is
1900 used to provide cached test results so these tests can be skipped over but
1901 the correct values used. The <a href="#structure-meta-site" title="3.6. meta/site/">meta/site directory</a>
1902 contains test results sorted into different categories like architecture, endianess and
1903 the libc used. Siteinfo provides a list of files containing data relevant to
1904 the current build in the <em class="glossterm"><a href="#var-CONFIG_SITE" title="CONFIG_SITE">CONFIG_SITE
1905 </a></em> variable which autotools will automatically pick up.
1906 </p><p>
1907 The class also provides variables like <em class="glossterm"><a href="#var-SITEINFO_ENDIANESS" title="SITEINFO_ENDIANESS">SITEINFO_ENDIANESS</a></em>
1908 and <em class="glossterm"><a href="#var-SITEINFO_BITS" title="SITEINFO_BITS">SITEINFO_BITS</a>
1909 </em> which can be used elsewhere in the metadata.
1910 </p><p>
1911 This class is included from <code class="filename">base.bbclass</code> and is hence always active.
1912 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-classes-others"></a>18. Other Classes</h2></div></div></div><p>
1913 Only the most useful/important classes are covered here but there are
1914 others, see the <code class="filename">meta/classes</code> directory for the rest.
1915 </p></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-images"></a>Appendix 4. Reference: Images</h2></div></div></div><p>
1916 Poky has several standard images covering most people's standard needs. A full
1917 list of image targets can be found by looking in the <code class="filename">
1918 meta/packages/images/</code> directory. The standard images are listed below
1919 along with details of what they contain:
1920 </p><div class="itemizedlist"><ul type="disc"><li><p>
1921 <span class="emphasis"><em>poky-image-minimal</em></span> - A small image, just enough
1922 to allow a device to boot
1923 </p></li><li><p>
1924 <span class="emphasis"><em>poky-image-base</em></span> - console only image with full
1925 support of target device hardware
1926 </p></li><li><p>
1927 <span class="emphasis"><em>poky-image-core</em></span> - X11 image with simple apps like
1928 terminal, editor and file manager
1929 </p></li><li><p>
1930 <span class="emphasis"><em>poky-image-sato</em></span> - X11 image with Sato theme and
1931 Pimlico applications. Also contains terminal, editor and file manager.
1932 </p></li><li><p>
1933 <span class="emphasis"><em>poky-image-sdk</em></span> - X11 image like poky-image-sato but
1934 also include native toolchain and libraries needed to build applications
1935 on the device itself. Also includes testing and profiling tools and debug
1936 symbols.
1937 </p></li><li><p>
1938 <span class="emphasis"><em>meta-toolchain</em></span> - This generates a tarball containing
1939 a standalone toolchain which can be used externally to Poky. It is self
1940 contained and unpacks to the <code class="filename">/usr/local/poky</code>
1941 directory. It also contains a copy of QEMU and the scripts neccessary to run
1942 poky QEMU images.
1943 </p></li><li><p>
1944 <span class="emphasis"><em>meta-toolchain-sdk</em></span> - This includes everything in
1945 meta-toolchain but also includes development headers and libraries
1946 forming a complete standalone SDK. See the <a href="#platdev-appdev-external-sdk" title="1.2. Developing externally using the Poky SDK">
1947 Developing using the Poky SDK</a> and <a href="#platdev-appdev-external-anjuta" title="1.1. Developing externally using the Anjuta Plugin">
1948 Developing using the Anjuta Plugin</a> sections for more information.
1949 </p></li></ul></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-features"></a>Appendix 5. Reference: Features</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref-features-distro">1. Distro</a></span></dt><dt><span class="section"><a href="#ref-features-machine">2. Machine</a></span></dt><dt><span class="section"><a href="#ref-features-image">3. Reference: Images</a></span></dt></dl></div><p>'Features' provide a mechanism for working out which packages
1950 should be included in the generated images. Distributions can
1951 select which features they want to support through the
1952 <a href="#var-DISTRO_FEATURES"><em class="glossterm"><a href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></em></a>
1953 variable which is set in the distribution configuration file
1954 (poky.conf for Poky). Machine features are set in the
1955 <a href="#var-MACHINE_FEATURES"><em class="glossterm"><a href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></em></a>
1956 variable which is set in the machine configuration file and
1957 specifies which hardware features a given machine has.
1958 </p><p>These two variables are combined to work out which kernel modules,
1959 utilities and other packages to include. A given distribution can
1960 support a selected subset of features so some machine features might not
1961 be included if the distribution itself doesn't support them.
1962 </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-features-distro"></a>1. Distro</h2></div></div></div><p>The items below are valid options for <a href="#var-DISTRO_FEATURES"><em class="glossterm"><a href="#var-DISTRO_FEATURES" title="DISTRO_FEATURES">DISTRO_FEATURES</a></em></a>.
1963 </p><div class="itemizedlist"><ul type="disc"><li><p>
1964 alsa - ALSA support will be included (OSS compatibility
1965 kernel modules will be installed if available)
1966 </p></li><li><p>
1967 bluetooth - Include bluetooth support (integrated BT only)
1968 </p></li><li><p>
1969 ext2 - Include tools for supporting for devices with internal
1970 HDD/Microdrive for storing files (instead of Flash only devices)
1971 </p></li><li><p>
1972 irda - Include Irda support
1973 </p></li><li><p>
1974 keyboard - Include keyboard support (e.g. keymaps will be
1975 loaded during boot).
1976 </p></li><li><p>
1977 pci - Include PCI bus support
1978 </p></li><li><p>
1979 pcmcia - Include PCMCIA/CompactFlash support
1980 </p></li><li><p>
1981 usbgadget - USB Gadget Device support (for USB
1982 networking/serial/storage)
1983 </p></li><li><p>
1984 usbhost - USB Host support (allows to connect external
1985 keyboard, mouse, storage, network etc)
1986 </p></li><li><p>
1987 wifi - WiFi support (integrated only)
1988 </p></li><li><p>
1989 cramfs - CramFS support
1990 </p></li><li><p>
1991 ipsec - IPSec support
1992 </p></li><li><p>
1993 ipv6 - IPv6 support
1994 </p></li><li><p>
1995 nfs - NFS client support (for mounting NFS exports on
1996 device)
1997 </p></li><li><p>
1998 ppp - PPP dialup support
1999 </p></li><li><p>
2000 smbfs - SMB networks client support (for mounting
2001 Samba/Microsoft Windows shares on device)
2002 </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-features-machine"></a>2. Machine</h2></div></div></div><p>The items below are valid options for <a href="#var-MACHINE_FEATURES"><em class="glossterm"><a href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></em></a>.
2003 </p><div class="itemizedlist"><ul type="disc"><li><p>
2004 acpi - Hardware has ACPI (x86/x86_64 only)
2005 </p></li><li><p>
2006 alsa - Hardware has ALSA audio drivers
2007 </p></li><li><p>
2008 apm - Hardware uses APM (or APM emulation)
2009 </p></li><li><p>
2010 bluetooth - Hardware has integrated BT
2011 </p></li><li><p>
2012 ext2 - Hardware HDD or Microdrive
2013 </p></li><li><p>
2014 irda - Hardware has Irda support
2015 </p></li><li><p>
2016 keyboard - Hardware has a keyboard
2017 </p></li><li><p>
2018 pci - Hardware has a PCI bus
2019 </p></li><li><p>
2020 pcmcia - Hardware has PCMCIA or CompactFlash sockets
2021 </p></li><li><p>
2022 screen - Hardware has a screen
2023 </p></li><li><p>
2024 serial - Hardware has serial support (usually RS232)
2025 </p></li><li><p>
2026 touchscreen - Hardware has a touchscreen
2027 </p></li><li><p>
2028 usbgadget - Hardware is USB gadget device capable
2029 </p></li><li><p>
2030 usbhost - Hardware is USB Host capable
2031 </p></li><li><p>
2032 wifi - Hardware has integrated WiFi
2033 </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-features-image"></a>3. Reference: Images</h2></div></div></div><p>
2034 The contents of images generated by Poky can be controlled by the <a href="#var-IMAGE_FEATURES"><em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em></a>
2035 variable in local.conf. Through this you can add several different
2036 predefined packages such as development utilities or packages with debug
2037 information needed to investigate application problems or profile applications.
2038 </p><p>
2039 Current list of <a href="#var-IMAGE_FEATURES"><em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em></a> contains:
2040 </p><div class="itemizedlist"><ul type="disc"><li><p>
2041 apps-console-core - Core console applications such as ssh daemon,
2042 avahi daemon, portmap (for mounting NFS shares)
2043 </p></li><li><p>
2044 x11-base - X11 server + minimal desktop
2045 </p></li><li><p>
2046 x11-sato - OpenedHand Sato environment
2047 </p></li><li><p>
2048 apps-x11-core - Core X11 applications such as an X Terminal, file manager, file editor
2049 </p></li><li><p>
2050 apps-x11-games - A set of X11 games
2051 </p></li><li><p>
2052 apps-x11-pimlico - OpenedHand Pimlico application suite
2053 </p></li><li><p>
2054 tools-sdk - A full SDK which runs on device
2055 </p></li><li><p>
2056 tools-debug - Debugging tools such as strace and gdb
2057 </p></li><li><p>
2058 tools-profile - Profiling tools such as oprofile, exmap and LTTng
2059 </p></li><li><p>
2060 tools-testapps - Device testing tools (e.g. touchscreen debugging)
2061 </p></li><li><p>
2062 nfs-server - NFS server (exports / over NFS to everybody)
2063 </p></li><li><p>
2064 dev-pkgs - Development packages (headers and extra library links) for all packages
2065 installed in a given image
2066 </p></li><li><p>
2067 dbg-pkgs - Debug packages for all packages installed in a given image
2068 </p></li></ul></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-variables-glos"></a>Appendix 6. Reference: Variables Glossary</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="glossary"><a href="#ref-variables-glossary">Glossary</a></span></dt></dl></div><p>
2069 This section lists common variables used in Poky and gives an overview
2070 of their function and contents.
2071</p><div class="glossary"><div class="titlepage"><div><div><h2 class="title"><a name="ref-variables-glossary"></a>Glossary</h2></div></div></div><p>
2072 <a href="#var-glossary-a" title="A">A</a>
2073 <a href="#var-glossary-b" title="B">B</a>
2074 <a href="#var-glossary-c" title="C">C</a>
2075 <a href="#var-glossary-d" title="D">D</a>
2076 <a href="#var-glossary-e" title="E">E</a>
2077 <a href="#var-glossary-f" title="F">F</a>
2078
2079 <a href="#var-glossary-h" title="H">H</a>
2080 <a href="#var-glossary-i" title="I">I</a>
2081
2082 <a href="#var-glossary-k" title="K">K</a>
2083 <a href="#var-glossary-l" title="L">L</a>
2084 <a href="#var-glossary-m" title="M">M</a>
2085
2086
2087 <a href="#var-glossary-p" title="P">P</a>
2088
2089 <a href="#var-glossary-r" title="R">R</a>
2090 <a href="#var-glossary-s" title="S">S</a>
2091 <a href="#var-glossary-t" title="T">T</a>
2092
2093
2094 <a href="#var-glossary-w" title="W">W</a>
2095
2096
2097
2098 </p><div class="glossdiv"><h3 class="title">A</h3><dl><dt><a name="var-AUTHOR"></a>AUTHOR</dt><dd><p>E-mail address to contact original author(s) - to
2099 send patches, forward bugs...</p></dd><dt><a name="var-AUTOREV"></a>AUTOREV</dt><dd><p>Use current (newest) source revision - used with
2100 <em class="glossterm"><a href="#var-SRCREV" title="SRCREV">SRCREV</a></em>
2101 variable.</p></dd></dl></div><div class="glossdiv"><h3 class="title">B</h3><dl><dt><a name="var-BB_NUMBER_THREADS"></a>BB_NUMBER_THREADS</dt><dd><p>Number of BitBake threads</p></dd><dt><a name="var-BBFILES"></a>BBFILES</dt><dd><p>List of recipes used by BitBake to build software</p></dd><dt><a name="var-BBINCLUDELOGS"></a>BBINCLUDELOGS</dt><dd><p>Variable which controls how BitBake displays logs on build failure.</p></dd></dl></div><div class="glossdiv"><h3 class="title">C</h3><dl><dt><a name="var-CFLAGS"></a>CFLAGS</dt><dd><p>
2102 Flags passed to C compiler for the target system. Evaluates to the same
2103 as <a href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a>.
2104 </p></dd><dt><a name="var-COMPATIBLE_MACHINES"></a>COMPATIBLE_MACHINES</dt><dd><p>A regular expression which evalutates to match the machines the recipe
2105 works with. It stops recipes being run on machines they're incompatible with
2106 which is partciuarly useful with kernels. It also helps to to increase parsing
2107 speed as if its found the current machine is not compatible, further parsing
2108 of the recipe is skipped.</p></dd><dt><a name="var-CONFIG_SITE"></a>CONFIG_SITE</dt><dd><p>
2109 Contains a list of files which containing autoconf test results relevant
2110 to the current build. This variable is used by the autotools utilities
2111 when running configure.
2112 </p></dd><dt><a name="var-CVS_TARBALL_STASH"></a>CVS_TARBALL_STASH</dt><dd><p>Location to search for
2113 pre-generated tarballs when fetching from remote SCM
2114 repositories (CVS/SVN/GIT)</p></dd></dl></div><div class="glossdiv"><h3 class="title">D</h3><dl><dt><a name="var-D"></a>D</dt><dd><p>Destination directory</p></dd><dt><a name="var-DEBUG_BUILD"></a>DEBUG_BUILD</dt><dd><p>
2115 Build packages with debugging information. This influences the value
2116 <a href="#var-SELECTED_OPTIMIZATION" title="SELECTED_OPTIMIZATION">SELECTED_OPTIMIZATION</a>
2117 takes.
2118 </p></dd><dt><a name="var-DEBUG_OPTIMIZATION"></a>DEBUG_OPTIMIZATION</dt><dd><p>
2119 The options to pass in <a href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a>
2120 and <a href="#var-CFLAGS" title="CFLAGS">CFLAGS</a> when compiling a system for debugging.
2121 This defaults to "-O -fno-omit-frame-pointer -g".
2122 </p></dd><dt><a name="var-DEFAULT_PREFERENCE"></a>DEFAULT_PREFERENCE</dt><dd><p>Priority of recipe</p></dd><dt><a name="var-DEPENDS"></a>DEPENDS</dt><dd><p>
2123 A list of build time dependencies for a given recipe. These indicate
2124 recipes that must have staged before this recipe can configure.
2125 </p></dd><dt><a name="var-DESCRIPTION"></a>DESCRIPTION</dt><dd><p>Package description used by package
2126 managers</p></dd><dt><a name="var-DESTDIR"></a>DESTDIR</dt><dd><p>Destination directory</p></dd><dt><a name="var-DISTRO"></a>DISTRO</dt><dd><p>Short name of distribution</p></dd><dt><a name="var-DISTRO_EXTRA_RDEPENDS"></a>DISTRO_EXTRA_RDEPENDS</dt><dd><p>List of packages required by distribution.</p></dd><dt><a name="var-DISTRO_EXTRA_RRECOMMENDS"></a>DISTRO_EXTRA_RRECOMMENDS</dt><dd><p>List of packages which extend usability of
2127 image. Those packages will be automatically
2128 installed but can be removed by user.</p></dd><dt><a name="var-DISTRO_FEATURES"></a>DISTRO_FEATURES</dt><dd><p>Features of the distribution.</p></dd><dt><a name="var-DISTRO_NAME"></a>DISTRO_NAME</dt><dd><p>Long name of distribution</p></dd><dt><a name="var-DISTRO_VERSION"></a>DISTRO_VERSION</dt><dd><p>Version of distribution</p></dd><dt><a name="var-DL_DIR"></a>DL_DIR</dt><dd><p>Directory where all fetched sources will be stored</p></dd></dl></div><div class="glossdiv"><h3 class="title">E</h3><dl><dt><a name="var-ENABLE_BINARY_LOCALE_GENERATION"></a>ENABLE_BINARY_LOCALE_GENERATION</dt><dd><p>Variable which control which locales for glibc are
2129 to be generated during build (useful if target device
2130 has 64M RAM or less)</p></dd><dt><a name="var-EXTRA_OECONF"></a>EXTRA_OECONF</dt><dd><p>Additional 'configure' script options</p></dd><dt><a name="var-EXTRA_OEMAKE"></a>EXTRA_OEMAKE</dt><dd><p>Additional GNU make options</p></dd></dl></div><div class="glossdiv"><h3 class="title">F</h3><dl><dt><a name="var-FILES"></a>FILES</dt><dd><p>list of directories/files which will be placed
2131 in packages</p></dd><dt><a name="var-FULL_OPTIMIZATION"></a>FULL_OPTIMIZATION</dt><dd><p>
2132 The options to pass in <a href="#var-TARGET_CFLAGS" title="TARGET_CFLAGS">TARGET_CFLAGS</a>
2133 and <a href="#var-CFLAGS" title="CFLAGS">CFLAGS</a> when compiling an optimised system.
2134 This defaults to "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
2135 </p></dd></dl></div><div class="glossdiv"><h3 class="title">H</h3><dl><dt><a name="var-HOMEPAGE"></a>HOMEPAGE</dt><dd><p>Website where more info about package can be found</p></dd></dl></div><div class="glossdiv"><h3 class="title">I</h3><dl><dt><a name="var-IMAGE_FEATURES"></a>IMAGE_FEATURES</dt><dd><p><a href="#ref-features-image" title="3. Reference: Images">List of
2136 features</a> present in resulting images</p></dd><dt><a name="var-IMAGE_FSTYPES"></a>IMAGE_FSTYPES</dt><dd><p>Formats of rootfs images which we want to have
2137 created</p></dd><dt><a name="var-IMAGE_INSTALL"></a>IMAGE_INSTALL</dt><dd><p>List of packages used to build image</p></dd><dt><a name="var-INHIBIT_PACKAGE_STRIP"></a>INHIBIT_PACKAGE_STRIP</dt><dd><p>
2138 This variable causes the build to not strip binaries in
2139 resulting packages.
2140 </p></dd><dt><a name="var-INHERIT"></a>INHERIT</dt><dd><p>
2141 This variable causes the named class to be inherited at
2142 this point during parsing. Its only valid in configuration
2143 files.
2144 </p></dd><dt><a name="var-INITSCRIPT_PACKAGES"></a>INITSCRIPT_PACKAGES</dt><dd><p>
2145 Scope: Used in recipes when using update-rc.d.bbclass. Optional, defaults to PN.
2146 </p><p>
2147 A list of the packages which contain initscripts. If multiple
2148 packages are specified you need to append the package name
2149 to the other INITSCRIPT_* as an override.
2150 </p></dd><dt><a name="var-INITSCRIPT_NAME"></a>INITSCRIPT_NAME</dt><dd><p>
2151 Scope: Used in recipes when using update-rc.d.bbclass. Mandatory.
2152 </p><p>
2153 The filename of the initscript (as installed to ${etcdir}/init.d).
2154 </p></dd><dt><a name="var-INITSCRIPT_PARAMS"></a>INITSCRIPT_PARAMS</dt><dd><p>
2155 Scope: Used in recipes when using update-rc.d.bbclass. Mandatory.
2156 </p><p>
2157 Specifies the options to pass to update-rc.d. An example is
2158 "start 99 5 2 . stop 20 0 1 6 ." which gives the script a
2159 runlevel of 99, starts the script in initlevels 2 and 5 and
2160 stops it in levels 0, 1 and 6.
2161 </p></dd></dl></div><div class="glossdiv"><h3 class="title">K</h3><dl><dt><a name="var-KERNEL_IMAGETYPE"></a>KERNEL_IMAGETYPE</dt><dd><p>The type of kernel to build for a device, usually set by the
2162 machine configuration files and defaults to "zImage". This is used
2163 when building the kernel and is passed to "make" as the target to
2164 build.</p></dd></dl></div><div class="glossdiv"><h3 class="title">L</h3><dl><dt><a name="var-LICENSE"></a>LICENSE</dt><dd><p>List of package source licenses.</p></dd></dl></div><div class="glossdiv"><h3 class="title">M</h3><dl><dt><a name="var-MACHINE"></a>MACHINE</dt><dd><p>Target device</p></dd><dt><a name="var-MACHINE_ESSENTIAL_RDEPENDS"></a>MACHINE_ESSENTIAL_RDEPENDS</dt><dd><p>List of packages required to boot device</p></dd><dt><a name="var-MACHINE_ESSENTIAL_RRECOMMENDS"></a>MACHINE_ESSENTIAL_RRECOOMENDS</dt><dd><p>List of packages required to boot device (usually
2165 additional kernel modules)</p></dd><dt><a name="var-MACHINE_EXTRA_RDEPENDS"></a>MACHINE_EXTRA_RDEPENDS</dt><dd><p>List of packages required to use device</p></dd><dt><a name="var-MACHINE_EXTRA_RRECOMMENDS"></a>MACHINE_EXTRA_RRECOMMNEDS</dt><dd><p>List of packages useful to use device (for example
2166 additional kernel modules)</p></dd><dt><a name="var-MACHINE_FEATURES"></a>MACHINE_FEATURES</dt><dd><p>List of device features - defined in <a href="#ref-features-machine" title="2. Machine">machine
2167 features section</a></p></dd><dt><a name="var-MAINTAINER"></a>MAINTAINER</dt><dd><p>E-mail of distribution maintainer</p></dd></dl></div><div class="glossdiv"><h3 class="title">P</h3><dl><dt><a name="var-PACKAGE_ARCH"></a>PACKAGE_ARCH</dt><dd><p>Architecture of resulting package</p></dd><dt><a name="var-PACKAGE_CLASSES"></a>PACKAGE_CLASSES</dt><dd><p>List of resulting packages formats</p></dd><dt><a name="var-PACKAGE_EXTRA_ARCHS"></a>PACKAGE_EXTRA_ARCHS</dt><dd><p>List of architectures compatible with device
2168 CPU. Usable when build is done for few different
2169 devices with misc processors (like XScale and
2170 ARM926-EJS)</p></dd><dt><a name="var-PACKAGES"></a>PACKAGES</dt><dd><p>List of packages to be created from recipe.
2171 The default value is "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev"</p></dd><dt><a name="var-PN"></a>PN</dt><dd><p>Name of package.
2172 </p></dd><dt><a name="var-PR"></a>PR</dt><dd><p>Revision of package.
2173 </p></dd><dt><a name="var-PV"></a>PV</dt><dd><p>Version of package.
2174 The default value is "1.0"</p></dd><dt><a name="var-PE"></a>PE</dt><dd><p>
2175 Epoch of the package. The default value is "1". The field is used
2176 to make upgrades possible when the versioning scheme changes in
2177 some backwards incompatible way.
2178 </p></dd><dt><a name="var-PREFERRED_PROVIDER"></a>PREFERRED_PROVIDER</dt><dd><p>If multiple recipes provide an item, this variable
2179 determines which one should be given preference. It
2180 should be set to the "$PN" of the recipe to be preferred.</p></dd><dt><a name="var-PREFERRED_VERSION"></a>PREFERRED_VERSION</dt><dd><p>
2181 If there are multiple versions of recipe available, this
2182 variable determines which one should be given preference. It
2183 should be set to the "$PV" of the recipe to be preferred.
2184 </p></dd><dt><a name="var-POKYLIBC"></a>POKYLIBC</dt><dd><p>Libc implementation selector - glibc or uclibc can be selected.</p></dd><dt><a name="var-POKYMODE"></a>POKYMODE</dt><dd><p>Toolchain selector. It can be external toolchain
2185 built from Poky or few supported combinations of
2186 upstream GCC or CodeSourcery Labs toolchain.</p></dd></dl></div><div class="glossdiv"><h3 class="title">R</h3><dl><dt><a name="var-RCONFLICTS"></a>RCONFLICTS</dt><dd><p>List of packages which which conflict with this
2187 one. Package will not be installed if they will not
2188 be removed first.</p></dd><dt><a name="var-RDEPENDS"></a>RDEPENDS</dt><dd><p>
2189 A list of run-time dependencies for a package. These packages
2190 need to be installed alongside the package it applies to so
2191 the package will run correctly, an example is a perl script
2192 which would rdepend on perl. Since this variable applies to
2193 output packages there would usually be an override attached
2194 to this variable like RDEPENDS_${PN}-dev. Names in this field
2195 should be as they are in <a href="#var-PACKAGES" title="PACKAGES">PACKAGES
2196 </a> namespave before any renaming of the output package
2197 by classes like debian.bbclass.
2198 </p></dd><dt><a name="var-ROOT_FLASH_SIZE"></a>ROOT_FLASH_SIZE</dt><dd><p>Size of rootfs in megabytes</p></dd><dt><a name="var-RRECOMMENDS"></a>RRECOMMENDS</dt><dd><p>List of packages which extend usability of
2199 package. Those packages will be automatically
2200 installed but can be removed by user.</p></dd><dt><a name="var-RREPLACES"></a>RREPLACES</dt><dd><p>List of packages which are replaced with this
2201 one.</p></dd></dl></div><div class="glossdiv"><h3 class="title">S</h3><dl><dt><a name="var-S"></a>S</dt><dd><p>
2202 Path to unpacked sources (by default:
2203 "${<a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a>}/${<a href="#var-PN" title="PN">PN</a>}-${<a href="#var-PV" title="PV">PV</a>}")
2204 </p></dd><dt><a name="var-SECTION"></a>SECTION</dt><dd><p>Section where package should be put - used
2205 by package managers</p></dd><dt><a name="var-SELECTED_OPTIMIZATION"></a>SELECTED_OPTIMIZATION</dt><dd><p>
2206 The variable takes the value of <a href="#var-FULL_OPTIMIZATION" title="FULL_OPTIMIZATION">FULL_OPTIMIZATION</a>
2207 unless <a href="#var-DEBUG_BUILD" title="DEBUG_BUILD">DEBUG_BUILD</a> = "1" in which case
2208 <a href="#var-DEBUG_OPTIMIZATION" title="DEBUG_OPTIMIZATION">DEBUG_OPTIMIZATION</a> is used.
2209 </p></dd><dt><a name="var-SERIAL_CONSOLE"></a>SERIAL_CONSOLE</dt><dd><p>Speed and device for serial port used to attach
2210 serial console. This is given to kernel as "console"
2211 param and after boot getty is started on that port
2212 so remote login is possible.</p></dd><dt><a name="var-SHELLCMDS"></a>SHELLCMDS</dt><dd><p>
2213 A list of commands to run within the a shell, used by <em class="glossterm"><a href="#var-TERMCMDRUN" title="TERMCMDRUN">TERMCMDRUN</a></em>. It defaults to
2214 <em class="glossterm"><a href="#var-SHELLRCCMD" title="SHELLRCCMD">SHELLRCCMD</a></em>.
2215 </p></dd><dt><a name="var-SHELLRCCMD"></a>SHELLRCCMD</dt><dd><p>
2216 How to launch a shell, defaults to bash.
2217 </p></dd><dt><a name="var-SITEINFO_ENDIANESS"></a>SITEINFO_ENDIANESS</dt><dd><p>
2218 Contains "le" for little-endian or "be" for big-endian depending
2219 on the endian byte order of the target system.
2220 </p></dd><dt><a name="var-SITEINFO_BITS"></a>SITEINFO_BITS</dt><dd><p>
2221 Contains "32" or "64" depending on the number of bits for the
2222 CPU of the target system.
2223 </p></dd><dt><a name="var-SRC_URI"></a>SRC_URI</dt><dd><p>List of source files (local or remote ones)</p></dd><dt><a name="var-SRC_URI_OVERRIDES_PACKAGE_ARCH"></a>SRC_URI_OVERRIDES_PACKAGE_ARCH</dt><dd><p>
2224 By default there is code which automatically detects whether
2225 <em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em>
2226 contains files which are machine specific and if this is the case it
2227 automatically changes
2228 <em class="glossterm"><a href="#var-PACKAGE_ARCH" title="PACKAGE_ARCH">PACKAGE_ARCH</a></em>.
2229 Setting this variable to "0" disables that behaviour.
2230 </p></dd><dt><a name="var-SRCDATE"></a>SRCDATE</dt><dd><p>
2231 Date of source code used to build package (if it was fetched
2232 from SCM).
2233 </p></dd><dt><a name="var-SRCREV"></a>SRCREV</dt><dd><p>
2234 Revision of source code used to build package (Subversion,
2235 GIT, Bazaar only).
2236 </p></dd><dt><a name="var-STAGING_KERNEL_DIR"></a>STAGING_KERNEL_DIR</dt><dd><p>
2237 Directory with kernel headers required to build out-of-tree
2238 modules.
2239 </p></dd><dt><a name="var-STAMPS"></a>STAMPS</dt><dd><p>
2240 Directory (usually TMPDIR/stamps) with timestamps of
2241 executed tasks.
2242 </p></dd></dl></div><div class="glossdiv"><h3 class="title">T</h3><dl><dt><a name="var-TARGET_ARCH"></a>TARGET_ARCH</dt><dd><p>The architecture of the device we're building for.
2243 A number of values are possible but Poky primarily supports
2244 "arm" and "i586".</p></dd><dt><a name="var-TARGET_CFLAGS"></a>TARGET_CFLAGS</dt><dd><p>
2245 Flags passed to C compiler for the target system. Evaluates to the same
2246 as <a href="#var-CFLAGS" title="CFLAGS">CFLAGS</a>.
2247 </p></dd><dt><a name="var-TARGET_FPU"></a>TARGET_FPU</dt><dd><p>Method of handling FPU code. For FPU-less targets
2248 (most of ARM cpus) it has to be set to "soft" otherwise
2249 kernel emulation will get used which will result in
2250 performance penalty.</p></dd><dt><a name="var-TARGET_OS"></a>TARGET_OS</dt><dd><p>Type of target operating system. Can be "linux"
2251 for glibc based system, "linux-uclibc" for uClibc. For
2252 ARM/EABI targets there are also "linux-gnueabi" and
2253 "linux-uclibc-gnueabi" values possible.</p></dd><dt><a name="var-TERMCMD"></a>TERMCMD</dt><dd><p>
2254 This command is used by bitbake to lauch a terminal window with a
2255 shell. The shell is unspecified so the user's default shell is used.
2256 By default it is set to <span><strong class="command">gnome-terminal</strong></span> but it can
2257 be any X11 terminal application or terminal multiplexers like screen.
2258 </p></dd><dt><a name="var-TERMCMDRUN"></a>TERMCMDRUN</dt><dd><p>
2259 This command is similar to <em class="glossterm"><a href="#var-TERMCMD" title="TERMCMD">TERMCMD</a></em> however instead of the users shell it runs the command specified by the <em class="glossterm"><a href="#var-SHELLCMDS" title="SHELLCMDS">SHELLCMDS</a></em> variable.
2260 </p></dd></dl></div><div class="glossdiv"><h3 class="title">W</h3><dl><dt><a name="var-WORKDIR"></a>WORKDIR</dt><dd><p>Path to directory in tmp/work/ where package
2261 will be built.</p></dd></dl></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="ref-varlocality"></a>Appendix 7. Reference: Variable Locality (Distro, Machine, Recipe etc.)</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#ref-varlocality-config-distro">1. Distro Configuration</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-machine">2. Machine Configuration</a></span></dt><dt><span class="section"><a href="#ref-varlocality-config-local">3. Local Configuration (local.conf)</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-required">4. Recipe Variables - Required</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-dependencies">5. Recipe Variables - Dependencies</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-paths">6. Recipe Variables - Paths</a></span></dt><dt><span class="section"><a href="#ref-varlocality-recipe-build">7. Recipe Variables - Extra Build Information</a></span></dt></dl></div><p>
2262 Whilst most variables can be used in almost any context (.conf, .bbclass,
2263 .inc or .bb file), variables are often associated with a particular
2264 locality/context. This section describes some common associations.
2265 </p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-config-distro"></a>1. Distro Configuration</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="#var-DISTRO"><em class="glossterm"><a href="#var-DISTRO" title="DISTRO">DISTRO</a></em></a></p></li><li><p><a href="#var-DISTRO_NAME"><em class="glossterm"><a href="#var-DISTRO_NAME" title="DISTRO_NAME">DISTRO_NAME</a></em></a></p></li><li><p><a href="#var-DISTRO_VERSION"><em class="glossterm"><a href="#var-DISTRO_VERSION" title="DISTRO_VERSION">DISTRO_VERSION</a></em></a></p></li><li><p><a href="#var-MAINTAINER"><em class="glossterm"><a href="#var-MAINTAINER" title="MAINTAINER">MAINTAINER</a></em></a></p></li><li><p><a href="#var-PACKAGE_CLASSES"><em class="glossterm"><a href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></em></a></p></li><li><p><a href="#var-TARGET_OS"><em class="glossterm"><a href="#var-TARGET_OS" title="TARGET_OS">TARGET_OS</a></em></a></p></li><li><p><a href="#var-TARGET_FPU"><em class="glossterm"><a href="#var-TARGET_FPU" title="TARGET_FPU">TARGET_FPU</a></em></a></p></li><li><p><a href="#var-POKYMODE"><em class="glossterm"><a href="#var-POKYMODE" title="POKYMODE">POKYMODE</a></em></a></p></li><li><p><a href="#var-POKYLIBC"><em class="glossterm"><a href="#var-POKYLIBC" title="POKYLIBC">POKYLIBC</a></em></a></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-config-machine"></a>2. Machine Configuration</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="#var-TARGET_ARCH"><em class="glossterm"><a href="#var-TARGET_ARCH" title="TARGET_ARCH">TARGET_ARCH</a></em></a></p></li><li><p><a href="#var-SERIAL_CONSOLE"><em class="glossterm"><a href="#var-SERIAL_CONSOLE" title="SERIAL_CONSOLE">SERIAL_CONSOLE</a></em></a></p></li><li><p><a href="#var-PACKAGE_EXTRA_ARCHS"><em class="glossterm"><a href="#var-PACKAGE_EXTRA_ARCHS" title="PACKAGE_EXTRA_ARCHS">PACKAGE_EXTRA_ARCHS</a></em></a></p></li><li><p><a href="#var-IMAGE_FSTYPES"><em class="glossterm"><a href="#var-IMAGE_FSTYPES" title="IMAGE_FSTYPES">IMAGE_FSTYPES</a></em></a></p></li><li><p><a href="#var-ROOT_FLASH_SIZE"><em class="glossterm"><a href="#var-ROOT_FLASH_SIZE" title="ROOT_FLASH_SIZE">ROOT_FLASH_SIZE</a></em></a></p></li><li><p><a href="#var-MACHINE_FEATURES"><em class="glossterm"><a href="#var-MACHINE_FEATURES" title="MACHINE_FEATURES">MACHINE_FEATURES</a></em></a></p></li><li><p><a href="#var-MACHINE_EXTRA_RDEPENDS"><em class="glossterm"><a href="#var-MACHINE_EXTRA_RDEPENDS" title="MACHINE_EXTRA_RDEPENDS">MACHINE_EXTRA_RDEPENDS</a></em></a></p></li><li><p><a href="#var-MACHINE_EXTRA_RRECOMMENDS"><em class="glossterm"><a href="#var-MACHINE_EXTRA_RRECOMMENDS" title="MACHINE_EXTRA_RRECOMMNEDS">MACHINE_EXTRA_RRECOMMENDS</a></em></a></p></li><li><p><a href="#var-MACHINE_ESSENTIAL_RDEPENDS"><em class="glossterm"><a href="#var-MACHINE_ESSENTIAL_RDEPENDS" title="MACHINE_ESSENTIAL_RDEPENDS">MACHINE_ESSENTIAL_RDEPENDS</a></em></a></p></li><li><p><a href="#var-MACHINE_ESSENTIAL_RRECOMMENDS"><em class="glossterm"><a href="#var-MACHINE_ESSENTIAL_RRECOMMENDS" title="MACHINE_ESSENTIAL_RRECOOMENDS">MACHINE_ESSENTIAL_RRECOMMENDS</a></em></a></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-config-local"></a>3. Local Configuration (local.conf)</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><a href="#var-DISTRO"><em class="glossterm"><a href="#var-DISTRO" title="DISTRO">DISTRO</a></em></a></p></li><li><p><a href="#var-MACHINE"><em class="glossterm"><a href="#var-MACHINE" title="MACHINE">MACHINE</a></em></a></p></li><li><p><a href="#var-DL_DIR"><em class="glossterm"><a href="#var-DL_DIR" title="DL_DIR">DL_DIR</a></em></a></p></li><li><p><a href="#var-BBFILES"><em class="glossterm"><a href="#var-BBFILES" title="BBFILES">BBFILES</a></em></a></p></li><li><p><a href="#var-IMAGE_FEATURES"><em class="glossterm"><a href="#var-IMAGE_FEATURES" title="IMAGE_FEATURES">IMAGE_FEATURES</a></em></a></p></li><li><p><a href="#var-PACKAGE_CLASSES"><em class="glossterm"><a href="#var-PACKAGE_CLASSES" title="PACKAGE_CLASSES">PACKAGE_CLASSES</a></em></a></p></li><li><p><a href="#var-BB_NUMBER_THREADS"><em class="glossterm"><a href="#var-BB_NUMBER_THREADS" title="BB_NUMBER_THREADS">BB_NUMBER_THREADS</a></em></a></p></li><li><p><a href="#var-BBINCLUDELOGS"><em class="glossterm"><a href="#var-BBINCLUDELOGS" title="BBINCLUDELOGS">BBINCLUDELOGS</a></em></a></p></li><li><p><a href="#var-CVS_TARBALL_STASH"><em class="glossterm"><a href="#var-CVS_TARBALL_STASH" title="CVS_TARBALL_STASH">CVS_TARBALL_STASH</a></em></a></p></li><li><p><a href="#var-ENABLE_BINARY_LOCALE_GENERATION"><em class="glossterm"><a href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">ENABLE_BINARY_LOCALE_GENERATION</a></em></a></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-recipe-required"></a>4. Recipe Variables - Required</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><em class="glossterm"><a href="#var-DESCRIPTION" title="DESCRIPTION">DESCRIPTION</a></em></p></li><li><p><em class="glossterm"><a href="#var-LICENSE" title="LICENSE">LICENSE</a></em></p></li><li><p><em class="glossterm"><a href="#var-SECTION" title="SECTION">SECTION</a></em></p></li><li><p><em class="glossterm"><a href="#var-HOMEPAGE" title="HOMEPAGE">HOMEPAGE</a></em></p></li><li><p><em class="glossterm"><a href="#var-AUTHOR" title="AUTHOR">AUTHOR</a></em></p></li><li><p><em class="glossterm"><a href="#var-SRC_URI" title="SRC_URI">SRC_URI</a></em></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-recipe-dependencies"></a>5. Recipe Variables - Dependencies</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><em class="glossterm"><a href="#var-DEPENDS" title="DEPENDS">DEPENDS</a></em></p></li><li><p><em class="glossterm"><a href="#var-RDEPENDS" title="RDEPENDS">RDEPENDS</a></em></p></li><li><p><em class="glossterm"><a href="#var-RRECOMMENDS" title="RRECOMMENDS">RRECOMMENDS</a></em></p></li><li><p><em class="glossterm"><a href="#var-RCONFLICTS" title="RCONFLICTS">RCONFLICTS</a></em></p></li><li><p><em class="glossterm"><a href="#var-RREPLACES" title="RREPLACES">RREPLACES</a></em></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-recipe-paths"></a>6. Recipe Variables - Paths</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><em class="glossterm"><a href="#var-WORKDIR" title="WORKDIR">WORKDIR</a></em></p></li><li><p><em class="glossterm"><a href="#var-S" title="S">S</a></em></p></li><li><p><em class="glossterm"><a href="#var-FILES" title="FILES">FILES</a></em></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref-varlocality-recipe-build"></a>7. Recipe Variables - Extra Build Information</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><em class="glossterm"><a href="#var-EXTRA_OECONF" title="EXTRA_OECONF">EXTRA_OECONF</a></em></p></li><li><p><em class="glossterm"><a href="#var-EXTRA_OEMAKE" title="EXTRA_OEMAKE">EXTRA_OEMAKE</a></em></p></li><li><p><em class="glossterm"><a href="#var-PACKAGES" title="PACKAGES">PACKAGES</a></em></p></li><li><p><em class="glossterm"><a href="#var-DEFAULT_PREFERENCE" title="DEFAULT_PREFERENCE">DEFAULT_PREFERENCE</a></em></p></li></ul></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="faq"></a>Appendix 8. FAQ</h2></div></div></div><div class="qandaset"><dl><dt>8.1. <a href="#id1089074">
2266 How does Poky differ from OpenEmbedded?
2267 </a></dt><dt>8.2. <a href="#id1089095">
2268 How can you claim Poky is stable?
2269 </a></dt><dt>8.3. <a href="#id1089122">
2270 How do I get support for my board added to Poky?
2271 </a></dt><dt>8.4. <a href="#id1089143">
2272 Are there any products running poky ?
2273 </a></dt><dt>8.5. <a href="#id1089157">
2274 What is the Poky output ?
2275 </a></dt><dt>8.6. <a href="#id1089167">
2276 How do I add my package to Poky?
2277 </a></dt><dt>8.7. <a href="#id1089176">
2278 Do I have to reflash my entire board with a new poky image when recompiling a package?
2279 </a></dt><dt>8.8. <a href="#id1089187">
2280 What is GNOME Mobile? What's the difference between GNOME Mobile and GNOME?
2281 </a></dt><dt>8.9. <a href="#id1089203">
2282 How do I make Poky work in RHEL/CentOS?
2283 </a></dt><dt>8.10. <a href="#id1089270">
2284 I see lots of 404 responses for files on http://folks.o-hand.com/~richard/poky/sources/*. Is something wrong?
2285 </a></dt><dt>8.11. <a href="#id1089285">
2286 I have a machine specific data in a package for one machine only but the package is
2287 being marked as machine specific in all cases, how do I stop it?
2288 </a></dt></dl><table border="0" summary="Q and A Set"><col align="left" width="1%"><tbody><tr class="question"><td align="left" valign="top"><a name="id1089074"></a><a name="id1089075"></a><b>8.1.</b></td><td align="left" valign="top"><p>
2289 How does Poky differ from <a href="http://www.openembedded.org/" target="_top">OpenEmbedded</a>?
2290 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2291 Poky is a derivative of <a href="http://www.openembedded.org/" target="_top">OpenEmbedded</a>, a stable,
2292 smaller subset focused on the GNOME Mobile environment. Development
2293 in Poky is closely tied to OpenEmbedded with features being merged
2294 regularly between the two for mutual benefit.
2295 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089095"></a><a name="id1089096"></a><b>8.2.</b></td><td align="left" valign="top"><p>
2296 How can you claim Poky is stable?
2297 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2298 There are three areas that help with stability;
2299
2300 </p><div class="itemizedlist"><ul type="disc"><li><p>
2301 We keep Poky small and focused - around 650 packages compared to over 5000 for full OE
2302 </p></li><li><p>
2303 We only support hardware that we have access to for testing
2304 </p></li><li><p>
2305 We have a Buildbot which provides continuous build and integration tests
2306 </p></li></ul></div><p>
2307 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089122"></a><a name="id1089123"></a><b>8.3.</b></td><td align="left" valign="top"><p>
2308 How do I get support for my board added to Poky?
2309 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2310 There are two main ways to get a board supported in Poky;
2311 </p><div class="itemizedlist"><ul type="disc"><li><p>
2312 Send us the board if we don't have it yet
2313 </p></li><li><p>
2314 Send us bitbake recipes if you have them (see the Poky handbook to find out how to create recipes)
2315 </p></li></ul></div><p>
2316 Usually if it's not a completely exotic board then adding support in Poky should be fairly straightforward.
2317 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089143"></a><a name="id1089144"></a><b>8.4.</b></td><td align="left" valign="top"><p>
2318 Are there any products running poky ?
2319 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2320 The <a href="http://vernier.com/labquest/" target="_top">Vernier Labquest</a> is using Poky (for more about the Labquest see the case study at OpenedHand). There are a number of pre-production devices using Poky and we will announce those as soon as they are released.
2321 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089157"></a><a name="id1089158"></a><b>8.5.</b></td><td align="left" valign="top"><p>
2322 What is the Poky output ?
2323 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2324 The output of a Poky build will depend on how it was started, as the same set of recipes can be used to output various formats. Usually the output is a flashable image ready for the target device.
2325 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089167"></a><a name="id1089168"></a><b>8.6.</b></td><td align="left" valign="top"><p>
2326 How do I add my package to Poky?
2327 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2328 To add a package you need to create a bitbake recipe - see the Poky handbook to find out how to create a recipe.
2329 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089176"></a><a name="id1089177"></a><b>8.7.</b></td><td align="left" valign="top"><p>
2330 Do I have to reflash my entire board with a new poky image when recompiling a package?
2331 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2332 Poky can build packages in various formats, ipkg, Debian package, or RPM. The package can then be upgraded using the package tools on the device, much like on a desktop distribution like Ubuntu or Fedora.
2333 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089187"></a><a name="id1089188"></a><b>8.8.</b></td><td align="left" valign="top"><p>
2334 What is GNOME Mobile? What's the difference between GNOME Mobile and GNOME?
2335 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2336 <a href="http://www.gnome.org/mobile/" target="_top">GNOME Mobile</a> is a subset of the GNOME platform targeted at mobile and embedded devices. The the main difference between GNOME Mobile and standard GNOME is that desktop-orientated libraries have been removed, along with deprecated libraries, creating a much smaller footprint.
2337 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089203"></a><a name="id1089204"></a><b>8.9.</b></td><td align="left" valign="top"><p>
2338 How do I make Poky work in RHEL/CentOS?
2339 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2340 To get Poky working under RHEL/CentOS 5.1 you need to first install some required packages. The standard CentOS packages needed are:
2341 </p><div class="itemizedlist"><ul type="disc"><li><p>
2342 "Development tools" (selected during installation)
2343 </p></li><li><p>
2344 texi2html
2345 </p></li><li><p>
2346 compat-gcc-34
2347 </p></li></ul></div><p>
2348 </p><p>
2349 On top of those the following external packages are needed:
2350 </p><div class="itemizedlist"><ul type="disc"><li><p>
2351 python-sqlite2 from <a href="http://dag.wieers.com/rpm/packages/python-sqlite2/" target="_top">DAG
2352 repository</a>
2353 </p></li><li><p>
2354 help2man from <a href="http://centos.karan.org/el5/extras/testing/i386/RPMS/help2man-1.33.1-2.noarch.rpm" target="_top">Karan
2355 repository</a>
2356 </p></li></ul></div><p>
2357 </p><p>
2358 Once these packages are installed Poky will be able to build standard images however there
2359 may be a problem with QEMU segfaulting. You can either disable the generation of binary
2360 locales by setting <em class="glossterm"><a href="#var-ENABLE_BINARY_LOCALE_GENERATION" title="ENABLE_BINARY_LOCALE_GENERATION">ENABLE_BINARY_LOCALE_GENERATION</a>
2361 </em> to "0" or remove the linux-2.6-execshield.patch from the kernel and rebuild
2362 it since its that patch which causes the problems with QEMU.
2363 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089270"></a><a name="id1089271"></a><b>8.10.</b></td><td align="left" valign="top"><p>
2364 I see lots of 404 responses for files on http://folks.o-hand.com/~richard/poky/sources/*. Is something wrong?
2365 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2366 Nothing is wrong, Poky will check any configured source mirrors before downloading
2367 from the upstream sources. It does this searching for both source archives and
2368 pre-checked out versions of SCM managed software. This is so in large installations,
2369 it can reduce load on the SCM servers themselves. The address above is one of the
2370 default mirrors configured into standard Poky so if an upstream source disappears,
2371 we can place sources there so builds continue to work.
2372 </p></td></tr><tr class="question"><td align="left" valign="top"><a name="id1089285"></a><a name="id1089286"></a><b>8.11.</b></td><td align="left" valign="top"><p>
2373 I have a machine specific data in a package for one machine only but the package is
2374 being marked as machine specific in all cases, how do I stop it?
2375 </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>
2376 Set <em class="glossterm"><a href="#var-SRC_URI_OVERRIDES_PACKAGE_ARCH" title="SRC_URI_OVERRIDES_PACKAGE_ARCH">SRC_URI_OVERRIDES_PACKAGE_ARCH</a>
2377 </em> = "0" in the .bb file but make sure the package is manually marked as
2378 machine specific in the case that needs it. The code which handles <em class="glossterm"><a href="#var-SRC_URI_OVERRIDES_PACKAGE_ARCH" title="SRC_URI_OVERRIDES_PACKAGE_ARCH">SRC_URI_OVERRIDES_PACKAGE_ARCH</a></em>
2379 is in base.bbclass.
2380 </p></td></tr></tbody></table></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="resources"></a>Appendix 9. Contributing to Poky</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#resources-intro">1. Introduction</a></span></dt><dt><span class="section"><a href="#resources-bugtracker">2. Bugtracker</a></span></dt><dt><span class="section"><a href="#resources-mailinglist">3. Mailing list</a></span></dt><dt><span class="section"><a href="#resources-irc">4. IRC</a></span></dt><dt><span class="section"><a href="#resources-links">5. Links</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-intro"></a>1. Introduction</h2></div></div></div><p>
2381 We're happy for people to experiment with Poky and there are a number of places to
2382 find help if you run into difficulties or find bugs. To find out how to download
2383 source code see the <a href="#intro-getit" title="5. Obtaining Poky">Obtaining Poky</a> section of
2384 the Introduction.
2385 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-bugtracker"></a>2. Bugtracker</h2></div></div></div><p>
2386 Problems with Poky should be reported in the
2387 <a href="http://bugzilla.o-hand.com/" target="_top">bug tracker</a>.
2388 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-mailinglist"></a>3. Mailing list</h2></div></div></div><p>
2389 To subscribe to the mailing list send mail to:
2390 </p><p>
2391 </p><pre class="literallayout">
2392poky+subscribe &lt;at&gt; openedhand &lt;dot&gt; com
2393 </pre><p>
2394 </p><p>
2395 Then follow the simple instructions in subsequent reply. Archives are
2396 available <a href="http://lists.o-hand.com/poky/" target="_top">here</a>.
2397 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-irc"></a>4. IRC</h2></div></div></div><p>
2398 Join #poky on freenode.
2399 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources-links"></a>5. Links</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p>
2400 <a href="http://pokylinux.org" target="_top">The Poky website</a>
2401 </p></li><li><p>
2402 <a href="http://www.openedhand.com/" target="_top">OpenedHand</a> - The
2403 company behind Poky.
2404 </p></li><li><p>
2405 <a href="http://www.openembedded.org/" target="_top">OpenEmbedded</a>
2406 - The upstream generic embedded distribution Poky derives
2407 from (and contributes to).
2408 </p></li><li><p>
2409 <a href="http://developer.berlios.de/projects/bitbake/" target="_top">Bitbake</a>
2410 - The tool used to process Poky metadata.
2411 </p></li><li><p>
2412 <a href="http://bitbake.berlios.de/manual/" target="_top">Bitbake User
2413 Manual</a>
2414 </p></li><li><p>
2415 <a href="http://pimlico-project.org/" target="_top">Pimlico</a> - A
2416 suite of lightweight Personal Information Management (PIM)
2417 applications designed primarily for handheld and mobile
2418 devices.
2419 </p></li><li><p>
2420 <a href="http://fabrice.bellard.free.fr/qemu/" target="_top">QEMU</a>
2421 - An open source machine emulator and virtualizer.
2422 </p></li></ul></div></div></div><div class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="contact"></a>Appendix 10. OpenedHand Contact Information</h2></div></div></div><div class="literallayout"><p><br>
2423OpenedHand Ltd<br>
2424Unit R, Homesdale Business Center<br>
2425216-218 Homesdale Rd<br>
2426Bromley, BR1 2QZ<br>
2427England<br>
2428+44 (0) 208 819 6559<br>
2429info@openedhand.com</p></div></div><div class="index"><div class="titlepage"><div><div><h2 class="title"><a name="index"></a>Index</h2></div></div></div><div class="index"></div></div></div></body></html>
diff --git a/handbook/poky-handbook.png b/handbook/poky-handbook.png
new file mode 100644
index 0000000000..333442e0d6
--- /dev/null
+++ b/handbook/poky-handbook.png
Binary files differ
diff --git a/handbook/poky-handbook.xml b/handbook/poky-handbook.xml
new file mode 100644
index 0000000000..c0c87cb0c0
--- /dev/null
+++ b/handbook/poky-handbook.xml
@@ -0,0 +1,111 @@
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<book id='poky-handbook' lang='en'
5 xmlns:xi="http://www.w3.org/2003/XInclude"
6 xmlns="http://docbook.org/ns/docbook"
7 >
8 <bookinfo>
9
10 <mediaobject>
11 <imageobject>
12 <imagedata fileref='common/poky-handbook.png'
13 format='SVG'
14 align='center'/>
15 </imageobject>
16 </mediaobject>
17
18 <title>Poky Handbook</title>
19 <subtitle>Hitchhiker's Guide to Poky</subtitle>
20
21 <authorgroup>
22 <author>
23 <firstname>Richard</firstname> <surname>Purdie</surname>
24 <affiliation>
25 <orgname>OpenedHand Ltd</orgname>
26 </affiliation>
27 <email>richard@openedhand.com</email>
28 </author>
29
30 <author>
31 <firstname>Tomas</firstname> <surname>Frydrych</surname>
32 <affiliation>
33 <orgname>OpenedHand Ltd</orgname>
34 </affiliation>
35 <email>tf@openedhand.com</email>
36 </author>
37
38 <author>
39 <firstname>Marcin</firstname> <surname>Juszkiewicz</surname>
40 <affiliation>
41 <orgname>OpenedHand Ltd</orgname>
42 </affiliation>
43 <email>hrw@openedhand.com</email>
44 </author>
45 <author>
46 <firstname>Dodji</firstname> <surname>Seketeli</surname>
47 <affiliation>
48 <orgname>OpenedHand Ltd</orgname>
49 </affiliation>
50 <email>dodji@openedhand.com</email>
51 </author>
52 </authorgroup>
53
54 <revhistory>
55 <revision>
56 <revnumber>3.1</revnumber>
57 <date>15 Feburary 2008</date>
58 <revremark>Poky 3.1 (Pinky) Documentation Release</revremark>
59 </revision>
60 </revhistory>
61
62 <copyright>
63 <year>2007</year>
64 <holder>OpenedHand Limited</holder>
65 </copyright>
66
67 <legalnotice>
68 <para>
69 Permission is granted to copy, distribute and/or modify this document under
70 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/">Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
71 </para>
72 </legalnotice>
73
74 </bookinfo>
75
76 <xi:include href="introduction.xml"/>
77
78 <xi:include href="usingpoky.xml"/>
79
80 <xi:include href="extendpoky.xml"/>
81
82 <xi:include href="development.xml"/>
83
84 <xi:include href="ref-structure.xml"/>
85
86 <xi:include href="ref-bitbake.xml"/>
87
88 <xi:include href="ref-classes.xml"/>
89
90 <xi:include href="ref-images.xml"/>
91
92 <xi:include href="ref-features.xml"/>
93
94 <xi:include href="ref-variables.xml"/>
95
96 <xi:include href="ref-varlocality.xml"/>
97
98 <xi:include href="faq.xml"/>
99
100 <xi:include href="resources.xml"/>
101
102 <xi:include href="contactus.xml"/>
103
104 <index id='index'>
105 <title>Index</title>
106 </index>
107
108</book>
109<!--
110vim: expandtab tw=80 ts=4
111-->
diff --git a/handbook/poky-logo.svg b/handbook/poky-logo.svg
new file mode 100644
index 0000000000..d0be402870
--- /dev/null
+++ b/handbook/poky-logo.svg
@@ -0,0 +1,117 @@
1<?xml version="1.0" encoding="utf-8"?>
2<!-- Generator: Adobe Illustrator 13.0.0, SVG Export Plug-In -->
3<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd" [
4 <!ENTITY ns_flows "http://ns.adobe.com/Flows/1.0/">
5]>
6<svg version="1.1"
7 xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/"
8 x="0px" y="0px" width="300px" height="300px" viewBox="-40.981 -92.592 300 300" enable-background="new -40.981 -92.592 300 300"
9 xml:space="preserve">
10<defs>
11</defs>
12<path fill="#6AC7BD" d="M48.96,48.476v0.003h0.001v-0.061C48.962,48.438,48.96,48.457,48.96,48.476z"/>
13<g opacity="0.65">
14 <g>
15 <path fill="#EF412A" d="M24.482,23.998v-0.003C10.961,23.994,0,34.955,0,48.476l0.001,0.003v0.003
16 C0.003,62.001,10.962,72.96,24.482,72.96l0,0H0v24.482h0.003c13.52-0.002,24.479-10.962,24.479-24.481h0.003
17 C38.005,72.959,48.963,62,48.963,48.479v-0.003C48.962,34.957,38.001,23.998,24.482,23.998z M24.482,50.928
18 c-1.352,0-2.448-1.096-2.448-2.448s1.096-2.448,2.448-2.448s2.448,1.096,2.448,2.448S25.834,50.928,24.482,50.928z"/>
19 </g>
20</g>
21<g opacity="0.65">
22 <g>
23 <path fill="#A9C542" d="M119.96,48.842c0.064-1.294,1.126-2.326,2.437-2.326c1.31,0,2.371,1.032,2.436,2.327
24 c12.378-1.223,22.046-11.662,22.046-24.36h-24.482C122.396,10.961,111.435,0,97.915,0v24.485
25 C97.917,37.183,107.584,47.619,119.96,48.842z M124.833,49.084c-0.064,1.295-1.126,2.327-2.436,2.327h-0.001v22.033h24.482v-0.003
26 C146.876,60.745,137.208,50.308,124.833,49.084z M119.949,48.963H97.915v24.479h0c12.698,0,23.137-9.668,24.36-22.043
27 C120.981,51.334,119.949,50.274,119.949,48.963z"/>
28 </g>
29</g>
30<g opacity="0.65">
31 <g>
32 <path fill="#F9C759" d="M168.912,48.967c0-1.311,1.033-2.371,2.328-2.436c-1.222-12.379-11.661-22.049-24.361-22.049v24.481
33 c0,13.521,10.961,24.481,24.482,24.481v-22.03C170.007,51.415,168.912,50.319,168.912,48.967z M195.841,48.978
34 c0-0.005,0.001-0.009,0.001-0.014V24.482h-0.004c-12.698,0.002-23.136,9.672-24.356,22.049c1.294,0.064,2.326,1.125,2.326,2.436
35 s-1.032,2.372-2.327,2.436c1.198,12.187,11.333,21.743,23.763,22.042h-23.883v24.482h0.003
36 c13.515-0.002,24.47-10.954,24.478-24.467h0.002V48.979L195.841,48.978z M195.832,48.964h0.01v0.014L195.832,48.964z"/>
37 </g>
38</g>
39<g opacity="0.65">
40 <g>
41 <path fill="#6AC7BD" d="M70.994,48.479H48.962v0.002h22.033C70.995,48.481,70.994,48.48,70.994,48.479z M73.44,24.001h-0.003
42 v22.031c0.002,0,0.003,0,0.005,0c1.352,0,2.448,1.096,2.448,2.448s-1.096,2.448-2.448,2.448c-1.351,0-2.446-1.094-2.448-2.445
43 H48.958v0.003c0.002,13.519,10.961,24.478,24.479,24.478s24.477-10.959,24.479-24.478v-0.003
44 C97.916,34.963,86.958,24.003,73.44,24.001z"/>
45 </g>
46</g>
47<g opacity="0.65">
48 <g>
49 <path fill="#EF412A" d="M24.482,23.998v-0.003C10.961,23.994,0,34.955,0,48.476h22.034c0.002-1.351,1.097-2.445,2.448-2.445
50 c1.352,0,2.448,1.096,2.448,2.448s-1.096,2.448-2.448,2.448v22.01C24.469,59.427,13.514,48.479,0,48.479V72.96h24.481l0,0H0
51 v24.482h0.003c13.52-0.002,24.479-10.962,24.479-24.481h0.003C38.005,72.959,48.963,62,48.963,48.479v-0.003
52 C48.962,34.957,38.001,23.998,24.482,23.998z"/>
53 </g>
54</g>
55<g opacity="0.65">
56 <g>
57 <path fill="#A9C542" d="M122.397,46.516c1.31,0,2.371,1.032,2.436,2.327c12.378-1.223,22.046-11.662,22.046-24.36h-24.482
58 L122.397,46.516L122.397,46.516z M97.915,0v24.482h24.481C122.396,10.961,111.435,0,97.915,0z M122.275,46.528
59 c-1.223-12.377-11.662-22.046-24.361-22.046v24.482h0v24.479h0c12.698,0,23.137-9.668,24.36-22.043
60 c-1.294-0.065-2.326-1.125-2.326-2.436C119.949,47.653,120.98,46.593,122.275,46.528z M124.833,49.084
61 c-0.064,1.295-1.126,2.327-2.436,2.327h-0.001v22.033h24.482v-0.003C146.876,60.745,137.208,50.308,124.833,49.084z"/>
62 </g>
63</g>
64<g opacity="0.65">
65 <g>
66 <path fill="#F9C759" d="M173.795,49.1c-0.071,1.289-1.129,2.315-2.435,2.315c-1.354,0-2.449-1.096-2.449-2.448
67 c0-1.311,1.033-2.371,2.328-2.436c-1.222-12.379-11.661-22.049-24.361-22.049v24.481c0,13.521,10.961,24.481,24.482,24.481v24.482
68 h0.003c13.515-0.002,24.47-10.954,24.478-24.467h0.001v-0.016h-0.001C195.833,60.753,186.167,50.322,173.795,49.1z
69 M195.838,24.482c-12.698,0.002-23.136,9.672-24.356,22.049c1.293,0.064,2.324,1.124,2.326,2.433h22.033v0.015
70 c0-0.005,0.001-0.01,0.001-0.015V24.482H195.838z"/>
71 </g>
72</g>
73<g opacity="0.65">
74 <g>
75 <path fill="#6AC7BD" d="M71.007,48.347c0.068-1.242,1.055-2.23,2.297-2.301c-0.795-8.026-5.454-14.913-12.103-18.762
76 C57.601,25.2,53.424,24,48.965,24h-0.003c0,4.46,1.199,8.638,3.283,12.24C56.093,42.891,62.98,47.552,71.007,48.347z
77 M48.962,48.418c0,0.02-0.001,0.038-0.001,0.058v0.003h0.001V48.418z M70.995,48.482c0-0.001,0-0.001,0-0.002H48.962v0.002H70.995
78 z M73.44,24.001h-0.003v22.031c0.002,0,0.003,0,0.005,0c1.352,0,2.448,1.096,2.448,2.448s-1.096,2.448-2.448,2.448
79 c-1.351,0-2.446-1.094-2.448-2.445H48.958v0.003c0.002,13.519,10.961,24.478,24.479,24.478s24.477-10.959,24.479-24.478v-0.003
80 C97.916,34.963,86.958,24.003,73.44,24.001z"/>
81 </g>
82</g>
83<g opacity="0.65">
84 <g>
85 <path fill="#EF412A" d="M24.482,23.998v-0.003C10.961,23.994,0,34.955,0,48.476h22.034c0.002-1.351,1.097-2.445,2.448-2.445
86 c1.352,0,2.448,1.096,2.448,2.448s-1.096,2.448-2.448,2.448c-1.311,0-2.372-1.033-2.436-2.327
87 C9.669,49.824,0.001,60.262,0.001,72.96H0v24.482h0.003c13.52-0.002,24.479-10.962,24.479-24.481h0.003
88 C38.005,72.959,48.963,62,48.963,48.479v-0.003C48.962,34.957,38.001,23.998,24.482,23.998z"/>
89 </g>
90</g>
91<g opacity="0.65">
92 <g>
93 <path fill="#A9C542" d="M119.949,48.963c0-1.352,1.096-2.448,2.448-2.448c1.31,0,2.371,1.032,2.436,2.327
94 c12.378-1.223,22.046-11.662,22.046-24.36h-24.482C122.396,10.961,111.435,0,97.915,0v24.482h24.479
95 c-13.52,0.002-24.478,10.962-24.478,24.481h0v24.479h0c12.698,0,23.137-9.668,24.36-22.043
96 C120.981,51.334,119.949,50.274,119.949,48.963z M124.833,49.084c-0.064,1.295-1.126,2.327-2.436,2.327h-0.001v22.033h24.482
97 v-0.003C146.876,60.745,137.208,50.308,124.833,49.084z"/>
98 </g>
99</g>
100<g opacity="0.65">
101 <g>
102 <path fill="#F9C759" d="M195.841,48.979l-0.006-0.015h0.006V48.979c0-0.005,0.001-0.01,0.001-0.015V24.482h-0.004
103 c-12.698,0.002-23.136,9.672-24.356,22.049c1.294,0.064,2.326,1.125,2.326,2.436c0,1.352-1.096,2.448-2.447,2.448
104 c-1.354,0-2.449-1.096-2.449-2.448c0-1.311,1.033-2.371,2.328-2.436c-1.222-12.379-11.661-22.049-24.361-22.049v24.481
105 c0,13.521,10.961,24.481,24.482,24.481v24.482h0.003c13.519-0.002,24.479-10.963,24.479-24.482h-23.884
106 C185.203,73.126,195.841,62.299,195.841,48.979z"/>
107 </g>
108</g>
109<g opacity="0.65">
110 <g>
111 <path fill="#6AC7BD" d="M73.44,24.001h-0.003C59.919,24.003,48.96,34.959,48.958,48.476v0.003h0.003v0.002l-0.004,0.001v0.003
112 c0.002,13.519,10.961,24.478,24.479,24.478s24.477-10.959,24.479-24.478v-0.003C97.916,34.963,86.958,24.003,73.44,24.001z
113 M73.442,50.928c-1.352,0-2.448-1.096-2.448-2.448s1.096-2.448,2.448-2.448s2.448,1.096,2.448,2.448S74.794,50.928,73.442,50.928z
114 "/>
115 </g>
116</g>
117</svg>
diff --git a/handbook/ref-bitbake.xml b/handbook/ref-bitbake.xml
new file mode 100644
index 0000000000..8652424466
--- /dev/null
+++ b/handbook/ref-bitbake.xml
@@ -0,0 +1,340 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='ref-bitbake'>
5
6 <title>Reference: Bitbake</title>
7
8 <para>
9 Bitbake a program written in Python which interprets the metadata
10 that makes up Poky. At some point, people wonder what actually happens
11 when you type <command>bitbake poky-image-sato</command>. This section
12 aims to give an overview of what happens behind the scenes from a
13 BitBake perspective.
14 </para>
15
16 <para>
17 It is worth noting that bitbake aims to be a generic "task" executor
18 capable of handling complex dependency relationships. As such it has no
19 real knowledge of what the tasks its executing actually do. It just
20 considers a list of tasks with dependencies and handles metadata
21 consisting of variables in a certain format which get passed to the
22 tasks.
23 </para>
24
25 <section id='ref-bitbake-parsing'>
26 <title>Parsing</title>
27
28 <para>
29 The first thing BitBake does is work out its configuration by
30 looking for a file called <filename>bitbake.conf</filename>.
31 Bitbake searches through the <varname>BBPATH</varname> environment
32 variable looking for a <filename class="directory">conf/</filename>
33 directory containing a <filename>bitbake.conf</filename> file and
34 adds the first <filename>bitbake.conf</filename> file found in
35 <varname>BBPATH</varname> (similar to the PATH environment variable).
36 For Poky, <filename>bitbake.conf</filename> is found in <filename
37 class="directory">meta/conf/</filename>.
38 </para>
39
40 <para>
41 In Poky, <filename>bitbake.conf</filename> lists other configuration
42 files to include from a <filename class="directory">conf/</filename>
43 directory below the directories listed in <varname>BBPATH</varname>.
44 In general the most important configuration file from a user's perspective
45 is <filename>local.conf</filename>, which contains a users customized
46 settings for Poky. Other notable configuration files are the distribution
47 configuration file (set by the <glossterm><link linkend='var-DISTRO'>
48 DISTRO</link></glossterm> variable) and the machine configuration file
49 (set by the <glossterm><link linkend='var-MACHINE'>MACHINE</link>
50 </glossterm> variable). The <glossterm><link linkend='var-DISTRO'>
51 DISTRO</link></glossterm> and <glossterm><link linkend='var-MACHINE'>
52 MACHINE</link></glossterm> environment variables are both usually set in
53 the <filename>local.conf</filename> file. Valid distribution
54 configuration files are available in the <filename class="directory">
55 meta/conf/distro/</filename> directory and valid machine configuration
56 files in the <filename class="directory">meta/conf/machine/</filename>
57 directory. Within the <filename class="directory">
58 meta/conf/machine/include/</filename> directory are various <filename>
59 tune-*.inc</filename> configuration files which provide common
60 "tuning" settings specific to and shared between particular
61 architectures and machines.
62 </para>
63
64 <para>
65 After the parsing of the configuration files some standard classes
66 are included. In particular, <filename>base.bbclass</filename> is
67 always included, as will any other classes
68 specified in the configuration using the <glossterm><link
69 linkend='var-INHERIT'>INHERIT</link></glossterm>
70 variable. Class files are searched for in a classes subdirectory
71 under the paths in <varname>BBPATH</varname> in the same way as
72 configuration files.
73 </para>
74
75 <para>
76 After the parsing of the configuration files is complete, the
77 variable <glossterm><link linkend='var-BBFILES'>BBFILES</link></glossterm>
78 is set, usually in
79 <filename>local.conf</filename>, and defines the list of places to search for
80 <filename class="extension">.bb</filename> files. By
81 default this specifies the <filename class="directory">meta/packages/
82 </filename> directory within Poky, but other directories such as
83 <filename class="directory">meta-extras/</filename> can be included
84 too. If multiple directories are specified a system referred to as
85 <link linkend='usingpoky-changes-collections'>"collections"</link> is used to
86 determine which files have priority.
87 </para>
88
89 <para>
90 Bitbake parses each <filename class="extension">.bb</filename> file in
91 <glossterm><link linkend='var-BBFILES'>BBFILES</link></glossterm> and
92 stores the values of various variables. In summary, for each
93 <filename class="extension">.bb</filename>
94 file the configuration + base class of variables are set, followed
95 by the data in the <filename class="extension">.bb</filename> file
96 itself, followed by any inherit commands that
97 <filename class="extension">.bb</filename> file might contain.
98 </para>
99
100 <para>
101 Parsing <filename class="extension">.bb</filename> files is a time
102 consuming process, so a cache is kept to speed up subsequent parsing.
103 This cache is invalid if the timestamp of the <filename class="extension">.bb</filename>
104 file itself has changed, or if the timestamps of any of the include,
105 configuration or class files the <filename class="extension">.bb</filename>
106 file depends on have changed.
107 </para>
108 </section>
109
110 <section id='ref-bitbake-providers'>
111 <title>Preferences and Providers</title>
112
113 <para>
114 Once all the <filename class="extension">.bb</filename> files have been
115 parsed, BitBake will proceed to build "poky-image-sato" (or whatever was
116 specified on the commandline) and looks for providers of that target.
117 Once a provider is selected, BitBake resolves all the dependencies for
118 the target. In the case of "poky-image-sato", it would lead to
119 <filename>task-oh.bb</filename> and <filename>task-base.bb</filename>
120 which in turn would lead to packages like <application>Contacts</application>,
121 <application>Dates</application>, <application>BusyBox</application>
122 and these in turn depend on glibc and the toolchain.
123 </para>
124
125 <para>
126 Sometimes a target might have multiple providers and a common example
127 is "virtual/kernel" that is provided by each kernel package. Each machine
128 will often elect the best provider of its kernel with a line like the
129 following in the machine configuration file:
130 </para>
131 <programlisting><glossterm><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></glossterm>_virtual/kernel = "linux-rp"</programlisting>
132 <para>
133 The default <glossterm><link linkend='var-PREFERRED_PROVIDER'>
134 PREFERRED_PROVIDER</link></glossterm> is the provider with the same name as
135 the target.
136 </para>
137
138 <para>
139 Understanding how providers are chosen is complicated by the fact
140 multiple versions might be present. Bitbake defaults to the highest
141 version of a provider by default. Version comparisons are made using
142 the same method as Debian. The <glossterm><link
143 linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm>
144 variable can be used to specify a particular version
145 (usually in the distro configuration) but the order can
146 also be influenced by the <glossterm><link
147 linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>
148 variable. By default files
149 have a preference of "0". Setting the
150 <glossterm><link
151 linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm> to "-1" will
152 make a package unlikely to be used unless it was explicitly referenced and
153 "1" makes it likely the package will be used.
154 <glossterm><link
155 linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm> overrides
156 any default preference. <glossterm><link
157 linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>
158 is often used to mark more
159 experimental new versions of packages until they've undergone sufficient
160 testing to be considered stable.
161 </para>
162
163 <para>
164 The end result is that internally, BitBake has now built a list of
165 providers for each target it needs in order of priority.
166 </para>
167 </section>
168
169 <section id='ref-bitbake-dependencies'>
170 <title>Dependencies</title>
171
172 <para>
173 Each target BitBake builds consists of multiple tasks (e.g. fetch,
174 unpack, patch, configure, compile etc.). For best performance on
175 multi-core systems, BitBake considers each task as an independent
176 entity with a set of dependencies. There are many variables that
177 are used to signify these dependencies and more information can be found
178 found about these in the <ulink url='http://bitbake.berlios.de/manual/'>
179 BitBake manual</ulink>. At a basic level it is sufficient to know
180 that BitBake uses the <glossterm><link
181 linkend='var-DEPENDS'>DEPENDS</link></glossterm> and
182 <glossterm><link linkend='var-RDEPENDS'>RDEPENDS</link></glossterm> variables when
183 calculating dependencies and descriptions of these variables are
184 available through the links.
185 </para>
186
187 </section>
188
189 <section id='ref-bitbake-tasklist'>
190 <title>The Task List</title>
191
192 <para>
193 Based on the generated list of providers and the dependency information,
194 BitBake can now calculate exactly which tasks it needs to run and in what
195 order. The build now starts with BitBake forking off threads up to
196 the limit set in the <glossterm><link
197 linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm> variable
198 as long there are tasks ready to run, i.e. tasks with all their
199 dependencies met.
200 </para>
201
202 <para>
203 As each task completes, a timestamp is written to the directory
204 specified by the <glossterm><link
205 linkend='var-STAMPS'>STAMPS</link></glossterm> variable (usually
206 <filename class="directory">build/tmp/stamps/*/</filename>). On
207 subsequent runs, BitBake looks at the <glossterm><link
208 linkend='var-STAMPS'>STAMPS</link></glossterm>
209 directory and will not rerun
210 tasks its already completed unless a timestamp is found to be invalid.
211 Currently, invalid timestamps are only considered on a per <filename
212 class="extension">.bb</filename> file basis so if for example the configure stamp has a timestamp greater than the
213 compile timestamp for a given target the compile task would rerun but this
214 has no effect on other providers depending on that target. This could
215 change or become configurable in future versions of BitBake. Some tasks
216 are marked as "nostamp" tasks which means no timestamp file will be written
217 and the task will always rerun.
218 </para>
219
220 <para>Once all the tasks have been completed BitBake exits.</para>
221
222 </section>
223
224 <section id='ref-bitbake-runtask'>
225 <title>Running a Task</title>
226
227 <para>
228 It's worth noting what BitBake does to run a task. A task can either
229 be a shell task or a python task. For shell tasks, BitBake writes a
230 shell script to <filename>${WORKDIR}/temp/run.do_taskname.pid</filename>
231 and then executes the script. The generated
232 shell script contains all the exported variables, and the shell functions
233 with all variables expanded. Output from the shell script is
234 sent to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
235 Looking at the
236 expanded shell functions in the run file and the output in the log files
237 is a useful debugging technique.
238 </para>
239
240 <para>
241 Python functions are executed internally to BitBake itself and
242 logging goes to the controlling terminal. Future versions of BitBake will
243 write the functions to files in a similar way to shell functions and
244 logging will also go to the log files in a similar way.
245 </para>
246 </section>
247
248
249 <section id='ref-bitbake-commandline'>
250 <title>Commandline</title>
251
252 <para>
253 To quote from "bitbake --help":
254 </para>
255
256 <screen>Usage: bitbake [options] [package ...]
257
258Executes the specified task (default is 'build') for a given set of BitBake files.
259It expects that BBFILES is defined, which is a space separated list of files to
260be executed. BBFILES does support wildcards.
261Default BBFILES are the .bb files in the current directory.
262
263Options:
264 --version show program's version number and exit
265 -h, --help show this help message and exit
266 -b BUILDFILE, --buildfile=BUILDFILE
267 execute the task against this .bb file, rather than a
268 package from BBFILES.
269 -k, --continue continue as much as possible after an error. While the
270 target that failed, and those that depend on it,
271 cannot be remade, the other dependencies of these
272 targets can be processed all the same.
273 -f, --force force run of specified cmd, regardless of stamp status
274 -i, --interactive drop into the interactive mode also called the BitBake
275 shell.
276 -c CMD, --cmd=CMD Specify task to execute. Note that this only executes
277 the specified task for the providee and the packages
278 it depends on, i.e. 'compile' does not implicitly call
279 stage for the dependencies (IOW: use only if you know
280 what you are doing). Depending on the base.bbclass a
281 listtasks tasks is defined and will show available
282 tasks
283 -r FILE, --read=FILE read the specified file before bitbake.conf
284 -v, --verbose output more chit-chat to the terminal
285 -D, --debug Increase the debug level. You can specify this more
286 than once.
287 -n, --dry-run don't execute, just go through the motions
288 -p, --parse-only quit after parsing the BB files (developers only)
289 -d, --disable-psyco disable using the psyco just-in-time compiler (not
290 recommended)
291 -s, --show-versions show current and preferred versions of all packages
292 -e, --environment show the global or per-package environment (this is
293 what used to be bbread)
294 -g, --graphviz emit the dependency trees of the specified packages in
295 the dot syntax
296 -I IGNORED_DOT_DEPS, --ignore-deps=IGNORED_DOT_DEPS
297 Stop processing at the given list of dependencies when
298 generating dependency graphs. This can help to make
299 the graph more appealing
300 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
301 Show debug logging for the specified logging domains
302 -P, --profile profile the command and print a report</screen>
303
304 </section>
305
306 <section id='ref-bitbake-fetchers'>
307 <title>Fetchers</title>
308
309 <para>
310 As well as the containing the parsing and task/dependency handling
311 code, bitbake also contains a set of "fetcher" modules which allow
312 fetching of source code from various types of sources. Example
313 sources might be from disk with the metadata, from websites, from
314 remote shell accounts or from SCM systems like cvs/subversion/git.
315 </para>
316
317 <para>
318 The fetchers are usually triggered by entries in
319 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. Information about the
320 options and formats of entries for specific fetchers can be found in the
321 <ulink url='http://bitbake.berlios.de/manual/'>BitBake manual</ulink>.
322 </para>
323
324 <para>
325 One useful feature for certain SCM fetchers is the ability to
326 "auto-update" when the upstream SCM changes version. Since this
327 requires certain functionality from the SCM only certain systems
328 support it, currently Subversion, Bazaar and to a limited extent, Git. It
329 works using the <glossterm><link linkend='var-SRCREV'>SRCREV</link>
330 </glossterm> variable. See the <link linkend='platdev-appdev-srcrev'>
331 developing with an external SCM based project</link> section for more
332 information.
333 </para>
334
335 </section>
336
337</appendix>
338<!--
339vim: expandtab tw=80 ts=4 spell spelllang=en_gb
340-->
diff --git a/handbook/ref-classes.xml b/handbook/ref-classes.xml
new file mode 100644
index 0000000000..1cef9012c1
--- /dev/null
+++ b/handbook/ref-classes.xml
@@ -0,0 +1,460 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='ref-classes'>
5<title>Reference: Classes</title>
6
7<para>
8 Class files are used to abstract common functionality and share it amongst multiple
9 <filename class="extension">.bb</filename> files. Any metadata usually found in a
10 <filename class="extension">.bb</filename> file can also be placed in a class
11 file. Class files are identified by the extension
12 <filename class="extension">.bbclass</filename> and are usually placed
13 in a <filename class="directory">classes/</filename> directory beneath the
14 <filename class="directory">meta/</filename> directory or the <filename
15 class="directory">build/</filename> directory in the same way as <filename
16 class="extension">.conf</filename> files in the <filename
17 class="directory">conf</filename> directory. Class files are searched for
18 in BBPATH in the same was as <filename class="extension">.conf</filename> files too.
19</para>
20
21<para>
22 In most cases inheriting the class is enough to enable its features, although
23 for some classes you may need to set variables and/or override some of the
24 default behaviour.
25</para>
26
27<section id='ref-classes-base'>
28 <title>The base class - <filename>base.bbclass</filename></title>
29
30 <para>
31 The base class is special in that every <filename class="extension">.bb</filename>
32 file inherits it automatically. It contains definitions of standard basic
33 tasks such as fetching, unpacking, configuring (empty by default), compiling
34 (runs any Makefile present), installing (empty by default) and packaging
35 (empty by default). These are often overridden or extended by other classes
36 such as <filename>autotools.bbclass</filename> or
37 <filename>package.bbclass</filename>. The class contains some commonly
38 some commonly used functions such as <function>oe_libinstall</function>
39 and <function>oe_runmake</function>. The end of the class file has a
40 list of standard mirrors for software projects for use by the fetcher code.
41 </para>
42</section>
43
44<section id='ref-classes-autotools'>
45 <title>Autotooled Packages - <filename>autotools.bbclass</filename></title>
46
47 <para>
48 Autotools (autoconf, automake, libtool) brings standardisation and this
49 class aims to define a set of tasks (configure, compile etc.) that will
50 work for all autotooled packages. It should usualy be enough to define
51 a few standard variables as documented in the <link
52 linkend='usingpoky-extend-addpkg-autotools'>simple autotools
53 example</link> section and then simply "inherit autotools". This class
54 can also work with software that emulates autotools.
55 </para>
56
57 <para>
58 Its useful to have some idea of the tasks this class defines work and
59 what they do behind the scenes.
60 </para>
61
62 <itemizedlist>
63 <listitem>
64 <para>
65 'do_configure' regenearates the configure script and
66 then launches it with a standard set of arguments used during
67 cross-compilation. Additional parameters can be passed to
68 <command>configure</command> through the <glossterm><link
69 linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></glossterm> variable.
70 </para>
71 </listitem>
72 <listitem>
73 <para>
74 'do_compile' runs <command>make</command> with arguments specifying
75 the compiler and linker. Additional arguments can be passed through
76 the <glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link>
77 </glossterm> variable.
78 </para>
79 </listitem>
80 <listitem>
81 <para>
82 'do_install' runs <command>make install</command> passing a DESTDIR
83 option taking its value from the standard <glossterm><link
84 linkend='var-DESTDIR'>DESTDIR</link></glossterm> variable.
85 </para>
86 </listitem>
87 </itemizedlist>
88
89 <para>
90 By default the class does not stage headers and libraries so
91 the recipe author needs to add their own <function>do_stage()</function>
92 task. For typical recipes the following example code will usually be
93 enough:
94 <programlisting>
95do_stage() {
96autotools_stage_all
97}</programlisting>
98 </para>
99</section>
100
101<section id='ref-classes-update-alternatives'>
102 <title>Alternatives - <filename>update-alternatives.bbclass</filename></title>
103
104 <para>
105 Several programs can fulfill the same or similar function and
106 they can be installed with the same name. For example the <command>ar</command>
107 command is available from the "busybox", "binutils" and "elfutils" packages.
108 This class handles the renaming of the binaries so multiple packages
109 can be installed which would otherwise conflict and yet the
110 <command>ar</command> command still works regardless of which are installed
111 or subsequently removed. It renames the conflicting binary in each package
112 and symlinks the highest priority binary during installation or removal
113 of packages.
114
115 Four variables control this class:
116 </para>
117
118
119 <variablelist>
120 <varlistentry>
121 <term>ALTERNATIVE_NAME</term>
122 <listitem>
123 <para>
124 Name of binary which will be replaced (<command>ar</command> in this example)
125 </para>
126 </listitem>
127 </varlistentry>
128 <varlistentry>
129 <term>ALTERNATIVE_LINK</term>
130 <listitem>
131 <para>
132 Path to resulting binary ("/bin/ar" in this example)
133 </para>
134 </listitem>
135 </varlistentry>
136 <varlistentry>
137 <term>ALTERNATIVE_PATH</term>
138 <listitem>
139 <para>
140 Path to real binary ("/usr/bin/ar.binutils" in this example)
141 </para>
142 </listitem>
143 </varlistentry>
144 <varlistentry>
145 <term>ALTERNATIVE_PRIORITY</term>
146 <listitem>
147 <para>
148 Priority of binary, the version with the most features should have the highest priority
149 </para>
150 </listitem>
151 </varlistentry>
152 </variablelist>
153</section>
154
155<section id='ref-classes-update-rc.d'>
156 <title>Initscripts - <filename>update-rc.d.bbclass</filename></title>
157
158 <para>
159 This class uses update-rc.d to safely install an initscript on behalf of
160 the package. Details such as making sure the initscript is stopped before
161 a package is removed and started when the package is installed are taken
162 care of. Three variables control this class,
163 <link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link>,
164 <link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link> and
165 <link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link>. See the
166 links for details.
167 </para>
168</section>
169
170<section id='ref-classes-binconfig'>
171 <title>Binary config scripts - <filename>binconfig.bbclass</filename></title>
172
173 <para>
174 Before pkg-config became widespread, libraries shipped shell
175 scripts to give information about the libraries and include paths needed
176 to build software (usually named 'LIBNAME-config'). This class assists
177 any recipe using such scripts.
178 </para>
179
180 <para>
181 During staging Bitbake installs such scripts into the <filename
182 class="directory">staging/</filename> directory. It also changes all
183 paths to point into the <filename class="directory">staging/</filename>
184 directory so all builds which use the script will use the correct
185 directories for the cross compiling layout.
186 </para>
187</section>
188
189<section id='ref-classes-debian'>
190 <title>Debian renaming - <filename>debian.bbclass</filename></title>
191
192 <para>
193 This class renames packages so that they follow the Debian naming
194 policy, i.e. 'glibc' becomes 'libc6' and 'glibc-devel' becomes
195 'libc6-dev'.
196 </para>
197</section>
198
199<section id='ref-classes-pkgconfig'>
200 <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title>
201
202 <para>
203 Pkg-config brought standardisation and this class aims to make its
204 integration smooth for all libraries which make use of it.
205 </para>
206
207 <para>
208 During staging Bitbake installs pkg-config data into the <filename
209 class="directory">staging/</filename> directory. By making use of
210 sysroot functionality within pkgconfig this class no longer has to
211 manipulate the files.
212 </para>
213</section>
214
215<section id='ref-classes-src-distribute'>
216 <title>Distribution of sources - <filename>src_distribute_local.bbclass</filename></title>
217
218 <para>
219 Many software licenses require providing the sources for compiled
220 binaries. To simplify this process two classes were created:
221 <filename>src_distribute.bbclass</filename> and
222 <filename>src_distribute_local.bbclass</filename>.
223 </para>
224
225 <para>
226 Result of their work are <filename class="directory">tmp/deploy/source/</filename>
227 subdirs with sources sorted by <glossterm><link linkend='var-LICENSE'>LICENSE</link>
228 </glossterm> field. If recipe lists few licenses (or has entries like "Bitstream Vera") source archive is put in each
229 license dir.
230 </para>
231
232 <para>
233 Src_distribute_local class has three modes of operating:
234 </para>
235
236 <itemizedlist>
237 <listitem><para>copy - copies the files to the distribute dir</para></listitem>
238 <listitem><para>symlink - symlinks the files to the distribute dir</para></listitem>
239 <listitem><para>move+symlink - moves the files into distribute dir, and symlinks them back</para></listitem>
240 </itemizedlist>
241</section>
242
243<section id='ref-classes-perl'>
244 <title>Perl modules - <filename>cpan.bbclass</filename></title>
245
246 <para>
247 Recipes for Perl modules are simple - usually needs only
248 pointing to source archive and inheriting of proper bbclass.
249 Building is split into two methods dependly on method used by
250 module authors.
251 </para>
252
253 <para>
254 Modules which use old Makefile.PL based build system require
255 using of <filename>cpan.bbclass</filename> in their recipes.
256 </para>
257
258 <para>
259 Modules which use Build.PL based build system require
260 using of <filename>cpan_build.bbclass</filename> in their recipes.
261 </para>
262
263</section>
264
265<section id='ref-classes-distutils'>
266 <title>Python extensions - <filename>distutils.bbclass</filename></title>
267
268 <para>
269 Recipes for Python extensions are simple - usually needs only
270 pointing to source archive and inheriting of proper bbclass.
271 Building is split into two methods dependly on method used by
272 module authors.
273 </para>
274
275 <para>
276 Extensions which use autotools based build system require using
277 of autotools and distutils-base bbclasses in their recipes.
278 </para>
279
280 <para>
281 Extensions which use distutils build system require using
282 of <filename>distutils.bbclass</filename> in their recipes.
283 </para>
284
285</section>
286
287<section id='ref-classes-devshell'>
288 <title>Developer Shell - <filename>devshell.bbclass</filename></title>
289
290 <para>
291 This class adds the devshell task. Its usually up to distribution policy
292 to include this class (Poky does). See the <link
293 linkend='platdev-appdev-devshell'>developing with 'devshell' section</link>
294 for more information about using devshell.
295 </para>
296
297</section>
298
299<section id='ref-classes-package'>
300 <title>Packaging - <filename>package*.bbclass</filename></title>
301
302 <para>
303 The packaging classes add support for generating packages from the output
304 from builds. The core generic functionality is in
305 <filename>package.bbclass</filename>, code specific to particular package
306 types is contained in various sub classes such as
307 <filename>package_deb.bbclass</filename> and <filename>package_ipk.bbclass</filename>.
308 Most users will
309 want one or more of these classes and this is controlled by the <glossterm>
310 <link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></glossterm>
311 variable. The first class listed in this variable will be used for image
312 generation. Since images are generated from packages a packaging class is
313 needed to enable image generation.
314 </para>
315
316</section>
317
318<section id='ref-classes-kernel'>
319 <title>Building kernels - <filename>kernel.bbclass</filename></title>
320
321 <para>
322 This class handle building of Linux kernels and the class contains code to know how to build both 2.4 and 2.6 kernel trees. All needed headers are
323 staged into <glossterm><link
324 linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></glossterm>
325 directory to allow building of out-of-tree modules using <filename>module.bbclass</filename>.
326 </para>
327 <para>
328 The means that each kerel module built is packaged separately and inter-modules dependencies are
329 created by parsing the <command>modinfo</command> output. If all modules are
330 required then installing "kernel-modules" package will install all
331 packages with modules and various other kernel packages such as "kernel-vmlinux" are also generated.
332 </para>
333
334 <para>
335 Various other classes are used by the kernel and module classes internally including
336 <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>,
337 <filename>module-base.bbclass</filename> and <filename>linux-kernel-base.bbclass</filename>.
338 </para>
339</section>
340
341<section id='ref-classes-image'>
342 <title>Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title>
343
344 <para>
345 Those classes add support for creating images in many formats. First the
346 rootfs is created from packages by one of the <filename>rootfs_*.bbclass</filename>
347 files (depending on package format used) and then image is created.
348
349 The <glossterm><link
350 linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></glossterm>
351 variable controls which types of image to generate.
352
353 The list of packages to install into the image is controlled by the
354 <glossterm><link
355 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm>
356 variable.
357 </para>
358</section>
359
360<section id='ref-classes-sanity'>
361 <title>Host System sanity checks - <filename>sanity.bbclass</filename></title>
362
363 <para>
364 This class checks prerequisite software is present to try and identify
365 and notify the user of problems which will affect their build. It also
366 performs basic checks of the users configuration from local.conf to
367 prevent common mistakes and resulting build failures. Its usually up to
368 distribution policy to include this class (Poky does).
369 </para>
370</section>
371
372<section id='ref-classes-insane'>
373 <title>Generated output quality assurance checks - <filename>insane.bbclass</filename></title>
374
375 <para>
376 This class adds a step to package generation which sanity checks the
377 packages generated by Poky. There are an ever increasing range of checks
378 this makes, checking for common problems which break builds/packages/images,
379 see the bbclass file for more information. Its usually up to distribution
380 policy to include this class (Poky doesn't at the time of writing but plans
381 to soon).
382 </para>
383</section>
384
385<section id='ref-classes-siteinfo'>
386 <title>Autotools configuration data cache - <filename>siteinfo.bbclass</filename></title>
387
388 <para>
389 Autotools can require tests which have to execute on the target hardware.
390 Since this isn't possible in general when cross compiling, siteinfo is
391 used to provide cached test results so these tests can be skipped over but
392 the correct values used. The <link linkend='structure-meta-site'>meta/site directory</link>
393 contains test results sorted into different categories like architecture, endianess and
394 the libc used. Siteinfo provides a list of files containing data relevant to
395 the current build in the <glossterm><link linkend='var-CONFIG_SITE'>CONFIG_SITE
396 </link></glossterm> variable which autotools will automatically pick up.
397 </para>
398 <para>
399 The class also provides variables like <glossterm><link
400 linkend='var-SITEINFO_ENDIANESS'>SITEINFO_ENDIANESS</link></glossterm>
401 and <glossterm><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link>
402 </glossterm> which can be used elsewhere in the metadata.
403 </para>
404 <para>
405 This class is included from <filename>base.bbclass</filename> and is hence always active.
406 </para>
407</section>
408
409<section id='ref-classes-others'>
410 <title>Other Classes</title>
411
412 <para>
413 Only the most useful/important classes are covered here but there are
414 others, see the <filename class="directory">meta/classes</filename> directory for the rest.
415 </para>
416</section>
417
418<!-- Undocumented classes are:
419 base_srpm.bbclass
420 bootimg.bbclass
421 ccache.inc
422 ccdv.bbclass
423 cml1.bbclass
424 cross.bbclass
425 flow-lossage.bbclass
426 gconf.bbclass
427 gettext.bbclass
428 gnome.bbclass
429 gtk-icon-cache.bbclass
430 icecc.bbclass
431 lib_package.bbclass
432 mozilla.bbclass
433 multimachine.bbclass
434 native.bbclass
435 oelint.bbclass
436 patch.bbclass
437 patcher.bbclass
438 pkg_distribute.bbclass
439 pkg_metainfo.bbclass
440 poky.bbclass
441 rm_work.bbclass
442 rpm_core.bbclass
443 scons.bbclass
444 sdk.bbclass
445 sdl.bbclass
446 sip.bbclass
447 sourcepkg.bbclass
448 srec.bbclass
449 syslinux.bbclass
450 tinderclient.bbclass
451 tmake.bbclass
452 xfce.bbclass
453 xlibs.bbclass
454-->
455
456
457</appendix>
458<!--
459vim: expandtab tw=80 ts=4
460-->
diff --git a/handbook/ref-features.xml b/handbook/ref-features.xml
new file mode 100644
index 0000000000..cde9588116
--- /dev/null
+++ b/handbook/ref-features.xml
@@ -0,0 +1,302 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='ref-features'>
5 <title>Reference: Features</title>
6
7 <para>'Features' provide a mechanism for working out which packages
8 should be included in the generated images. Distributions can
9 select which features they want to support through the
10 <glossterm linkend='var-DISTRO_FEATURES'><link
11 linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></glossterm>
12 variable which is set in the distribution configuration file
13 (poky.conf for Poky). Machine features are set in the
14 <glossterm linkend='var-MACHINE_FEATURES'><link
15 linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></glossterm>
16 variable which is set in the machine configuration file and
17 specifies which hardware features a given machine has.
18 </para>
19
20 <para>These two variables are combined to work out which kernel modules,
21 utilities and other packages to include. A given distribution can
22 support a selected subset of features so some machine features might not
23 be included if the distribution itself doesn't support them.
24 </para>
25
26 <section id='ref-features-distro'>
27 <title>Distro</title>
28
29 <para>The items below are valid options for <glossterm linkend='var-DISTRO_FEATURES'><link
30 linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></glossterm>.
31 </para>
32
33 <itemizedlist>
34 <listitem>
35 <para>
36 alsa - ALSA support will be included (OSS compatibility
37 kernel modules will be installed if available)
38 </para>
39 </listitem>
40 <listitem>
41 <para>
42 bluetooth - Include bluetooth support (integrated BT only)
43 </para>
44 </listitem>
45 <listitem>
46 <para>
47 ext2 - Include tools for supporting for devices with internal
48 HDD/Microdrive for storing files (instead of Flash only devices)
49 </para>
50 </listitem>
51 <listitem>
52 <para>
53 irda - Include Irda support
54 </para>
55 </listitem>
56 <listitem>
57 <para>
58 keyboard - Include keyboard support (e.g. keymaps will be
59 loaded during boot).
60 </para>
61 </listitem>
62 <listitem>
63 <para>
64 pci - Include PCI bus support
65 </para>
66 </listitem>
67 <listitem>
68 <para>
69 pcmcia - Include PCMCIA/CompactFlash support
70 </para>
71 </listitem>
72 <listitem>
73 <para>
74 usbgadget - USB Gadget Device support (for USB
75 networking/serial/storage)
76 </para>
77 </listitem>
78 <listitem>
79 <para>
80 usbhost - USB Host support (allows to connect external
81 keyboard, mouse, storage, network etc)
82 </para>
83 </listitem>
84 <listitem>
85 <para>
86 wifi - WiFi support (integrated only)
87 </para>
88 </listitem>
89 <listitem>
90 <para>
91 cramfs - CramFS support
92 </para>
93 </listitem>
94 <listitem>
95 <para>
96 ipsec - IPSec support
97 </para>
98 </listitem>
99 <listitem>
100 <para>
101 ipv6 - IPv6 support
102 </para>
103 </listitem>
104 <listitem>
105 <para>
106 nfs - NFS client support (for mounting NFS exports on
107 device)
108 </para>
109 </listitem>
110 <listitem>
111 <para>
112 ppp - PPP dialup support
113 </para>
114 </listitem>
115 <listitem>
116 <para>
117 smbfs - SMB networks client support (for mounting
118 Samba/Microsoft Windows shares on device)
119 </para>
120 </listitem>
121 </itemizedlist>
122 </section>
123
124 <section id='ref-features-machine'>
125 <title>Machine</title>
126
127 <para>The items below are valid options for <glossterm linkend='var-MACHINE_FEATURES'><link
128 linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></glossterm>.
129 </para>
130
131 <itemizedlist>
132 <listitem>
133 <para>
134 acpi - Hardware has ACPI (x86/x86_64 only)
135 </para>
136 </listitem>
137 <listitem>
138 <para>
139 alsa - Hardware has ALSA audio drivers
140 </para>
141 </listitem>
142 <listitem>
143 <para>
144 apm - Hardware uses APM (or APM emulation)
145 </para>
146 </listitem>
147 <listitem>
148 <para>
149 bluetooth - Hardware has integrated BT
150 </para>
151 </listitem>
152 <listitem>
153 <para>
154 ext2 - Hardware HDD or Microdrive
155 </para>
156 </listitem>
157 <listitem>
158 <para>
159 irda - Hardware has Irda support
160 </para>
161 </listitem>
162 <listitem>
163 <para>
164 keyboard - Hardware has a keyboard
165 </para>
166 </listitem>
167 <listitem>
168 <para>
169 pci - Hardware has a PCI bus
170 </para>
171 </listitem>
172 <listitem>
173 <para>
174 pcmcia - Hardware has PCMCIA or CompactFlash sockets
175 </para>
176 </listitem>
177 <listitem>
178 <para>
179 screen - Hardware has a screen
180 </para>
181 </listitem>
182 <listitem>
183 <para>
184 serial - Hardware has serial support (usually RS232)
185 </para>
186 </listitem>
187 <listitem>
188 <para>
189 touchscreen - Hardware has a touchscreen
190 </para>
191 </listitem>
192 <listitem>
193 <para>
194 usbgadget - Hardware is USB gadget device capable
195 </para>
196 </listitem>
197 <listitem>
198 <para>
199 usbhost - Hardware is USB Host capable
200 </para>
201 </listitem>
202 <listitem>
203 <para>
204 wifi - Hardware has integrated WiFi
205 </para>
206 </listitem>
207 </itemizedlist>
208 </section>
209
210 <section id='ref-features-image'>
211 <title>Reference: Images</title>
212
213 <para>
214 The contents of images generated by Poky can be controlled by the <glossterm
215 linkend='var-IMAGE_FEATURES'><link
216 linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
217 variable in local.conf. Through this you can add several different
218 predefined packages such as development utilities or packages with debug
219 information needed to investigate application problems or profile applications.
220 </para>
221
222 <para>
223 Current list of <glossterm
224 linkend='var-IMAGE_FEATURES'><link
225 linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> contains:
226 </para>
227
228 <itemizedlist>
229 <listitem>
230 <para>
231 apps-console-core - Core console applications such as ssh daemon,
232 avahi daemon, portmap (for mounting NFS shares)
233 </para>
234 </listitem>
235 <listitem>
236 <para>
237 x11-base - X11 server + minimal desktop
238 </para>
239 </listitem>
240 <listitem>
241 <para>
242 x11-sato - OpenedHand Sato environment
243 </para>
244 </listitem>
245 <listitem>
246 <para>
247 apps-x11-core - Core X11 applications such as an X Terminal, file manager, file editor
248 </para>
249 </listitem>
250 <listitem>
251 <para>
252 apps-x11-games - A set of X11 games
253 </para>
254 </listitem>
255 <listitem>
256 <para>
257 apps-x11-pimlico - OpenedHand Pimlico application suite
258 </para>
259 </listitem>
260 <listitem>
261 <para>
262 tools-sdk - A full SDK which runs on device
263 </para>
264 </listitem>
265 <listitem>
266 <para>
267 tools-debug - Debugging tools such as strace and gdb
268 </para>
269 </listitem>
270 <listitem>
271 <para>
272 tools-profile - Profiling tools such as oprofile, exmap and LTTng
273 </para>
274 </listitem>
275 <listitem>
276 <para>
277 tools-testapps - Device testing tools (e.g. touchscreen debugging)
278 </para>
279 </listitem>
280 <listitem>
281 <para>
282 nfs-server - NFS server (exports / over NFS to everybody)
283 </para>
284 </listitem>
285 <listitem>
286 <para>
287 dev-pkgs - Development packages (headers and extra library links) for all packages
288 installed in a given image
289 </para>
290 </listitem>
291 <listitem>
292 <para>
293 dbg-pkgs - Debug packages for all packages installed in a given image
294 </para>
295 </listitem>
296 </itemizedlist>
297 </section>
298</appendix>
299
300<!--
301vim: expandtab tw=80 ts=4 spell spelllang=en_gb
302-->
diff --git a/handbook/ref-images.xml b/handbook/ref-images.xml
new file mode 100644
index 0000000000..80e36aec60
--- /dev/null
+++ b/handbook/ref-images.xml
@@ -0,0 +1,69 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='ref-images'>
5 <title>Reference: Images</title>
6
7 <para>
8 Poky has several standard images covering most people's standard needs. A full
9 list of image targets can be found by looking in the <filename class="directory">
10 meta/packages/images/</filename> directory. The standard images are listed below
11 along with details of what they contain:
12 </para>
13
14 <itemizedlist>
15 <listitem>
16 <para>
17 <emphasis>poky-image-minimal</emphasis> - A small image, just enough
18 to allow a device to boot
19 </para>
20 </listitem>
21 <listitem>
22 <para>
23 <emphasis>poky-image-base</emphasis> - console only image with full
24 support of target device hardware
25 </para>
26 </listitem>
27 <listitem>
28 <para>
29 <emphasis>poky-image-core</emphasis> - X11 image with simple apps like
30 terminal, editor and file manager
31 </para>
32 </listitem>
33 <listitem>
34 <para>
35 <emphasis>poky-image-sato</emphasis> - X11 image with Sato theme and
36 Pimlico applications. Also contains terminal, editor and file manager.
37 </para>
38 </listitem>
39 <listitem>
40 <para>
41 <emphasis>poky-image-sdk</emphasis> - X11 image like poky-image-sato but
42 also include native toolchain and libraries needed to build applications
43 on the device itself. Also includes testing and profiling tools and debug
44 symbols.
45 </para>
46 </listitem>
47 <listitem>
48 <para>
49 <emphasis>meta-toolchain</emphasis> - This generates a tarball containing
50 a standalone toolchain which can be used externally to Poky. It is self
51 contained and unpacks to the <filename class="directory">/usr/local/poky</filename>
52 directory. It also contains a copy of QEMU and the scripts neccessary to run
53 poky QEMU images.
54 </para>
55 </listitem>
56 <listitem>
57 <para>
58 <emphasis>meta-toolchain-sdk</emphasis> - This includes everything in
59 meta-toolchain but also includes development headers and libraries
60 forming a complete standalone SDK. See the <link linkend='platdev-appdev-external-sdk'>
61 Developing using the Poky SDK</link> and <link linkend='platdev-appdev-external-anjuta'>
62 Developing using the Anjuta Plugin</link> sections for more information.
63 </para>
64 </listitem>
65 </itemizedlist>
66</appendix>
67<!--
68vim: expandtab tw=80 ts=4
69-->
diff --git a/handbook/ref-structure.xml b/handbook/ref-structure.xml
new file mode 100644
index 0000000000..8a564e77b3
--- /dev/null
+++ b/handbook/ref-structure.xml
@@ -0,0 +1,365 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='ref-structure'>
5
6<title>Reference: Directory Structure</title>
7
8<para>
9 Poky consists of several components and understanding what these are
10 and where they're located is one of the keys to using it. This section walks
11 through the Poky directory structure giving information about the various
12 files and directories.
13</para>
14
15<section id='structure-core'>
16 <title>Top level core components</title>
17
18 <section id='structure-core-bitbake'>
19 <title><filename class="directory">bitbake/</filename></title>
20
21 <para>
22 A copy of BitBake is included within Poky for ease of use, and should
23 usually match the current BitBake stable release from the BitBake project.
24 Bitbake, a metadata interpreter, reads the Poky metadata and runs the tasks
25 defined in the Poky metadata. Failures are usually from the metadata, not
26 BitBake itself, so most users don't need to worry about BitBake. The
27 <filename class="directory">bitbake/bin/</filename> directory is placed
28 into the PATH environment variable by the <link
29 linkend="structure-core-script">poky-init-build-env</link> script.
30 </para>
31 <para>
32 For more information on BitBake please see the BitBake project site at
33 <ulink url="http://bitbake.berlios.de/"/>
34 and the BitBake on-line manual at <ulink url="http://bitbake.berlios.de/manual/"/>.
35 </para>
36 </section>
37
38 <section id='structure-core-build'>
39 <title><filename class="directory">build/</filename></title>
40
41 <para>
42 This directory contains user configuration files and the output
43 from Poky.
44 </para>
45 </section>
46
47 <section id='structure-core-meta'>
48 <title><filename class="directory">meta/</filename></title>
49
50 <para>
51 This directory contains the core metadata, a key part of Poky. Within this
52 directory there are definitions of the machines, the Poky distribution
53 and the packages that make up a given system.
54 </para>
55 </section>
56
57 <section id='structure-core-meta-extras'>
58 <title><filename class="directory">meta-extras/</filename></title>
59
60 <para>
61 This directory is similar to <filename class="directory">meta/</filename>,
62 and contains some extra metadata not included in standard Poky. These are
63 disabled by default, and are not supported as part of Poky.
64 </para>
65 </section>
66
67 <section id='structure-core-scripts'>
68 <title><filename class="directory">scripts/</filename></title>
69
70 <para>
71 This directory contains various integration scripts which implement
72 extra functionality in the Poky environment, such as the QEMU
73 scripts. This directory is appended to the PATH environment variable by the
74 <link linkend="structure-core-script">poky-init-build-env</link> script.
75 </para>
76 </section>
77
78 <section id='structure-core-sources'>
79 <title><filename class="directory">sources/</filename></title>
80
81 <para>
82 While not part of a checkout, Poky will create this directory as
83 part of any build. Any downloads are placed in this directory (as
84 specified by the <glossterm><link linkend='var-DL_DIR'>DL_DIR</link>
85 </glossterm> variable). This directory can be shared between Poky
86 builds to save downloading files multiple times. SCM checkouts are
87 also stored here as e.g. <filename class="directory">sources/svn/
88 </filename>, <filename class="directory">sources/cvs/</filename> or
89 <filename class="directory">sources/git/</filename> and the
90 sources directory may contain archives of checkouts for various
91 revisions or dates.
92 </para>
93
94 <para>
95 It's worth noting that BitBake creates <filename class="extension">.md5
96 </filename> stamp files for downloads. It uses these to mark downloads as
97 complete as well as for checksum and access accounting purposes. If you add
98 a file manually to the directory, you need to touch the corresponding
99 <filename class="extension">.md5</filename> file too.
100 </para>
101
102 <para>
103 This location can be overridden by setting <glossterm><link
104 linkend='var-DL_DIR'>DL_DIR</link></glossterm> in <filename>local.conf
105 </filename>. This directory can be shared between builds and even between
106 machines via NFS, so downloads are only made once, speeding up builds.
107 </para>
108
109 </section>
110
111 <section id='structure-core-script'>
112 <title><filename>poky-init-build-env</filename></title>
113
114 <para>
115 This script is used to setup the Poky build environment. Sourcing this file in
116 a shell makes changes to PATH and sets other core BitBake variables based on the
117 current working directory. You need to use this before running Poky commands.
118 Internally it uses scripts within the <filename class="directory">scripts/
119 </filename> directory to do the bulk of the work.
120 </para>
121 </section>
122</section>
123
124<section id='structure-build'>
125 <title><filename class="directory">build/</filename> - The Build Directory</title>
126
127 <section id='structure-build-conf-local.conf'>
128 <title><filename>build/conf/local.conf</filename></title>
129
130 <para>
131 This file contains all the local user configuration of Poky. If there
132 is no <filename>local.conf</filename> present, it is created from
133 <filename>local.conf.sample</filename>. The <filename>local.conf</filename>
134 file contains documentation on the various configuration options. Any
135 variable set here overrides any variable set elsewhere within Poky unless
136 that variable is hardcoded within Poky (e.g. by using '=' instead of '?=').
137 Some variables are hardcoded for various reasons but these variables are
138 relatively rare.
139 </para>
140
141 <para>
142 Edit this file to set the <glossterm><link linkend='var-MACHINE'>MACHINE</link></glossterm> for which you want to build, which package types you
143 wish to use (PACKAGE_CLASSES) or where downloaded files should go
144 (<glossterm><link linkend='var-DL_DIR'>DL_DIR</link></glossterm>).
145 </para>
146 </section>
147
148 <section id='structure-build-tmp'>
149 <title><filename class="directory">build/tmp/</filename></title>
150
151 <para>
152 This is created by BitBake if it doesn't exist and is where all the Poky output
153 is placed. To clean Poky and start a build from scratch (other than downloads),
154 you can wipe this directory. The <filename class="directory">tmp/
155 </filename> directory has some important sub-components detailed below.
156 </para>
157 </section>
158
159 <section id='structure-build-tmp-cache'>
160 <title><filename class="directory">build/tmp/cache/</filename></title>
161
162 <para>
163 When BitBake parses the metadata it creates a cache file of the result which can
164 be used when subsequently running commands. These are stored here on
165 a per machine basis.
166 </para>
167 </section>
168
169 <section id='structure-build-tmp-cross'>
170 <title><filename class="directory">build/tmp/cross/</filename></title>
171
172 <para>
173 The cross compiler when generated is placed into this directory and those
174 beneath it.
175 </para>
176 </section>
177
178 <section id='structure-build-tmp-deploy'>
179 <title><filename class="directory">build/tmp/deploy/</filename></title>
180
181 <para>Any 'end result' output from Poky is placed under here.</para>
182 </section>
183
184 <section id='structure-build-tmp-deploy-deb'>
185 <title><filename class="directory">build/tmp/deploy/deb/</filename></title>
186
187 <para>
188 Any .deb packages emitted by Poky are placed here, sorted into feeds for
189 different architecture types.
190 </para>
191 </section>
192
193 <section id='structure-build-tmp-deploy-images'>
194 <title><filename class="directory">build/tmp/deploy/images/</filename></title>
195
196 <para>
197 Complete filesystem images are placed here. If you want to flash the resulting
198 image from a build onto a device, look here for them.
199 </para>
200 </section>
201
202 <section id='structure-build-tmp-deploy-ipk'>
203 <title><filename class="directory">build/tmp/deploy/ipk/</filename></title>
204
205 <para>Any resulting .ipk packages emitted by Poky are placed here.</para>
206 </section>
207
208 <section id='structure-build-tmp-rootfs'>
209 <title><filename class="directory">build/tmp/rootfs/</filename></title>
210
211 <para>
212 This is a temporary scratch area used when creating filesystem images. It is run
213 under fakeroot and is not useful once that fakeroot session has ended as
214 information is lost. It is left around since it is still useful in debugging
215 image creation problems.
216 </para>
217 </section>
218
219 <section id='structure-build-tmp-staging'>
220 <title><filename class="directory">build/tmp/staging/</filename></title>
221
222 <para>
223 Any package needing to share output with other packages does so within staging.
224 This means it contains any shared header files and any shared libraries amongst
225 other data. It is subdivided by architecture so multiple builds can run within
226 the one build directory.
227 </para>
228 </section>
229
230 <section id='structure-build-tmp-stamps'>
231 <title><filename class="directory">build/tmp/stamps/</filename></title>
232
233 <para>
234 This is used by BitBake for accounting purposes to keep track of which tasks
235 have been run and when. It is also subdivided by architecture. The files are
236 empty and the important information is the filenames and timestamps.</para>
237 </section>
238
239 <section id='structure-build-tmp-work'>
240 <title><filename class="directory">build/tmp/work/</filename></title>
241
242 <para>
243 This directory contains various subdirectories for each architecture, and each package built by BitBake has its own work directory under the appropriate architecture subdirectory. All tasks are executed from this work directory. As an example, the source for a particular package will be unpacked, patched, configured and compiled all within its own work directory.
244 </para>
245
246 <para>
247 It is worth considering the structure of a typical work directory. An
248 example is the linux-rp kernel, version 2.6.20 r7 on the machine spitz
249 built within Poky. For this package a work directory of <filename
250 class="directory">tmp/work/spitz-poky-linux-gnueabi/linux-rp-2.6.20-r7/
251 </filename>, referred to as <glossterm><link linkend='var-WORKDIR'>WORKDIR
252 </link></glossterm>, is created. Within this directory, the source is
253 unpacked to linux-2.6.20 and then patched by quilt (see <link
254 linkend="usingpoky-modifying-packages-quilt">Section 3.5.1</link>).
255 Within the <filename class="directory">linux-2.6.20</filename> directory,
256 standard Quilt directories <filename class="directory">linux-2.6.20/patches</filename>
257 and <filename class="directory">linux-2.6.20/.pc</filename> are created,
258 and standard quilt commands can be used.
259 </para>
260
261 <para>
262 There are other directories generated within <glossterm><link
263 linkend='var-WORKDIR'>WORKDIR</link></glossterm>. The most important
264 is <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm><filename class="directory">/temp/</filename> which has log files for each
265 task (<filename>log.do_*.pid</filename>) and the scripts BitBake runs for
266 each task (<filename>run.do_*.pid</filename>). The <glossterm><link
267 linkend='var-WORKDIR'>WORKDIR</link></glossterm><filename
268 class="directory">/image/</filename> directory is where <command>make
269 install</command> places its output which is then split into subpackages
270 within <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm><filename class="directory">/install/</filename>.
271 </para>
272 </section>
273</section>
274
275<section id='structure-meta'>
276 <title><filename class="directory">meta/</filename> - The Metadata</title>
277
278 <para>
279 As mentioned previously, this is the core of Poky. It has several
280 important subdivisions:
281 </para>
282
283 <section id='structure-meta-classes'>
284 <title><filename class="directory">meta/classes/</filename></title>
285
286 <para>
287 Contains the <filename class="extension">*.bbclass</filename> files. Class
288 files are used to abstract common code allowing it to be reused by multiple
289 packages. The <filename>base.bbclass</filename> file is inherited by every
290 package. Examples of other important classes are
291 <filename>autotools.bbclass</filename> that in theory allows any
292 Autotool-enabled package to work with Poky with minimal effort, or
293 <filename>kernel.bbclass</filename> that contains common code and functions
294 for working with the linux kernel. Functions like image generation or
295 packaging also have their specific class files (<filename>image.bbclass
296 </filename>, <filename>rootfs_*.bbclass</filename> and
297 <filename>package*.bbclass</filename>).
298 </para>
299 </section>
300
301 <section id='structure-meta-conf'>
302 <title><filename class="directory">meta/conf/</filename></title>
303
304 <para>
305 This is the core set of configuration files which start from
306 <filename>bitbake.conf</filename> and from which all other configuration
307 files are included (see the includes at the end of the file, even
308 <filename>local.conf</filename> is loaded from there!). While
309 <filename>bitbake.conf</filename> sets up the defaults, these can often be
310 overridden by user (<filename>local.conf</filename>), machine or
311 distribution configuration files.
312 </para>
313 </section>
314
315 <section id='structure-meta-conf-machine'>
316 <title><filename class="directory">meta/conf/machine/</filename></title>
317
318 <para>
319 Contains all the machine configuration files. If you set MACHINE="spitz", the
320 end result is Poky looking for a <filename>spitz.conf</filename> file in this directory. The includes
321 directory contains various data common to multiple machines. If you want to add
322 support for a new machine to Poky, this is the directory to look in.
323 </para>
324 </section>
325
326 <section id='structure-meta-conf-distro'>
327 <title><filename class="directory">meta/conf/distro/</filename></title>
328
329 <para>
330 Any distribution specific configuration is controlled from here. OpenEmbedded
331 supports multiple distributions of which Poky is one. Poky only contains the
332 Poky distribution so poky.conf is the main file here. This includes the
333 versions and SRCDATES for applications which are configured here. An example of
334 an alternative configuration is poky-bleeding.conf although this mainly inherits
335 its configuration from Poky itself.
336 </para>
337 </section>
338
339 <section id='structure-meta-packages'>
340 <title><filename class="directory">meta/packages/</filename></title>
341
342 <para>
343 Each application (package) Poky can build has an associated .bb file which are
344 all stored under this directory. Poky finds them through the BBFILES variable
345 which defaults to packages/*/*.bb. Adding a new piece of software to Poky
346 consists of adding the appropriate .bb file. The .bb files from OpenEmbedded
347 upstream are usually compatible although they are not supported.
348 </para>
349 </section>
350
351 <section id='structure-meta-site'>
352 <title><filename class="directory">meta/site/</filename></title>
353
354 <para>
355 Certain autoconf test results cannot be determined when cross compiling since it
356 can't run tests on a live system. This directory therefore contains a list of
357 cached results for various architectures which is passed to autoconf.
358 </para>
359 </section>
360</section>
361
362</appendix>
363<!--
364vim: expandtab tw=80 ts=4
365-->
diff --git a/handbook/ref-variables.xml b/handbook/ref-variables.xml
new file mode 100644
index 0000000000..437e8240f6
--- /dev/null
+++ b/handbook/ref-variables.xml
@@ -0,0 +1,825 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<!-- Dummy chapter -->
5<appendix id='ref-variables-glos'>
6
7<title>Reference: Variables Glossary</title>
8
9<para>
10 This section lists common variables used in Poky and gives an overview
11 of their function and contents.
12</para>
13
14<glossary id='ref-variables-glossary'>
15
16
17 <para>
18 <link linkend='var-glossary-a'>A</link>
19 <link linkend='var-glossary-b'>B</link>
20 <link linkend='var-glossary-c'>C</link>
21 <link linkend='var-glossary-d'>D</link>
22 <link linkend='var-glossary-e'>E</link>
23 <link linkend='var-glossary-f'>F</link>
24<!-- <link linkend='var-glossary-g'>G</link> -->
25 <link linkend='var-glossary-h'>H</link>
26 <link linkend='var-glossary-i'>I</link>
27<!-- <link linkend='var-glossary-j'>J</link> -->
28 <link linkend='var-glossary-k'>K</link>
29 <link linkend='var-glossary-l'>L</link>
30 <link linkend='var-glossary-m'>M</link>
31<!-- <link linkend='var-glossary-n'>N</link> -->
32<!-- <link linkend='var-glossary-o'>O</link> -->
33 <link linkend='var-glossary-p'>P</link>
34<!-- <link linkend='var-glossary-q'>Q</link> -->
35 <link linkend='var-glossary-r'>R</link>
36 <link linkend='var-glossary-s'>S</link>
37 <link linkend='var-glossary-t'>T</link>
38<!-- <link linkend='var-glossary-u'>U</link> -->
39<!-- <link linkend='var-glossary-v'>V</link> -->
40 <link linkend='var-glossary-w'>W</link>
41<!-- <link linkend='var-glossary-x'>X</link> -->
42<!-- <link linkend='var-glossary-y'>Y</link> -->
43<!-- <link linkend='var-glossary-z'>Z</link>-->
44 </para>
45
46 <glossdiv id='var-glossary-a'><title>A</title>
47
48 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
49 <glossdef>
50 <para>E-mail address to contact original author(s) - to
51 send patches, forward bugs...</para>
52 </glossdef>
53 </glossentry>
54
55 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
56 <glossdef>
57 <para>Use current (newest) source revision - used with
58 <glossterm><link linkend='var-SRCREV'>SRCREV</link></glossterm>
59 variable.</para>
60 </glossdef>
61 </glossentry>
62
63 </glossdiv>
64
65 <glossdiv id='var-glossary-b'><title>B</title>
66
67 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
68 <glossdef>
69 <para>Number of BitBake threads</para>
70 </glossdef>
71 </glossentry>
72
73 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
74 <glossdef>
75 <para>List of recipes used by BitBake to build software</para>
76 </glossdef>
77 </glossentry>
78
79 <!-- BBPATH is not a usable variable in .bb files and should not be listed here -->
80
81 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
82 <glossdef>
83 <para>Variable which controls how BitBake displays logs on build failure.</para>
84 </glossdef>
85 </glossentry>
86
87 </glossdiv>
88
89 <glossdiv id='var-glossary-c'><title>C</title>
90
91 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
92 <glossdef>
93 <para>
94 Flags passed to C compiler for the target system. Evaluates to the same
95 as <link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link>.
96 </para>
97 </glossdef>
98 </glossentry>
99
100 <glossentry id='var-COMPATIBLE_MACHINES'><glossterm>COMPATIBLE_MACHINES</glossterm>
101 <glossdef>
102 <para>A regular expression which evalutates to match the machines the recipe
103 works with. It stops recipes being run on machines they're incompatible with
104 which is partciuarly useful with kernels. It also helps to to increase parsing
105 speed as if its found the current machine is not compatible, further parsing
106 of the recipe is skipped.</para>
107 </glossdef>
108 </glossentry>
109
110 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
111 <glossdef>
112 <para>
113 Contains a list of files which containing autoconf test results relevant
114 to the current build. This variable is used by the autotools utilities
115 when running configure.
116 </para>
117 </glossdef>
118 </glossentry>
119
120
121 <glossentry id='var-CVS_TARBALL_STASH'><glossterm>CVS_TARBALL_STASH</glossterm>
122 <glossdef>
123 <para>Location to search for
124 pre-generated tarballs when fetching from remote SCM
125 repositories (CVS/SVN/GIT)</para>
126 </glossdef>
127 </glossentry>
128
129 </glossdiv>
130
131 <glossdiv id='var-glossary-d'><title>D</title>
132
133 <glossentry id='var-D'><glossterm>D</glossterm>
134 <glossdef>
135 <para>Destination directory</para>
136 </glossdef>
137 </glossentry>
138
139 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
140 <glossdef>
141 <para>
142 Build packages with debugging information. This influences the value
143 <link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link>
144 takes.
145 </para>
146 </glossdef>
147 </glossentry>
148
149 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
150 <glossdef>
151 <para>
152 The options to pass in <link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link>
153 and <link linkend='var-CFLAGS'>CFLAGS</link> when compiling a system for debugging.
154 This defaults to "-O -fno-omit-frame-pointer -g".
155 </para>
156 </glossdef>
157 </glossentry>
158
159 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
160 <glossdef>
161 <para>Priority of recipe</para>
162 </glossdef>
163 </glossentry>
164
165 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
166 <glossdef>
167 <para>
168 A list of build time dependencies for a given recipe. These indicate
169 recipes that must have staged before this recipe can configure.
170 </para>
171 </glossdef>
172 </glossentry>
173
174 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
175 <glossdef>
176 <para>Package description used by package
177 managers</para>
178 </glossdef>
179 </glossentry>
180
181 <glossentry id='var-DESTDIR'><glossterm>DESTDIR</glossterm>
182 <glossdef>
183 <para>Destination directory</para>
184 </glossdef>
185 </glossentry>
186
187 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
188 <glossdef>
189 <para>Short name of distribution</para>
190 </glossdef>
191 </glossentry>
192
193 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
194 <glossdef>
195 <para>List of packages required by distribution.</para>
196 </glossdef>
197 </glossentry>
198
199 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
200 <glossdef>
201 <para>List of packages which extend usability of
202 image. Those packages will be automatically
203 installed but can be removed by user.</para>
204 </glossdef>
205 </glossentry>
206
207 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
208 <glossdef>
209 <para>Features of the distribution.</para>
210 </glossdef>
211 </glossentry>
212
213 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
214 <glossdef>
215 <para>Long name of distribution</para>
216 </glossdef>
217 </glossentry>
218
219 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
220 <glossdef>
221 <para>Version of distribution</para>
222 </glossdef>
223 </glossentry>
224
225 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
226 <glossdef>
227 <para>Directory where all fetched sources will be stored</para>
228 </glossdef>
229
230 </glossentry>
231 </glossdiv>
232
233 <glossdiv id='var-glossary-e'><title>E</title>
234
235 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
236 <glossdef>
237 <para>Variable which control which locales for glibc are
238 to be generated during build (useful if target device
239 has 64M RAM or less)</para>
240 </glossdef>
241 </glossentry>
242
243 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
244 <glossdef>
245 <para>Additional 'configure' script options</para>
246 </glossdef>
247 </glossentry>
248
249 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
250 <glossdef>
251 <para>Additional GNU make options</para>
252 </glossdef>
253 </glossentry>
254
255 </glossdiv>
256
257 <glossdiv id='var-glossary-f'><title>F</title>
258
259 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
260 <glossdef>
261 <para>list of directories/files which will be placed
262 in packages</para>
263 </glossdef>
264 </glossentry>
265
266 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
267 <glossdef>
268 <para>
269 The options to pass in <link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link>
270 and <link linkend='var-CFLAGS'>CFLAGS</link> when compiling an optimised system.
271 This defaults to "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
272 </para>
273 </glossdef>
274 </glossentry>
275
276 </glossdiv>
277
278<!-- <glossdiv id='var-glossary-g'><title>G</title>-->
279<!-- </glossdiv>-->
280
281 <glossdiv id='var-glossary-h'><title>H</title>
282
283 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
284 <glossdef>
285 <para>Website where more info about package can be found</para>
286 </glossdef>
287 </glossentry>
288
289 </glossdiv>
290
291 <glossdiv id='var-glossary-i'><title>I</title>
292
293 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
294 <glossdef>
295 <para><link linkend="ref-features-image">List of
296 features</link> present in resulting images</para>
297 </glossdef>
298 </glossentry>
299
300 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
301 <glossdef>
302 <para>Formats of rootfs images which we want to have
303 created</para>
304 </glossdef>
305 </glossentry>
306
307 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
308 <glossdef>
309 <para>List of packages used to build image</para>
310 </glossdef>
311 </glossentry>
312
313 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
314 <glossdef>
315 <para>
316 This variable causes the build to not strip binaries in
317 resulting packages.
318 </para>
319 </glossdef>
320 </glossentry>
321
322
323 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
324 <glossdef>
325 <para>
326 This variable causes the named class to be inherited at
327 this point during parsing. Its only valid in configuration
328 files.
329 </para>
330 </glossdef>
331 </glossentry>
332
333
334 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
335 <glossdef>
336 <para>
337 Scope: Used in recipes when using update-rc.d.bbclass. Optional, defaults to PN.
338 </para>
339 <para>
340 A list of the packages which contain initscripts. If multiple
341 packages are specified you need to append the package name
342 to the other INITSCRIPT_* as an override.
343 </para>
344 </glossdef>
345 </glossentry>
346
347 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
348 <glossdef>
349 <para>
350 Scope: Used in recipes when using update-rc.d.bbclass. Mandatory.
351 </para>
352 <para>
353 The filename of the initscript (as installed to ${etcdir}/init.d).
354 </para>
355 </glossdef>
356 </glossentry>
357
358 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
359 <glossdef>
360 <para>
361 Scope: Used in recipes when using update-rc.d.bbclass. Mandatory.
362 </para>
363 <para>
364 Specifies the options to pass to update-rc.d. An example is
365 "start 99 5 2 . stop 20 0 1 6 ." which gives the script a
366 runlevel of 99, starts the script in initlevels 2 and 5 and
367 stops it in levels 0, 1 and 6.
368 </para>
369 </glossdef>
370 </glossentry>
371
372
373 </glossdiv>
374
375<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
376<!-- </glossdiv>-->
377
378 <glossdiv id='var-glossary-k'><title>K</title>
379
380 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
381 <glossdef>
382 <para>The type of kernel to build for a device, usually set by the
383 machine configuration files and defaults to "zImage". This is used
384 when building the kernel and is passed to "make" as the target to
385 build.</para>
386 </glossdef>
387 </glossentry>
388
389 </glossdiv>
390
391 <glossdiv id='var-glossary-l'><title>L</title>
392
393 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
394 <glossdef>
395 <para>List of package source licenses.</para>
396 </glossdef>
397 </glossentry>
398
399 </glossdiv>
400
401 <glossdiv id='var-glossary-m'><title>M</title>
402
403 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
404 <glossdef>
405 <para>Target device</para>
406 </glossdef>
407 </glossentry>
408
409 <glossentry id='var-MACHINE_ESSENTIAL_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_RDEPENDS</glossterm>
410 <glossdef>
411 <para>List of packages required to boot device</para>
412 </glossdef>
413 </glossentry>
414
415 <glossentry id='var-MACHINE_ESSENTIAL_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_RRECOOMENDS</glossterm>
416 <glossdef>
417 <para>List of packages required to boot device (usually
418 additional kernel modules)</para>
419 </glossdef>
420 </glossentry>
421
422 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
423 <glossdef>
424 <para>List of packages required to use device</para>
425 </glossdef>
426 </glossentry>
427
428 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMNEDS</glossterm>
429 <glossdef>
430 <para>List of packages useful to use device (for example
431 additional kernel modules)</para>
432 </glossdef>
433 </glossentry>
434
435 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
436 <glossdef>
437 <para>List of device features - defined in <link
438 linkend='ref-features-machine'>machine
439 features section</link></para>
440 </glossdef>
441 </glossentry>
442
443 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
444 <glossdef>
445 <para>E-mail of distribution maintainer</para>
446 </glossdef>
447 </glossentry>
448 </glossdiv>
449
450<!-- <glossdiv id='var-glossary-n'><title>N</title>-->
451<!-- </glossdiv>-->
452
453<!-- <glossdiv id='var-glossary-o'><title>O</title>-->
454<!-- </glossdiv>-->
455
456 <glossdiv id='var-glossary-p'><title>P</title>
457
458 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
459 <glossdef>
460 <para>Architecture of resulting package</para>
461 </glossdef>
462 </glossentry>
463
464 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
465 <glossdef>
466 <para>List of resulting packages formats</para>
467 </glossdef>
468 </glossentry>
469
470 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
471 <glossdef>
472 <para>List of architectures compatible with device
473 CPU. Usable when build is done for few different
474 devices with misc processors (like XScale and
475 ARM926-EJS)</para>
476 </glossdef>
477 </glossentry>
478
479 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
480 <glossdef>
481 <para>List of packages to be created from recipe.
482 The default value is "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev"</para>
483 </glossdef>
484 </glossentry>
485
486 <glossentry id='var-PN'><glossterm>PN</glossterm>
487 <glossdef>
488 <para>Name of package.
489 </para>
490 </glossdef>
491 </glossentry>
492
493 <glossentry id='var-PR'><glossterm>PR</glossterm>
494 <glossdef>
495 <para>Revision of package.
496 </para>
497 </glossdef>
498 </glossentry>
499
500 <glossentry id='var-PV'><glossterm>PV</glossterm>
501 <glossdef>
502 <para>Version of package.
503 The default value is "1.0"</para>
504 </glossdef>
505 </glossentry>
506
507 <glossentry id='var-PE'><glossterm>PE</glossterm>
508 <glossdef>
509 <para>
510 Epoch of the package. The default value is "1". The field is used
511 to make upgrades possible when the versioning scheme changes in
512 some backwards incompatible way.
513 </para>
514 </glossdef>
515 </glossentry>
516
517 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
518 <glossdef>
519 <para>If multiple recipes provide an item, this variable
520 determines which one should be given preference. It
521 should be set to the "$PN" of the recipe to be preferred.</para>
522 </glossdef>
523 </glossentry>
524
525 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
526 <glossdef>
527 <para>
528 If there are multiple versions of recipe available, this
529 variable determines which one should be given preference. It
530 should be set to the "$PV" of the recipe to be preferred.
531 </para>
532 </glossdef>
533 </glossentry>
534
535 <glossentry id='var-POKYLIBC'><glossterm>POKYLIBC</glossterm>
536 <glossdef>
537 <para>Libc implementation selector - glibc or uclibc can be selected.</para>
538 </glossdef>
539 </glossentry>
540
541 <glossentry id='var-POKYMODE'><glossterm>POKYMODE</glossterm>
542 <glossdef>
543 <para>Toolchain selector. It can be external toolchain
544 built from Poky or few supported combinations of
545 upstream GCC or CodeSourcery Labs toolchain.</para>
546 </glossdef>
547 </glossentry>
548
549 </glossdiv>
550
551<!-- <glossdiv id='var-glossary-q'><title>Q</title>-->
552<!-- </glossdiv>-->
553
554 <glossdiv id='var-glossary-r'><title>R</title>
555
556 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
557 <glossdef>
558 <para>List of packages which which conflict with this
559 one. Package will not be installed if they will not
560 be removed first.</para>
561 </glossdef>
562 </glossentry>
563
564 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
565 <glossdef>
566 <para>
567 A list of run-time dependencies for a package. These packages
568 need to be installed alongside the package it applies to so
569 the package will run correctly, an example is a perl script
570 which would rdepend on perl. Since this variable applies to
571 output packages there would usually be an override attached
572 to this variable like RDEPENDS_${PN}-dev. Names in this field
573 should be as they are in <link linkend='var-PACKAGES'>PACKAGES
574 </link> namespave before any renaming of the output package
575 by classes like debian.bbclass.
576 </para>
577 </glossdef>
578 </glossentry>
579
580 <glossentry id='var-ROOT_FLASH_SIZE'><glossterm>ROOT_FLASH_SIZE</glossterm>
581 <glossdef>
582 <para>Size of rootfs in megabytes</para>
583 </glossdef>
584 </glossentry>
585
586 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
587 <glossdef>
588 <para>List of packages which extend usability of
589 package. Those packages will be automatically
590 installed but can be removed by user.</para>
591 </glossdef>
592 </glossentry>
593
594 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
595 <glossdef>
596 <para>List of packages which are replaced with this
597 one.</para>
598 </glossdef>
599 </glossentry>
600
601 </glossdiv>
602
603 <glossdiv id='var-glossary-s'><title>S</title>
604
605 <glossentry id='var-S'><glossterm>S</glossterm>
606 <glossdef>
607 <para>
608 Path to unpacked sources (by default:
609 "${<link linkend='var-WORKDIR'>WORKDIR</link>}/${<link linkend='var-PN'>PN</link>}-${<link linkend='var-PV'>PV</link>}")
610 </para>
611 </glossdef>
612 </glossentry>
613
614 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
615 <glossdef>
616 <para>Section where package should be put - used
617 by package managers</para>
618 </glossdef>
619 </glossentry>
620
621 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
622 <glossdef>
623 <para>
624 The variable takes the value of <link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link>
625 unless <link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link> = "1" in which case
626 <link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link> is used.
627 </para>
628 </glossdef>
629 </glossentry>
630
631
632 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
633 <glossdef>
634 <para>Speed and device for serial port used to attach
635 serial console. This is given to kernel as "console"
636 param and after boot getty is started on that port
637 so remote login is possible.</para>
638 </glossdef>
639 </glossentry>
640
641 <glossentry id='var-SHELLCMDS'><glossterm>SHELLCMDS</glossterm>
642 <glossdef>
643 <para>
644 A list of commands to run within the a shell, used by <glossterm><link
645 linkend='var-TERMCMDRUN'>TERMCMDRUN</link></glossterm>. It defaults to
646 <glossterm><link linkend='var-SHELLRCCMD'>SHELLRCCMD</link></glossterm>.
647 </para>
648 </glossdef>
649 </glossentry>
650
651 <glossentry id='var-SHELLRCCMD'><glossterm>SHELLRCCMD</glossterm>
652 <glossdef>
653 <para>
654 How to launch a shell, defaults to bash.
655 </para>
656 </glossdef>
657 </glossentry>
658
659 <glossentry id='var-SITEINFO_ENDIANESS'><glossterm>SITEINFO_ENDIANESS</glossterm>
660 <glossdef>
661 <para>
662 Contains "le" for little-endian or "be" for big-endian depending
663 on the endian byte order of the target system.
664 </para>
665 </glossdef>
666 </glossentry>
667
668 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
669 <glossdef>
670 <para>
671 Contains "32" or "64" depending on the number of bits for the
672 CPU of the target system.
673 </para>
674 </glossdef>
675 </glossentry>
676
677 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
678 <glossdef>
679 <para>List of source files (local or remote ones)</para>
680 </glossdef>
681 </glossentry>
682
683 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
684 <glossdef>
685 <para>
686 By default there is code which automatically detects whether
687 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>
688 contains files which are machine specific and if this is the case it
689 automatically changes
690 <glossterm><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></glossterm>.
691 Setting this variable to "0" disables that behaviour.
692 </para>
693 </glossdef>
694 </glossentry>
695
696 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
697 <glossdef>
698 <para>
699 Date of source code used to build package (if it was fetched
700 from SCM).
701 </para>
702 </glossdef>
703 </glossentry>
704
705 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
706 <glossdef>
707 <para>
708 Revision of source code used to build package (Subversion,
709 GIT, Bazaar only).
710 </para>
711 </glossdef>
712 </glossentry>
713
714 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
715 <glossdef>
716 <para>
717 Directory with kernel headers required to build out-of-tree
718 modules.
719 </para>
720 </glossdef>
721 </glossentry>
722
723 <glossentry id='var-STAMPS'><glossterm>STAMPS</glossterm>
724 <glossdef>
725 <para>
726 Directory (usually TMPDIR/stamps) with timestamps of
727 executed tasks.
728 </para>
729 </glossdef>
730 </glossentry>
731
732 </glossdiv>
733
734 <glossdiv id='var-glossary-t'><title>T</title>
735
736 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
737 <glossdef>
738 <para>The architecture of the device we're building for.
739 A number of values are possible but Poky primarily supports
740 "arm" and "i586".</para>
741 </glossdef>
742 </glossentry>
743
744 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
745 <glossdef>
746 <para>
747 Flags passed to C compiler for the target system. Evaluates to the same
748 as <link linkend='var-CFLAGS'>CFLAGS</link>.
749 </para>
750 </glossdef>
751 </glossentry>
752
753
754 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
755 <glossdef>
756 <para>Method of handling FPU code. For FPU-less targets
757 (most of ARM cpus) it has to be set to "soft" otherwise
758 kernel emulation will get used which will result in
759 performance penalty.</para>
760 </glossdef>
761 </glossentry>
762
763 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
764 <glossdef>
765 <para>Type of target operating system. Can be "linux"
766 for glibc based system, "linux-uclibc" for uClibc. For
767 ARM/EABI targets there are also "linux-gnueabi" and
768 "linux-uclibc-gnueabi" values possible.</para>
769 </glossdef>
770 </glossentry>
771
772 <glossentry id='var-TERMCMD'><glossterm>TERMCMD</glossterm>
773 <glossdef>
774 <para>
775 This command is used by bitbake to lauch a terminal window with a
776 shell. The shell is unspecified so the user's default shell is used.
777 By default it is set to <command>gnome-terminal</command> but it can
778 be any X11 terminal application or terminal multiplexers like screen.
779 </para>
780 </glossdef>
781 </glossentry>
782
783 <glossentry id='var-TERMCMDRUN'><glossterm>TERMCMDRUN</glossterm>
784 <glossdef>
785 <para>
786 This command is similar to <glossterm><link
787 linkend='var-TERMCMD'>TERMCMD</link></glossterm> however instead of the users shell it runs the command specified by the <glossterm><link
788 linkend='var-SHELLCMDS'>SHELLCMDS</link></glossterm> variable.
789 </para>
790 </glossdef>
791 </glossentry>
792
793 </glossdiv>
794
795<!-- <glossdiv id='var-glossary-u'><title>U</title>-->
796<!-- </glossdiv>-->
797
798<!-- <glossdiv id='var-glossary-v'><title>V</title>-->
799<!-- </glossdiv>-->
800
801 <glossdiv id='var-glossary-w'><title>W</title>
802
803 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
804 <glossdef>
805 <para>Path to directory in tmp/work/ where package
806 will be built.</para>
807 </glossdef>
808 </glossentry>
809
810 </glossdiv>
811
812<!-- <glossdiv id='var-glossary-x'><title>X</title>-->
813<!-- </glossdiv>-->
814
815<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
816<!-- </glossdiv>-->
817
818<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
819<!-- </glossdiv>-->
820
821</glossary>
822</appendix>
823<!--
824vim: expandtab tw=80 ts=4
825-->
diff --git a/handbook/ref-varlocality.xml b/handbook/ref-varlocality.xml
new file mode 100644
index 0000000000..a0c185694b
--- /dev/null
+++ b/handbook/ref-varlocality.xml
@@ -0,0 +1,204 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='ref-varlocality'>
5 <title>Reference: Variable Locality (Distro, Machine, Recipe etc.)</title>
6
7 <para>
8 Whilst most variables can be used in almost any context (.conf, .bbclass,
9 .inc or .bb file), variables are often associated with a particular
10 locality/context. This section describes some common associations.
11 </para>
12
13 <section id='ref-varlocality-config-distro'>
14 <title>Distro Configuration</title>
15
16 <itemizedlist>
17 <listitem>
18 <para><glossterm linkend='var-DISTRO'><link linkend='var-DISTRO'>DISTRO</link></glossterm></para>
19 </listitem>
20 <listitem>
21 <para><glossterm linkend='var-DISTRO_NAME'><link linkend='var-DISTRO_NAME'>DISTRO_NAME</link></glossterm></para>
22 </listitem>
23 <listitem>
24 <para><glossterm linkend='var-DISTRO_VERSION'><link linkend='var-DISTRO_VERSION'>DISTRO_VERSION</link></glossterm></para>
25 </listitem>
26 <listitem>
27 <para><glossterm linkend='var-MAINTAINER'><link linkend='var-MAINTAINER'>MAINTAINER</link></glossterm></para>
28 </listitem>
29 <listitem>
30 <para><glossterm linkend='var-PACKAGE_CLASSES'><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></glossterm></para>
31 </listitem>
32 <listitem>
33 <para><glossterm linkend='var-TARGET_OS'><link linkend='var-TARGET_OS'>TARGET_OS</link></glossterm></para>
34 </listitem>
35 <listitem>
36 <para><glossterm linkend='var-TARGET_FPU'><link linkend='var-TARGET_FPU'>TARGET_FPU</link></glossterm></para>
37 </listitem>
38 <listitem>
39 <para><glossterm linkend='var-POKYMODE'><link linkend='var-POKYMODE'>POKYMODE</link></glossterm></para>
40 </listitem>
41 <listitem>
42 <para><glossterm linkend='var-POKYLIBC'><link linkend='var-POKYLIBC'>POKYLIBC</link></glossterm></para>
43 </listitem>
44 </itemizedlist>
45 </section>
46
47 <section id='ref-varlocality-config-machine'>
48 <title>Machine Configuration</title>
49
50 <itemizedlist>
51 <listitem>
52 <para><glossterm linkend='var-TARGET_ARCH'><link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm></para>
53 </listitem>
54 <listitem>
55 <para><glossterm linkend='var-SERIAL_CONSOLE'><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE</link></glossterm></para>
56 </listitem>
57 <listitem>
58 <para><glossterm linkend='var-PACKAGE_EXTRA_ARCHS'><link linkend='var-PACKAGE_EXTRA_ARCHS'>PACKAGE_EXTRA_ARCHS</link></glossterm></para>
59 </listitem>
60 <listitem>
61 <para><glossterm linkend='var-IMAGE_FSTYPES'><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></glossterm></para>
62 </listitem>
63 <listitem>
64 <para><glossterm linkend='var-ROOT_FLASH_SIZE'><link linkend='var-ROOT_FLASH_SIZE'>ROOT_FLASH_SIZE</link></glossterm></para>
65 </listitem>
66 <listitem>
67 <para><glossterm linkend='var-MACHINE_FEATURES'><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></glossterm></para>
68 </listitem>
69 <listitem>
70 <para><glossterm linkend='var-MACHINE_EXTRA_RDEPENDS'><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></glossterm></para>
71 </listitem>
72 <listitem>
73 <para><glossterm linkend='var-MACHINE_EXTRA_RRECOMMENDS'><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></glossterm></para>
74 </listitem>
75 <listitem>
76 <para><glossterm linkend='var-MACHINE_ESSENTIAL_RDEPENDS'><link linkend='var-MACHINE_ESSENTIAL_RDEPENDS'>MACHINE_ESSENTIAL_RDEPENDS</link></glossterm></para>
77 </listitem>
78 <listitem>
79 <para><glossterm linkend='var-MACHINE_ESSENTIAL_RRECOMMENDS'><link linkend='var-MACHINE_ESSENTIAL_RRECOMMENDS'>MACHINE_ESSENTIAL_RRECOMMENDS</link></glossterm></para>
80 </listitem>
81 </itemizedlist>
82 </section>
83
84 <section id='ref-varlocality-config-local'>
85 <title>Local Configuration (local.conf)</title>
86 <itemizedlist>
87 <listitem>
88 <para><glossterm linkend='var-DISTRO'><link linkend='var-DISTRO'>DISTRO</link></glossterm></para>
89 </listitem>
90 <listitem>
91 <para><glossterm linkend='var-MACHINE'><link linkend='var-MACHINE'>MACHINE</link></glossterm></para>
92 </listitem>
93 <listitem>
94 <para><glossterm linkend='var-DL_DIR'><link linkend='var-DL_DIR'>DL_DIR</link></glossterm></para>
95 </listitem>
96 <listitem>
97 <para><glossterm linkend='var-BBFILES'><link linkend='var-BBFILES'>BBFILES</link></glossterm></para>
98 </listitem>
99 <listitem>
100 <para><glossterm linkend='var-IMAGE_FEATURES'><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm></para>
101 </listitem>
102 <listitem>
103 <para><glossterm linkend='var-PACKAGE_CLASSES'><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></glossterm></para>
104 </listitem>
105 <listitem>
106 <para><glossterm linkend='var-BB_NUMBER_THREADS'><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm></para>
107 </listitem>
108 <listitem>
109 <para><glossterm linkend='var-BBINCLUDELOGS'><link linkend='var-BBINCLUDELOGS'>BBINCLUDELOGS</link></glossterm></para>
110 </listitem>
111 <listitem>
112 <para><glossterm linkend='var-CVS_TARBALL_STASH'><link linkend='var-CVS_TARBALL_STASH'>CVS_TARBALL_STASH</link></glossterm></para>
113 </listitem>
114 <listitem>
115 <para><glossterm linkend='var-ENABLE_BINARY_LOCALE_GENERATION'><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link></glossterm></para>
116 </listitem>
117 </itemizedlist>
118 </section>
119
120 <section id='ref-varlocality-recipe-required'>
121 <title>Recipe Variables - Required</title>
122
123 <itemizedlist>
124 <listitem>
125 <para><glossterm><link linkend='var-DESCRIPTION'>DESCRIPTION</link></glossterm></para>
126 </listitem>
127 <listitem>
128 <para><glossterm><link linkend='var-LICENSE'>LICENSE</link></glossterm></para>
129 </listitem>
130 <listitem>
131 <para><glossterm><link linkend='var-SECTION'>SECTION</link></glossterm></para>
132 </listitem>
133 <listitem>
134 <para><glossterm><link linkend='var-HOMEPAGE'>HOMEPAGE</link></glossterm></para>
135 </listitem>
136 <listitem>
137 <para><glossterm><link linkend='var-AUTHOR'>AUTHOR</link></glossterm></para>
138 </listitem>
139 <listitem>
140 <para><glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm></para>
141 </listitem>
142 </itemizedlist>
143 </section>
144
145 <section id='ref-varlocality-recipe-dependencies'>
146 <title>Recipe Variables - Dependencies</title>
147
148 <itemizedlist>
149 <listitem>
150 <para><glossterm><link linkend='var-DEPENDS'>DEPENDS</link></glossterm></para>
151 </listitem>
152 <listitem>
153 <para><glossterm><link linkend='var-RDEPENDS'>RDEPENDS</link></glossterm></para>
154 </listitem>
155 <listitem>
156 <para><glossterm><link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></glossterm></para>
157 </listitem>
158 <listitem>
159 <para><glossterm><link linkend='var-RCONFLICTS'>RCONFLICTS</link></glossterm></para>
160 </listitem>
161 <listitem>
162 <para><glossterm><link linkend='var-RREPLACES'>RREPLACES</link></glossterm></para>
163 </listitem>
164 </itemizedlist>
165 </section>
166
167 <section id='ref-varlocality-recipe-paths'>
168 <title>Recipe Variables - Paths</title>
169
170 <itemizedlist>
171 <listitem>
172 <para><glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm></para>
173 </listitem>
174 <listitem>
175 <para><glossterm><link linkend='var-S'>S</link></glossterm></para>
176 </listitem>
177 <listitem>
178 <para><glossterm><link linkend='var-FILES'>FILES</link></glossterm></para>
179 </listitem>
180 </itemizedlist>
181 </section>
182
183 <section id='ref-varlocality-recipe-build'>
184 <title>Recipe Variables - Extra Build Information</title>
185
186 <itemizedlist>
187 <listitem>
188 <para><glossterm><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></glossterm></para>
189 </listitem>
190 <listitem>
191 <para><glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm></para>
192 </listitem>
193 <listitem>
194 <para><glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm></para>
195 </listitem>
196 <listitem>
197 <para><glossterm><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm></para>
198 </listitem>
199 </itemizedlist>
200 </section>
201</appendix>
202<!--
203vim: expandtab tw=80 ts=4 spell spelllang=en_gb
204-->
diff --git a/handbook/resources.xml b/handbook/resources.xml
new file mode 100644
index 0000000000..6d06364ae5
--- /dev/null
+++ b/handbook/resources.xml
@@ -0,0 +1,92 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<appendix id='resources'>
5<title>Contributing to Poky</title>
6
7<section id='resources-intro'>
8 <title>Introduction</title>
9 <para>
10 We're happy for people to experiment with Poky and there are a number of places to
11 find help if you run into difficulties or find bugs. To find out how to download
12 source code see the <link linkend='intro-getit'>Obtaining Poky</link> section of
13 the Introduction.
14 </para>
15</section>
16
17<section id='resources-bugtracker'>
18 <title>Bugtracker</title>
19
20 <para>
21 Problems with Poky should be reported in the
22 <ulink url='http://bugzilla.o-hand.com/'>bug tracker</ulink>.
23 </para>
24</section>
25
26<section id='resources-mailinglist'>
27 <title>Mailing list</title>
28
29 <para>
30 To subscribe to the mailing list send mail to:
31 </para>
32 <para>
33 <literallayout class='monospaced'>
34poky+subscribe &lt;at&gt; openedhand &lt;dot&gt; com
35 </literallayout>
36 </para>
37 <para>
38 Then follow the simple instructions in subsequent reply. Archives are
39 available <ulink
40 url="http://lists.o-hand.com/poky/">here</ulink>.
41 </para>
42</section>
43
44<section id='resources-irc'>
45 <title>IRC</title>
46
47 <para>
48 Join #poky on freenode.
49 </para>
50</section>
51
52<section id='resources-links'>
53 <title>Links</title>
54
55 <itemizedlist>
56 <listitem><para>
57 <ulink url='http://pokylinux.org'>The Poky website</ulink>
58 </para></listitem>
59 <listitem><para>
60 <ulink url='http://www.openedhand.com/'>OpenedHand</ulink> - The
61 company behind Poky.
62 </para></listitem>
63 <listitem><para>
64 <ulink url='http://www.openembedded.org/'>OpenEmbedded</ulink>
65 - The upstream generic embedded distribution Poky derives
66 from (and contributes to).
67 </para></listitem>
68 <listitem><para>
69 <ulink url='http://developer.berlios.de/projects/bitbake/'>Bitbake</ulink>
70 - The tool used to process Poky metadata.
71 </para></listitem>
72 <listitem><para>
73 <ulink url='http://bitbake.berlios.de/manual/'>Bitbake User
74 Manual</ulink>
75 </para></listitem>
76 <listitem><para>
77 <ulink url='http://pimlico-project.org/'>Pimlico</ulink> - A
78 suite of lightweight Personal Information Management (PIM)
79 applications designed primarily for handheld and mobile
80 devices.
81 </para></listitem>
82 <listitem><para>
83 <ulink url='http://fabrice.bellard.free.fr/qemu/'>QEMU</ulink>
84 - An open source machine emulator and virtualizer.
85 </para></listitem>
86 </itemizedlist>
87</section>
88
89</appendix>
90<!--
91vim: expandtab tw=80 ts=4
92-->
diff --git a/handbook/style.css b/handbook/style.css
new file mode 100644
index 0000000000..fb95694f9c
--- /dev/null
+++ b/handbook/style.css
@@ -0,0 +1,957 @@
1/*
2 Generic XHTML / DocBook XHTML CSS Stylesheet.
3
4 Browser wrangling and typographic design by
5 Oyvind Kolas / pippin@gimp.org
6
7 Customised for Poky by
8 Matthew Allum / mallum@o-hand.com
9
10 Thanks to:
11 Liam R. E. Quin
12 William Skaggs
13 Jakub Steiner
14
15 Structure
16 ---------
17
18 The stylesheet is divided into the following sections:
19
20 Positioning
21 Margins, paddings, width, font-size, clearing.
22 Decorations
23 Borders, style
24 Colors
25 Colors
26 Graphics
27 Graphical backgrounds
28 Nasty IE tweaks
29 Workarounds needed to make it work in internet explorer,
30 currently makes the stylesheet non validating, but up until
31 this point it is validating.
32 Mozilla extensions
33 Transparency for footer
34 Rounded corners on boxes
35
36*/
37
38
39 /*************** /
40 / Positioning /
41/ ***************/
42
43body {
44 font-family: Verdana, Sans, sans-serif;
45
46 min-width: 640px;
47 width: 80%;
48 margin: 0em auto;
49 padding: 2em 5em 5em 5em;
50 color: #333;
51}
52
53h1,h2,h3,h4,h5,h6,h7 {
54 font-family: Arial, Sans;
55 color:#999999;
56 clear: both;
57}
58
59h1 {
60 font-size: 2em;
61 text-align: left;
62 padding: 0em 0em 0em 0em;
63 margin: 2em 0em 0em 0em;
64}
65
66h2.subtitle {
67 margin: 0.10em 0 3.0em 0;
68 padding: 0 0 0 0;
69 font-size: 1.8em;
70 padding-left: 20%;
71 font-weight: normal;
72 font-style: italic;
73}
74
75h2 {
76 margin: 2em 0em 0.66em 0em;
77 padding: 0.5em 0em 0em 0em;
78 font-size: 1.5em;
79 font-weight: normal;
80}
81
82h3.subtitle {
83 margin: 0em 0em 1em 0em;
84 padding: 0em 0em 0em 0em;
85 font-size: 142.14%;
86 text-align : right;
87}
88
89h3 {
90 margin: 1em 0em 0.5em 0em;
91 padding: 1em 0em 0em 0em;
92 font-size: 140%;
93 font-weight: normal;
94}
95
96h4 {
97 margin: 1em 0em 0.5em 0em;
98 padding: 1em 0em 0em 0em;
99 font-size: 120%;
100 font-weight: normal;
101}
102
103h5 {
104 margin: 1em 0em 0.5em 0em;
105 padding: 1em 0em 0em 0em;
106 font-size: 110.000%;
107 border-bottom: 1px solid black;
108}
109
110h6 {
111 margin: 1em 0em 0em 0em;
112 padding: 1em 0em 0em 0em;
113 font-size: 80%;
114 font-weight: normal;
115}
116
117.authorgroup {
118 background-color: transparent;
119 background-repeat: no-repeat;
120 padding-top: 256;
121 background-image: url("poky-beaver.png");
122 background-position: right top;
123 float: right;
124 margin-top: -256px;
125 padding-right: 50px;
126 margin-left: 50px;
127 text-align: right;
128 width: 200px;
129}
130
131h3.author {
132 margin: 0 0 0 0;
133 padding: 0 0 0 0;
134 font-weight: normal;
135 font-size: 100%;
136 clear: both;
137}
138
139.author tt.email {
140 font-size: 66%;
141}
142
143.titlepage hr {
144 width: 0;
145 clear: both;
146}
147
148.revhistory {
149 padding-top: 2em;
150 clear: both;
151}
152
153.toc,
154.list-of-tables,
155.list-of-examples,
156.list-of-figures {
157 padding: 1.33em 0em 2.5em 0em;
158}
159
160.toc p,
161.list-of-tables p,
162.list-of-figures p,
163.list-of-examples p {
164 padding: 0 0 0 0;
165 padding: 0em 0em 0.3em;
166 margin: 1.5em 0 0 0;
167}
168
169.toc p b,
170.list-of-tables p b,
171.list-of-figures p b,
172.list-of-examples p b{
173 font-size: 100.0%;
174 font-weight: bold;
175}
176
177.toc dl,
178.list-of-tables dl,
179.list-of-figures dl,
180.list-of-examples dl {
181 margin: 0 0 0.5em 0;
182 padding: 0 0 0 0;
183}
184
185.toc dt {
186 margin: 0 0 0 0;
187 padding: 0 0 0 0;
188}
189
190.toc dd {
191 margin: 0em 0em 0em 2.6em;
192 padding: 0 0 0 0;
193}
194
195div.glossary dl,
196div.variablelist dl {
197}
198
199.glossary dl dt,
200.variablelist dl dt,
201.variablelist dl dt span.term {
202 font-weight: normal;
203 width: 20em;
204 text-align: right;
205}
206
207.variablelist dl dt {
208 margin-top: 0.5em;
209}
210
211.glossary dl dd,
212.variablelist dl dd {
213 margin-top: -1em;
214 margin-left: 25.5em;
215}
216
217.glossary dd p,
218.variablelist dd p {
219 margin-top: 0em;
220 margin-bottom: 1em;
221}
222
223
224div.calloutlist table td {
225 padding: 0 0 0 0;
226 margin: 0 0 0 0;
227}
228
229div.calloutlist table td p {
230 margin-top: 0em;
231 margin-bottom: 1em;
232}
233
234div p.copyright {
235 text-align: left;
236}
237
238div.legalnotice p.legalnotice-title {
239 margin-bottom: 0;
240}
241
242p {
243 line-height: 1.5em;
244 margin-top: 0;
245
246}
247
248dl {
249 padding-top: 0em;
250}
251
252hr {
253 border: solid 1px;
254}
255
256
257.mediaobject,
258.mediaobjectco {
259 text-align: center;
260}
261
262img {
263 border: none;
264}
265
266.mediaobject img,
267.mediaobjectco img{
268 max-width: 36em;
269}
270
271ul {
272 padding: 0 0 0 1.5em;
273}
274
275ul li {
276 padding: 0 0 0 0;
277}
278
279ul li p {
280 text-align: left;
281}
282
283table {
284 width :100%;
285}
286
287th {
288 padding: 0.25em;
289 text-align: left;
290 font-weight: normal;
291 vertical-align: top;
292}
293
294td {
295 padding: 0.25em;
296 vertical-align: top;
297}
298
299p a[id] {
300 margin: 0;
301 padding: 0;
302 display: inline;
303 background-image: none;
304}
305
306a {
307 text-decoration: underline;
308 color: #444;
309}
310
311pre {
312 overflow : auto;
313}
314
315a:hover {
316 text-decoration: underline;
317 /*font-weight: bold;*/
318}
319
320
321div.informalfigure,
322div.informalexample,
323div.informaltable,
324div.figure,
325div.table,
326div.example {
327 margin: 1em 0em;
328 padding: 1em;
329 page-break-inside: avoid;
330}
331
332
333div.informalfigure p.title b,
334div.informalexample p.title b,
335div.informaltable p.title b,
336div.figure p.title b,
337div.example p.title b,
338div.table p.title b{
339 padding-top: 0;
340 margin-top: 0;
341 font-size: 100%;
342 font-weight: normal;
343}
344
345.mediaobject .caption,
346.mediaobject .caption p {
347 text-align: left;
348 padding-top: 0.5em;
349 padding-bottom: 0.5em;
350}
351
352.epigraph {
353 padding-left: 55%;
354 margin-bottom: 1em;
355}
356
357.epigraph p {
358 text-align: left;
359}
360
361.epigraph .quote {
362 font-style: italic;
363}
364.epigraph .attribution {
365 font-style: normal;
366 text-align: right;
367}
368
369span.application {
370 font-style: italic;
371}
372
373.programlisting {
374 font-family: monospace;
375 font-size: 80%;
376 white-space: pre;
377 margin: 1.33em 0em;
378 padding: 1.33em;
379}
380
381.tip,
382.warning,
383.caution,
384.note {
385 margin-top: 1em;
386 margin-bottom: 1em;
387
388}
389
390/* force full width of table within div */
391.tip table,
392.warning table,
393.caution table,
394.note table {
395 border: none;
396 width: 100%;
397}
398
399
400.tip table th,
401.warning table th,
402.caution table th,
403.note table th {
404 padding: 0.8em 0.0em 0.0em 0.0em;
405 margin : 0 0 0 0;
406}
407
408.tip p,
409.warning p,
410.caution p,
411.note p {
412 margin-top: 0.5em;
413 margin-bottom: 0.5em;
414 padding-right: 1em;
415 text-align: left;
416}
417
418.acronym {
419 text-transform: uppercase;
420}
421
422b.keycap,
423.keycap {
424 padding: 0.09em 0.3em;
425 margin: 0;
426}
427
428.itemizedlist li {
429 clear: none;
430}
431
432.filename {
433 font-size: medium;
434 font-family: Courier, monospace;
435}
436
437
438div.navheader, div.heading{
439 position: absolute;
440 left: 0;
441 top: 0;
442 width: 100%;
443 background-color: #cdf;
444 width: 100%;
445}
446
447div.navfooter, div.footing{
448 position: fixed;
449 left: 0em;
450 bottom: 0em;
451 background-color: #eee;
452 width: 100%;
453}
454
455
456div.navheader td,
457div.navfooter td {
458 font-size: 66%;
459}
460
461div.navheader table th {
462 /*font-family: Georgia, Times, serif;*/
463 /*font-size: x-large;*/
464 font-size: 80%;
465}
466
467div.navheader table {
468 border-left: 0;
469 border-right: 0;
470 border-top: 0;
471 width: 100%;
472}
473
474div.navfooter table {
475 border-left: 0;
476 border-right: 0;
477 border-bottom: 0;
478 width: 100%;
479}
480
481div.navheader table td a,
482div.navfooter table td a {
483 color: #777;
484 text-decoration: none;
485}
486
487/* normal text in the footer */
488div.navfooter table td {
489 color: black;
490}
491
492div.navheader table td a:visited,
493div.navfooter table td a:visited {
494 color: #444;
495}
496
497
498/* links in header and footer */
499div.navheader table td a:hover,
500div.navfooter table td a:hover {
501 text-decoration: underline;
502 background-color: transparent;
503 color: #33a;
504}
505
506div.navheader hr,
507div.navfooter hr {
508 display: none;
509}
510
511
512.qandaset tr.question td p {
513 margin: 0 0 1em 0;
514 padding: 0 0 0 0;
515}
516
517.qandaset tr.answer td p {
518 margin: 0 0 1em 0;
519 padding: 0 0 0 0;
520}
521.answer td {
522 padding-bottom: 1.5em;
523}
524
525.emphasis {
526 font-weight: bold;
527}
528
529
530 /************* /
531 / decorations /
532/ *************/
533
534.titlepage {
535}
536
537.part .title {
538}
539
540.subtitle {
541 border: none;
542}
543
544/*
545h1 {
546 border: none;
547}
548
549h2 {
550 border-top: solid 0.2em;
551 border-bottom: solid 0.06em;
552}
553
554h3 {
555 border-top: 0em;
556 border-bottom: solid 0.06em;
557}
558
559h4 {
560 border: 0em;
561 border-bottom: solid 0.06em;
562}
563
564h5 {
565 border: 0em;
566}
567*/
568
569.programlisting {
570 border: solid 1px;
571}
572
573div.figure,
574div.table,
575div.informalfigure,
576div.informaltable,
577div.informalexample,
578div.example {
579 border : 1px solid;
580}
581
582
583
584.tip,
585.warning,
586.caution,
587.note {
588 border : 1px solid;
589}
590
591.tip table th,
592.warning table th,
593.caution table th,
594.note table th {
595 border-bottom : 1px solid;
596}
597
598.question td {
599 border-top: 1px solid black;
600}
601
602.answer {
603}
604
605
606b.keycap,
607.keycap {
608 border: 1px solid;
609}
610
611
612div.navheader, div.heading{
613 border-bottom: 1px solid;
614}
615
616
617div.navfooter, div.footing{
618 border-top: 1px solid;
619}
620
621 /********* /
622 / colors /
623/ *********/
624
625body {
626 color: #333;
627 background: white;
628}
629
630a {
631 background: transparent;
632}
633
634a:hover {
635 background-color: #dedede;
636}
637
638
639h1,
640h2,
641h3,
642h4,
643h5,
644h6,
645h7,
646h8 {
647 background-color : transparent;
648}
649
650hr {
651 border-color: #aaa;
652}
653
654
655.tip, .warning, .caution, .note {
656 border-color : #aaa;
657}
658
659
660.tip table th,
661.warning table th,
662.caution table th,
663.note table th {
664 border-bottom-color: #aaa;
665}
666
667
668.warning {
669 background-color: #fea;
670}
671
672.caution {
673 background-color: #fea;
674}
675
676.tip {
677 background-color: #eff;
678}
679
680.note {
681 background-color: #dfc;
682}
683
684.glossary dl dt,
685.variablelist dl dt,
686.variablelist dl dt span.term {
687 color: #044;
688}
689
690div.figure,
691div.table,
692div.example,
693div.informalfigure,
694div.informaltable,
695div.informalexample {
696 border-color: #aaa;
697}
698
699pre.programlisting {
700 color: black;
701 background-color: #fff;
702 border-color: #aaa;
703 border-width: 2px;
704}
705
706.guimenu,
707.guilabel,
708.guimenuitem {
709 background-color: #eee;
710}
711
712
713b.keycap,
714.keycap {
715 background-color: #eee;
716 border-color: #999;
717}
718
719
720div.navheader {
721 border-color: black;
722}
723
724
725div.navfooter {
726 border-color: black;
727}
728
729
730 /*********** /
731 / graphics /
732/ ***********/
733
734/*
735body {
736 background-image: url("images/body_bg.jpg");
737 background-attachment: fixed;
738}
739
740.navheader,
741.note,
742.tip {
743 background-image: url("images/note_bg.jpg");
744 background-attachment: fixed;
745}
746
747.warning,
748.caution {
749 background-image: url("images/warning_bg.jpg");
750 background-attachment: fixed;
751}
752
753.figure,
754.informalfigure,
755.example,
756.informalexample,
757.table,
758.informaltable {
759 background-image: url("images/figure_bg.jpg");
760 background-attachment: fixed;
761}
762
763*/
764h1,
765h2,
766h3,
767h4,
768h5,
769h6,
770h7{
771}
772
773div.preface .titlepage .title,
774div.colophon .title,
775div.chapter .titlepage .title {
776 background-image: url("images/title-bg.png");
777 background-position: bottom;
778 background-repeat: repeat-x;
779}
780
781div.section div.section .titlepage .title,
782div.sect2 .titlepage .title {
783 background: none;
784}
785
786
787h1.title {
788 background-color: transparent;
789 background-image: url("poky-handbook.png");
790 background-repeat: no-repeat;
791 height: 256;
792 text-indent: -9000px;
793 overflow:hidden;
794}
795
796h2.subtitle {
797 background-color: transparent;
798 text-indent: -9000px;
799 overflow:hidden;
800 width: 0;
801 display: none;
802}
803
804 /*************************************** /
805 / pippin.gimp.org specific alterations /
806/ ***************************************/
807
808/*
809div.heading, div.navheader {
810 color: #777;
811 font-size: 80%;
812 padding: 0;
813 margin: 0;
814 text-align: left;
815 position: absolute;
816 top: 0px;
817 left: 0px;
818 width: 100%;
819 height: 50px;
820 background: url('/gfx/heading_bg.png') transparent;
821 background-repeat: repeat-x;
822 background-attachment: fixed;
823 border: none;
824}
825
826div.heading a {
827 color: #444;
828}
829
830div.footing, div.navfooter {
831 border: none;
832 color: #ddd;
833 font-size: 80%;
834 text-align:right;
835
836 width: 100%;
837 padding-top: 10px;
838 position: absolute;
839 bottom: 0px;
840 left: 0px;
841
842 background: url('/gfx/footing_bg.png') transparent;
843}
844*/
845
846
847
848 /****************** /
849 / nasty ie tweaks /
850/ ******************/
851
852/*
853div.heading, div.navheader {
854 width:expression(document.body.clientWidth + "px");
855}
856
857div.footing, div.navfooter {
858 width:expression(document.body.clientWidth + "px");
859 margin-left:expression("-5em");
860}
861body {
862 padding:expression("4em 5em 0em 5em");
863}
864*/
865
866 /**************************************** /
867 / mozilla vendor specific css extensions /
868/ ****************************************/
869/*
870div.navfooter, div.footing{
871 -moz-opacity: 0.8;
872}
873
874div.figure,
875div.table,
876div.informalfigure,
877div.informaltable,
878div.informalexample,
879div.example,
880.tip,
881.warning,
882.caution,
883.note {
884 -moz-border-radius: 0.5em;
885}
886
887b.keycap,
888.keycap {
889 -moz-border-radius: 0.3em;
890}
891*/
892
893table tr td table tr td {
894 display: none;
895}
896
897
898hr {
899 display: none;
900}
901
902table {
903 border: 0;
904}
905
906 .photo {
907 float:right;
908 margin-left: 1.5em;
909 margin-bottom: 1.5em;
910 margin-top: 0em;
911 max-width: 17em;
912 border: 1px solid gray;
913 padding: 3px;
914 background: white;
915}
916 .seperator {
917 padding-top: 2em;
918 clear :both;
919 }
920
921 #validators {
922 margin-top: 5em;
923 text-align: right;
924 color: #777;
925 }
926 @media print {
927 body {
928 font-size: 8pt;
929 }
930 .noprint {
931 display: none;
932 }
933 }
934
935
936.tip,
937.note {
938 background: #91ae35;
939 color: #fff;
940 padding: 20px;
941 margin: 20px;
942}
943
944.tip h3,
945.note h3 {
946 padding: 0;
947 margin: 0;
948 font-size: 2em;
949 font-weight: bold;
950 color: #fff;
951}
952
953.tip a,
954.note a {
955 color: #fff;
956 text-decoration: underline;
957} \ No newline at end of file
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-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-03 15:12:49 +0000