summaryrefslogtreecommitdiffstats
path: root/documentation/poky-ref-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/poky-ref-manual')
-rw-r--r--documentation/poky-ref-manual/Makefile38
-rw-r--r--documentation/poky-ref-manual/TODO11
-rw-r--r--documentation/poky-ref-manual/bsp-guide.xml61
-rw-r--r--documentation/poky-ref-manual/bsp.xml451
-rw-r--r--documentation/poky-ref-manual/development.xml825
-rw-r--r--documentation/poky-ref-manual/examples/hello-autotools/hello_2.3.bb7
-rw-r--r--documentation/poky-ref-manual/examples/hello-single/files/helloworld.c8
-rw-r--r--documentation/poky-ref-manual/examples/hello-single/hello.bb16
-rw-r--r--documentation/poky-ref-manual/examples/libxpm/libxpm_3.5.6.bb13
-rw-r--r--documentation/poky-ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb13
-rw-r--r--documentation/poky-ref-manual/extendpoky.xml1040
-rw-r--r--documentation/poky-ref-manual/faq.xml314
-rw-r--r--documentation/poky-ref-manual/introduction.xml352
-rw-r--r--documentation/poky-ref-manual/poky-beaver.pngbin0 -> 26252 bytes
-rw-r--r--documentation/poky-ref-manual/poky-handbook.pngbin0 -> 17829 bytes
-rw-r--r--documentation/poky-ref-manual/poky-handbook.xml102
-rw-r--r--documentation/poky-ref-manual/poky-logo.svg117
-rw-r--r--documentation/poky-ref-manual/ref-bitbake.xml348
-rw-r--r--documentation/poky-ref-manual/ref-classes.xml455
-rw-r--r--documentation/poky-ref-manual/ref-features.xml302
-rw-r--r--documentation/poky-ref-manual/ref-images.xml72
-rw-r--r--documentation/poky-ref-manual/ref-structure.xml514
-rw-r--r--documentation/poky-ref-manual/ref-variables.xml879
-rw-r--r--documentation/poky-ref-manual/ref-varlocality.xml211
-rw-r--r--documentation/poky-ref-manual/resources.xml142
-rw-r--r--documentation/poky-ref-manual/screenshots/ss-anjuta-poky-1.pngbin0 -> 96531 bytes
-rw-r--r--documentation/poky-ref-manual/screenshots/ss-anjuta-poky-2.pngbin0 -> 76419 bytes
-rw-r--r--documentation/poky-ref-manual/screenshots/ss-oprofile-viewer.pngbin0 -> 51240 bytes
-rw-r--r--documentation/poky-ref-manual/screenshots/ss-sato.pngbin0 -> 38689 bytes
-rw-r--r--documentation/poky-ref-manual/style.css953
-rw-r--r--documentation/poky-ref-manual/usingpoky.xml316
31 files changed, 7560 insertions, 0 deletions
diff --git a/documentation/poky-ref-manual/Makefile b/documentation/poky-ref-manual/Makefile
new file mode 100644
index 0000000000..b023045d0e
--- /dev/null
+++ b/documentation/poky-ref-manual/Makefile
@@ -0,0 +1,38 @@
1all: html pdf tarball
2
3pdf:
4 cd ..; ./tools/poky-docbook-to-pdf ./poky-ref-manual/poky-handbook.xml ./template
5 cd..; ./tools/poky-docbook-to-pdf ./poky-ref-manual/bsp-guide.xml ./template
6
7XSLTOPTS = --stringparam html.stylesheet style.css \
8 --stringparam chapter.autolabel 1 \
9 --stringparam appendix.autolabel 1 \
10 --stringparam section.autolabel 1 \
11 --stringparam section.label.includes.component.label 1 \
12 --xinclude
13
14##
15# These URI should be rewritten by your distribution's xml catalog to
16# match your localy installed XSL stylesheets.
17XSL_BASE_URI = http://docbook.sourceforge.net/release/xsl/current
18XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl
19
20html:
21# See http://www.sagehill.net/docbookxsl/HtmlOutput.html
22 xsltproc $(XSLTOPTS) -o poky-handbook.html $(XSL_XHTML_URI) poky-handbook.xml
23 xsltproc $(XSLTOPTS) -o bsp-guide.html $(XSL_XHTML_URI) bsp-guide.xml
24
25tarball: html
26 tar -cvzf poky-handbook.tgz poky-handbook.html style.css screenshots/ss-sato.png poky-beaver.png poky-handbook.png
27
28validate:
29 xmllint --postvalid --xinclude --noout poky-handbook.xml
30
31OUTPUTS = poky-handbook.tgz poky-handbook.html poky-handbook.pdf bsp-guide.pdf
32SOURCES = *.png *.xml *.css *.svg
33
34publish:
35 scp -r $(OUTPUTS) $(SOURCES) o-hand.com:/srv/www/pokylinux.org/doc/
36
37clean:
38 rm $(OUTPUTS)
diff --git a/documentation/poky-ref-manual/TODO b/documentation/poky-ref-manual/TODO
new file mode 100644
index 0000000000..ee0db977cc
--- /dev/null
+++ b/documentation/poky-ref-manual/TODO
@@ -0,0 +1,11 @@
1Handbook Todo List:
2
3 * Document adding a new IMAGE_FEATURE to the customising images section
4 * Add instructions about using zaurus/openmoko emulation
5 * Add component overview/block diagrams
6 * Software Deevelopment intro should mention its software development for
7 intended target and could be a different arch etc and thus special case.
8 * Expand insane.bbclass documentation to cover tests
9 * Document remaining classes (see list in ref-classes)
10 * Document formfactor
11
diff --git a/documentation/poky-ref-manual/bsp-guide.xml b/documentation/poky-ref-manual/bsp-guide.xml
new file mode 100644
index 0000000000..2f4906c173
--- /dev/null
+++ b/documentation/poky-ref-manual/bsp-guide.xml
@@ -0,0 +1,61 @@
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='template/poky-handbook.png'
13 format='SVG'
14 align='center' scalefit='1' width='100%'/>
15 </imageobject>
16 </mediaobject>
17
18 <title>Board Support Package (BSP) Developers Guide</title>
19
20 <authorgroup>
21 <author>
22 <firstname>Richard</firstname> <surname>Purdie</surname>
23 <affiliation>
24 <orgname>Intel Corporation</orgname>
25 </affiliation>
26 <email>richard@linux.intel.com</email>
27 </author>
28 </authorgroup>
29
30 <revhistory>
31 <revision>
32 <revnumber>0.4</revnumber>
33 <date>26 May 2010</date>
34 <revremark>Alpha Draft</revremark>
35 </revision>
36 </revhistory>
37
38 <copyright>
39 <year>2010</year>
40 <holder>Intel Corporation</holder>
41 </copyright>
42
43 <legalnotice>
44 <para>
45 Permission is granted to copy, distribute and/or modify this document under
46 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.
47 </para>
48 </legalnotice>
49
50 </bookinfo>
51
52 <xi:include href="bsp.xml"/>
53
54 <index id='index'>
55 <title>Index</title>
56 </index>
57
58</book>
59<!--
60vim: expandtab tw=80 ts=4
61-->
diff --git a/documentation/poky-ref-manual/bsp.xml b/documentation/poky-ref-manual/bsp.xml
new file mode 100644
index 0000000000..e0ca31732b
--- /dev/null
+++ b/documentation/poky-ref-manual/bsp.xml
@@ -0,0 +1,451 @@
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='bsp'>
5
6 <title>Board Support Packages (BSP) - Developers Guide</title>
7
8 <para>
9 A Board Support Package (BSP) is a collection of information which together
10 defines how to support a particular hardware device, set of devices, or
11 hardware platform. It will include information about the hardware features
12 present on the device and kernel configuration information along with any
13 additional hardware drivers required. It will also list any additional software
14 components required in addition to a generic Linux software stack for both
15 essential and optional platform features.
16 </para>
17
18 <para>
19 The intent of this document is to define a structure for these components
20 so that BSPs follow a commonly understood layout, allowing them to be
21 provided in a common form that everyone understands. It also allows end-users
22 to become familiar with one common format and encourages standardisation
23 of software support of hardware.
24 </para>
25
26 <para>
27 The proposed format does have elements that are specific to the Poky and
28 OpenEmbedded build systems. It is intended that this information can be
29 used by other systems besides Poky/OpenEmbedded and that it will be simple
30 to extract information and convert to other formats if required. The format
31 described can be directly accepted as a layer by Poky using its standard
32 layers mechanism, but it is important to recognise that the BSP captures all
33 the hardware specific details in one place in a standard format, which is
34 useful for any person wishing to use the hardware platform regardless of
35 the build system in use.
36 </para>
37
38 <para>
39 The BSP specification does not include a build system or other tools -
40 it is concerned with the hardware specific components only. At the end
41 distribution point the BSP may be shipped combined with a build system
42 and other tools, but it is important to maintain the distinction that these
43 are separate components which may just be combined in certain end products.
44 </para>
45
46 <section id='bsp-filelayout'>
47 <title>Example Filesystem Layout</title>
48
49 <para>
50 The BSP consists of a file structure inside a base directory, meta-bsp in this example, where "bsp" is a placeholder for the machine or platform name. Examples of some files that it could contain are:
51 </para>
52
53 <para>
54 <programlisting>
55meta-bsp/
56meta-bsp/binary/zImage
57meta-bsp/binary/poky-image-minimal.directdisk
58meta-bsp/conf/layer.conf
59meta-bsp/conf/machine/*.conf
60meta-bsp/conf/machine/include/tune-*.inc
61meta-bsp/packages/bootloader/bootloader_0.1.bb
62meta-bsp/packages/linux/linux-bsp-2.6.50/*.patch
63meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
64meta-bsp/packages/linux/linux-bsp_2.6.50.bb
65meta-bsp/packages/modem/modem-driver_0.1.bb
66meta-bsp/packages/modem/modem-daemon_0.1.bb
67meta-bsp/packages/image-creator/image-creator-native_0.1.bb
68meta-bsp/prebuilds/
69
70 </programlisting>
71 </para>
72
73 <para>
74 The following sections detail what these files and directories could contain.
75 </para>
76
77 </section>
78
79 <section id='bsp-filelayout-binary'>
80 <title>Prebuilt User Binaries (meta-bsp/binary/*)</title>
81
82 <para>
83 This optional area contains useful prebuilt kernels and userspace filesystem
84 images appropriate to the target system. Users could use these to get a system
85 running and quickly get started on development tasks. The exact types of binaries
86 present will be highly hardware-dependent but a README file should be present
87 explaining how to use them with the target hardware. If prebuilt binaries are
88 present, source code to meet licensing requirements must also be provided in
89 some form.
90 </para>
91
92 </section>
93
94 <section id='bsp-filelayout-layer'>
95 <title>Layer Configuration (meta-bsp/conf/layer.conf)</title>
96
97 <para>
98 This file identifies the structure as a Poky layer. This file identifies the
99 contents of the layer and contains information about how Poky should use
100 it. In general it will most likely be a standard boilerplate file consisting of:
101 </para>
102
103 <para>
104 <programlisting>
105# We have a conf directory, add to BBPATH
106BBPATH := "${BBPATH}${LAYERDIR}"
107
108# We have a packages directory, add to BBFILES
109BBFILES := "${BBFILES} ${LAYERDIR}/packages/*/*.bb"
110
111BBFILE_COLLECTIONS += "bsp"
112BBFILE_PATTERN_bsp := "^${LAYERDIR}/"
113BBFILE_PRIORITY_bsp = "5"
114 </programlisting>
115 </para>
116
117 <para>
118 which simply makes bitbake aware of the packages and conf directories.
119 </para>
120
121 <para>
122 This file is required for recognition of the BSP by Poky.
123 </para>
124
125 </section>
126
127 <section id='bsp-filelayout-machine'>
128 <title>Hardware Configuration Options (meta-bsp/conf/machine/*.conf)</title>
129
130 <para>
131 The machine files bind together all the information contained elsewhere
132 in the BSP into a format that Poky/OpenEmbedded can understand. If
133 the BSP supports multiple machines, multiple machine configuration files
134 can be present. These filenames correspond to the values users set the
135 MACHINE variable to.
136 </para>
137
138 <para>
139 These files would define things like which kernel package to use
140 (PREFERRED_PROVIDER of virtual/kernel), which hardware drivers to
141 include in different types of images, any special software components
142 that are needed, any bootloader information, and also any special image
143 format requirements.
144 </para>
145
146 <para>
147 At least one machine file is required for a Poky BSP layer but more than one may be present.
148 </para>
149
150 </section>
151
152 <section id='bsp-filelayout-tune'>
153 <title>Hardware Optimisation Options (meta-bsp/conf/machine/include/tune-*.inc)</title>
154
155 <para>
156 These are shared hardware "tuning" definitions and are commonly used to
157 pass specific optimisation flags to the compiler. An example is
158 tune-atom.inc:
159 </para>
160 <para>
161 <programlisting>
162BASE_PACKAGE_ARCH = "core2"
163TARGET_CC_ARCH = "-m32 -march=core2 -msse3 -mtune=generic -mfpmath=sse"
164 </programlisting>
165 </para>
166 <para>
167 which defines a new package architecture called "core2" and uses the
168 optimization flags specified, which are carefully chosen to give best
169 performance on atom cpus.
170 </para>
171 <para>
172 The tune file would be included by the machine definition and can be
173 contained in the BSP or reference one from the standard core set of
174 files included with Poky itself.
175 </para>
176 <para>
177 These files are optional for a Poky BSP layer.
178 </para>
179 </section>
180 <section id='bsp-filelayout-kernel'>
181 <title>Linux Kernel Configuration (meta-bsp/packages/linux/*)</title>
182
183 <para>
184 These files make up the definition of a kernel to use with this
185 hardware. In this case it is a complete self-contained kernel with its own
186 configuration and patches but kernels can be shared between many
187 machines as well. Taking some specific example files:
188 </para>
189 <para>
190 <programlisting>
191meta-bsp/packages/linux/linux-bsp_2.6.50.bb
192 </programlisting>
193 </para>
194 <para>
195 which is the core kernel recipe which firstly details where to get the kernel
196 source from. All standard source code locations are supported so this could
197 be a release tarball, some git repository, or source included in
198 the directory within the BSP itself. It then contains information about which
199 patches to apply and how to configure and build it. It can reuse the main
200 Poky kernel build class, so the definitions here can remain very simple.
201 </para>
202 <para>
203 <programlisting>
204linux-bsp-2.6.50/*.patch
205 </programlisting>
206 </para>
207 <para>
208 which are patches which may be applied against the base kernel, wherever
209 they may have been obtained from.
210 </para>
211 <para>
212 <programlisting>
213meta-bsp/packages/linux/linux-bsp-2.6.50/defconfig-bsp
214 </programlisting>
215 </para>
216 <para>
217 which is the configuration information to use to configure the kernel.
218 </para>
219 <para>
220 Examples of kernel recipes are available in Poky itself. These files are
221 optional since a kernel from Poky itself could be selected, although it
222 would be unusual not to have a kernel configuration.
223 </para>
224 </section>
225
226 <section id='bsp-filelayout-packages'>
227 <title>Other Software (meta-bsp/packages/*)</title>
228
229 <para>
230 This area includes other pieces of software which the hardware may need for best
231 operation. These are just examples of the kind of things that may be
232 encountered. These are standard .bb file recipes in the usual Poky format,
233 so for examples, see standard Poky recipes. The source can be included directly,
234 referred to in source control systems or release tarballs of external software projects.
235 </para>
236 <para>
237 <programlisting>
238meta-bsp/packages/bootloader/bootloader_0.1.bb
239 </programlisting>
240 </para>
241 <para>
242 Some kind of bootloader recipe which may be used to generate a new
243 bootloader binary. Sometimes these are included in the final image
244 format and needed to reflash hardware.
245 </para>
246 <para>
247 <programlisting>
248meta-bsp/packages/modem/modem-driver_0.1.bb
249meta-bsp/packages/modem/modem-daemon_0.1.bb
250 </programlisting>
251 </para>
252 <para>
253 These are examples of a hardware driver and also a hardware daemon which
254 may need to be included in images to make the hardware useful. "modem"
255 is one example but there may be other components needed like firmware.
256 </para>
257 <para>
258 <programlisting>
259meta-bsp/packages/image-creator/image-creator-native_0.1.bb
260 </programlisting>
261 </para>
262 <para>
263 Sometimes the device will need an image in a very specific format for
264 its update mechanism to accept and reflash with it. Recipes to build the
265 tools needed to do this can be included with the BSP.
266 </para>
267 <para>
268 These files only need be provided if the platform requires them.
269 </para>
270 </section>
271
272 <section id='bs-filelayout-bbappend'>
273 <title>Append BSP specific information to existing recipes</title>
274
275 <para>
276 Say you have a recipe like pointercal which has machine-specific information in it,
277 and then you have your new BSP code in a layer. Before the .bbappend extension was
278 introduced, you'd have to copy the whole pointercal recipe and files into your layer,
279 and then add the single file for your machine, which is ugly.
280
281 .bbappend makes the above work much easier, to allow BSP-specific information to be merged
282 with the original recipe easily. When bitbake finds any X.bbappend files, they will be
283 included after bitbake loads X.bb but before finalise or anonymous methods run.
284 This allows the BSP layer to poke around and do whatever it might want to customise
285 the original recipe.
286
287 .bbappend is expected to include the below two lines in the head (which may be changed
288 in the future):
289 </para>
290
291 <programlisting>
292THISDIR := "${@os.path.dirname(bb.data.getVar('FILE', d, True))}"
293FILESPATH =. "${@base_set_filespath(["${THISDIR}/${PN}"], d)}:"
294 </programlisting>
295
296 <para>
297 Then the BSP could add machine-specific config files in layer directory, which will be
298 added by bitbake. You can look at meta-emenlow/packages/formfactor as an example.
299 </para>
300 </section>
301
302 <section id='bsp-filelayout-prebuilds'>
303 <title>Prebuild Data (meta-bsp/prebuilds/*)</title>
304
305 <para>
306 The location can contain a precompiled representation of the source code
307 contained elsewhere in the BSP layer. It can be processed and used by
308 Poky to provide much faster build times, assuming a compatible configuration is used.
309 </para>
310
311 <para>
312 These files are optional.
313 </para>
314
315 </section>
316
317 <section id='bsp-click-through-licensing'>
318 <title>BSP 'Click-through' Licensing Procedure</title>
319
320 <note><para> This section is here as a description of how
321 click-through licensing is expected to work, and is
322 not yet not impemented.
323 </para></note>
324
325 <para>
326 In some cases, a BSP may contain separately licensed IP
327 (Intellectual Property) for a component, which imposes
328 upon the user a requirement to accept the terms of a
329 'click-through' license. Once the license is accepted
330 (in whatever form that may be, see details below) the
331 Poky build system can then build and include the
332 corresponding component in the final BSP image. Some
333 affected components may be essential to the normal
334 functioning of the system and have no 'free' replacement
335 i.e. the resulting system would be non-functional
336 without them. Other components may be simply
337 'good-to-have' or purely elective, or if essential
338 nonetheless have a 'free' (possibly less-capable)
339 version which may substituted for in the BSP recipe.
340 </para>
341
342 <para>
343 For the latter cases, where it is possible to do so from
344 a functionality perspective, the Poky website will make
345 available a 'de-featured' BSP completely free of
346 encumbered IP, which can be used directly and without
347 any further licensing requirements. If present, this
348 fully 'de-featured' BSP will be named meta-bsp (i.e. the
349 normal default naming convention). This is the simplest
350 and therefore preferred option if available, assuming
351 the resulting functionality meets requirements.
352 </para>
353
354 <para>
355 If however, a non-encumbered version is unavailable or
356 the 'free' version would provide unsuitable
357 functionality or quality, an encumbered version can be
358 used. Encumbered versions of a BSP are given names of
359 the form meta-bsp-nonfree. There are several ways
360 within the Poky build system to satisfy the licensing
361 requirements for an encumbered BSP, in roughly the
362 following order of preference:
363 </para>
364
365 <itemizedlist>
366 <listitem>
367
368 <para>
369 Get a license key (or keys) for the encumbered BSP
370 by
371 visiting <ulink url='https://pokylinux.org/bsp-keys.html'>https://pokylinux.org/bsp-keys.html</ulink>
372 and give the web form there the name of the BSP
373 and your e-mail address.
374 </para>
375
376 <programlisting>
377 [screenshot of dialog box]
378 </programlisting>
379
380 <para>
381 After agreeing to any applicable license terms, the
382 BSP key(s) will be immediately sent to the address
383 given and can be used by specifying BSPKEY_&lt;keydomain&gt;
384 environment variables when building the image:
385 </para>
386
387 <programlisting>
388 $ BSPKEY_&lt;keydomain&gt;=&lt;key&gt; bitbake poky-image-sato
389 </programlisting>
390
391 <para>
392 This will allow the encumbered image to be built
393 with no change at all to the normal build process.
394 </para>
395
396 <para>
397 Equivalently and probably more conveniently, a line
398 for each key can instead be put into the user's
399 local.conf file.
400 </para>
401
402 <para>
403 The &lt;keydomain&gt; component of the
404 BSPKEY_&lt;keydomain&gt; is required because there
405 may be multiple licenses in effect for a give BSP; a
406 given &lt;keydomain&gt; in such cases corresponds to
407 a particular license. In order for an encumbered
408 BSP encompassing multiple key domains to be built
409 successfully, a &lt;keydomain&gt; entry for each
410 applicable license must be present in local.conf or
411 supplied on the command-line.
412 </para>
413 </listitem>
414 <listitem>
415 <para>
416 Do nothing - build as you normally would, and follow
417 any license prompts that originate from the
418 encumbered BSP (the build will cleanly stop at this
419 point). These usually take the form of instructions
420 needed to manually fetch the encumbered package(s)
421 and md5 sums into e.g. the poky/build/downloads
422 directory. Once the manual package fetch has been
423 completed, restarting the build will continue where
424 it left off, this time without the prompt since the
425 license requirements will have been satisfied.
426 </para>
427 </listitem>
428 <listitem>
429 <para>
430 Get a full-featured BSP recipe rather than a key, by
431 visiting
432 <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>.
433 Accepting the license agreement(s) presented will
434 subsequently allow you to download a tarball
435 containing a full-featured BSP legally cleared for
436 your use by the just-given license agreement(s).
437 This method will also allow the encumbered image to
438 be built with no change at all to the normal build
439 process.
440 </para>
441 </listitem>
442 </itemizedlist>
443 <para>
444 Note that method 3 is also the only option available
445 when downloading pre-compiled images generated from
446 non-free BSPs. Those images are likewise available at
447 <ulink url='https://pokylinux.org/bsps.html'>https://pokylinux.org/bsps.html</ulink>.
448 </para>
449 </section>
450
451</chapter>
diff --git a/documentation/poky-ref-manual/development.xml b/documentation/poky-ref-manual/development.xml
new file mode 100644
index 0000000000..a383a2f4a8
--- /dev/null
+++ b/documentation/poky-ref-manual/development.xml
@@ -0,0 +1,825 @@
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">/opt/poky</filename> directory and contain
23 a setup script, e.g.
24 <filename>/opt/poky/environment-setup-i586-poky-linux</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-external-anjuta">
41 <title>Developing externally using the Anjuta plugin</title>
42
43 <para>
44 An Anjuta IDE plugin exists to make developing software within the Poky framework
45 easier for the application developer. It presents a graphical IDE from which the
46 developer can cross compile an application then deploy and execute the output in a QEMU
47 emulation session. It also supports cross debugging and profiling.
48 </para>
49<!-- DISBALED, TOO BIG!
50 <screenshot>
51 <mediaobject>
52 <imageobject>
53 <imagedata fileref="screenshots/ss-anjuta-poky-1.png" format="PNG"/>
54 </imageobject>
55 <caption>
56 <para>The Anjuta Poky SDK plugin showing an active QEMU session running Sato</para>
57 </caption>
58 </mediaobject>
59 </screenshot>
60-->
61 <para>
62 To use the plugin, a toolchain and SDK built by Poky is required along with Anjuta it's development
63 headers and the Anjuta plugin. The Poky Anjuta plugin is available to download as a tarball at the
64 <ulink url='http://labs.o-hand.com/anjuta-poky-sdk-plugin/'>OpenedHand labs</ulink> page or
65 directly from the Poky Git repository located at git://git.pokylinux.org/anjuta-poky; a web interface
66 to the repository can be accessed at <ulink url='http://git.pokylinux.org/?p=anjuta-poky.git;a=summary'/>.
67 </para>
68 <para>
69 See the README file contained in the project for more information on dependencies and building
70 the plugin. If you want to disable remote gdb debugging, please pass --diable-gdb-integration
71 switch when doing configure.
72 </para>
73
74 <section id="platdev-appdev-external-anjuta-setup">
75 <title>Setting up the Anjuta plugin</title>
76
77 <para>Extract the tarball for the toolchain into / as root. The
78 toolchain will be installed into
79 <filename class="directory">/opt/poky</filename>.</para>
80
81 <para>To use the plugin, first open or create an existing
82 project. If creating a new project the "C GTK+" project type
83 will allow itself to be cross-compiled. However you should be
84 aware that this uses glade for the UI.</para>
85
86 <para>To activate the plugin go to
87 <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice>,
88 then choose <guilabel>General</guilabel> from the left hand side. Choose the
89 Installed plugins tab, scroll down to <guilabel>Poky
90 SDK</guilabel> and check the
91 box. The plugin is now activated but first it must be
92 configured.</para>
93 </section>
94
95 <section id="platdev-appdev-external-anjuta-configuration">
96 <title>Configuring the Anjuta plugin</title>
97
98 <para>The configuration options for the SDK can be found by choosing
99 the <guilabel>Poky SDK</guilabel> icon from the left hand side. The following options
100 need to be set:</para>
101
102 <itemizedlist>
103
104 <listitem><para><guilabel>SDK root</guilabel>: If we use external toolchain, we need to set SDK root.
105 this is the root directory of the SDK's sysroot. For an i586 SDK this will be <filename
106 class="directory">/opt/poky/</filename>.
107 This directory will contain directories named like "bin",
108 "include", "var", etc. under your selected target architecture subdirectory<filename class="directory">
109 /opt/poky/sysroot/i586-poky-linux/</filename>. Needed cross compile tools are under
110 <filename class ="directory">/opt/poky/sysroot/i586-pokysdk-linux/</filename>
111 </para></listitem>
112
113 <listitem><para><guilabel>Poky root</guilabel>: If we have local poky build tree, we need to set the Poky root.
114 this is the root directory of the poky build tree, if you build your i586 target architecture
115 under the subdirectory of build_x86 within your poky tree, the Poky root directory should be
116 <filename class="directory">${Poky_tree}/build_x86/</filename>.
117 </para></listitem>
118
119 <listitem><para><guilabel>Target Architecture</guilabel>: this is the cross compile
120 triplet, e.g. "i586-poky-linux". This target triplet is the prefix extracted from
121 the set up script file name. For examle, "i586-poky-linux" is extracted from set up script file
122 <filename>/opt/poky/environment-setup-i586-poky-linux</filename>
123 </para></listitem>
124
125 <listitem><para><guilabel>Kernel</guilabel>: use the file chooser to select the kernel
126 to use with QEMU</para></listitem>
127
128 <listitem><para><guilabel>Root filesystem</guilabel>: use the file chooser to select
129 the root filesystem directory, this is the directory where you use "poky-extract-sdk" command to
130 extract the poky-image-sdk tarball.</para></listitem>
131 </itemizedlist>
132<!-- DISBALED, TOO BIG!
133 <screenshot>
134 <mediaobject>
135 <imageobject>
136 <imagedata fileref="screenshots/ss-anjuta-poky-2.png" format="PNG"/>
137 </imageobject>
138 <caption>
139 <para>Anjuta Preferences Dialog</para>
140 </caption>
141 </mediaobject>
142 </screenshot>
143-->
144
145 </section>
146
147 <section id="platdev-appdev-external-anjuta-usage">
148 <title>Using the Anjuta plugin</title>
149
150 <para>As an example, cross-compiling a project, deploying it into
151 QEMU and running a debugger against it and then doing a system
152 wide profile.</para>
153
154 <para>Choose <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
155 Configure</guimenuitem></menuchoice> or
156 <menuchoice><guimenu>Build</guimenu><guimenuitem>Run
157 Autogenerate</guimenuitem></menuchoice> to run "configure"
158 (or to run "autogen") for the project. This passes command line
159 arguments to instruct it to cross-compile.</para>
160
161 <para>Next do
162 <menuchoice><guimenu>Build</guimenu><guimenuitem>Build
163 Project</guimenuitem></menuchoice> to build and compile the
164 project. If you have previously built the project in the same
165 tree without using the cross-compiler you may find that your
166 project fails to link. Simply do
167 <menuchoice><guimenu>Build</guimenu><guimenuitem>Clean
168 Project</guimenuitem></menuchoice> to remove the old
169 binaries. You may then try building again.</para>
170
171 <para>Next start QEMU by using
172 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Start
173 QEMU</guimenuitem></menuchoice>, this will start QEMU and
174 will show any error messages in the message view. Once Poky has
175 fully booted within QEMU you may now deploy into it.</para>
176
177 <para>Once built and QEMU is running, choose
178 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Deploy</guimenuitem></menuchoice>,
179 this will install the package into a temporary directory and
180 then copy using rsync over SSH into the target. Progress and
181 messages will be shown in the message view.</para>
182
183 <para>To debug a program installed into onto the target choose
184 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Debug
185 remote</guimenuitem></menuchoice>. This prompts for the
186 local binary to debug and also the command line to run on the
187 target. The command line to run should include the full path to
188 the to binary installed in the target. This will start a
189 gdbserver over SSH on the target and also an instance of a
190 cross-gdb in a local terminal. This will be preloaded to connect
191 to the server and use the <guilabel>SDK root</guilabel> to find
192 symbols. This gdb will connect to the target and load in
193 various libraries and the target program. You should setup any
194 breakpoints or watchpoints now since you might not be able to
195 interrupt the execution later. You may stop
196 the debugger on the target using
197 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Stop
198 debugger</guimenuitem></menuchoice>.</para>
199
200 <para>It is also possible to execute a command in the target over
201 SSH, the appropriate environment will be be set for the
202 execution. Choose
203 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Run
204 remote</guimenuitem></menuchoice> to do this. This will open
205 a terminal with the SSH command inside.</para>
206
207 <para>To do a system wide profile against the system running in
208 QEMU choose
209 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Profile
210 remote</guimenuitem></menuchoice>. This will start up
211 OProfileUI with the appropriate parameters to connect to the
212 server running inside QEMU and will also supply the path to the
213 debug information necessary to get a useful profile.</para>
214
215 </section>
216 </section>
217
218
219 <section id="platdev-appdev-qemu">
220 <title>Developing externally in QEMU</title>
221 <para>
222 Running Poky QEMU images is covered in the <link
223 linkend='intro-quickstart-qemu'>Running an Image</link> section.
224 </para>
225 <para>
226 Poky's QEMU images contain a complete native toolchain. This means
227 that applications can be developed within QEMU in the same was as a
228 normal system. Using qemux86 on an x86 machine is fast since the
229 guest and host architectures match, qemuarm is slower but gives
230 faithful emulation of ARM specific issues. To speed things up these
231 images support using distcc to call a cross-compiler outside the
232 emulated system too. If <command>runqemu</command> was used to start
233 QEMU, and distccd is present on the host system, any bitbake cross
234 compiling toolchain available from the build system will automatically
235 be used from within qemu simply by calling distcc
236 (<command>export CC="distcc"</command> can be set in the enviroment).
237 Alterntatively, if a suitable SDK/toolchain is present in
238 <filename class="directory">/opt/poky</filename> it will also
239 automatically be used.
240 </para>
241
242 <para>
243 There are several options for connecting into the emulated system.
244 QEMU provides a framebuffer interface which has standard consoles
245 available. There is also a serial connection available which has a
246 console to the system running on it and IP networking as standard.
247 The images have a dropbear ssh server running with the root password
248 disabled allowing standard ssh and scp commands to work. The images
249 also contain an NFS server exporting the guest's root filesystem
250 allowing that to be made available to the host.
251 </para>
252 </section>
253
254 <section id="platdev-appdev-insitu">
255 <title>Developing in Poky directly</title>
256 <para>
257 Working directly in Poky is a fast and effective development technique.
258 The idea is that you can directly edit files in
259 <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>
260 or the source directory <glossterm><link linkend='var-S'>S</link></glossterm>
261 and then force specific tasks to rerun in order to test the changes.
262 An example session working on the matchbox-desktop package might
263 look like this:
264 </para>
265
266 <para>
267 <literallayout class='monospaced'>
268$ bitbake matchbox-desktop
269$ sh
270$ cd tmp/work/armv5te-poky-linux-gnueabi/matchbox-desktop-2.0+svnr1708-r0/
271$ cd matchbox-desktop-2
272$ vi src/main.c
273$ exit
274$ bitbake matchbox-desktop -c compile -f
275$ bitbake matchbox-desktop
276</literallayout>
277 </para>
278
279 <para>
280 Here, we build the package, change into the work directory for the package,
281 change a file, then recompile the package. Instead of using sh like this,
282 you can also use two different terminals. The risk with working like this
283 is that a command like unpack could wipe out the changes you've made to the
284 work directory so you need to work carefully.
285 </para>
286
287 <para>
288 It is useful when making changes directly to the work directory files to do
289 so using quilt as detailed in the <link linkend='usingpoky-modifying-packages-quilt'>
290 modifying packages with quilt</link> section. The resulting patches can be copied
291 into the recipe directory and used directly in the <glossterm><link
292 linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
293 </para>
294 <para>
295 For a review of the skills used in this section see Sections <link
296 linkend="usingpoky-components-bitbake">2.1.1</link> and <link
297 linkend="usingpoky-debugging-taskrunning">2.4.2</link>.
298 </para>
299
300 </section>
301
302 <section id="platdev-appdev-devshell">
303 <title>Developing with 'devshell'</title>
304
305 <para>
306 When debugging certain commands or even to just edit packages, the
307 'devshell' can be a useful tool. To start it you run a command like:
308 </para>
309
310 <para>
311 <literallayout class='monospaced'>
312$ bitbake matchbox-desktop -c devshell
313</literallayout>
314 </para>
315
316 <para>
317 which will open a terminal with a shell prompt within the Poky
318 environment. This means PATH is setup to include the cross toolchain,
319 the pkgconfig variables are setup to find the right .pc files,
320 configure will be able to find the Poky site files etc. Within this
321 environment, you can run configure or compile command as if they
322 were being run by Poky itself. You are also changed into the
323 source (<glossterm><link linkend='var-S'>S</link></glossterm>)
324 directory automatically. When finished with the shell just exit it
325 or close the terminal window.
326 </para>
327
328 <para>
329 The default shell used by devshell is the gnome-terminal. Other
330 forms of terminal can also be used by setting the <glossterm>
331 <link linkend='var-TERMCMD'>TERMCMD</link></glossterm> and <glossterm>
332 <link linkend='var-TERMCMDRUN'>TERMCMDRUN</link></glossterm> variables
333 in local.conf. For examples of the other options available, see
334 <filename>meta/conf/bitbake.conf</filename>. An external shell is
335 launched rather than opening directly into the original terminal
336 window to make interaction with bitbakes multiple threads easier
337 and also allow a client/server split of bitbake in the future
338 (devshell will still work over X11 forwarding or similar).
339 </para>
340
341 <para>
342 It is worth remembering that inside devshell you need to use the full
343 compiler name such as <command>arm-poky-linux-gnueabi-gcc</command>
344 instead of just <command>gcc</command> and the same applies to other
345 applications from gcc, bintuils, libtool etc. Poky will have setup
346 environmental variables such as CC to assist applications, such as make,
347 find the correct tools.
348 </para>
349
350 </section>
351
352 <section id="platdev-appdev-srcrev">
353 <title>Developing within Poky with an external SCM based package</title>
354
355 <para>
356 If you're working on a recipe which pulls from an external SCM it
357 is possible to have Poky notice new changes added to the
358 SCM and then build the latest version. This only works for SCMs
359 where its possible to get a sensible revision number for changes.
360 Currently it works for svn, git and bzr repositories.
361 </para>
362
363 <para>
364 To enable this behaviour it is simply a case of adding <glossterm>
365 <link linkend='var-SRCREV'>SRCREV</link></glossterm>_pn-<glossterm>
366 <link linkend='var-PN'>PN</link></glossterm> = "${AUTOREV}" to
367 local.conf where <glossterm><link linkend='var-PN'>PN</link></glossterm>
368 is the name of the package for which you want to enable automatic source
369 revision updating.
370 </para>
371 </section>
372
373 </section>
374
375<section id="platdev-gdb-remotedebug">
376 <title>Debugging with GDB Remotely</title>
377
378 <para>
379 <ulink url="http://sourceware.org/gdb/">GDB</ulink> (The GNU Project Debugger)
380 allows you to examine running programs to understand and fix problems and
381 also to perform postmortem style analsys of program crashes. It is available
382 as a package within poky and installed by default in sdk images. It works best
383 when -dbg packages for the application being debugged are installed as the
384 extra symbols give more meaningful output from GDB.
385 </para>
386
387 <para>
388 Sometimes, due to memory or disk space constraints, it is not possible
389 to use GDB directly on the remote target to debug applications. This is
390 due to the fact that
391 GDB needs to load the debugging information and the binaries of the
392 process being debugged. GDB then needs to perform many
393 computations to locate information such as function names, variable
394 names and values, stack traces, etc. even before starting the debugging
395 process. This places load on the target system and can alter the
396 characteristics of the program being debugged.
397 </para>
398 <para>
399 This is where GDBSERVER comes into play as it runs on the remote target
400 and does not load any debugging information from the debugged process.
401 Instead, the debugging information processing is done by a GDB instance
402 running on a distant computer - the host GDB. The host GDB then sends
403 control commands to GDBSERVER to make it stop or start the debugged
404 program, as well as read or write some memory regions of that debugged
405 program. All the debugging information loading and processing as well
406 as the heavy debugging duty is done by the host GDB, giving the
407 GDBSERVER running on the target a chance to remain small and fast.
408 </para>
409 <para>
410 As the host GDB is responsible for loading the debugging information and
411 doing the necessary processing to make actual debugging happen, the
412 user has to make sure it can access the unstripped binaries complete
413 with their debugging information and compiled with no optimisations. The
414 host GDB must also have local access to all the libraries used by the
415 debugged program. On the remote target the binaries can remain stripped
416 as GDBSERVER does not need any debugging information there. However they
417 must also be compiled without optimisation matching the host's binaries.
418 </para>
419
420 <para>
421 The binary being debugged on the remote target machine is hence referred
422 to as the 'inferior' in keeping with GDB documentation and terminology.
423 Further documentation on GDB, is available on
424 <ulink url="http://sourceware.org/gdb/documentation/">on their site</ulink>.
425 </para>
426
427 <section id="platdev-gdb-remotedebug-launch-gdbserver">
428 <title>Launching GDBSERVER on the target</title>
429 <para>
430 First, make sure gdbserver is installed on the target. If not,
431 install the gdbserver package (which needs the libthread-db1
432 package).
433 </para>
434 <para>
435 To launch GDBSERVER on the target and make it ready to "debug" a
436 program located at <emphasis>/path/to/inferior</emphasis>, connect
437 to the target and launch:
438 <programlisting>$ gdbserver localhost:2345 /path/to/inferior</programlisting>
439 After that, gdbserver should be listening on port 2345 for debugging
440 commands coming from a remote GDB process running on the host computer.
441 Communication between the GDBSERVER and the host GDB will be done using
442 TCP. To use other communication protocols please refer to the
443 GDBSERVER documentation.
444 </para>
445 </section>
446
447 <section id="platdev-gdb-remotedebug-launch-gdb">
448 <title>Launching GDB on the host computer</title>
449
450 <para>
451 Running GDB on the host computer takes a number of stages, described in the
452 following sections.
453 </para>
454
455 <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
456 <title>Build the cross GDB package</title>
457 <para>
458 A suitable gdb cross binary is required which runs on your host computer but
459 knows about the the ABI of the remote target. This can be obtained from
460 the the Poky toolchain, e.g.
461 <filename>/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/armv5te-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb</filename>
462 which "x86_64" is the host architecture, "arm" is the target architecture and "linux-gnueabi" the target ABI.
463 </para>
464
465 <para>
466 Alternatively this can be built directly by Poky. To do this you would build
467 the gdb-cross package so for example you would run:
468 <programlisting>bitbake gdb-cross</programlisting>
469 Once built, the cross gdb binary can be found at
470 <programlisting>tmp/sysroots/&lt;host-arch&gt;/usr/bin/\
471&lt;target-arch&gt;-poky-&lt;target-abi&gt;/&lt;target-arch&gt;-poky-&lt;target-abi&gt;-gdb </programlisting>
472 </para>
473
474 </section>
475 <section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins">
476
477 <title>Making the inferior binaries available</title>
478
479 <para>
480 The inferior binary needs to be available to GDB complete with all debugging
481 symbols in order to get the best possible results along with any libraries
482 the inferior depends on and their debugging symbols. There are a number of
483 ways this can be done.
484 </para>
485
486 <para>
487 Perhaps the easiest is to have an 'sdk' image corresponding to the plain
488 image installed on the device. In the case of 'pky-image-sato',
489 'poky-image-sdk' would contain suitable symbols. The sdk images already
490 have the debugging symbols installed so its just a question expanding the
491 archive to some location and telling GDB where this is.
492 </para>
493
494 <para>
495 Alternatively, poky can build a custom directory of files for a specific
496 debugging purpose by reusing its tmp/rootfs directory, on the host computer
497 in a slightly different way to normal. This directory contains the contents
498 of the last built image. This process assumes the image running on the
499 target was the last image to be built by Poky, the package <emphasis>foo</emphasis>
500 contains the inferior binary to be debugged has been built without without
501 optimisation and has debugging information available.
502 </para>
503 <para>
504 Firstly you want to install the <emphasis>foo</emphasis> package to tmp/rootfs
505 by doing:
506 </para>
507 <programlisting>tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
508tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/opkg.conf -o \
509tmp/rootfs/ update</programlisting>
510 <para>
511 then,
512 </para>
513 <programlisting>tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
514tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/opkg.conf \
515-o tmp/rootfs install foo
516
517tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
518tmp/work/&lt;target-abi&gt;/poky-image-sato-1.0-r0/opkg.conf \
519-o tmp/rootfs install foo-dbg</programlisting>
520 <para>
521 which installs the debugging information too.
522 </para>
523
524 </section>
525 <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
526
527 <title>Launch the host GDB</title>
528 <para>
529 To launch the host GDB, run the cross gdb binary identified above with
530 the inferior binary specified on the commandline:
531 <programlisting>&lt;target-arch&gt;-poky-&lt;target-abi&gt;-gdb rootfs/usr/bin/foo</programlisting>
532 This loads the binary of program <emphasis>foo</emphasis>
533 as well as its debugging information. Once the gdb prompt
534 appears, you must instruct GDB to load all the libraries
535 of the inferior from tmp/rootfs:
536 <programlisting>set solib-absolute-prefix /path/to/tmp/rootfs</programlisting>
537 where <filename>/path/to/tmp/rootfs</filename> must be
538 the absolute path to <filename>tmp/rootfs</filename> or wherever the
539 binaries with debugging information are located.
540 </para>
541 <para>
542 Now, tell GDB to connect to the GDBSERVER running on the remote target:
543 <programlisting>target remote remote-target-ip-address:2345</programlisting>
544 Where remote-target-ip-address is the IP address of the
545 remote target where the GDBSERVER is running. 2345 is the
546 port on which the GDBSERVER is running.
547 </para>
548
549 </section>
550 <section id="platdev-gdb-remotedebug-launch-gdb-using">
551
552 <title>Using the Debugger</title>
553 <para>
554 Debugging can now proceed as normal, as if the debugging were being done on the
555 local machine, for example to tell GDB to break in the <emphasis>main</emphasis>
556 function, for instance:
557 <programlisting>break main</programlisting>
558 and then to tell GDB to "continue" the inferior execution,
559 <programlisting>continue</programlisting>
560 </para>
561 <para>
562 For more information about using GDB please see the
563 project's online documentation at <ulink
564 url="http://sourceware.org/gdb/download/onlinedocs/"/>.
565 </para>
566 </section>
567 </section>
568
569</section>
570
571<section id="platdev-oprofile">
572 <title>Profiling with OProfile</title>
573
574 <para>
575 <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
576 statistical profiler well suited to finding performance
577 bottlenecks in both userspace software and the kernel. It provides
578 answers to questions like "Which functions does my application spend
579 the most time in when doing X?". Poky is well integrated with OProfile
580 to make profiling applications on target hardware straightforward.
581 </para>
582
583 <para>
584 To use OProfile you need an image with OProfile installed. The easiest
585 way to do this is with "tools-profile" in <glossterm><link
586 linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>. You also
587 need debugging symbols to be available on the system where the analysis
588 will take place. This can be achieved with "dbg-pkgs" in <glossterm><link
589 linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm> or by
590 installing the appropriate -dbg packages. For
591 successful call graph analysis the binaries must preserve the frame
592 pointer register and hence should be compiled with the
593 "-fno-omit-framepointer" flag. In Poky this can be achieved with
594 <glossterm><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION
595 </link></glossterm> = "-fexpensive-optimizations -fno-omit-framepointer
596 -frename-registers -O2" or by setting <glossterm><link
597 linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></glossterm> = "1" in
598 local.conf (the latter will also add extra debug information making the
599 debug packages large).
600 </para>
601
602 <section id="platdev-oprofile-target">
603 <title>Profiling on the target</title>
604
605 <para>
606 All the profiling work can be performed on the target device. A
607 simple OProfile session might look like:
608 </para>
609
610 <para>
611 <literallayout class='monospaced'>
612# opcontrol --reset
613# opcontrol --start --separate=lib --no-vmlinux -c 5
614[do whatever is being profiled]
615# opcontrol --stop
616$ opreport -cl
617</literallayout>
618 </para>
619
620 <para>
621 Here, the reset command clears any previously profiled data,
622 OProfile is then started. The options used to start OProfile mean
623 dynamic library data is kept separately per application, kernel
624 profiling is disabled and callgraphing is enabled up to 5 levels
625 deep. To profile the kernel, you would specify the
626 <parameter>--vmlinux=/path/to/vmlinux</parameter> option (the vmlinux file is usually in
627 <filename class="directory">/boot/</filename> in Poky and must match the running kernel). The profile is
628 then stopped and the results viewed with opreport with options
629 to see the separate library symbols and callgraph information.
630 </para>
631 <para>
632 Callgraphing means OProfile not only logs infomation about which
633 functions time is being spent in but also which functions
634 called those functions (their parents) and which functions that
635 function calls (its children). The higher the callgraphing depth,
636 the more accurate the results but this also increased the loging
637 overhead so it should be used with caution. On ARM, binaries need
638 to have the frame pointer enabled for callgraphing to work (compile
639 with the gcc option -fno-omit-framepointer).
640 </para>
641 <para>
642 For more information on using OProfile please see the OProfile
643 online documentation at <ulink
644 url="http://oprofile.sourceforge.net/docs/"/>.
645 </para>
646 </section>
647
648 <section id="platdev-oprofile-oprofileui">
649 <title>Using OProfileUI</title>
650
651 <para>
652 A graphical user interface for OProfile is also available. You can
653 either use prebuilt Debian packages from the <ulink
654 url='http://debian.o-hand.com/'>OpenedHand repository</ulink> or
655 download and build from svn at
656 http://svn.o-hand.com/repos/oprofileui/trunk/. If the
657 "tools-profile" image feature is selected, all necessary binaries
658 are installed onto the target device for OProfileUI interaction.
659 </para>
660
661<!-- DISBALED, Need a more 'contexual' shot?
662 <screenshot>
663 <mediaobject>
664 <imageobject>
665 <imagedata fileref="screenshots/ss-oprofile-viewer.png" format="PNG"/>
666 </imageobject>
667 <caption>
668 <para>OProfileUI Viewer showing an application being profiled on a remote device</para>
669 </caption>
670 </mediaobject>
671 </screenshot>
672-->
673 <para>
674 In order to convert the data in the sample format from the target
675 to the host the <filename>opimport</filename> program is needed.
676 This is not included in standard Debian OProfile packages but an
677 OProfile package with this addition is also available from the <ulink
678 url='http://debian.o-hand.com/'>OpenedHand repository</ulink>.
679 We recommend using OProfile 0.9.3 or greater. Other patches to
680 OProfile may be needed for recent OProfileUI features, but Poky
681 usually includes all needed patches on the target device. Please
682 see the <ulink
683 url='http://svn.o-hand.com/repos/oprofileui/trunk/README'>
684 OProfileUI README</ulink> for up to date information, and the
685 <ulink url="http://labs.o-hand.com/oprofileui">OProfileUI website
686 </ulink> for more information on the OProfileUI project.
687 </para>
688
689 <section id="platdev-oprofile-oprofileui-online">
690 <title>Online mode</title>
691
692 <para>
693 This assumes a working network connection with the target
694 hardware. In this case you just need to run <command>
695 "oprofile-server"</command> on the device. By default it listens
696 on port 4224. This can be changed with the <parameter>--port</parameter> command line
697 option.
698
699 </para>
700
701 <para>
702 The client program is called <command>oprofile-viewer</command>. The
703 UI is relatively straightforward, the key functionality is accessed
704 through the buttons on the toolbar (which are duplicated in the
705 menus.) These buttons are:
706 </para>
707
708 <itemizedlist>
709 <listitem>
710 <para>
711 Connect - connect to the remote host, the IP address or hostname for the
712 target can be supplied here.
713 </para>
714 </listitem>
715 <listitem>
716 <para>
717 Disconnect - disconnect from the target.
718 </para>
719 </listitem>
720 <listitem>
721 <para>
722 Start - start the profiling on the device.
723 </para>
724 </listitem>
725 <listitem>
726 <para>
727 Stop - stop the profiling on the device and download the data to the local
728 host. This will generate the profile and show it in the viewer.
729 </para>
730 </listitem>
731 <listitem>
732 <para>
733 Download - download the data from the target, generate the profile and show it
734 in the viewer.
735 </para>
736 </listitem>
737 <listitem>
738 <para>
739 Reset - reset the sample data on the device. This will remove the sample
740 information that was collected on a previous sampling run. Ensure you do this
741 if you do not want to include old sample information.
742 </para>
743 </listitem>
744 <listitem>
745 <para>
746 Save - save the data downloaded from the target to another directory for later
747 examination.
748 </para>
749 </listitem>
750 <listitem>
751 <para>
752 Open - load data that was previously saved.
753 </para>
754 </listitem>
755 </itemizedlist>
756
757 <para>
758 The behaviour of the client is to download the complete 'profile archive' from
759 the target to the host for processing. This archive is a directory containing
760 the sample data, the object files and the debug information for said object
761 files. This archive is then converted using a script included in this
762 distribution ('oparchconv') that uses 'opimport' to convert the archive from
763 the target to something that can be processed on the host.
764 </para>
765
766 <para>
767 Downloaded archives are kept in /tmp and cleared up when they are no longer in
768 use.
769 </para>
770
771 <para>
772 If you wish to profile into the kernel, this is possible, you just need to ensure
773 a vmlinux file matching the running kernel is available. In Poky this is usually
774 located in /boot/vmlinux-KERNELVERSION, where KERNEL-version is the version of
775 the kernel e.g. 2.6.23. Poky generates separate vmlinux packages for each kernel
776 it builds so it should be a question of just ensuring a matching package is
777 installed (<command> opkg install kernel-vmlinux</command>. These are automatically
778 installed into development and profiling images alongside OProfile. There is a
779 configuration option within the OProfileUI settings page where the location of
780 the vmlinux file can be entered.
781 </para>
782
783 <para>
784 Waiting for debug symbols to transfer from the device can be slow and it's not
785 always necessary to actually have them on device for OProfile use. All that is
786 needed is a copy of the filesystem with the debug symbols present on the viewer
787 system. The <link linkend='platdev-gdb-remotedebug-launch-gdb'>GDB remote debug
788 section</link> covers how to create such a directory with Poky and the location
789 of this directory can again be specified in the OProfileUI settings dialog. If
790 specified, it will be used where the file checksums match those on the system
791 being profiled.
792 </para>
793 </section>
794 <section id="platdev-oprofile-oprofileui-offline">
795 <title>Offline mode</title>
796
797 <para>
798 If no network access to the target is available an archive for processing in
799 'oprofile-viewer' can be generated with the following set of command.
800 </para>
801
802 <para>
803 <literallayout class='monospaced'>
804# opcontrol --reset
805# opcontrol --start --separate=lib --no-vmlinux -c 5
806[do whatever is being profiled]
807# opcontrol --stop
808# oparchive -o my_archive
809</literallayout>
810 </para>
811
812 <para>
813 Where my_archive is the name of the archive directory where you would like the
814 profile archive to be kept. The directory will be created for you. This can
815 then be copied to another host and loaded using 'oprofile-viewer''s open
816 functionality. The archive will be converted if necessary.
817 </para>
818 </section>
819 </section>
820</section>
821
822</chapter>
823<!--
824vim: expandtab tw=80 ts=4
825-->
diff --git a/documentation/poky-ref-manual/examples/hello-autotools/hello_2.3.bb b/documentation/poky-ref-manual/examples/hello-autotools/hello_2.3.bb
new file mode 100644
index 0000000000..5c5332f731
--- /dev/null
+++ b/documentation/poky-ref-manual/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/documentation/poky-ref-manual/examples/hello-single/files/helloworld.c b/documentation/poky-ref-manual/examples/hello-single/files/helloworld.c
new file mode 100644
index 0000000000..fc7169b7b8
--- /dev/null
+++ b/documentation/poky-ref-manual/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/documentation/poky-ref-manual/examples/hello-single/hello.bb b/documentation/poky-ref-manual/examples/hello-single/hello.bb
new file mode 100644
index 0000000000..d815b1ed73
--- /dev/null
+++ b/documentation/poky-ref-manual/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/documentation/poky-ref-manual/examples/libxpm/libxpm_3.5.6.bb b/documentation/poky-ref-manual/examples/libxpm/libxpm_3.5.6.bb
new file mode 100644
index 0000000000..2710189b2a
--- /dev/null
+++ b/documentation/poky-ref-manual/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/documentation/poky-ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb b/documentation/poky-ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb
new file mode 100644
index 0000000000..b21dc653af
--- /dev/null
+++ b/documentation/poky-ref-manual/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/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml
new file mode 100644
index 0000000000..662096844d
--- /dev/null
+++ b/documentation/poky-ref-manual/extendpoky.xml
@@ -0,0 +1,1040 @@
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 Before writing a recipe from scratch it is often useful to check
30 whether someone else has written one already. OpenEmbedded is a good place
31 to look as it has a wider scope and hence a wider range of packages.
32 Poky aims to be compatible with OpenEmbedded so most recipes should
33 just work in Poky.
34 </para>
35
36 <para>
37 For new packages, the simplest way to add a recipe is to base it on a similar
38 pre-existing recipe. There are some examples below of how to add
39 standard types of packages:
40 </para>
41
42 <section id='usingpoky-extend-addpkg-singlec'>
43 <title>Single .c File Package (Hello World!)</title>
44
45 <para>
46 To build an application from a single file stored locally (e.g. under "files/")
47 requires a recipe which has the file listed in the <glossterm><link
48 linkend='var-SRC_URI'>SRC_URI</link></glossterm> variable. In addition
49 the <function>do_compile</function> and <function>do_install</function>
50 tasks need to be manually written. The <glossterm><link linkend='var-S'>
51 S</link></glossterm> variable defines the directory containing the source
52 code which in this case is set equal to <glossterm><link linkend='var-WORKDIR'>
53 WORKDIR</link></glossterm>, the directory BitBake uses for the build.
54 </para>
55 <programlisting>
56DESCRIPTION = "Simple helloworld application"
57SECTION = "examples"
58LICENSE = "MIT"
59PR = "r0"
60
61SRC_URI = "file://helloworld.c"
62
63S = "${WORKDIR}"
64
65do_compile() {
66 ${CC} helloworld.c -o helloworld
67}
68
69do_install() {
70 install -d ${D}${bindir}
71 install -m 0755 helloworld ${D}${bindir}
72}
73 </programlisting>
74
75 <para>
76 As a result of the build process "helloworld", "helloworld-dbg" and "hellworld-dev"
77 packages will be built by default. It is possible to<link linkend='usingpoky-extend-addpkg-files'>
78 customise the packaging process</link>.
79 </para>
80 </section>
81
82 <section id='usingpoky-extend-addpkg-autotools'>
83 <title>Autotooled Package</title>
84
85 <para>
86 Applications which use autotools (autoconf, automake)
87 require a recipe which has a source archive listed in
88 <glossterm><link
89 linkend='var-SRC_URI'>SRC_URI</link></glossterm> and
90 <command>inherit autotools</command> to instruct BitBake to use the
91 <filename>autotools.bbclass</filename> which has
92 definitions of all the steps
93 needed to build an autotooled application.
94 The result of the build will be automatically packaged and if
95 the application uses NLS to localise then packages with
96 locale information will be generated (one package per
97 language). Below is one example (hello_2.2.bb)
98 </para>
99
100 <programlisting>
101DESCRIPTION = "GNU Helloworld application"
102SECTION = "examples"
103LICENSE = "GPLv2+"
104LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
105PR = "r0"
106
107SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
108
109inherit autotools gettext
110 </programlisting>
111
112 <para>
113 <glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link>
114 </glossterm> is used to <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
115 track source license change</link>. Autotool based recipe can be quickly
116 created this way like above example.
117 </para>
118
119 </section>
120
121 <section id='usingpoky-extend-addpkg-makefile'>
122 <title>Makefile-Based Package</title>
123
124 <para>
125 Applications which use GNU make require a recipe which has
126 the source archive listed in <glossterm><link
127 linkend='var-SRC_URI'>SRC_URI</link></glossterm>.
128 Adding a <function>do_compile</function> step
129 is not needed as by default BitBake will start the "make"
130 command to compile the application. If there is a need for
131 additional options to make then they should be stored in the
132 <glossterm><link
133 linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm> variable - BitBake
134 will pass them into the GNU
135 make invocation. A <function>do_install</function> task is required
136 - otherwise BitBake will run an empty <function>do_install</function>
137 task by default.
138 </para>
139
140 <para>
141 Some applications may require extra parameters to be passed to
142 the compiler, for example an additional header path. This can
143 be done buy adding to the <glossterm><link
144 linkend='var-CFLAGS'>CFLAGS</link></glossterm> variable, as in the example below:
145 </para>
146
147 <programlisting>
148CFLAGS_prepend = "-I ${S}/include "
149 </programlisting>
150
151 <para>
152 mtd-utils is an example as Makefile-based:
153 </para>
154
155 <programlisting>
156DESCRIPTION = "Tools for managing memory technology devices."
157SECTION = "base"
158DEPENDS = "zlib lzo e2fsprogs util-linux"
159HOMEPAGE = "http://www.linux-mtd.infradead.org/"
160LICENSE = "GPLv2"
161
162SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=v${PV}"
163
164S = "${WORKDIR}/git/"
165
166EXTRA_OEMAKE = "'CC=${CC}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' \
167 'BUILDDIR=${S}'"
168
169do_install () {
170 oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \
171 INCLUDEDIR=${includedir}
172 install -d ${D}${includedir}/mtd/
173 for f in ${S}/include/mtd/*.h; do
174 install -m 0644 $f ${D}${includedir}/mtd/
175 done
176}
177 </programlisting>
178
179 </section>
180
181 <section id='usingpoky-extend-addpkg-files'>
182 <title>Controlling packages content</title>
183
184 <para>
185 The variables <glossterm><link
186 linkend='var-PACKAGES'>PACKAGES</link></glossterm> and
187 <glossterm><link linkend='var-FILES'>FILES</link></glossterm> are used to split an
188 application into multiple packages.
189 </para>
190
191 <para>
192 Below the "libXpm" recipe (libxpm_3.5.7.bb) is used as an example. By
193 default the "libXpm" recipe generates one package
194 which contains the library
195 and also a few binaries. The recipe can be adapted to
196 split the binaries into separate packages.
197 </para>
198
199 <programlisting>
200require xorg-lib-common.inc
201
202DESCRIPTION = "X11 Pixmap library"
203LICENSE = "X-BSD"
204DEPENDS += "libxext libsm libxt"
205PR = "r3"
206PE = "1"
207
208XORG_PN = "libXpm"
209
210PACKAGES =+ "sxpm cxpm"
211FILES_cxpm = "${bindir}/cxpm"
212FILES_sxpm = "${bindir}/sxpm"
213 </programlisting>
214
215 <para>
216 In this example we want to ship the "sxpm" and "cxpm" binaries
217 in separate packages. Since "bindir" would be packaged into the
218 main <glossterm><link linkend='var-PN'>PN</link></glossterm>
219 package as standard we prepend the <glossterm><link
220 linkend='var-PACKAGES'>PACKAGES</link></glossterm> variable so
221 additional package names are added to the start of list. The
222 extra <glossterm><link linkend='var-FILES'>FILES</link></glossterm>_*
223 variables then contain information to specify which files and
224 directories goes into which package. Files included by earlier
225 package are skipped by latter packages, and thus main <glossterm>
226 <link linkend='var-PN'>PN</link></glossterm> will not include
227 above listed files
228 </para>
229 </section>
230
231 <section id='usingpoky-extend-addpkg-postinstalls'>
232 <title>Post Install Scripts</title>
233
234 <para>
235 To add a post-installation script to a package, add
236 a <function>pkg_postinst_PACKAGENAME()</function>
237 function to the .bb file
238 where PACKAGENAME is the name of the package to attach
239 the postinst script to. Normally <glossterm><link
240 linkend='var-PN'>PN</link></glossterm> can be used which expands
241 to PACKAGENAME automatically. A post-installation function has the
242 following structure:
243 </para>
244 <programlisting>
245pkg_postinst_PACKAGENAME () {
246#!/bin/sh -e
247# Commands to carry out
248}
249 </programlisting>
250 <para>
251 The script defined in the post installation function
252 gets called when the rootfs is made. If the script succeeds,
253 the package is marked as installed. If the script fails,
254 the package is marked as unpacked and the script will be
255 executed again on the first boot of the image.
256 </para>
257
258 <para>
259 Sometimes it is necessary that the execution of a post-installation
260 script is delayed until the first boot, because the script
261 needs to be executed on the device itself. To delay script execution
262 until boot time, the post-installation function should have the
263 following structure:
264 </para>
265
266 <programlisting>
267pkg_postinst_PACKAGENAME () {
268#!/bin/sh -e
269if [ x"$D" = "x" ]; then
270 # Actions to carry out on the device go here
271else
272 exit 1
273fi
274}
275 </programlisting>
276
277 <para>
278 The structure above delays execution until first boot
279 because the <glossterm><link
280 linkend='var-D'>D</link></glossterm> variable points
281 to the 'image'
282 directory when the rootfs is being made at build time but
283 is unset when executed on the first boot.
284 </para>
285 </section>
286
287 </section>
288
289 <section id='usingpoky-extend-customimage'>
290 <title>Customising Images</title>
291
292 <para>
293 Poky images can be customised to satisfy
294 particular requirements. Several methods are detailed below
295 along with guidelines of when to use them.
296 </para>
297
298 <section id='usingpoky-extend-customimage-custombb'>
299 <title>Customising Images through a custom image .bb files</title>
300
301 <para>
302 One way to get additional software into an image is by creating a
303 custom image. The recipe will contain two lines:
304 </para>
305
306 <programlisting>
307IMAGE_INSTALL = "task-poky-x11-base package1 package2"
308
309inherit poky-image
310 </programlisting>
311
312 <para>
313 By creating a custom image, a developer has total control
314 over the contents of the image. It is important to use
315 the correct names of packages in the <glossterm><link
316 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> variable.
317 The names must be in
318 the OpenEmbedded notation instead of Debian notation, for example
319 "glibc-dev" instead of "libc6-dev" etc.
320 </para>
321
322 <para>
323 The other method of creating a new image is by modifying
324 an existing image. For example if a developer wants to add
325 "strace" into "poky-image-sato" the following recipe can
326 be used:
327 </para>
328
329 <programlisting>
330require poky-image-sato.bb
331
332IMAGE_INSTALL += "strace"
333 </programlisting>
334
335 </section>
336
337 <section id='usingpoky-extend-customimage-customtasks'>
338 <title>Customising Images through custom tasks</title>
339
340 <para>
341 For complex custom images, the best approach is to create a custom
342 task package which is then used to build the image (or images). A good
343 example of a tasks package is <filename>meta/packages/tasks/task-poky.bb
344 </filename>. The <glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm>
345 variable lists the task packages to build (along with the complementary
346 -dbg and -dev packages). For each package added,
347 <glossterm><link linkend='var-PACKAGES'>RDEPENDS</link></glossterm> and
348 <glossterm><link linkend='var-PACKAGES'>RRECOMMENDS</link></glossterm>
349 entries can then be added each containing a list of packages the parent
350 task package should contain. An example would be:
351 </para>
352
353 <para>
354 <programlisting>
355DESCRIPTION = "My Custom Tasks"
356
357PACKAGES = "\
358 task-custom-apps \
359 task-custom-apps-dbg \
360 task-custom-apps-dev \
361 task-custom-tools \
362 task-custom-tools-dbg \
363 task-custom-tools-dev \
364 "
365
366RDEPENDS_task-custom-apps = "\
367 dropbear \
368 portmap \
369 psplash"
370
371RDEPENDS_task-custom-tools = "\
372 oprofile \
373 oprofileui-server \
374 lttng-control \
375 lttng-viewer"
376
377RRECOMMENDS_task-custom-tools = "\
378 kernel-module-oprofile"
379</programlisting>
380 </para>
381
382 <para>
383 In this example, two task packages are created, task-custom-apps and
384 task-custom-tools with the dependencies and recommended package dependencies
385 listed. To build an image using these task packages, you would then add
386 "task-custom-apps" and/or "task-custom-tools" to <glossterm><link
387 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> or other forms
388 of image dependencies as described in other areas of this section.
389 </para>
390 </section>
391
392 <section id='usingpoky-extend-customimage-imagefeatures'>
393 <title>Customising Images through custom <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm></title>
394
395 <para>
396 Ultimately users may want to add extra image "features" as used by Poky with the
397 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
398 variable. To create these, the best reference is <filename>meta/classes/poky-image.bbclass</filename>
399 which illustrates how poky achieves this. In summary, the file looks at the contents of the
400 <glossterm><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></glossterm>
401 variable and then maps this into a set of tasks or packages. Based on this then the
402 <glossterm><link linkend='var-IMAGE_INSTALL'> IMAGE_INSTALL</link></glossterm>
403 variable is generated automatically. Extra features can be added by
404 extending the class or creating a custom class for use with specialised image .bb files.
405 </para>
406 </section>
407
408 <section id='usingpoky-extend-customimage-localconf'>
409 <title>Customising Images through local.conf</title>
410
411 <para>
412 It is possible to customise image contents by abusing
413 variables used by distribution maintainers in local.conf.
414 This method only allows the addition of packages and
415 is not recommended.
416 </para>
417
418 <para>
419 To add an "strace" package into the image the following is
420 added to local.conf:
421 </para>
422
423 <programlisting>
424DISTRO_EXTRA_RDEPENDS += "strace"
425 </programlisting>
426
427 <para>
428 However, since the <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'>
429 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable is for
430 distribution maintainers this method does not make
431 adding packages as simple as a custom .bb file. Using
432 this method, a few packages will need to be recreated if they have been
433 created before and then the image is rebuilt.
434 </para>
435 <programlisting>
436bitbake -c clean task-boot task-base task-poky
437bitbake poky-image-sato
438 </programlisting>
439
440 <para>
441 Cleaning task-* packages is required because they use the
442 <glossterm><link linkend='var-DISTRO_EXTRA_RDEPENDS'>
443 DISTRO_EXTRA_RDEPENDS</link></glossterm> variable. There is no need to
444 build them by hand as Poky images depend on the packages they contain so
445 dependencies will be built automatically when building the image. For this reason we don't use the
446 "rebuild" task in this case since "rebuild" does not care about
447 dependencies - it only rebuilds the specified package.
448 </para>
449
450 </section>
451
452 </section>
453
454<section id="platdev-newmachine">
455 <title>Porting Poky to a new machine</title>
456 <para>
457 Adding a new machine to Poky is a straightforward process and
458 this section gives an idea of the changes that are needed. This guide is
459 meant to cover adding machines similar to those Poky already supports.
460 Adding a totally new architecture might require gcc/glibc changes as
461 well as updates to the site information and, whilst well within Poky's
462 capabilities, is outside the scope of this section.
463 </para>
464
465 <section id="platdev-newmachine-conffile">
466 <title>Adding the machine configuration file</title>
467 <para>
468 A .conf file needs to be added to conf/machine/ with details of the
469 device being added. The name of the file determines the name Poky will
470 use to reference this machine.
471 </para>
472
473 <para>
474 The most important variables to set in this file are <glossterm>
475 <link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></glossterm>
476 (e.g. "arm"), <glossterm><link linkend='var-PREFERRED_PROVIDER'>
477 PREFERRED_PROVIDER</link></glossterm>_virtual/kernel (see below) and
478 <glossterm><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES
479 </link></glossterm> (e.g. "kernel26 apm screen wifi"). Other variables
480 like <glossterm><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE
481 </link></glossterm> (e.g. "115200 ttyS0"), <glossterm>
482 <link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link>
483 </glossterm> (e.g. "zImage") and <glossterm><link linkend='var-IMAGE_FSTYPES'>
484 IMAGE_FSTYPES</link></glossterm> (e.g. "tar.gz jffs2") might also be
485 needed. Full details on what these variables do and the meaning of
486 their contents is available through the links. There're lots of existing
487 machine .conf files which can be easily leveraged from meta/conf/machine/.
488 </para>
489 </section>
490
491 <section id="platdev-newmachine-kernel">
492 <title>Adding a kernel for the machine</title>
493 <para>
494 Poky needs to be able to build a kernel for the machine. You need
495 to either create a new kernel recipe for this machine or extend an
496 existing recipe. There are plenty of kernel examples in the
497 meta/recipes-kernel/linux directory which can be used as references.
498 </para>
499 <para>
500 If creating a new recipe the "normal" recipe writing rules apply
501 for setting up a <glossterm><link linkend='var-SRC_URI'>SRC_URI
502 </link></glossterm> including any patches and setting <glossterm>
503 <link linkend='var-S'>S</link></glossterm> to point at the source
504 code. You will need to create a configure task which configures the
505 unpacked kernel with a defconfig be that through a "make defconfig"
506 command or more usually though copying in a suitable defconfig and
507 running "make oldconfig". By making use of "inherit kernel" and also
508 maybe some of the linux-*.inc files, most other functionality is
509 centralised and the the defaults of the class normally work well.
510 </para>
511 <para>
512 If extending an existing kernel it is usually a case of adding a
513 suitable defconfig file in a location similar to that used by other
514 machine's defconfig files in a given kernel, possibly listing it in
515 the SRC_URI and adding the machine to the expression in <glossterm>
516 <link linkend='var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</link>
517 </glossterm>:
518 </para>
519 <programlisting>
520COMPATIBLE_MACHINE = '(qemux86|qemumips)'
521 </programlisting>
522 </section>
523
524 <section id="platdev-newmachine-formfactor">
525 <title>Adding a formfactor configuration file</title>
526 <para>
527 A formfactor configuration file provides information about the
528 target hardware on which Poky is running, and that Poky cannot
529 obtain from other sources such as the kernel. Some examples of
530 information contained in a formfactor configuration file include
531 framebuffer orientation, whether or not the system has a keyboard,
532 the positioning of the keyboard in relation to the screen, and
533 screen resolution.
534 </para>
535 <para>
536 Sane defaults should be used in most cases, but if customisation is
537 necessary you need to create a <filename>machconfig</filename> file
538 under <filename>meta/packages/formfactor/files/MACHINENAME/</filename>
539 where <literal>MACHINENAME</literal> is the name for which this infomation
540 applies. For information about the settings available and the defaults, please see
541 <filename>meta/packages/formfactor/files/config</filename>. Below is one
542 example for qemuarm:
543 </para>
544 <programlisting>
545HAVE_TOUCHSCREEN=1
546HAVE_KEYBOARD=1
547
548DISPLAY_CAN_ROTATE=0
549DISPLAY_ORIENTATION=0
550#DISPLAY_WIDTH_PIXELS=640
551#DISPLAY_HEIGHT_PIXELS=480
552#DISPLAY_BPP=16
553DISPLAY_DPI=150
554DISPLAY_SUBPIXEL_ORDER=vrgb
555 </programlisting>
556 </section>
557</section>
558
559<section id='usingpoky-changes'>
560 <title>Making and Maintaining Changes</title>
561
562 <para>
563 We recognise that people will want to extend/configure/optimise Poky for
564 their specific uses, especially due to the extreme configurability and
565 flexibility Poky offers. To ensure ease of keeping pace with future
566 changes in Poky we recommend making changes to Poky in a controlled way.
567 </para>
568 <para>
569 Poky supports the idea of <link
570 linkend='usingpoky-changes-layers'>"layers"</link> which when used
571 properly can massively ease future upgrades and allow segregation
572 between the Poky core and a given developer's changes. Some other advice on
573 managing changes to Poky is also given in the following section.
574 </para>
575
576 <section id="usingpoky-changes-layers">
577 <title>Bitbake Layers</title>
578
579 <para>
580 Often, people want to extend Poky either through adding packages
581 or overriding files contained within Poky to add their own
582 functionality. Bitbake has a powerful mechanism called
583 layers which provides a way to handle this extension in a fully
584 supported and non-invasive fashion.
585 </para>
586
587 <para>
588 The Poky tree includes several additional layers which demonstrate
589 this functionality, such as meta-emenlow and meta-extras.
590 The meta-emenlow layer is an example layer enabled by default. The meta-extras
591 repostory is not enabled by default but enabling any layer is as easy as adding
592 the layers path to the BBLAYERS variable in your bblayers.conf. this is how
593 meta-extras are enabled in Poky builds:
594 </para>
595 <para>
596 <literallayout class='monospaced'>LCONF_VERSION = "1"
597
598BBFILES ?= ""
599BBLAYERS = " \
600 /path/to/poky/meta \
601 /path/to/poky/meta-moblin \
602 /path/to/poky/meta-emenlow \
603 /path/to/poky/meta-extras \
604 "
605</literallayout>
606 </para>
607
608 <para>
609 Bitbake parses the conf/layer.conf of each of the layers in BBLAYERS
610 to add the layers packages, classes and configuration to Poky.
611 To create your own layer, independent of the main Poky repository,
612 you need only create a directory with a conf/layer.conf file and
613 add the directory to your bblayers.conf.
614 </para>
615
616 <para>
617 The meta-emenlow/conf/layer.conf demonstrates the required syntax:
618 <literallayout class='monospaced'># We have a conf and classes directory, add to BBPATH
619BBPATH := "${BBPATH}:${LAYERDIR}"
620
621# We have a packages directory, add to BBFILES
622BBFILES := "${BBFILES} ${LAYERDIR}/packages/*/*.bb \
623 ${LAYERDIR}/packages/*/*.bbappend"
624
625BBFILE_COLLECTIONS += "emenlow"
626BBFILE_PATTERN_emenlow := "^${LAYERDIR}/"
627BBFILE_PRIORITY_emenlow = "6"
628 </literallayout>
629 </para>
630
631 <para>
632 As can be seen, the layers recipes are added to
633 <glossterm> <link linkend='var-BBFILES'>BBFILES</link></glossterm>. The
634 BBFILE_COLLECTIONS variable is then appended to with the
635 layer name. The BBFILE_PATTERN variable is immediately expanded
636 with a regular expression used to match files from BBFILES into
637 a particular layer, in this case by using the base pathname.
638 The BBFILE_PRIORITY variable then assigns different
639 priorities to the files in different layers. This is useful
640 in situations where the same package might appear in multiple
641 layers and allows you to choose which layer should 'win'.
642 Note the use of <glossterm><link linkend='var-LAYERDIR'>
643 LAYERDIR</link></glossterm> with the immediate expansion operator.
644 <glossterm><link linkend='var-LAYERDIR'>LAYERDIR</link></glossterm>
645 expands to the directory of the current layer and
646 requires use of the immediate expansion operator so that Bitbake
647 does not lazily expand the variable when it's parsing a
648 different directory.
649 </para>
650
651 <para>
652 Additional bbclass and configuration files can be locationed by
653 bitbake through the addition to the BBPATH
654 environment variable. In this case, the first file with the
655 matching name found in BBPATH is the one that is used, just
656 like the PATH variable for binaries. It is therefore recommended
657 that you use unique bbclass and configuration file names in your
658 custom layer.
659 </para>
660
661 <para>
662 The recommended approach for custom layers is to store them in a
663 git repository of the format meta-prvt-XXXX and have this repository
664 cloned alongside the other meta directories in the Poky tree.
665 This way you can keep your Poky tree and it's configuration entirely
666 inside POKYBASE.
667 </para>
668 </section>
669
670 <section id='usingpoky-changes-commits'>
671 <title>Committing Changes</title>
672
673 <para>
674 Modifications to Poky are often managed under some kind of source
675 revision control system. The policy for committing to such systems
676 is important as some simple policy can significantly improve
677 usability. The tips below are based on the policy followed for the
678 Poky core.
679 </para>
680
681 <para>
682 It helps to use a consistent style for commit messages when committing
683 changes. We've found a style where the first line of a commit message
684 summarises the change and starts with the name of any package affected
685 work well. Not all changes are to specific packages so the prefix could
686 also be a machine name or class name instead. If a change needs a longer
687 description this should follow the summary:
688 </para>
689
690 <literallayout class='monospaced'>
691 bitbake/data.py: Add emit_func() and generate_dependencies() functions
692
693 These functions allow generation of dependency data between funcitons and
694 variables allowing moves to be made towards generating checksums and allowing
695 use of the dependency information in other parts of bitbake.
696
697 Signed-off-by: Richard Purdie rpurdie@linux.intel.com
698 </literallayout>
699
700 <para>
701 Any commit should be self contained in that it should leave the
702 metadata in a consistent state, buildable before and after the
703 commit. This helps ensure the autobuilder test results are valid
704 but is good practice regardless.
705 </para>
706 </section>
707
708 <section id='usingpoky-changes-prbump'>
709 <title>Package Revision Incrementing</title>
710
711 <para>
712 If a committed change will result in changing the package output
713 then the value of the <glossterm><link linkend='var-PR'>PR</link>
714 </glossterm> variable needs to be increased (commonly referred to
715 as 'bumped') as part of that commit. Only integer values are used
716 and <glossterm><link linkend='var-PR'>PR</link></glossterm> =
717 "r0" should be added into new recipes as, while this is the
718 default value, not having the variable defined in a recipe makes
719 it easy to miss incrementing it when updating the recipe.
720 When upgrading the version of a package (<glossterm><link
721 linkend='var-PV'>PV</link></glossterm>), the <glossterm><link
722 linkend='var-PR'>PR</link></glossterm> variable should be reset to "r0".
723 </para>
724
725 <para>
726 The aim is that the package version will only ever increase. If
727 for some reason <glossterm><link linkend='var-PV'>PV</link></glossterm>
728 will change and but not increase, the <glossterm><link
729 linkend='var-PE'>PE</link></glossterm> (Package Epoch) can
730 be increased (it defaults to '0'). The version numbers aim to
731 follow the <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
732 Debian Version Field Policy Guidelines</ulink> which define how
733 versions are compared and hence what "increasing" means.
734 </para>
735
736 <para>
737 There are two reasons for doing this, the first is to ensure that
738 when a developer updates and rebuilds, they get all the changes to
739 the repository and don't have to remember to rebuild any sections.
740 The second is to ensure that target users are able to upgrade their
741 devices via their package manager such as with the <command>
742 opkg upgrade</command> commands (or similar for
743 dpkg/apt or rpm based systems). The aim is to ensure Poky has
744 upgradable packages in all cases.
745 </para>
746 </section>
747 <section id='usingpoky-changes-collaborate'>
748 <title>Using Poky in a Team Environment</title>
749
750 <para>
751 It may not be immediately clear how Poky can work in a team environment,
752 or scale to a large team of developers. The specifics of any situation
753 will determine the best solution and poky offers immense flexibility in
754 that aspect but there are some practises that experience has shown to work
755 well.
756 </para>
757
758 <para>
759 The core component of any development effort with Poky is often an
760 automated build testing framework and image generation process. This
761 can be used to check that the metadata is buildable, highlight when
762 commits break the builds and provide up to date images allowing people
763 to test the end result and use them as a base platform for further
764 development. Experience shows that buildbot is a good fit for this role
765 and that it works well to configure it to make two types of build -
766 incremental builds and 'from scratch'/full builds. The incremental builds
767 can be tied to a commit hook which triggers them each time a commit is
768 made to the metadata and are a useful acid test of whether a given commit
769 breaks the build in some serious way. They catch lots of simple errors
770 and whilst they won't catch 100% of failures, the tests are fast so
771 developers can get feedback on their changes quickly. The full builds
772 are builds that build everything from the ground up and test everything.
773 They usually happen at preset times such as at night when the machine
774 load isn't high from the incremental builds.
775 <ulink url='http://autobuilder.pokylinux.org:8010'>poky autobuilder</ulink>
776 is an example implementation with buildbot.
777 </para>
778
779 <para>
780 Most teams have pieces of software undergoing active development. It is of
781 significant benefit to put these under control of a source control system
782 compatible with Poky such as git or svn. The autobuilder can then be set to
783 pull the latest revisions of these packages so the latest commits get tested
784 by the builds allowing any issues to be highlighted quickly. Poky easily
785 supports configurations where there is both a stable known good revision
786 and a floating revision to test. Poky can also only take changes from specific
787 source control branches giving another way it can be used to track/test only
788 specified changes.
789 </para>
790 <para>
791 Perhaps the hardest part of setting this up is the policy that surrounds
792 the different source control systems, be them software projects or the Poky
793 metadata itself. The circumstances will be different in each case but this is
794 one of Poky's advantages - the system itself doesn't force any particular policy
795 unlike a lot of build systems, allowing the best policy to be chosen for the
796 circumstances.
797 </para>
798 </section>
799
800 <section id='usingpoky-changes-updatingimages'>
801 <title>Updating Existing Images</title>
802
803 <para>
804 Often, rather than reflashing a new image you might wish to install updated
805 packages into an existing running system. This can be done by sharing the <filename class="directory">tmp/deploy/ipk/</filename> directory through a web server and then on the device, changing <filename>/etc/opkg/base-feeds.conf</filename> to point at this server, for example by adding:
806 </para>
807 <literallayout class='monospaced'>
808src/gz all http://www.mysite.com/somedir/deploy/ipk/all
809src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a
810src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard</literallayout>
811 </section>
812 </section>
813
814 <section id='usingpoky-modifing-packages'>
815 <title>Modifying Package Source Code</title>
816
817 <para>
818 Poky is usually used to build software rather than modifying
819 it. However, there are ways Poky can be used to modify software.
820 </para>
821
822 <para>
823 During building, the sources are available in <glossterm><link
824 linkend='var-WORKDIR'>WORKDIR</link></glossterm> directory.
825 Where exactly this is depends on the type of package and the
826 architecture of target device. For a standard recipe not
827 related to <glossterm><link
828 linkend='var-MACHINE'>MACHINE</link></glossterm> it will be
829 <filename>tmp/work/PACKAGE_ARCH-poky-TARGET_OS/PN-PV-PR/</filename>.
830 Target device dependent packages use <glossterm><link
831 linkend='var-MACHINE'>MACHINE
832 </link></glossterm>
833 instead of <glossterm><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH
834 </link></glossterm>
835 in the directory name.
836 </para>
837
838 <tip>
839 <para>
840 Check the package recipe sets the <glossterm><link
841 linkend='var-S'>S</link></glossterm> variable to something
842 other than standard <filename>WORKDIR/PN-PV/</filename> value.
843 </para>
844 </tip>
845 <para>
846 After building a package, a user can modify the package source code
847 without problem. The easiest way to test changes is by calling the
848 "compile" task:
849 </para>
850
851 <programlisting>
852bitbake -c compile -f NAME_OF_PACKAGE
853 </programlisting>
854
855 <para>
856 "-f" or "--force" is used to force re-execution of the specified task.
857 Other tasks may also be called this way. But note that all the modifications
858 in <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>
859 are gone once you executes "-c clean" for a package.
860 </para>
861
862 <section id='usingpoky-modifying-packages-quilt'>
863 <title>Modifying Package Source Code with quilt</title>
864
865 <para>
866 By default Poky uses <ulink
867 url='http://savannah.nongnu.org/projects/quilt'>quilt</ulink>
868 to manage patches in <function>do_patch</function> task.
869 It is a powerful tool which can be used to track all
870 modifications done to package sources.
871 </para>
872
873 <para>
874 Before modifying source code it is important to
875 notify quilt so it will track changes into new patch
876 file:
877 <programlisting>
878quilt new NAME-OF-PATCH.patch
879 </programlisting>
880
881 Then add all files which will be modified into that
882 patch:
883 <programlisting>
884quilt add file1 file2 file3
885 </programlisting>
886
887 Now start editing. At the end quilt needs to be used
888 to generate final patch which will contain all
889 modifications:
890 <programlisting>
891quilt refresh
892 </programlisting>
893
894 The resulting patch file can be found in the
895 <filename class="directory">patches/</filename> subdirectory of the source
896 (<glossterm><link linkend='var-S'>S</link></glossterm>) directory. For future builds it
897 should be copied into
898 Poky metadata and added into <glossterm><link
899 linkend='var-SRC_URI'>SRC_URI</link></glossterm> of a recipe:
900 <programlisting>
901SRC_URI += "file://NAME-OF-PATCH.patch"
902 </programlisting>
903
904 This also requires a bump of <glossterm><link
905 linkend='var-PR'>PR</link></glossterm> value in the same recipe as we changed resulting packages.
906 </para>
907
908 </section>
909
910 </section>
911 <section id='usingpoky-configuring-LIC_FILES_CHKSUM'>
912 <title>Track license change</title>
913 <para>
914 The license of one upstream project may change in the future, and Poky provides
915 one mechanism to track such license change - <glossterm>
916 <link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></glossterm> variable.
917 </para>
918
919 <section id='usingpoky-specifying-LIC_FILES_CHKSUM'>
920 <title>Specifying the LIC_FILES_CHKSUM variable </title>
921
922 <programlisting>
923LIC_FILES_CHKSUM = "file://COPYING; md5=xxxx \
924 file://licfile1.txt; beginline=5; endline=29;md5=yyyy \
925 file://licfile2.txt; endline=50;md5=zzzz \
926 ..."
927 </programlisting>
928
929 <para>
930 <glossterm><link linkend='var-S'>S</link></glossterm> is the default directory
931 for searching files listed in <glossterm><link linkend='var-LIC_FILES_CHKSUM'>
932 LIC_FILES_CHKSUM</link></glossterm>. Relative path could be used too:
933 </para>
934
935 <programlisting>
936LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
937 md5=bb14ed3c4cda583abc85401304b5cd4e"
938LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
939 </programlisting>
940
941 <para>
942 The first line locates a file in <glossterm><link linkend='var-S'>
943 S</link></glossterm>/src/ls.c, and the second line refers to a file in
944 <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>, which is the parent
945 of <glossterm><link linkend='var-S'>S</link></glossterm>
946 </para>
947
948 </section>
949
950 <section id='usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax'>
951 <title>Explanation of syntax</title>
952
953 <para>
954 This parameter lists all the important files containing the text
955of licenses for the
956source code. It is also possible to specify on which line the license text
957starts and on which line it ends within that file using the "beginline" and
958"endline" parameters. If the "beginline" parameter is not specified then license
959text begins from the 1st line is assumed. Similarly if "endline" parameter is
960not specified then the license text ends at the last line in the file is
961assumed. So if a file contains only licensing information, then there is no need
962to specify "beginline" and "endline" parameters.
963 </para>
964 <para>
965The "md5" parameter stores the md5 checksum of the license text. So if
966the license text changes in any way from a file, then its md5 sum will differ and will not
967match with the previously stored md5 checksum. This mismatch will trigger build
968failure, notifying developer about the license text md5 mismatch, and allowing
969the developer to review the license text changes. Also note that if md5 checksum
970is not matched while building, the correct md5 checksum is printed in the build
971log which can be easily copied to .bb file.
972 </para>
973 <para>
974There is no limit on how many files can be specified on this parameter. But generally every
975project would need specifying of just one or two files for license tracking.
976Many projects would have a "COPYING" file which will store all the
977license information for all the source code files. If the "COPYING" file
978is valid then tracking only that file would be enough.
979 </para>
980 <tip>
981 <para>
9821. If you specify empty or invalid "md5" parameter; then while building
983the package, bitbake will give md5 not matched error, and also show the correct
984"md5" parameter value both on the screen and in the build log
985 </para>
986 <para>
9872. If the whole file contains only license text, then there is no need to
988specify "beginline" and "endline" parameters.
989 </para>
990 </tip>
991 </section>
992 </section>
993 <section id='usingpoky-configuring-DISTRO_PN_ALIAS'>
994 <title>Handle package name alias</title>
995 <para>
996Poky implements a distro_check task which automatically connects to major distributions
997and checks whether they contains same package. Sometimes the same package has different
998names in different distributions, which results in a mismatch from distro_check task
999This can be solved by defining per distro recipe name alias -
1000<glossterm><link linkend='var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</link></glossterm>
1001 </para>
1002
1003 <section id='usingpoky-specifying-DISTRO_PN_ALIAS'>
1004 <title>Specifying the DISTRO_PN_ALIAS variable </title>
1005
1006 <programlisting>
1007DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
1008 distro2=package_name_alias2 \
1009 distro3=package_name_alias3 \
1010 ..."
1011 </programlisting>
1012 <para>
1013Use space as the delimiter if there're multiple distro aliases
1014 </para>
1015 <tip>
1016 <para>
1017The current code can check if the src package for a recipe exists in the latest
1018releases of these distributions automatically.
1019 </para>
1020 <programlisting>
1021Fedora, OpenSuSE, Debian, Ubuntu, Mandriva
1022 </programlisting>
1023 <para>
1024For example, this command will generate a report, listing which linux distros include the
1025sources for each of the poky recipe.
1026 </para>
1027 <programlisting>
1028bitbake world -f -c distro_check
1029 </programlisting>
1030 <para>
1031The results will be stored in the build/tmp/log/distro_check-${DATETIME}.results file.
1032 </para>
1033 </tip>
1034 </section>
1035 </section>
1036</chapter>
1037
1038<!--
1039vim: expandtab tw=80 ts=4
1040-->
diff --git a/documentation/poky-ref-manual/faq.xml b/documentation/poky-ref-manual/faq.xml
new file mode 100644
index 0000000000..b209fff81d
--- /dev/null
+++ b/documentation/poky-ref-manual/faq.xml
@@ -0,0 +1,314 @@
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 an autobuilder 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, ipk (for ipkg/opkg), Debian package (.deb), or RPM. The packages 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 I see the error 'chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x'. What's wrong?
142 </para>
143 </question>
144 <answer>
145 <para>
146 You're probably running the build on an NTFS filesystem. Use a sane one like ext2/3/4 instead!
147 </para>
148 </answer>
149 </qandaentry>
150 <qandaentry>
151 <question>
152 <para>
153 How do I make Poky work in RHEL/CentOS?
154 </para>
155 </question>
156 <answer>
157 <para>
158 To get Poky working under RHEL/CentOS 5.1 you need to first install some required packages. The standard CentOS packages needed are:
159 <itemizedlist>
160 <listitem>
161 <para>
162 "Development tools" (selected during installation)
163 </para>
164 </listitem>
165 <listitem>
166 <para>
167 texi2html
168 </para>
169 </listitem>
170 <listitem>
171 <para>
172 compat-gcc-34
173 </para>
174 </listitem>
175 </itemizedlist>
176 </para>
177
178 <para>
179 On top of those the following external packages are needed:
180 <itemizedlist>
181 <listitem>
182 <para>
183 python-sqlite2 from <ulink
184 url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG
185 repository</ulink>
186 </para>
187 </listitem>
188 <listitem>
189 <para>
190 help2man from <ulink
191 url='http://centos.karan.org/el5/extras/testing/i386/RPMS/help2man-1.33.1-2.noarch.rpm'>Karan
192 repository</ulink>
193 </para>
194 </listitem>
195 </itemizedlist>
196 </para>
197
198 <para>
199 Once these packages are installed Poky will be able to build standard images however there
200 may be a problem with QEMU segfaulting. You can either disable the generation of binary
201 locales by setting <glossterm><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
202 </glossterm> to "0" or remove the linux-2.6-execshield.patch from the kernel and rebuild
203 it since its that patch which causes the problems with QEMU.
204 </para>
205 </answer>
206 </qandaentry>
207 <qandaentry>
208 <question>
209 <para>
210 I see lots of 404 responses for files on http://pokylinux.org/sources/*. Is something wrong?
211 </para>
212 </question>
213 <answer>
214 <para>
215 Nothing is wrong, Poky will check any configured source mirrors before downloading
216 from the upstream sources. It does this searching for both source archives and
217 pre-checked out versions of SCM managed software. This is so in large installations,
218 it can reduce load on the SCM servers themselves. The address above is one of the
219 default mirrors configured into standard Poky so if an upstream source disappears,
220 we can place sources there so builds continue to work.
221 </para>
222 </answer>
223 </qandaentry>
224 <qandaentry>
225 <question>
226 <para>
227 I have a machine specific data in a package for one machine only but the package is
228 being marked as machine specific in all cases, how do I stop it?
229 </para>
230 </question>
231 <answer>
232 <para>
233 Set <glossterm><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
234 </glossterm> = "0" in the .bb file but make sure the package is manually marked as
235 machine specific in the case that needs it. The code which handles <glossterm><link
236 linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link></glossterm>
237 is in base.bbclass.
238 </para>
239 </answer>
240 </qandaentry>
241 <qandaentry>
242 <question>
243 <para>
244 I'm behind a firewall and need to use a proxy server. How do I do that?
245 </para>
246 </question>
247 <answer>
248 <para>
249 Most source fetching by Poky is done by wget and you therefore need to specify the proxy
250 settings in a .wgetrc file in your home directory. Example settings in that file would be
251 'http_proxy = http://proxy.yoyodyne.com:18023/' and 'ftp_proxy = http://proxy.yoyodyne.com:18023/'.
252 Poky also includes a site.conf.sample file which shows how to configure cvs and git proxy servers
253 if needed.
254 </para>
255 </answer>
256 </qandaentry>
257 <qandaentry>
258 <question>
259 <para>
260 I'm using Ubuntu Intrepid and am seeing build failures. Whats wrong?
261 </para>
262 </question>
263 <answer>
264 <para>
265 In Intrepid, Ubuntu turned on by default normally optional compile-time security features
266 and warnings. There are more details at <ulink
267 url='https://wiki.ubuntu.com/CompilerFlags'>https://wiki.ubuntu.com/CompilerFlags</ulink>.
268 You can work around this problem by disabling those options by adding " -Wno-format-security -U_FORTIFY_SOURCE"
269 to the BUILD_CPPFLAGS variable in conf/bitbake.conf.
270 </para>
271 </answer>
272 </qandaentry>
273 <qandaentry>
274 <question>
275 <para>
276 Whats the difference between foo and foo-native?
277 </para>
278 </question>
279 <answer>
280 <para>
281 The *-native targets are designed to run on the system the build is running on. These are usually tools that are needed to assist the build in some way such as quilt-native which is used to apply patches. The non-native version is the one that would run on the target device.
282 </para>
283 </answer>
284 </qandaentry>
285 <qandaentry>
286 <question>
287 <para>
288 I'm seeing random build failures. Help?!
289 </para>
290 </question>
291 <answer>
292 <para>
293 If the same build is failing in totally different and random ways the most likely explaination is that either the hardware you're running it on has some problem or if you are running it under virtualisation, the virtualisation probably has bugs. Poky processes a massive amount of data causing lots of network, disk and cpu activity and is senstive to even single bit failure in any of these areas. Totally random failures have always been traced back to hardware or virtualisation issues.
294 </para>
295 </answer>
296 </qandaentry>
297 <qandaentry>
298 <question>
299 <para>
300 What do we need to ship for licence complience?
301 </para>
302 </question>
303 <answer>
304 <para>
305 This is a difficult question and you need to consult your lawyer for the answer for your specific case. Its worth bearing in mind that for GPL complience there needs to be enough information shipped to allow someone else to rebuild the same end result as you are shipping. This means sharing the source code, any patches applied to it but also any configuration information about how that package was configured and built.
306 </para>
307 </answer>
308 </qandaentry>
309</qandaset>
310</appendix>
311<!--
312vim: expandtab tw=80 ts=4
313-->
314
diff --git a/documentation/poky-ref-manual/introduction.xml b/documentation/poky-ref-manual/introduction.xml
new file mode 100644
index 0000000000..0b407a142a
--- /dev/null
+++ b/documentation/poky-ref-manual/introduction.xml
@@ -0,0 +1,352 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
4<chapter id='intro'>
5<title>Introduction</title>
6
7<section id='intro-what-is'>
8 <title>What is Poky?</title>
9
10 <para>
11
12 Poky is an open source platform build tool. It is a complete
13 software development environment for the creation of Linux
14 devices. It aids the design, development, building, debugging,
15 simulation and testing of complete modern software stacks
16 using Linux, the X Window System and GNOME Mobile
17 based application frameworks. It is based on <ulink
18 url='http://openembedded.org/'>OpenEmbedded</ulink> but has
19 been customised with a particular focus.
20
21 </para>
22
23 <para> Poky was setup to:</para>
24
25 <itemizedlist>
26 <listitem>
27 <para>Provide an open source Linux, X11, Matchbox, GTK+, Pimlico, Clutter, and other <ulink url='http://gnome.org/mobile'>GNOME Mobile</ulink> technologies based full platform build and development tool.</para>
28 </listitem>
29 <listitem>
30 <para>Create a focused, stable, subset of OpenEmbedded that can be easily and reliably built and developed upon.</para>
31 </listitem>
32 <listitem>
33 <para>Fully support a wide range of x86, ARM, MIPS, PowerPC hardware and device virtulisation</para>
34 </listitem>
35 </itemizedlist>
36
37 <para>
38 Poky is primarily a platform builder which generates filesystem images
39 based on open source software such as the Kdrive X server, the Matchbox
40 window manager, the GTK+ toolkit and the D-Bus message bus system. Images
41 for many kinds of devices can be generated, however the standard example
42 machines target QEMU full system emulation(x86, ARM, MIPS and PowerPC) and the ARM based
43 Sharp Zaurus series of devices. Poky's ability to boot inside a QEMU
44 emulator makes it particularly suitable as a test platform for development
45 of embedded software.
46 </para>
47
48 <para>
49 An important component integrated within Poky is Sato, a GNOME Mobile
50 based user interface environment.
51 It is designed to work well with screens at very high DPI and restricted
52 size, such as those often found on smartphones and PDAs. It is coded with
53 focus on efficiency and speed so that it works smoothly on hand-held and
54 other embedded hardware. It will sit neatly on top of any device
55 using the GNOME Mobile stack, providing a well defined user experience.
56 </para>
57
58 <screenshot>
59 <mediaobject>
60 <imageobject>
61 <imagedata fileref="screenshots/ss-sato.png" format="PNG" align='center' scalefit='1' width="100%" contentdepth="100%"/>
62 </imageobject>
63 <caption>
64 <para>The Sato Desktop - A screenshot from a machine running a Poky built image</para>
65 </caption>
66 </mediaobject>
67 </screenshot>
68
69
70 <para>
71
72 Poky has a growing open source community and is also backed up by commercial organisations including <ulink url="http://www.intel.com/">Intel Corporation</ulink>.
73
74 </para>
75</section>
76
77<section id='intro-manualoverview'>
78 <title>Documentation Overview</title>
79
80 <para>
81 The handbook is split into sections covering different aspects of Poky.
82 The <link linkend='usingpoky'>'Using Poky' section</link> gives an overview
83 of the components that make up Poky followed by information about using and
84 debugging the Poky build system. The <link linkend='extendpoky'>'Extending Poky' section</link>
85 gives information about how to extend and customise Poky along with advice
86 on how to manage these changes.
87 The <link linkend='bsp'>'Board Support Packages (BSP) - Developers Guide' section</link>
88 gives information about how to develop BSP such as the common layout, the
89 software hardware configuration options etc.
90 The <link linkend='platdev'>'Platform Development with Poky'
91 section</link> gives information about interaction between Poky and target
92 hardware for common platform development tasks such as software development,
93 debugging and profiling. The rest of the manual
94 consists of several reference sections each giving details on a specific
95 section of Poky functionality.
96 </para>
97
98 <para>
99 This manual applies to Poky Release 3.3 (Green).
100 </para>
101
102</section>
103
104
105<section id='intro-requirements'>
106 <title>System Requirements</title>
107
108 <para>
109 We recommend Debian-based distributions, in particular a recent Ubuntu
110 release (10.04 or newer), as the host system for Poky. Nothing in Poky is
111 distribution specific and
112 other distributions will most likely work as long as the appropriate
113 prerequisites are installed - we know of Poky being used successfully on Redhat,
114 SUSE, Gentoo and Slackware host systems.
115 </para>
116
117 <para>On a Debian-based system, you need the following packages installed:</para>
118
119 <itemizedlist>
120 <listitem>
121 <para>build-essential</para>
122 </listitem>
123 <listitem>
124 <para>python (version 2.6 or later)</para>
125 </listitem>
126 <listitem>
127 <para>diffstat</para>
128 </listitem>
129 <listitem>
130 <para>texinfo</para>
131 </listitem>
132 <listitem>
133 <para>texi2html</para>
134 </listitem>
135 <listitem>
136 <para>cvs</para>
137 </listitem>
138 <listitem>
139 <para>subversion</para>
140 </listitem>
141 <listitem>
142 <para>wget</para>
143 </listitem>
144 <listitem>
145 <para>gawk</para>
146 </listitem>
147 <listitem>
148 <para>help2man</para>
149 </listitem>
150 <listitem>
151 <para>chrpath</para>
152 </listitem>
153 <listitem>
154 <para>mercurial</para>
155 </listitem>
156 </itemizedlist>
157 <para>Furthermore if you wish to run an emulated Poky image using <ulink url='http://qemu.org'>QEMU</ulink> (as in the quickstart below) you will need the following packages installed:</para>
158 <itemizedlist>
159 <listitem>
160 <para>libgl1-mesa-dev</para>
161 </listitem>
162 <listitem>
163 <para>libglu1-mesa-dev</para>
164 </listitem>
165 <listitem>
166 <para>libsdl1.2-dev</para>
167 </listitem>
168 <listitem>
169 <para>bochsbios (only to run qemux86 images)</para>
170 </listitem>
171 </itemizedlist>
172
173 <para>
174 Debian users can add debian.o-hand.com to their APT sources (See
175 <ulink url='http://debian.o-hand.com'/>
176 for instructions on doing this) and then run <command>
177 "apt-get install qemu poky-depends poky-scripts"</command> which will
178 automatically install all these dependencies. Virtualisation images with
179 Poky and all dependencies can also easily be built if required.
180 </para>
181
182 <para>
183 Poky can use a system provided QEMU or build its own depending on how it's
184 configured. See the options in <filename>local.conf</filename> for more details.
185 </para>
186</section>
187
188<section id='intro-quickstart'>
189 <title>Quick Start</title>
190
191 <section id='intro-quickstart-build'>
192 <title>Building and Running an Image</title>
193
194 <para>
195 If you want to try Poky, you can do so in a few commands. The example below
196 checks out the Poky source code, sets up a build environment, builds an
197 image and then runs that image under the QEMU emulator in x86 system emulation mode:
198 </para>
199
200 <para>
201 <literallayout class='monospaced'>
202$ wget http://pokylinux.org/releases/poky-green-3.3.tar.bz2
203$ tar xjvf poky-green-3.3.tar.bz2
204$ cd green-3.3/
205$ source poky-init-build-env
206$ bitbake poky-image-sato
207$ bitbake qemu-native
208$ runqemu qemux86
209</literallayout>
210 </para>
211
212 <note>
213 <para>
214 This process will need Internet access, about 20 GB of disk space
215 available, and you should expect the build to take about 4 - 5 hours since
216 it is building an entire Linux system from source including the toolchain!
217 </para>
218 </note>
219
220 <para>
221 To build for other machines see the <glossterm><link
222 linkend='var-MACHINE'>MACHINE</link></glossterm> variable in build/conf/local.conf.
223 This file contains other useful configuration information and the default version
224 has examples of common setup needs and is worth
225 reading. To take advantage of multiple processor cores to speed up builds for example, set the
226 <glossterm><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm>
227 and <glossterm><link linkend='var-PARALLEL_MAKE'>PARALLEL_MAKE</link></glossterm> variables.
228
229 The images/kernels built by Poky are placed in the <filename class="directory">tmp/deploy/images</filename>
230 directory.
231 </para>
232
233 <para>
234 You could also run <command>"poky-qemu zImage-qemuarm.bin poky-image-sato-qemuarm.ext2"
235 </command> within the images directory if you have the poky-scripts Debian package
236 installed from debian.o-hand.com. This allows the QEMU images to be used standalone
237 outside the Poky build environment.
238 </para>
239 <para>
240 To setup networking within QEMU see the <link linkend='usingpoky-install-qemu-networking'>
241 QEMU/USB networking with IP masquerading</link> section.
242 </para>
243
244 </section>
245 <section id='intro-quickstart-qemu'>
246 <title>Downloading and Using Prebuilt Images</title>
247
248 <para>
249 Prebuilt images from Poky are also available if you just want to run the system
250 under QEMU. To use these you need to:
251 </para>
252
253 <itemizedlist>
254 <listitem>
255 <para>
256 Add debian.o-hand.com to your APT sources (See
257 <ulink url='http://debian.o-hand.com'/> for instructions on doing this)
258 </para>
259 </listitem>
260 <listitem>
261 <para>Install patched QEMU and poky-scripts:</para>
262 <para>
263 <literallayout class='monospaced'>
264$ apt-get install qemu poky-scripts
265</literallayout>
266 </para>
267 </listitem>
268
269 <listitem>
270 <para>
271 Download a Poky QEMU release kernel (*zImage*qemu*.bin) and compressed
272 filesystem image (poky-image-*-qemu*.ext2.bz2) which
273 you'll need to decompress with 'bzip2 -d'. These are available from the
274 <ulink url='http://pokylinux.org/releases/green-3.3/'>last release</ulink>
275 or from the <ulink url='http://autobuilder.pokylinux.org/'>autobuilder</ulink>.
276 </para>
277 </listitem>
278 <listitem>
279 <para>Start the image:</para>
280 <para>
281 <literallayout class='monospaced'>
282$ poky-qemu &lt;kernel&gt; &lt;image&gt;
283</literallayout>
284 </para>
285 </listitem>
286 </itemizedlist>
287
288 <note><para>
289 A patched version of QEMU is required at present. A suitable version is available from
290 <ulink url='http://debian.o-hand.com'/>, it can be built
291 by poky (bitbake qemu-native) or can be downloaded/built as part of the toolchain/SDK tarballs.
292 </para></note>
293
294 </section>
295</section>
296
297<section id='intro-getit'>
298 <title>Obtaining Poky</title>
299
300 <section id='intro-getit-releases'>
301 <title>Releases</title>
302
303 <para>Periodically, we make releases of Poky and these are available
304 at <ulink url='http://pokylinux.org/releases/'/>.
305 These are more stable and tested than the nightly development images.</para>
306 </section>
307
308 <section id='intro-getit-nightly'>
309 <title>Nightly Builds</title>
310
311 <para>
312 We make nightly builds of Poky for testing purposes and to make the
313 latest developments available. The output from these builds is available
314 at <ulink url='http://autobuilder.pokylinux.org/'/>
315 where the numbers increase for each subsequent build and can be used to reference it.
316 </para>
317
318 <para>
319 Automated builds are available for "standard" Poky and for Poky SDKs and toolchains as well
320 as any testing versions we might have such as poky-bleeding. The toolchains can
321 be used either as external standalone toolchains or can be combined with Poky as a
322 prebuilt toolchain to reduce build time. Using the external toolchains is simply a
323 case of untarring the tarball into the root of your system (it only creates files in
324 <filename class="directory">/opt/poky</filename>) and then enabling the option
325 in <filename>local.conf</filename>.
326 </para>
327
328 </section>
329
330 <section id='intro-getit-dev'>
331 <title>Development Checkouts</title>
332
333 <para>
334 Poky is available from our GIT repository located at
335 git://git.pokylinux.org/poky.git; a web interface to the repository
336 can be accessed at <ulink url='http://git.pokylinux.org/'/>.
337 </para>
338
339 <para>
340 The 'master' is where the deveopment work takes place and you should use this if you're
341 after to work with the latest cutting edge developments. It is possible trunk
342 can suffer temporary periods of instability while new features are developed and
343 if this is undesireable we recommend using one of the release branches.
344 </para>
345 </section>
346
347</section>
348
349</chapter>
350<!--
351vim: expandtab tw=80 ts=4
352-->
diff --git a/documentation/poky-ref-manual/poky-beaver.png b/documentation/poky-ref-manual/poky-beaver.png
new file mode 100644
index 0000000000..9f9e6cf996
--- /dev/null
+++ b/documentation/poky-ref-manual/poky-beaver.png
Binary files differ
diff --git a/documentation/poky-ref-manual/poky-handbook.png b/documentation/poky-ref-manual/poky-handbook.png
new file mode 100644
index 0000000000..333442e0d6
--- /dev/null
+++ b/documentation/poky-ref-manual/poky-handbook.png
Binary files differ
diff --git a/documentation/poky-ref-manual/poky-handbook.xml b/documentation/poky-ref-manual/poky-handbook.xml
new file mode 100644
index 0000000000..fb2bc80df3
--- /dev/null
+++ b/documentation/poky-ref-manual/poky-handbook.xml
@@ -0,0 +1,102 @@
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='template/poky-handbook.png'
13 format='SVG'
14 align='center' scalefit='1' width='100%'/>
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>Intel Corporation</orgname>
26 </affiliation>
27 <email>richard@linux.intel.com</email>
28 </author>
29
30 <author>
31 <firstname>Tomas</firstname> <surname>Frydrych</surname>
32 <affiliation>
33 <orgname>Intel Corporation</orgname>
34 </affiliation>
35 </author>
36
37 <author>
38 <firstname>Marcin</firstname> <surname>Juszkiewicz</surname>
39 </author>
40 <author>
41 <firstname>Dodji</firstname> <surname>Seketeli</surname>
42 </author>
43 </authorgroup>
44
45 <revhistory>
46 <revision>
47 <revnumber>3.3+git</revnumber>
48 <date>11 June 2010</date>
49 <revremark>Poky Master Documentation</revremark>
50 </revision>
51 </revhistory>
52
53 <copyright>
54 <year>2007-2010</year>
55 <holder>Intel Corporation</holder>
56 </copyright>
57
58 <legalnotice>
59 <para>
60 Permission is granted to copy, distribute and/or modify this document under
61 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.
62 </para>
63 </legalnotice>
64
65 </bookinfo>
66
67 <xi:include href="introduction.xml"/>
68
69 <xi:include href="usingpoky.xml"/>
70
71 <xi:include href="extendpoky.xml"/>
72
73 <xi:include href="bsp.xml"/>
74
75 <xi:include href="development.xml"/>
76
77 <xi:include href="ref-structure.xml"/>
78
79 <xi:include href="ref-bitbake.xml"/>
80
81 <xi:include href="ref-classes.xml"/>
82
83 <xi:include href="ref-images.xml"/>
84
85 <xi:include href="ref-features.xml"/>
86
87 <xi:include href="ref-variables.xml"/>
88
89 <xi:include href="ref-varlocality.xml"/>
90
91 <xi:include href="faq.xml"/>
92
93 <xi:include href="resources.xml"/>
94
95 <index id='index'>
96 <title>Index</title>
97 </index>
98
99</book>
100<!--
101vim: expandtab tw=80 ts=4
102-->
diff --git a/documentation/poky-ref-manual/poky-logo.svg b/documentation/poky-ref-manual/poky-logo.svg
new file mode 100644
index 0000000000..d0be402870
--- /dev/null
+++ b/documentation/poky-ref-manual/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/documentation/poky-ref-manual/ref-bitbake.xml b/documentation/poky-ref-manual/ref-bitbake.xml
new file mode 100644
index 0000000000..eaf9467950
--- /dev/null
+++ b/documentation/poky-ref-manual/ref-bitbake.xml
@@ -0,0 +1,348 @@
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 is a program written in Python that 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 it is 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 that 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. Adding extra content to
85 <glossterm><link linkend='var-BBFILES'>BBFILES</link></glossterm> is best
86 acheived through the use of Bitbake
87 <link linkend='usingpoky-changes-layers'>"layers"</link>.
88 </para>
89
90 <para>
91 Bitbake parses each <filename class="extension">.bb</filename> file in
92 <glossterm><link linkend='var-BBFILES'>BBFILES</link></glossterm> and
93 stores the values of various variables. In summary, for each
94 <filename class="extension">.bb</filename>
95 file the configuration + base class of variables are set, followed
96 by the data in the <filename class="extension">.bb</filename> file
97 itself, followed by any inherit commands that
98 <filename class="extension">.bb</filename> file might contain.
99 </para>
100
101 <para>
102 Parsing <filename class="extension">.bb</filename> files is a time
103 consuming process, so a cache is kept to speed up subsequent parsing.
104 This cache is invalid if the timestamp of the <filename class="extension">.bb</filename>
105 file itself has changed, or if the timestamps of any of the include,
106 configuration or class files the <filename class="extension">.bb</filename>
107 file depends on have changed.
108 </para>
109 </section>
110
111 <section id='ref-bitbake-providers'>
112 <title>Preferences and Providers</title>
113
114 <para>
115 Once all the <filename class="extension">.bb</filename> files have been
116 parsed, BitBake will proceed to build "poky-image-sato" (or whatever was
117 specified on the commandline) and looks for providers of that target.
118 Once a provider is selected, BitBake resolves all the dependencies for
119 the target. In the case of "poky-image-sato", it would lead to
120 <filename>task-base.bb</filename>
121 which in turn would lead to packages like <application>Contacts</application>,
122 <application>Dates</application>, <application>BusyBox</application>
123 and these in turn depend on glibc and the toolchain.
124 </para>
125
126 <para>
127 Sometimes a target might have multiple providers and a common example
128 is "virtual/kernel" that is provided by each kernel package. Each machine
129 will often elect the best provider of its kernel with a line like the
130 following in the machine configuration file:
131 </para>
132 <programlisting><glossterm><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></glossterm>_virtual/kernel = "linux-rp"</programlisting>
133 <para>
134 The default <glossterm><link linkend='var-PREFERRED_PROVIDER'>
135 PREFERRED_PROVIDER</link></glossterm> is the provider with the same name as
136 the target.
137 </para>
138
139 <para>
140 Understanding how providers are chosen is complicated by the fact
141 multiple versions might be present. Bitbake defaults to the highest
142 version of a provider by default. Version comparisons are made using
143 the same method as Debian. The <glossterm><link
144 linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm>
145 variable can be used to specify a particular version
146 (usually in the distro configuration) but the order can
147 also be influenced by the <glossterm><link
148 linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>
149 variable. By default files
150 have a preference of "0". Setting the
151 <glossterm><link
152 linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm> to "-1" will
153 make a package unlikely to be used unless it was explicitly referenced and
154 "1" makes it likely the package will be used.
155 <glossterm><link
156 linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm> overrides
157 any <glossterm><link
158 linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>. <glossterm><link
159 linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>
160 is often used to mark more
161 experimental new versions of packages until they've undergone sufficient
162 testing to be considered stable.
163 </para>
164
165 <para>
166 The end result is that internally, BitBake has now built a list of
167 providers for each target it needs in order of priority.
168 </para>
169 </section>
170
171 <section id='ref-bitbake-dependencies'>
172 <title>Dependencies</title>
173
174 <para>
175 Each target BitBake builds consists of multiple tasks (e.g. fetch,
176 unpack, patch, configure, compile etc.). For best performance on
177 multi-core systems, BitBake considers each task as an independent
178 entity with a set of dependencies. There are many variables that
179 are used to signify these dependencies and more information can be found
180 about these in the <ulink url='http://bitbake.berlios.de/manual/'>
181 BitBake manual</ulink>. At a basic level it is sufficient to know
182 that BitBake uses the <glossterm><link
183 linkend='var-DEPENDS'>DEPENDS</link></glossterm> and
184 <glossterm><link linkend='var-RDEPENDS'>RDEPENDS</link></glossterm> variables when
185 calculating dependencies and descriptions of these variables are
186 available through the links.
187 </para>
188
189 </section>
190
191 <section id='ref-bitbake-tasklist'>
192 <title>The Task List</title>
193
194 <para>
195 Based on the generated list of providers and the dependency information,
196 BitBake can now calculate exactly which tasks it needs to run and in what
197 order. The build now starts with BitBake forking off threads up to
198 the limit set in the <glossterm><link
199 linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm> variable
200 as long as there are tasks ready to run, i.e. tasks with all their
201 dependencies met.
202 </para>
203
204 <para>
205 As each task completes, a timestamp is written to the directory
206 specified by the <glossterm><link
207 linkend='var-STAMPS'>STAMPS</link></glossterm> variable (usually
208 <filename class="directory">build/tmp/stamps/*/</filename>). On
209 subsequent runs, BitBake looks at the <glossterm><link
210 linkend='var-STAMPS'>STAMPS</link></glossterm>
211 directory and will not rerun
212 tasks its already completed unless a timestamp is found to be invalid.
213 Currently, invalid timestamps are only considered on a per <filename
214 class="extension">.bb</filename> file basis so if for example the configure stamp has a timestamp greater than the
215 compile timestamp for a given target the compile task would rerun but this
216 has no effect on other providers depending on that target. This could
217 change or become configurable in future versions of BitBake. Some tasks
218 are marked as "nostamp" tasks which means no timestamp file will be written
219 and the task will always rerun.
220 </para>
221
222 <para>Once all the tasks have been completed BitBake exits.</para>
223
224 </section>
225
226 <section id='ref-bitbake-runtask'>
227 <title>Running a Task</title>
228
229 <para>
230 It's worth noting what BitBake does to run a task. A task can either
231 be a shell task or a python task. For shell tasks, BitBake writes a
232 shell script to <filename>${WORKDIR}/temp/run.do_taskname.pid</filename>
233 and then executes the script. The generated
234 shell script contains all the exported variables, and the shell functions
235 with all variables expanded. Output from the shell script is
236 sent to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
237 Looking at the
238 expanded shell functions in the run file and the output in the log files
239 is a useful debugging technique.
240 </para>
241
242 <para>
243 Python functions are executed internally to BitBake itself and
244 logging goes to the controlling terminal. Future versions of BitBake will
245 write the functions to files in a similar way to shell functions and
246 logging will also go to the log files in a similar way.
247 </para>
248 </section>
249
250
251 <section id='ref-bitbake-commandline'>
252 <title>Commandline</title>
253
254 <para>
255 To quote from "bitbake --help":
256 </para>
257
258 <screen>Usage: bitbake [options] [package ...]
259
260Executes the specified task (default is 'build') for a given set of BitBake files.
261It expects that BBFILES is defined, which is a space separated list of files to
262be executed. BBFILES does support wildcards.
263Default BBFILES are the .bb files in the current directory.
264
265Options:
266 --version show program's version number and exit
267 -h, --help show this help message and exit
268 -b BUILDFILE, --buildfile=BUILDFILE
269 execute the task against this .bb file, rather than a
270 package from BBFILES.
271 -k, --continue continue as much as possible after an error. While the
272 target that failed, and those that depend on it,
273 cannot be remade, the other dependencies of these
274 targets can be processed all the same.
275 -a, --tryaltconfigs continue with builds by trying to use alternative
276 providers where possible.
277 -f, --force force run of specified cmd, regardless of stamp status
278 -c CMD, --cmd=CMD Specify task to execute. Note that this only executes
279 the specified task for the providee and the packages
280 it depends on, i.e. 'compile' does not implicitly call
281 stage for the dependencies (IOW: use only if you know
282 what you are doing). Depending on the base.bbclass a
283 listtasks tasks is defined and will show available
284 tasks
285 -r FILE, --read=FILE read the specified file before bitbake.conf
286 -v, --verbose output more chit-chat to the terminal
287 -D, --debug Increase the debug level. You can specify this more
288 than once.
289 -n, --dry-run don't execute, just go through the motions
290 -S, --dump-signatures
291 don't execute, just dump out the signature
292 construction information
293 -p, --parse-only quit after parsing the BB files (developers only)
294 -d, --disable-psyco disable using the psyco just-in-time compiler (not
295 recommended)
296 -s, --show-versions show current and preferred versions of all packages
297 -e, --environment show the global or per-package environment (this is
298 what used to be bbread)
299 -g, --graphviz emit the dependency trees of the specified packages in
300 the dot syntax
301 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
302 Assume these dependencies don't exist and are already
303 provided (equivalent to ASSUME_PROVIDED). Useful to
304 make dependency graphs more appealing
305 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
306 Show debug logging for the specified logging domains
307 -P, --profile profile the command and print a report
308 -u UI, --ui=UI userinterface to use
309 --revisions-changed Set the exit code depending on whether upstream
310 floating revisions have changed or not</screen>
311
312 </section>
313
314 <section id='ref-bitbake-fetchers'>
315 <title>Fetchers</title>
316
317 <para>
318 As well as the containing the parsing and task/dependency handling
319 code, bitbake also contains a set of "fetcher" modules which allow
320 fetching of source code from various types of sources. Example
321 sources might be from disk with the metadata, from websites, from
322 remote shell accounts or from SCM systems like cvs/subversion/git.
323 </para>
324
325 <para>
326 The fetchers are usually triggered by entries in
327 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. Information about the
328 options and formats of entries for specific fetchers can be found in the
329 <ulink url='http://bitbake.berlios.de/manual/'>BitBake manual</ulink>.
330 </para>
331
332 <para>
333 One useful feature for certain SCM fetchers is the ability to
334 "auto-update" when the upstream SCM changes version. Since this
335 requires certain functionality from the SCM only certain systems
336 support it, currently Subversion, Bazaar and to a limited extent, Git. It
337 works using the <glossterm><link linkend='var-SRCREV'>SRCREV</link>
338 </glossterm> variable. See the <link linkend='platdev-appdev-srcrev'>
339 developing with an external SCM based project</link> section for more
340 information.
341 </para>
342
343 </section>
344
345</appendix>
346<!--
347vim: expandtab tw=80 ts=4 spell spelllang=en_gb
348-->
diff --git a/documentation/poky-ref-manual/ref-classes.xml b/documentation/poky-ref-manual/ref-classes.xml
new file mode 100644
index 0000000000..036044dd28
--- /dev/null
+++ b/documentation/poky-ref-manual/ref-classes.xml
@@ -0,0 +1,455 @@
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 directory pointed
15 by BUILDDIR (e.g. <filename class="directory">build/</filename>)in the same way as
16 <filename 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 also contains some commonly
38 used functions such as <function>oe_runmake</function>.
39 </para>
40</section>
41
42<section id='ref-classes-autotools'>
43 <title>Autotooled Packages - <filename>autotools.bbclass</filename></title>
44
45 <para>
46 Autotools (autoconf, automake, libtool) brings standardisation and this
47 class aims to define a set of tasks (configure, compile etc.) that will
48 work for all autotooled packages. It should usualy be enough to define
49 a few standard variables as documented in the <link
50 linkend='usingpoky-extend-addpkg-autotools'>simple autotools
51 example</link> section and then simply "inherit autotools". This class
52 can also work with software that emulates autotools.
53 </para>
54
55 <para>
56 It's useful to have some idea on how the tasks defined by this class work
57 and what they do behind the scenes.
58 </para>
59
60 <itemizedlist>
61 <listitem>
62 <para>
63 'do_configure' regenearates the configure script (using autoreconf) and
64 then launches it with a standard set of arguments used during
65 cross-compilation. Additional parameters can be passed to
66 <command>configure</command> through the <glossterm><link
67 linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></glossterm> variable.
68 </para>
69 </listitem>
70 <listitem>
71 <para>
72 'do_compile' runs <command>make</command> with arguments specifying
73 the compiler and linker. Additional arguments can be passed through
74 the <glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link>
75 </glossterm> variable.
76 </para>
77 </listitem>
78 <listitem>
79 <para>
80 'do_install' runs <command>make install</command> passing a DESTDIR
81 option taking its value from the standard <glossterm><link
82 linkend='var-DESTDIR'>DESTDIR</link></glossterm> variable.
83 </para>
84 </listitem>
85 </itemizedlist>
86
87</section>
88
89<section id='ref-classes-update-alternatives'>
90 <title>Alternatives - <filename>update-alternatives.bbclass</filename></title>
91
92 <para>
93 Several programs can fulfill the same or similar function and
94 they can be installed with the same name. For example the <command>ar</command>
95 command is available from the "busybox", "binutils" and "elfutils" packages.
96 This class handles the renaming of the binaries so multiple packages
97 can be installed which would otherwise conflict and yet the
98 <command>ar</command> command still works regardless of which are installed
99 or subsequently removed. It renames the conflicting binary in each package
100 and symlinks the highest priority binary during installation or removal
101 of packages.
102
103 Four variables control this class:
104 </para>
105
106
107 <variablelist>
108 <varlistentry>
109 <term>ALTERNATIVE_NAME</term>
110 <listitem>
111 <para>
112 Name of binary which will be replaced (<command>ar</command> in this example)
113 </para>
114 </listitem>
115 </varlistentry>
116 <varlistentry>
117 <term>ALTERNATIVE_LINK</term>
118 <listitem>
119 <para>
120 Path to resulting binary ("/bin/ar" in this example)
121 </para>
122 </listitem>
123 </varlistentry>
124 <varlistentry>
125 <term>ALTERNATIVE_PATH</term>
126 <listitem>
127 <para>
128 Path to real binary ("/usr/bin/ar.binutils" in this example)
129 </para>
130 </listitem>
131 </varlistentry>
132 <varlistentry>
133 <term>ALTERNATIVE_PRIORITY</term>
134 <listitem>
135 <para>
136 Priority of binary, the version with the most features should have the highest priority
137 </para>
138 </listitem>
139 </varlistentry>
140 </variablelist>
141
142 <para>
143 Currently, only one binary per package is supported.
144 </para>
145</section>
146
147<section id='ref-classes-update-rc.d'>
148 <title>Initscripts - <filename>update-rc.d.bbclass</filename></title>
149
150 <para>
151 This class uses update-rc.d to safely install an initscript on behalf of
152 the package. Details such as making sure the initscript is stopped before
153 a package is removed and started when the package is installed are taken
154 care of. Three variables control this class,
155 <link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link>,
156 <link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link> and
157 <link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link>. See the
158 links for details.
159 </para>
160</section>
161
162<section id='ref-classes-binconfig'>
163 <title>Binary config scripts - <filename>binconfig.bbclass</filename></title>
164
165 <para>
166 Before pkg-config had become widespread, libraries shipped shell
167 scripts to give information about the libraries and include paths needed
168 to build software (usually named 'LIBNAME-config'). This class assists
169 any recipe using such scripts.
170 </para>
171
172 <para>
173 During staging Bitbake installs such scripts into the <filename
174 class="directory">sysroots/</filename> directory. It also changes all
175 paths to point into the <filename class="directory">sysroots/</filename>
176 directory so all builds which use the script will use the correct
177 directories for the cross compiling layout.
178 </para>
179</section>
180
181<section id='ref-classes-debian'>
182 <title>Debian renaming - <filename>debian.bbclass</filename></title>
183
184 <para>
185 This class renames packages so that they follow the Debian naming
186 policy, i.e. 'glibc' becomes 'libc6' and 'glibc-devel' becomes
187 'libc6-dev'.
188 </para>
189</section>
190
191<section id='ref-classes-pkgconfig'>
192 <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title>
193
194 <para>
195 Pkg-config brought standardisation and this class aims to make its
196 integration smooth for all libraries which make use of it.
197 </para>
198
199 <para>
200 During staging Bitbake installs pkg-config data into the <filename
201 class="directory">sysroots/</filename> directory. By making use of
202 sysroot functionality within pkgconfig this class no longer has to
203 manipulate the files.
204 </para>
205</section>
206
207<section id='ref-classes-src-distribute'>
208 <title>Distribution of sources - <filename>src_distribute_local.bbclass</filename></title>
209
210 <para>
211 Many software licenses require providing the sources for compiled
212 binaries. To simplify this process two classes were created:
213 <filename>src_distribute.bbclass</filename> and
214 <filename>src_distribute_local.bbclass</filename>.
215 </para>
216
217 <para>
218 Result of their work are <filename class="directory">tmp/deploy/source/</filename>
219 subdirs with sources sorted by <glossterm><link linkend='var-LICENSE'>LICENSE</link>
220 </glossterm> field. If recipe lists few licenses (or has entries like "Bitstream Vera") source archive is put in each
221 license dir.
222 </para>
223
224 <para>
225 Src_distribute_local class has three modes of operating:
226 </para>
227
228 <itemizedlist>
229 <listitem><para>copy - copies the files to the distribute dir</para></listitem>
230 <listitem><para>symlink - symlinks the files to the distribute dir</para></listitem>
231 <listitem><para>move+symlink - moves the files into distribute dir, and symlinks them back</para></listitem>
232 </itemizedlist>
233</section>
234
235<section id='ref-classes-perl'>
236 <title>Perl modules - <filename>cpan.bbclass</filename></title>
237
238 <para>
239 Recipes for Perl modules are simple - usually needs only
240 pointing to source archive and inheriting of proper bbclass.
241 Building is split into two methods dependly on method used by
242 module authors.
243 </para>
244
245 <para>
246 Modules which use old Makefile.PL based build system require
247 using of <filename>cpan.bbclass</filename> in their recipes.
248 </para>
249
250 <para>
251 Modules which use Build.PL based build system require
252 using of <filename>cpan_build.bbclass</filename> in their recipes.
253 </para>
254
255</section>
256
257<section id='ref-classes-distutils'>
258 <title>Python extensions - <filename>distutils.bbclass</filename></title>
259
260 <para>
261 Recipes for Python extensions are simple - they usually only
262 require pointing to the source archive and inheriting the proper
263 bbclasses.
264 Building is split into two methods depending on the build method
265 used by the module authors.
266 </para>
267
268 <para>
269 Extensions which use autotools based build system require use
270 of autotools and distutils-base bbclasses in their recipes.
271 </para>
272
273 <para>
274 Extensions which use distutils build system require use
275 of <filename>distutils.bbclass</filename> in their recipes.
276 </para>
277
278</section>
279
280<section id='ref-classes-devshell'>
281 <title>Developer Shell - <filename>devshell.bbclass</filename></title>
282
283 <para>
284 This class adds the devshell task. Its usually up to distribution policy
285 to include this class (Poky does). See the <link
286 linkend='platdev-appdev-devshell'>developing with 'devshell' section</link>
287 for more information about using devshell.
288 </para>
289
290</section>
291
292<section id='ref-classes-package'>
293 <title>Packaging - <filename>package*.bbclass</filename></title>
294
295 <para>
296 The packaging classes add support for generating packages from a builds
297 output. The core generic functionality is in
298 <filename>package.bbclass</filename>, code specific to particular package
299 types is contained in various sub classes such as
300 <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename>
301 and <filename>package_rpm.bbclass</filename>. Most users will
302 want one or more of these classes and this is controlled by the <glossterm>
303 <link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></glossterm>
304 variable. The first class listed in this variable will be used for image
305 generation. Since images are generated from packages a packaging class is
306 needed to enable image generation.
307 </para>
308
309</section>
310
311<section id='ref-classes-kernel'>
312 <title>Building kernels - <filename>kernel.bbclass</filename></title>
313
314 <para>
315 This class handles 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
316 staged into <glossterm><link
317 linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></glossterm>
318 directory to allow building of out-of-tree modules using <filename>module.bbclass</filename>.
319 </para>
320 <para>
321 This means that each kernel module built is packaged separately and inter-module dependencies are
322 created by parsing the <command>modinfo</command> output. If all modules are
323 required then installing the "kernel-modules" package will install all
324 packages with modules and various other kernel packages such as "kernel-vmlinux".
325 </para>
326
327 <para>
328 Various other classes are used by the kernel and module classes internally including
329 <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>,
330 <filename>module-base.bbclass</filename> and <filename>linux-kernel-base.bbclass</filename>.
331 </para>
332</section>
333
334<section id='ref-classes-image'>
335 <title>Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title>
336
337 <para>
338 Those classes add support for creating images in many formats. First the
339 rootfs is created from packages by one of the <filename>rootfs_*.bbclass</filename>
340 files (depending on package format used) and then image is created.
341
342 The <glossterm><link
343 linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></glossterm>
344 variable controls which types of image to generate.
345
346 The list of packages to install into the image is controlled by the
347 <glossterm><link
348 linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm>
349 variable.
350 </para>
351</section>
352
353<section id='ref-classes-sanity'>
354 <title>Host System sanity checks - <filename>sanity.bbclass</filename></title>
355
356 <para>
357 This class checks prerequisite software is present to
358 notify the users problems that will affect their build. It also
359 performs basic checks of the user configuration from local.conf to
360 prevent common mistakes resulting in build failures. It's usually up to
361 distribution policy whether to include this class (Poky does).
362 </para>
363</section>
364
365<section id='ref-classes-insane'>
366 <title>Generated output quality assurance checks - <filename>insane.bbclass</filename></title>
367
368 <para>
369 This class adds a step to package generation which sanity checks the
370 packages generated by Poky. There are an ever increasing range of checks
371 it performs, checking for common problems which break builds/packages/images,
372 see the bbclass file for more information. It's usually up to distribution
373 policy whether to include this class (Poky does).
374 </para>
375</section>
376
377<section id='ref-classes-siteinfo'>
378 <title>Autotools configuration data cache - <filename>siteinfo.bbclass</filename></title>
379
380 <para>
381 Autotools can require tests which have to execute on the target hardware.
382 Since this isn't possible in general when cross compiling, siteinfo is
383 used to provide cached test results so these tests can be skipped over but
384 the correct values used. The <link linkend='structure-meta-site'>meta/site directory</link>
385 contains test results sorted into different categories like architecture, endianess and
386 the libc used. Siteinfo provides a list of files containing data relevant to
387 the current build in the <glossterm><link linkend='var-CONFIG_SITE'>CONFIG_SITE
388 </link></glossterm> variable which autotools will automatically pick up.
389 </para>
390 <para>
391 The class also provides variables like <glossterm><link
392 linkend='var-SITEINFO_ENDIANESS'>SITEINFO_ENDIANESS</link></glossterm>
393 and <glossterm><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link>
394 </glossterm> which can be used elsewhere in the metadata.
395 </para>
396 <para>
397 This class is included from <filename>base.bbclass</filename> and is hence always active.
398 </para>
399</section>
400
401<section id='ref-classes-others'>
402 <title>Other Classes</title>
403
404 <para>
405 Only the most useful/important classes are covered here but there are
406 others, see the <filename class="directory">meta/classes</filename> directory for the rest.
407 </para>
408</section>
409
410<!-- Undocumented classes are:
411 base_srpm.bbclass
412 bootimg.bbclass
413 ccache.inc
414 ccdv.bbclass
415 cmake.bbclass
416 cml1.bbclass
417 cross.bbclass
418 flow-lossage.bbclass
419 gconf.bbclass
420 gettext.bbclass
421 gnome.bbclass
422 gtk-icon-cache.bbclass
423 icecc.bbclass
424 lib_package.bbclass
425 mirrors.bbclass
426 mozilla.bbclass
427 multimachine.bbclass
428 native.bbclass
429 oelint.bbclass
430 patch.bbclass
431 patcher.bbclass
432 pkg_distribute.bbclass
433 pkg_metainfo.bbclass
434 poky.bbclass
435 rm_work.bbclass
436 rpm_core.bbclass
437 scons.bbclass
438 sdk.bbclass
439 sdl.bbclass
440 sip.bbclass
441 sourcepkg.bbclass
442 srec.bbclass
443 syslinux.bbclass
444 tinderclient.bbclass
445 tmake.bbclass
446 utils.bbclass
447 xfce.bbclass
448 xlibs.bbclass
449-->
450
451
452</appendix>
453<!--
454vim: expandtab tw=80 ts=4
455-->
diff --git a/documentation/poky-ref-manual/ref-features.xml b/documentation/poky-ref-manual/ref-features.xml
new file mode 100644
index 0000000000..cde9588116
--- /dev/null
+++ b/documentation/poky-ref-manual/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/documentation/poky-ref-manual/ref-images.xml b/documentation/poky-ref-manual/ref-images.xml
new file mode 100644
index 0000000000..03583eb394
--- /dev/null
+++ b/documentation/poky-ref-manual/ref-images.xml
@@ -0,0 +1,72 @@
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 directories
10 <filename class="directory"> meta/recipes-core/images/</filename>,
11 <filename class="directory"> meta/packages/images/</filename>,
12 <filename class="directory"> meta/recipes-sato/images/</filename> and
13 <filename class="directory"> meta/packages/meta/</filename>. The standard
14 images are listed below along with details of what they contain:
15 </para>
16
17 <itemizedlist>
18 <listitem>
19 <para>
20 <emphasis>poky-image-minimal</emphasis> - A small image, just enough
21 to allow a device to boot
22 </para>
23 </listitem>
24 <listitem>
25 <para>
26 <emphasis>poky-image-base</emphasis> - console only image with full
27 support of target device hardware
28 </para>
29 </listitem>
30 <listitem>
31 <para>
32 <emphasis>poky-image-core</emphasis> - X11 image with simple apps like
33 terminal, editor and file manager
34 </para>
35 </listitem>
36 <listitem>
37 <para>
38 <emphasis>poky-image-sato</emphasis> - X11 image with Sato theme and
39 Pimlico applications. Also contains terminal, editor and file manager.
40 </para>
41 </listitem>
42 <listitem>
43 <para>
44 <emphasis>poky-image-sdk</emphasis> - X11 image like poky-image-sato but
45 also include native toolchain and libraries needed to build applications
46 on the device itself. Also includes testing and profiling tools and debug
47 symbols.
48 </para>
49 </listitem>
50 <listitem>
51 <para>
52 <emphasis>meta-toolchain</emphasis> - This generates a tarball containing
53 a standalone toolchain which can be used externally to Poky. It is self
54 contained and unpacks to the <filename class="directory">/opt/poky</filename>
55 directory. It also contains a copy of QEMU and the scripts neccessary to run
56 poky QEMU images.
57 </para>
58 </listitem>
59 <listitem>
60 <para>
61 <emphasis>meta-toolchain-sdk</emphasis> - This includes everything in
62 meta-toolchain but also includes development headers and libraries
63 forming a complete standalone SDK. See the <link linkend='platdev-appdev-external-sdk'>
64 Developing using the Poky SDK</link> and <link linkend='platdev-appdev-external-anjuta'>
65 Developing using the Anjuta Plugin</link> sections for more information.
66 </para>
67 </listitem>
68 </itemizedlist>
69</appendix>
70<!--
71vim: expandtab tw=80 ts=4
72-->
diff --git a/documentation/poky-ref-manual/ref-structure.xml b/documentation/poky-ref-manual/ref-structure.xml
new file mode 100644
index 0000000000..ca589de428
--- /dev/null
+++ b/documentation/poky-ref-manual/ref-structure.xml
@@ -0,0 +1,514 @@
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 use 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 generated by Poky in its standard configuration where the source tree is
44 combined with the output. It is also possible to place output and configuration
45 files in a directory separate from the Poky source, see the section <link
46 linkend='structure-core-script'>seperate output directory</link>.
47 </para>
48 </section>
49
50 <section id='structure-core-meta'>
51 <title><filename class="directory">meta/</filename></title>
52
53 <para>
54 This directory contains the core metadata, a key part of Poky. Within this
55 directory there are definitions of the machines, the Poky distribution
56 and the packages that make up a given system.
57 </para>
58 </section>
59
60 <section id='structure-core-meta-extras'>
61 <title><filename class="directory">meta-extras/</filename></title>
62
63 <para>
64 This directory is similar to <filename class="directory">meta/</filename>,
65 and contains some extra metadata not included in standard Poky. These are
66 disabled by default, and are not supported as part of Poky.
67 </para>
68 </section>
69
70 <section id='structure-core-meta-***'>
71 <title><filename class="directory">meta-***/</filename></title>
72
73 <para>
74 These directories are optional layers to be added to core metadata, which
75 are enabled by adding them to conf/bblayers.conf.
76 </para>
77 </section>
78
79 <section id='structure-core-scripts'>
80 <title><filename class="directory">scripts/</filename></title>
81
82 <para>
83 This directory contains various integration scripts which implement
84 extra functionality in the Poky environment, such as the QEMU
85 scripts. This directory is appended to the PATH environment variable by the
86 <link linkend="structure-core-script">poky-init-build-env</link> script.
87 </para>
88 </section>
89
90 <section id='structure-core-sources'>
91 <title><filename class="directory">sources/</filename></title>
92
93 <para>
94 While not part of a checkout, Poky will create this directory as
95 part of any build. Any downloads are placed in this directory (as
96 specified by the <glossterm><link linkend='var-DL_DIR'>DL_DIR</link>
97 </glossterm> variable). This directory can be shared between Poky
98 builds to save downloading files multiple times. SCM checkouts are
99 also stored here as e.g. <filename class="directory">sources/svn/
100 </filename>, <filename class="directory">sources/cvs/</filename> or
101 <filename class="directory">sources/git/</filename> and the
102 sources directory may contain archives of checkouts for various
103 revisions or dates.
104 </para>
105
106 <para>
107 It's worth noting that BitBake creates <filename class="extension">.md5
108 </filename> stamp files for downloads. It uses these to mark downloads as
109 complete as well as for checksum and access accounting purposes. If you add
110 a file manually to the directory, you need to touch the corresponding
111 <filename class="extension">.md5</filename> file too.
112 </para>
113
114 <para>
115 This location can be overridden by setting <glossterm><link
116 linkend='var-DL_DIR'>DL_DIR</link></glossterm> in <filename>local.conf
117 </filename>. This directory can be shared between builds and even between
118 machines via NFS, so downloads are only made once, speeding up builds.
119 </para>
120
121 </section>
122
123 <section id='handbook'>
124 <title><filename class="directory">handbook</filename></title>
125
126 <para>
127 This is the location where this handbook is generated
128 </para>
129 </section>
130
131 <section id='structure-core-script'>
132 <title><filename>poky-init-build-env</filename></title>
133
134 <para>
135 This script is used to setup the Poky build environment. Sourcing this file in
136 a shell makes changes to PATH and sets other core BitBake variables based on the
137 current working directory. You need to use this before running Poky commands.
138 Internally it uses scripts within the <filename class="directory">scripts/
139 </filename> directory to do the bulk of the work. This script supports
140 specifying any directory as the build output:
141 </para>
142
143 <programlisting>
144source POKY_SRC/poky-init-build-env [BUILDDIR]
145 </programlisting>
146
147 <para>
148 The above command can be typed from any directory, as long as POKY_SRC points to
149 the desired Poky source tree. The optional BUILDDIR could be any directory you'd
150 like Poky to generate the build output into.
151 </para>
152 </section>
153</section>
154
155<section id='structure-build'>
156 <title><filename class="directory">build/</filename> - The Build Directory</title>
157
158 <section id='structure-build-conf-local.conf'>
159 <title><filename>build/conf/local.conf</filename></title>
160
161 <para>
162 This file contains all the local user configuration of Poky. If there
163 is no <filename>local.conf</filename> present, it is created from
164 <filename>local.conf.sample</filename>. The <filename>local.conf</filename>
165 file contains documentation on the various configuration options. Any
166 variable set here overrides any variable set elsewhere within Poky unless
167 that variable is hardcoded within Poky (e.g. by using '=' instead of '?=').
168 Some variables are hardcoded for various reasons but these variables are
169 relatively rare.
170 </para>
171
172 <para>
173 Edit this file to set the <glossterm><link linkend='var-MACHINE'>MACHINE</link></glossterm> for which you want to build, which package types you
174 wish to use (PACKAGE_CLASSES) or where downloaded files should go
175 (<glossterm><link linkend='var-DL_DIR'>DL_DIR</link></glossterm>).
176 </para>
177 </section>
178
179 <section id='structure-build-conf-bblayers.conf'>
180 <title><filename>build/conf/bblayers.conf</filename></title>
181
182 <para>
183 This file defines layers walked by bitbake. If there's no <filename>
184 bblayers.conf</filename> present, it is created from <filename>bblayers.conf.sample
185 </filename> when the environment setup script is sourced.
186 </para>
187 </section>
188
189 <section id='structure-build-tmp'>
190 <title><filename class="directory">build/tmp/</filename></title>
191
192 <para>
193 This is created by BitBake if it doesn't exist and is where all the Poky output
194 is placed. To clean Poky and start a build from scratch (other than downloads),
195 you can wipe this directory. The <filename class="directory">tmp/
196 </filename> directory has some important sub-components detailed below.
197 </para>
198 </section>
199
200 <section id='structure-build-tmp-cache'>
201 <title><filename class="directory">build/tmp/cache/</filename></title>
202
203 <para>
204 When BitBake parses the metadata it creates a cache file of the result which can
205 be used when subsequently running commands. These are stored here on
206 a per machine basis.
207 </para>
208 </section>
209
210 <section id='structure-build-tmp-deploy'>
211 <title><filename class="directory">build/tmp/deploy/</filename></title>
212
213 <para>Any 'end result' output from Poky is placed under here.</para>
214 </section>
215
216 <section id='structure-build-tmp-deploy-deb'>
217 <title><filename class="directory">build/tmp/deploy/deb/</filename></title>
218
219 <para>
220 Any .deb packages emitted by Poky are placed here, sorted into feeds for
221 different architecture types.
222 </para>
223 </section>
224
225 <section id='structure-build-tmp-deploy-rpm'>
226 <title><filename class="directory">build/tmp/deploy/rpm/</filename></title>
227
228 <para>
229 Any .rpm packages emitted by Poky are placed here, sorted into feeds for
230 different architecture types.
231 </para>
232 </section>
233
234 <section id='structure-build-tmp-deploy-images'>
235 <title><filename class="directory">build/tmp/deploy/images/</filename></title>
236
237 <para>
238 Complete filesystem images are placed here. If you want to flash the resulting
239 image from a build onto a device, look here for them.
240 </para>
241 </section>
242
243 <section id='structure-build-tmp-deploy-ipk'>
244 <title><filename class="directory">build/tmp/deploy/ipk/</filename></title>
245
246 <para>Any resulting .ipk packages emitted by Poky are placed here.</para>
247 </section>
248
249 <section id='structure-build-tmp-sysroots'>
250 <title><filename class="directory">build/tmp/sysroots/</filename></title>
251
252 <para>
253 Any package needing to share output with other packages does so within sysroots.
254 This means it contains any shared header files and any shared libraries amongst
255 other data. It is subdivided by architecture so multiple builds can run within
256 the one build directory.
257 </para>
258 </section>
259
260 <section id='structure-build-tmp-stamps'>
261 <title><filename class="directory">build/tmp/stamps/</filename></title>
262
263 <para>
264 This is used by BitBake for accounting purposes to keep track of which tasks
265 have been run and when. It is also subdivided by architecture. The files are
266 empty and the important information is the filenames and timestamps.
267 </para>
268 </section>
269
270 <section id='structure-build-tmp-log'>
271 <title><filename class="directory">build/tmp/log/</filename></title>
272
273 <para>
274 This contains some general logs if not placing in a package's
275 <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>, such as
276 the log output from check_pkg or distro_check tasks.
277 </para>
278 </section>
279
280 <section id='structure-build-tmp-pkgdata'>
281 <title><filename class="directory">build/tmp/pkgdata/</filename></title>
282
283 <para>
284 This is an intermediate place for saving packaging data, which will be used
285 in later packaging process. For detail please refer to <link linkend='ref-classes-package'>
286 package.bbclass</link>.
287 </para>
288 </section>
289
290 <section id='structure-build-tmp-pstagelogs'>
291 <title><filename class="directory">build/tmp/pstagelogs/</filename></title>
292
293 <para>
294 This directory contains manifest for task based prebuilt. Each manifest is basically
295 a file list for installed files from a given task, which would be useful for later
296 packaging or cleanup process.
297 </para>
298 </section>
299
300 <section id='structure-build-tmp-work'>
301 <title><filename class="directory">build/tmp/work/</filename></title>
302
303 <para>
304 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.
305 </para>
306
307 <para>
308 It is worth considering the structure of a typical work directory. An
309 example is the linux-rp kernel, version 2.6.20 r7 on the machine spitz
310 built within Poky. For this package a work directory of <filename
311 class="directory">tmp/work/spitz-poky-linux-gnueabi/linux-rp-2.6.20-r7/
312 </filename>, referred to as <glossterm><link linkend='var-WORKDIR'>WORKDIR
313 </link></glossterm>, is created. Within this directory, the source is
314 unpacked to linux-2.6.20 and then patched by quilt (see <link
315 linkend="usingpoky-modifying-packages-quilt">Section 3.5.1</link>).
316 Within the <filename class="directory">linux-2.6.20</filename> directory,
317 standard Quilt directories <filename class="directory">linux-2.6.20/patches</filename>
318 and <filename class="directory">linux-2.6.20/.pc</filename> are created,
319 and standard quilt commands can be used.
320 </para>
321
322 <para>
323 There are other directories generated within <glossterm><link
324 linkend='var-WORKDIR'>WORKDIR</link></glossterm>. The most important
325 is <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm><filename class="directory">/temp/</filename> which has log files for each
326 task (<filename>log.do_*.pid</filename>) and the scripts BitBake runs for
327 each task (<filename>run.do_*.pid</filename>). The <glossterm><link
328 linkend='var-WORKDIR'>WORKDIR</link></glossterm><filename
329 class="directory">/image/</filename> directory is where <command>make
330 install</command> places its output which is then split into subpackages
331 within <glossterm><link linkend='var-WORKDIR'>WORKDIR</link></glossterm>
332 <filename class="directory">/packages-split/</filename>.
333 </para>
334 </section>
335</section>
336
337<section id='structure-meta'>
338 <title><filename class="directory">meta/</filename> - The Metadata</title>
339
340 <para>
341 As mentioned previously, this is the core of Poky. It has several
342 important subdivisions:
343 </para>
344
345 <section id='structure-meta-classes'>
346 <title><filename class="directory">meta/classes/</filename></title>
347
348 <para>
349 Contains the <filename class="extension">*.bbclass</filename> files. Class
350 files are used to abstract common code allowing it to be reused by multiple
351 packages. The <filename>base.bbclass</filename> file is inherited by every
352 package. Examples of other important classes are
353 <filename>autotools.bbclass</filename> that in theory allows any
354 Autotool-enabled package to work with Poky with minimal effort, or
355 <filename>kernel.bbclass</filename> that contains common code and functions
356 for working with the linux kernel. Functions like image generation or
357 packaging also have their specific class files (<filename>image.bbclass
358 </filename>, <filename>rootfs_*.bbclass</filename> and
359 <filename>package*.bbclass</filename>).
360 </para>
361 </section>
362
363 <section id='structure-meta-conf'>
364 <title><filename class="directory">meta/conf/</filename></title>
365
366 <para>
367 This is the core set of configuration files which start from
368 <filename>bitbake.conf</filename> and from which all other configuration
369 files are included (see the includes at the end of the file, even
370 <filename>local.conf</filename> is loaded from there!). While
371 <filename>bitbake.conf</filename> sets up the defaults, these can often be
372 overridden by user (<filename>local.conf</filename>), machine or
373 distribution configuration files.
374 </para>
375 </section>
376
377 <section id='structure-meta-conf-machine'>
378 <title><filename class="directory">meta/conf/machine/</filename></title>
379
380 <para>
381 Contains all the machine configuration files. If you set MACHINE="spitz", the
382 end result is Poky looking for a <filename>spitz.conf</filename> file in this directory. The includes
383 directory contains various data common to multiple machines. If you want to add
384 support for a new machine to Poky, this is the directory to look in.
385 </para>
386 </section>
387
388 <section id='structure-meta-conf-distro'>
389 <title><filename class="directory">meta/conf/distro/</filename></title>
390
391 <para>
392 Any distribution specific configuration is controlled from here. OpenEmbedded
393 supports multiple distributions of which Poky is one. Poky only contains the
394 Poky distribution so poky.conf is the main file here. This includes the
395 versions and SRCDATES for applications which are configured here. An example of
396 an alternative configuration is poky-bleeding.conf although this mainly inherits
397 its configuration from Poky itself.
398 </para>
399 </section>
400
401 <section id='structure-meta-recipes-bsp'>
402 <title><filename class="directory">meta/recipes-bsp/</filename></title>
403
404 <para>
405 Anything linking to specific hardware or hardware configuration information
406 are placed here, such as uboot, grub, etc.
407 </para>
408 </section>
409
410 <section id='structure-meta-recipes-connectivity'>
411 <title><filename class="directory">meta/recipes-connectivity/</filename></title>
412
413 <para>
414 Libraries and applications related to communication with other devices
415 </para>
416 </section>
417
418 <section id='structure-meta-recipes-core'>
419 <title><filename class="directory">meta/recipes-core/</filename></title>
420
421 <para>
422 What's needed to build a basic working Linux image including commonly used dependencies
423 </para>
424 </section>
425
426 <section id='structure-meta-recipes-devtools'>
427 <title><filename class="directory">meta/recipes-devtools/</filename></title>
428
429 <para>
430 Tools primarily used by the build system (but can also be used on targets)
431 </para>
432 </section>
433
434 <section id='structure-meta-recipes-extended'>
435 <title><filename class="directory">meta/recipes-extended/</filename></title>
436
437 <para>
438 Applications which whilst not essential add features compared to the alternatives in
439 core. May be needed for full tool functionality or LSB compliance.
440 </para>
441 </section>
442
443 <section id='structure-meta-recipes-gnome'>
444 <title><filename class="directory">meta/recipes-gnome/</filename></title>
445
446 <para>
447 All things related to the GTK+ application framework
448 </para>
449 </section>
450
451 <section id='structure-meta-recipes-graphics'>
452 <title><filename class="directory">meta/recipes-graphics/</filename></title>
453
454 <para>
455 X and other graphically related system libraries
456 </para>
457 </section>
458
459 <section id='structure-meta-recipes-kernel'>
460 <title><filename class="directory">meta/recipes-kernel/</filename></title>
461
462 <para>
463 The kernel and generic applications/libraries with strong kernel dependencies
464 </para>
465 </section>
466
467 <section id='structure-meta-recipes-multimedia'>
468 <title><filename class="directory">meta/recipes-multimedia/</filename></title>
469
470 <para>
471 Codecs and support utilties for audio, images and video
472 </para>
473 </section>
474
475 <section id='structure-meta-recipes-qt'>
476 <title><filename class="directory">meta/recipes-qt/</filename></title>
477
478 <para>
479 All things related to the QT application framework
480 </para>
481 </section>
482
483 <section id='structure-meta-recipes-sato'>
484 <title><filename class="directory">meta/recipes-sato/</filename></title>
485
486 <para>
487 The Sato demo/reference UI/UX, its associated apps and configuration
488 </para>
489 </section>
490
491 <section id='structure-meta-packages'>
492 <title><filename class="directory">meta/packages/</filename></title>
493
494 <para>
495 this is a catch-all place for the rest which not fits into above
496 recipes-***. Images and tasks are also placed here.
497 </para>
498 </section>
499
500 <section id='structure-meta-site'>
501 <title><filename class="directory">meta/site/</filename></title>
502
503 <para>
504 Certain autoconf test results cannot be determined when cross compiling since it
505 can't run tests on a live system. This directory therefore contains a list of
506 cached results for various architectures which is passed to autoconf.
507 </para>
508 </section>
509</section>
510
511</appendix>
512<!--
513vim: expandtab tw=80 ts=4
514-->
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
new file mode 100644
index 0000000000..7e10808525
--- /dev/null
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -0,0 +1,879 @@
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>The maximum number of tasks BitBake should run in parallel at any one time</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 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
88 <glossdef>
89 <para>Bare name of package with any suffixes like -cross -native
90 removed. </para>
91 </glossdef>
92 </glossentry>
93
94 </glossdiv>
95
96 <glossdiv id='var-glossary-c'><title>C</title>
97
98 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
99 <glossdef>
100 <para>
101 Flags passed to C compiler for the target system. Evaluates to the same
102 as <link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link>.
103 </para>
104 </glossdef>
105 </glossentry>
106
107 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
108 <glossdef>
109 <para>A regular expression which evalutates to match the machines the recipe
110 works with. It stops recipes being run on machines they're incompatible with,
111 which is partciuarly useful with kernels. It also helps to increase parsing
112 speed as further parsing of the recipe is skipped as if it found the current
113 machine is not compatible.</para>
114 </glossdef>
115 </glossentry>
116
117 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
118 <glossdef>
119 <para>
120 A list of files which contains autoconf test results relevant
121 to the current build. This variable is used by the autotools utilities
122 when running configure.
123 </para>
124 </glossdef>
125 </glossentry>
126
127 </glossdiv>
128
129 <glossdiv id='var-glossary-d'><title>D</title>
130
131 <glossentry id='var-D'><glossterm>D</glossterm>
132 <glossdef>
133 <para>Destination directory</para>
134 </glossdef>
135 </glossentry>
136
137 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
138 <glossdef>
139 <para>
140 Build packages with debugging information. This influences the value
141 <link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link>
142 takes.
143 </para>
144 </glossdef>
145 </glossentry>
146
147 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
148 <glossdef>
149 <para>
150 The options to pass in <link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link>
151 and <link linkend='var-CFLAGS'>CFLAGS</link> when compiling a system for debugging.
152 This defaults to "-O -fno-omit-frame-pointer -g".
153 </para>
154 </glossdef>
155 </glossentry>
156
157 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
158 <glossdef>
159 <para>Priority of recipe</para>
160 </glossdef>
161 </glossentry>
162
163 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
164 <glossdef>
165 <para>
166 A list of build time dependencies for a given recipe. These indicate
167 recipes that must have staged before this recipe can configure.
168 </para>
169 </glossdef>
170 </glossentry>
171
172 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
173 <glossdef>
174 <para>Package description used by package
175 managers</para>
176 </glossdef>
177 </glossentry>
178
179 <glossentry id='var-DESTDIR'><glossterm>DESTDIR</glossterm>
180 <glossdef>
181 <para>Destination directory</para>
182 </glossdef>
183 </glossentry>
184
185 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
186 <glossdef>
187 <para>Short name of distribution</para>
188 </glossdef>
189 </glossentry>
190
191 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
192 <glossdef>
193 <para>List of packages required by distribution.</para>
194 </glossdef>
195 </glossentry>
196
197 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
198 <glossdef>
199 <para>List of packages which extend usability of
200 image. Those packages will be automatically
201 installed but can be removed by user.</para>
202 </glossdef>
203 </glossentry>
204
205 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
206 <glossdef>
207 <para>Features of the distribution.</para>
208 </glossdef>
209 </glossentry>
210
211 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
212 <glossdef>
213 <para>Long name of distribution</para>
214 </glossdef>
215 </glossentry>
216
217 <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
218 <glossdef>
219 <para>Alias names of the recipe in various Linux distributions. </para>
220 <para>More information in
221 <link
222 linkend='usingpoky-configuring-DISTRO_PN_ALIAS'>
223 Configuring the DISTRO_PN_ALIAS variable section
224 </link>
225 </para>
226 </glossdef>
227 </glossentry>
228
229 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
230 <glossdef>
231 <para>Version of distribution</para>
232 </glossdef>
233 </glossentry>
234
235 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
236 <glossdef>
237 <para>Directory where all fetched sources will be stored</para>
238 </glossdef>
239
240 </glossentry>
241 </glossdiv>
242
243 <glossdiv id='var-glossary-e'><title>E</title>
244
245 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
246 <glossdef>
247 <para>Variable which control which locales for glibc are
248 to be generated during build (useful if target device
249 has 64M RAM or less)</para>
250 </glossdef>
251 </glossentry>
252
253 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
254 <glossdef>
255 <para>Additional cmake options</para>
256 </glossdef>
257 </glossentry>
258
259 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
260 <glossdef>
261 <para>Additional 'configure' script options</para>
262 </glossdef>
263 </glossentry>
264
265 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
266 <glossdef>
267 <para>Additional GNU make options</para>
268 </glossdef>
269 </glossentry>
270
271 </glossdiv>
272
273 <glossdiv id='var-glossary-f'><title>F</title>
274
275 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
276 <glossdef>
277 <para>list of directories/files which will be placed
278 in packages</para>
279 </glossdef>
280 </glossentry>
281
282 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
283 <glossdef>
284 <para>
285 The options to pass in <link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link>
286 and <link linkend='var-CFLAGS'>CFLAGS</link> when compiling an optimised system.
287 This defaults to "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
288 </para>
289 </glossdef>
290 </glossentry>
291
292 </glossdiv>
293
294<!-- <glossdiv id='var-glossary-g'><title>G</title>-->
295<!-- </glossdiv>-->
296
297 <glossdiv id='var-glossary-h'><title>H</title>
298
299 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
300 <glossdef>
301 <para>Website where more info about package can be found</para>
302 </glossdef>
303 </glossentry>
304
305 </glossdiv>
306
307 <glossdiv id='var-glossary-i'><title>I</title>
308
309 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
310 <glossdef>
311 <para><link linkend="ref-features-image">List of
312 features</link> present in resulting images</para>
313 </glossdef>
314 </glossentry>
315
316 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
317 <glossdef>
318 <para>Formats of rootfs images which we want to have
319 created</para>
320 </glossdef>
321 </glossentry>
322
323 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
324 <glossdef>
325 <para>List of packages used to build image</para>
326 </glossdef>
327 </glossentry>
328
329 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
330 <glossdef>
331 <para>
332 This variable causes the build to not strip binaries in
333 resulting packages.
334 </para>
335 </glossdef>
336 </glossentry>
337
338
339 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
340 <glossdef>
341 <para>
342 This variable causes the named class to be inherited at
343 this point during parsing. Its only valid in configuration
344 files.
345 </para>
346 </glossdef>
347 </glossentry>
348
349
350 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
351 <glossdef>
352 <para>
353 Scope: Used in recipes when using update-rc.d.bbclass. Optional, defaults to PN.
354 </para>
355 <para>
356 A list of the packages which contain initscripts. If multiple
357 packages are specified you need to append the package name
358 to the other INITSCRIPT_* as an override.
359 </para>
360 </glossdef>
361 </glossentry>
362
363 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
364 <glossdef>
365 <para>
366 Scope: Used in recipes when using update-rc.d.bbclass. Mandatory.
367 </para>
368 <para>
369 The filename of the initscript (as installed to ${etcdir}/init.d).
370 </para>
371 </glossdef>
372 </glossentry>
373
374 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
375 <glossdef>
376 <para>
377 Scope: Used in recipes when using update-rc.d.bbclass. Mandatory.
378 </para>
379 <para>
380 Specifies the options to pass to update-rc.d. An example is
381 "start 99 5 2 . stop 20 0 1 6 ." which gives the script a
382 runlevel of 99, starts the script in initlevels 2 and 5 and
383 stops it in levels 0, 1 and 6.
384 </para>
385 </glossdef>
386 </glossentry>
387
388
389 </glossdiv>
390
391<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
392<!-- </glossdiv>-->
393
394 <glossdiv id='var-glossary-k'><title>K</title>
395
396 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
397 <glossdef>
398 <para>The type of kernel to build for a device, usually set by the
399 machine configuration files and defaults to "zImage". This is used
400 when building the kernel and is passed to "make" as the target to
401 build.</para>
402 </glossdef>
403 </glossentry>
404
405 </glossdiv>
406
407 <glossdiv id='var-glossary-l'><title>L</title>
408
409 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
410 <glossdef>
411 <para>When used inside a layer.conf gives the path of the
412 current layer. This variable requires immediate expansion
413 (see the Bitbake manual) as lazy expansion can result in
414 the expansion happening in the wrong directory and therefore
415 giving the wrong value.</para>
416 </glossdef>
417 </glossentry>
418 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
419 <glossdef>
420 <para>List of package source licenses.</para>
421 </glossdef>
422 </glossentry>
423 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
424 <glossdef>
425 <para>Checksums of the license text in the recipe source code.
426 </para>
427 <para>This variable tracks changes in license text of the source
428 code files. If the license text is changed, it will trigger the build
429 failure, which gives developer an opportunity to review any
430 license change</para>
431 <para> This is an optional variable now, and the plan is to make
432 it a required variable in the future </para>
433 <para>See "meta/package/zlib/zlib_${PV}.bb" file for an example</para>
434
435 <para>More information in <link
436 linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
437 Configuring the LIC_FILES_CHKSUM variable section</link></para>
438 </glossdef>
439 </glossentry>
440
441 </glossdiv>
442
443 <glossdiv id='var-glossary-m'><title>M</title>
444
445 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
446 <glossdef>
447 <para>Target device</para>
448 </glossdef>
449 </glossentry>
450
451 <glossentry id='var-MACHINE_ESSENTIAL_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_RDEPENDS</glossterm>
452 <glossdef>
453 <para>List of packages required to boot device</para>
454 </glossdef>
455 </glossentry>
456
457 <glossentry id='var-MACHINE_ESSENTIAL_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_RRECOMMENDS</glossterm>
458 <glossdef>
459 <para>List of packages required to boot device (usually
460 additional kernel modules)</para>
461 </glossdef>
462 </glossentry>
463
464 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
465 <glossdef>
466 <para>List of packages required to use device</para>
467 </glossdef>
468 </glossentry>
469
470 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMNEDS</glossterm>
471 <glossdef>
472 <para>List of packages useful to use device (for example
473 additional kernel modules)</para>
474 </glossdef>
475 </glossentry>
476
477 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
478 <glossdef>
479 <para>List of device features - defined in <link
480 linkend='ref-features-machine'>machine
481 features section</link></para>
482 </glossdef>
483 </glossentry>
484
485 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
486 <glossdef>
487 <para>E-mail of distribution maintainer</para>
488 </glossdef>
489 </glossentry>
490 </glossdiv>
491
492<!-- <glossdiv id='var-glossary-n'><title>N</title>-->
493<!-- </glossdiv>-->
494
495<!-- <glossdiv id='var-glossary-o'><title>O</title>-->
496<!-- </glossdiv>-->
497
498 <glossdiv id='var-glossary-p'><title>P</title>
499
500 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
501 <glossdef>
502 <para>Architecture of resulting package</para>
503 </glossdef>
504 </glossentry>
505
506 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
507 <glossdef>
508 <para>List of resulting packages formats</para>
509 </glossdef>
510 </glossentry>
511
512 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
513 <glossdef>
514 <para>List of architectures compatible with device
515 CPU. Usable when build is done for few different
516 devices with misc processors (like XScale and
517 ARM926-EJS)</para>
518 </glossdef>
519 </glossentry>
520
521 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
522 <glossdef>
523 <para>List of packages to be created from recipe.
524 The default value is "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev"</para>
525 </glossdef>
526 </glossentry>
527
528 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
529 <glossdef>
530 <para>Extra options that are passed to the make command during the
531 compile tasks. This is usually of the form '-j 4' where the number
532 represents the maximum number of parallel threads make can run.</para>
533 </glossdef>
534 </glossentry>
535
536 <glossentry id='var-PN'><glossterm>PN</glossterm>
537 <glossdef>
538 <para>Name of package.
539 </para>
540 </glossdef>
541 </glossentry>
542
543 <glossentry id='var-PR'><glossterm>PR</glossterm>
544 <glossdef>
545 <para>Revision of package.
546 </para>
547 </glossdef>
548 </glossentry>
549
550 <glossentry id='var-PV'><glossterm>PV</glossterm>
551 <glossdef>
552 <para>Version of package.
553 The default value is "1.0"</para>
554 </glossdef>
555 </glossentry>
556
557 <glossentry id='var-PE'><glossterm>PE</glossterm>
558 <glossdef>
559 <para>
560 Epoch of the package. The default value is "0". The field is used
561 to make upgrades possible when the versioning scheme changes in
562 some backwards incompatible way.
563 </para>
564 </glossdef>
565 </glossentry>
566
567 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
568 <glossdef>
569 <para>If multiple recipes provide an item, this variable
570 determines which one should be given preference. It
571 should be set to the "$PN" of the recipe to be preferred.</para>
572 </glossdef>
573 </glossentry>
574
575 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
576 <glossdef>
577 <para>
578 If there are multiple versions of recipe available, this
579 variable determines which one should be given preference. It
580 should be set to the "$PV" of the recipe to be preferred.
581 </para>
582 </glossdef>
583 </glossentry>
584
585 <glossentry id='var-POKY_EXTRA_INSTALL'><glossterm>POKY_EXTRA_INSTALL</glossterm>
586 <glossdef>
587 <para>List of packages to be added to the image. This should
588 only be set in <filename>local.conf</filename>.</para>
589 </glossdef>
590 </glossentry>
591
592 <glossentry id='var-POKYLIBC'><glossterm>POKYLIBC</glossterm>
593 <glossdef>
594 <para>Libc implementation selector - glibc, eglibc, or uclibc can be selected.</para>
595 </glossdef>
596 </glossentry>
597
598 <glossentry id='var-POKYMODE'><glossterm>POKYMODE</glossterm>
599 <glossdef>
600 <para>Toolchain selector. It can be external toolchain
601 built from Poky or few supported combinations of
602 upstream GCC or CodeSourcery Labs toolchain.</para>
603 </glossdef>
604 </glossentry>
605
606 </glossdiv>
607
608<!-- <glossdiv id='var-glossary-q'><title>Q</title>-->
609<!-- </glossdiv>-->
610
611 <glossdiv id='var-glossary-r'><title>R</title>
612
613 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
614 <glossdef>
615 <para>List of packages which conflict with this
616 one. Package will not be installed if they are not
617 removed first.</para>
618 </glossdef>
619 </glossentry>
620
621 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
622 <glossdef>
623 <para>
624 A list of run-time dependencies for a package. These packages
625 need to be installed alongside the package it applies to so
626 the package will run correctly, an example is a perl script
627 which would rdepend on perl. Since this variable applies to
628 output packages there would usually be an override attached
629 to this variable like RDEPENDS_${PN}-dev. Names in this field
630 should be as they are in <link linkend='var-PACKAGES'>PACKAGES
631 </link> namespace before any renaming of the output package
632 by classes like debian.bbclass.
633 </para>
634 </glossdef>
635 </glossentry>
636
637 <glossentry id='var-ROOT_FLASH_SIZE'><glossterm>ROOT_FLASH_SIZE</glossterm>
638 <glossdef>
639 <para>Size of rootfs in megabytes</para>
640 </glossdef>
641 </glossentry>
642
643 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
644 <glossdef>
645 <para>List of packages which extend usability of the
646 package. Those packages will be automatically
647 installed but can be removed by user.</para>
648 </glossdef>
649 </glossentry>
650
651 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
652 <glossdef>
653 <para>List of packages which are replaced with this
654 one.</para>
655 </glossdef>
656 </glossentry>
657
658 </glossdiv>
659
660 <glossdiv id='var-glossary-s'><title>S</title>
661
662 <glossentry id='var-S'><glossterm>S</glossterm>
663 <glossdef>
664 <para>
665 Path to unpacked sources (by default:
666 "${<link linkend='var-WORKDIR'>WORKDIR</link>}/${<link linkend='var-PN'>PN</link>}-${<link linkend='var-PV'>PV</link>}")
667 </para>
668 </glossdef>
669 </glossentry>
670
671 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
672 <glossdef>
673 <para>Section where package should be put - used
674 by package managers</para>
675 </glossdef>
676 </glossentry>
677
678 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
679 <glossdef>
680 <para>
681 The variable takes the value of <link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link>
682 unless <link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link> = "1" in which case
683 <link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link> is used.
684 </para>
685 </glossdef>
686 </glossentry>
687
688
689 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
690 <glossdef>
691 <para>Speed and device for serial port used to attach
692 serial console. This is given to kernel as "console"
693 param and after boot getty is started on that port
694 so remote login is possible.</para>
695 </glossdef>
696 </glossentry>
697
698 <glossentry id='var-SHELLCMDS'><glossterm>SHELLCMDS</glossterm>
699 <glossdef>
700 <para>
701 A list of commands to run within the a shell, used by <glossterm><link
702 linkend='var-TERMCMDRUN'>TERMCMDRUN</link></glossterm>.
703 </para>
704 </glossdef>
705 </glossentry>
706
707 <glossentry id='var-SITEINFO_ENDIANESS'><glossterm>SITEINFO_ENDIANESS</glossterm>
708 <glossdef>
709 <para>
710 Contains "le" for little-endian or "be" for big-endian depending
711 on the endian byte order of the target system.
712 </para>
713 </glossdef>
714 </glossentry>
715
716 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
717 <glossdef>
718 <para>
719 Contains "32" or "64" depending on the number of bits for the
720 CPU of the target system.
721 </para>
722 </glossdef>
723 </glossentry>
724
725 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
726 <glossdef>
727 <para>List of source files (local or remote ones)</para>
728 </glossdef>
729 </glossentry>
730
731 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
732 <glossdef>
733 <para>
734 By default there is code which automatically detects whether
735 <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>
736 contains files which are machine specific and if this is the case it
737 automatically changes
738 <glossterm><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></glossterm>.
739 Setting this variable to "0" disables that behaviour.
740 </para>
741 </glossdef>
742 </glossentry>
743
744 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
745 <glossdef>
746 <para>
747 Date of source code used to build package (if it was fetched
748 from SCM).
749 </para>
750 </glossdef>
751 </glossentry>
752
753 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
754 <glossdef>
755 <para>
756 Revision of source code used to build package (Subversion,
757 GIT, Bazaar only).
758 </para>
759 </glossdef>
760 </glossentry>
761
762 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
763 <glossdef>
764 <para>
765 Directory with kernel headers required to build out-of-tree
766 modules.
767 </para>
768 </glossdef>
769 </glossentry>
770
771 <glossentry id='var-STAMPS'><glossterm>STAMPS</glossterm>
772 <glossdef>
773 <para>
774 Directory (usually TMPDIR/stamps) with timestamps of
775 executed tasks.
776 </para>
777 </glossdef>
778 </glossentry>
779
780 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
781 <glossdef>
782 <para>Short (72 char suggested) Summary of binary package for packaging sytems such as ipkg, rpm or debian, inherits DESCRIPTION by default</para>
783 </glossdef>
784 </glossentry>
785
786 </glossdiv>
787
788 <glossdiv id='var-glossary-t'><title>T</title>
789
790 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
791 <glossdef>
792 <para>The architecture of the device we're building for.
793 A number of values are possible but Poky primarily supports
794 "arm" and "i586".</para>
795 </glossdef>
796 </glossentry>
797
798 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
799 <glossdef>
800 <para>
801 Flags passed to C compiler for the target system. Evaluates to the same
802 as <link linkend='var-CFLAGS'>CFLAGS</link>.
803 </para>
804 </glossdef>
805 </glossentry>
806
807
808 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
809 <glossdef>
810 <para>Method of handling FPU code. For FPU-less targets
811 (most of ARM cpus) it has to be set to "soft" otherwise
812 kernel emulation will get used which will result in
813 performance penalty.</para>
814 </glossdef>
815 </glossentry>
816
817 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
818 <glossdef>
819 <para>Type of target operating system. Can be "linux"
820 for glibc based system, "linux-uclibc" for uClibc. For
821 ARM/EABI targets there are also "linux-gnueabi" and
822 "linux-uclibc-gnueabi" values possible.</para>
823 </glossdef>
824 </glossentry>
825
826 <glossentry id='var-TERMCMD'><glossterm>TERMCMD</glossterm>
827 <glossdef>
828 <para>
829 This command is used by bitbake to lauch a terminal window with a
830 shell. The shell is unspecified so the user's default shell is used.
831 By default it is set to <command>gnome-terminal</command> but it can
832 be any X11 terminal application or terminal multiplexers like screen.
833 </para>
834 </glossdef>
835 </glossentry>
836
837 <glossentry id='var-TERMCMDRUN'><glossterm>TERMCMDRUN</glossterm>
838 <glossdef>
839 <para>
840 This command is similar to <glossterm><link
841 linkend='var-TERMCMD'>TERMCMD</link></glossterm> however instead of the users shell it runs the command specified by the <glossterm><link
842 linkend='var-SHELLCMDS'>SHELLCMDS</link></glossterm> variable.
843 </para>
844 </glossdef>
845 </glossentry>
846
847 </glossdiv>
848
849<!-- <glossdiv id='var-glossary-u'><title>U</title>-->
850<!-- </glossdiv>-->
851
852<!-- <glossdiv id='var-glossary-v'><title>V</title>-->
853<!-- </glossdiv>-->
854
855 <glossdiv id='var-glossary-w'><title>W</title>
856
857 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
858 <glossdef>
859 <para>Path to directory in tmp/work/ where package
860 will be built.</para>
861 </glossdef>
862 </glossentry>
863
864 </glossdiv>
865
866<!-- <glossdiv id='var-glossary-x'><title>X</title>-->
867<!-- </glossdiv>-->
868
869<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
870<!-- </glossdiv>-->
871
872<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
873<!-- </glossdiv>-->
874
875</glossary>
876</appendix>
877<!--
878vim: expandtab tw=80 ts=4
879-->
diff --git a/documentation/poky-ref-manual/ref-varlocality.xml b/documentation/poky-ref-manual/ref-varlocality.xml
new file mode 100644
index 0000000000..87ef0833d7
--- /dev/null
+++ b/documentation/poky-ref-manual/ref-varlocality.xml
@@ -0,0 +1,211 @@
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-ENABLE_BINARY_LOCALE_GENERATION'><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link></glossterm></para>
113 </listitem>
114 </itemizedlist>
115 </section>
116
117 <section id='ref-varlocality-recipe-required'>
118 <title>Recipe Variables - Required</title>
119
120 <itemizedlist>
121 <listitem>
122 <para><glossterm><link linkend='var-DESCRIPTION'>DESCRIPTION</link></glossterm></para>
123 </listitem>
124 <listitem>
125 <para><glossterm><link linkend='var-LICENSE'>LICENSE</link></glossterm></para>
126 </listitem>
127 <listitem>
128 <para><glossterm><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</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
189 linkend='var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</link></glossterm></para>
190 </listitem>
191 <listitem>
192 <para><glossterm><link linkend='var-EXTRA_OECMAKE'>EXTRA_OECMAKE</link></glossterm></para>
193 </listitem>
194 <listitem>
195 <para><glossterm><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></glossterm></para>
196 </listitem>
197 <listitem>
198 <para><glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></glossterm></para>
199 </listitem>
200 <listitem>
201 <para><glossterm><link linkend='var-PACKAGES'>PACKAGES</link></glossterm></para>
202 </listitem>
203 <listitem>
204 <para><glossterm><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm></para>
205 </listitem>
206 </itemizedlist>
207 </section>
208</appendix>
209<!--
210vim: expandtab tw=80 ts=4 spell spelllang=en_gb
211-->
diff --git a/documentation/poky-ref-manual/resources.xml b/documentation/poky-ref-manual/resources.xml
new file mode 100644
index 0000000000..7561669fba
--- /dev/null
+++ b/documentation/poky-ref-manual/resources.xml
@@ -0,0 +1,142 @@
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.pokylinux.org/'>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 original company behind Poky.
62 </para></listitem>
63 <listitem><para>
64 <ulink url='http://www.intel.com/'>Intel Corporation</ulink> - The
65 company who acquired OpenedHand in 2008.
66 </para></listitem>
67
68 <listitem><para>
69 <ulink url='http://www.openembedded.org/'>OpenEmbedded</ulink>
70 - The upstream generic embedded distribution Poky derives
71 from (and contributes to).
72 </para></listitem>
73 <listitem><para>
74 <ulink url='http://developer.berlios.de/projects/bitbake/'>Bitbake</ulink>
75 - The tool used to process Poky metadata.
76 </para></listitem>
77 <listitem><para>
78 <ulink url='http://bitbake.berlios.de/manual/'>Bitbake User
79 Manual</ulink>
80 </para></listitem>
81 <listitem><para>
82 <ulink url='http://pimlico-project.org/'>Pimlico</ulink> - A
83 suite of lightweight Personal Information Management (PIM)
84 applications designed primarily for handheld and mobile
85 devices.
86 </para></listitem>
87 <listitem><para>
88 <ulink url='http://fabrice.bellard.free.fr/qemu/'>QEMU</ulink>
89 - An open source machine emulator and virtualizer.
90 </para></listitem>
91 </itemizedlist>
92</section>
93
94<section id='resources-contributions'>
95 <title>Contributions</title>
96
97 <para>
98 Contributions to Poky are very welcome. Patches should be sent to the Poky mailing list along with a Signed-off-by: line in the same style as the Linux kernel. Adding this line signifies the developer has agreed to the Developer's Certificate of Origin 1.1:
99 </para>
100
101 <programlisting>
102 Developer's Certificate of Origin 1.1
103
104 By making a contribution to this project, I certify that:
105
106 (a) The contribution was created in whole or in part by me and I
107 have the right to submit it under the open source license
108 indicated in the file; or
109
110 (b) The contribution is based upon previous work that, to the best
111 of my knowledge, is covered under an appropriate open source
112 license and I have the right under that license to submit that
113 work with modifications, whether created in whole or in part
114 by me, under the same open source license (unless I am
115 permitted to submit under a different license), as indicated
116 in the file; or
117
118 (c) The contribution was provided directly to me by some other
119 person who certified (a), (b) or (c) and I have not modified
120 it.
121
122 (d) I understand and agree that this project and the contribution
123 are public and that a record of the contribution (including all
124 personal information I submit with it, including my sign-off) is
125 maintained indefinitely and may be redistributed consistent with
126 this project or the open source license(s) involved.
127</programlisting>
128
129 <para>
130 A Poky contributions tree (poky-contrib, git://git.pokylinux.org/poky-contrib.git)
131 exists for people to stage contributions in, for regular contributors.
132 If people desire such access, please ask on the mailing list. Usually
133 access will be given to anyone with a proven track record of good patches.
134 </para>
135
136</section>
137
138
139</appendix>
140<!--
141vim: expandtab tw=80 ts=4
142-->
diff --git a/documentation/poky-ref-manual/screenshots/ss-anjuta-poky-1.png b/documentation/poky-ref-manual/screenshots/ss-anjuta-poky-1.png
new file mode 100644
index 0000000000..4e92012af5
--- /dev/null
+++ b/documentation/poky-ref-manual/screenshots/ss-anjuta-poky-1.png
Binary files differ
diff --git a/documentation/poky-ref-manual/screenshots/ss-anjuta-poky-2.png b/documentation/poky-ref-manual/screenshots/ss-anjuta-poky-2.png
new file mode 100644
index 0000000000..2c9bfb3bbd
--- /dev/null
+++ b/documentation/poky-ref-manual/screenshots/ss-anjuta-poky-2.png
Binary files differ
diff --git a/documentation/poky-ref-manual/screenshots/ss-oprofile-viewer.png b/documentation/poky-ref-manual/screenshots/ss-oprofile-viewer.png
new file mode 100644
index 0000000000..fa7d1dfa4f
--- /dev/null
+++ b/documentation/poky-ref-manual/screenshots/ss-oprofile-viewer.png
Binary files differ
diff --git a/documentation/poky-ref-manual/screenshots/ss-sato.png b/documentation/poky-ref-manual/screenshots/ss-sato.png
new file mode 100644
index 0000000000..5a05709245
--- /dev/null
+++ b/documentation/poky-ref-manual/screenshots/ss-sato.png
Binary files differ
diff --git a/documentation/poky-ref-manual/style.css b/documentation/poky-ref-manual/style.css
new file mode 100644
index 0000000000..c4d9df197c
--- /dev/null
+++ b/documentation/poky-ref-manual/style.css
@@ -0,0 +1,953 @@
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 0em 3.0em 0em;
68 padding: 0em 0em 0em 0em;
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: 256px;
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: 0em 0me 0em 0em;
133 padding: 0em 0em 0em 0em;
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: 0em;
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: 0em 0em 0em 0em;
165 padding: 0em 0em 0.3em;
166 margin: 1.5em 0em 0em 0em;
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: 0em 0em 0.5em 0em;
182 padding: 0em 0em 0em 0em;
183}
184
185.toc dt {
186 margin: 0em 0em 0em 0em;
187 padding: 0em 0em 0em 0em;
188}
189
190.toc dd {
191 margin: 0em 0em 0em 2.6em;
192 padding: 0em 0em 0em 0em;
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: 0em 0em 0em 0em;
226 margin: 0em 0em 0em 0em;
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: 0em;
240}
241
242p {
243 line-height: 1.5em;
244 margin-top: 0em;
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
266ul {
267 padding: 0em 0em 0em 1.5em;
268}
269
270ul li {
271 padding: 0em 0em 0em 0em;
272}
273
274ul li p {
275 text-align: left;
276}
277
278table {
279 width :100%;
280}
281
282th {
283 padding: 0.25em;
284 text-align: left;
285 font-weight: normal;
286 vertical-align: top;
287}
288
289td {
290 padding: 0.25em;
291 vertical-align: top;
292}
293
294p a[id] {
295 margin: 0px;
296 padding: 0px;
297 display: inline;
298 background-image: none;
299}
300
301a {
302 text-decoration: underline;
303 color: #444;
304}
305
306pre {
307 overflow: auto;
308}
309
310a:hover {
311 text-decoration: underline;
312 /*font-weight: bold;*/
313}
314
315
316div.informalfigure,
317div.informalexample,
318div.informaltable,
319div.figure,
320div.table,
321div.example {
322 margin: 1em 0em;
323 padding: 1em;
324 page-break-inside: avoid;
325}
326
327
328div.informalfigure p.title b,
329div.informalexample p.title b,
330div.informaltable p.title b,
331div.figure p.title b,
332div.example p.title b,
333div.table p.title b{
334 padding-top: 0em;
335 margin-top: 0em;
336 font-size: 100%;
337 font-weight: normal;
338}
339
340.mediaobject .caption,
341.mediaobject .caption p {
342 text-align: center;
343 font-size: 80%;
344 padding-top: 0.5em;
345 padding-bottom: 0.5em;
346}
347
348.epigraph {
349 padding-left: 55%;
350 margin-bottom: 1em;
351}
352
353.epigraph p {
354 text-align: left;
355}
356
357.epigraph .quote {
358 font-style: italic;
359}
360.epigraph .attribution {
361 font-style: normal;
362 text-align: right;
363}
364
365span.application {
366 font-style: italic;
367}
368
369.programlisting {
370 font-family: monospace;
371 font-size: 80%;
372 white-space: pre;
373 margin: 1.33em 0em;
374 padding: 1.33em;
375}
376
377.tip,
378.warning,
379.caution,
380.note {
381 margin-top: 1em;
382 margin-bottom: 1em;
383
384}
385
386/* force full width of table within div */
387.tip table,
388.warning table,
389.caution table,
390.note table {
391 border: none;
392 width: 100%;
393}
394
395
396.tip table th,
397.warning table th,
398.caution table th,
399.note table th {
400 padding: 0.8em 0.0em 0.0em 0.0em;
401 margin : 0em 0em 0em 0em;
402}
403
404.tip p,
405.warning p,
406.caution p,
407.note p {
408 margin-top: 0.5em;
409 margin-bottom: 0.5em;
410 padding-right: 1em;
411 text-align: left;
412}
413
414.acronym {
415 text-transform: uppercase;
416}
417
418b.keycap,
419.keycap {
420 padding: 0.09em 0.3em;
421 margin: 0em;
422}
423
424.itemizedlist li {
425 clear: none;
426}
427
428.filename {
429 font-size: medium;
430 font-family: Courier, monospace;
431}
432
433
434div.navheader, div.heading{
435 position: absolute;
436 left: 0em;
437 top: 0em;
438 width: 100%;
439 background-color: #cdf;
440 width: 100%;
441}
442
443div.navfooter, div.footing{
444 position: fixed;
445 left: 0em;
446 bottom: 0em;
447 background-color: #eee;
448 width: 100%;
449}
450
451
452div.navheader td,
453div.navfooter td {
454 font-size: 66%;
455}
456
457div.navheader table th {
458 /*font-family: Georgia, Times, serif;*/
459 /*font-size: x-large;*/
460 font-size: 80%;
461}
462
463div.navheader table {
464 border-left: 0em;
465 border-right: 0em;
466 border-top: 0em;
467 width: 100%;
468}
469
470div.navfooter table {
471 border-left: 0em;
472 border-right: 0em;
473 border-bottom: 0em;
474 width: 100%;
475}
476
477div.navheader table td a,
478div.navfooter table td a {
479 color: #777;
480 text-decoration: none;
481}
482
483/* normal text in the footer */
484div.navfooter table td {
485 color: black;
486}
487
488div.navheader table td a:visited,
489div.navfooter table td a:visited {
490 color: #444;
491}
492
493
494/* links in header and footer */
495div.navheader table td a:hover,
496div.navfooter table td a:hover {
497 text-decoration: underline;
498 background-color: transparent;
499 color: #33a;
500}
501
502div.navheader hr,
503div.navfooter hr {
504 display: none;
505}
506
507
508.qandaset tr.question td p {
509 margin: 0em 0em 1em 0em;
510 padding: 0em 0em 0em 0em;
511}
512
513.qandaset tr.answer td p {
514 margin: 0em 0em 1em 0em;
515 padding: 0em 0em 0em 0em;
516}
517.answer td {
518 padding-bottom: 1.5em;
519}
520
521.emphasis {
522 font-weight: bold;
523}
524
525
526 /************* /
527 / decorations /
528/ *************/
529
530.titlepage {
531}
532
533.part .title {
534}
535
536.subtitle {
537 border: none;
538}
539
540/*
541h1 {
542 border: none;
543}
544
545h2 {
546 border-top: solid 0.2em;
547 border-bottom: solid 0.06em;
548}
549
550h3 {
551 border-top: 0em;
552 border-bottom: solid 0.06em;
553}
554
555h4 {
556 border: 0em;
557 border-bottom: solid 0.06em;
558}
559
560h5 {
561 border: 0em;
562}
563*/
564
565.programlisting {
566 border: solid 1px;
567}
568
569div.figure,
570div.table,
571div.informalfigure,
572div.informaltable,
573div.informalexample,
574div.example {
575 border: 1px solid;
576}
577
578
579
580.tip,
581.warning,
582.caution,
583.note {
584 border: 1px solid;
585}
586
587.tip table th,
588.warning table th,
589.caution table th,
590.note table th {
591 border-bottom: 1px solid;
592}
593
594.question td {
595 border-top: 1px solid black;
596}
597
598.answer {
599}
600
601
602b.keycap,
603.keycap {
604 border: 1px solid;
605}
606
607
608div.navheader, div.heading{
609 border-bottom: 1px solid;
610}
611
612
613div.navfooter, div.footing{
614 border-top: 1px solid;
615}
616
617 /********* /
618 / colors /
619/ *********/
620
621body {
622 color: #333;
623 background: white;
624}
625
626a {
627 background: transparent;
628}
629
630a:hover {
631 background-color: #dedede;
632}
633
634
635h1,
636h2,
637h3,
638h4,
639h5,
640h6,
641h7,
642h8 {
643 background-color: transparent;
644}
645
646hr {
647 border-color: #aaa;
648}
649
650
651.tip, .warning, .caution, .note {
652 border-color: #aaa;
653}
654
655
656.tip table th,
657.warning table th,
658.caution table th,
659.note table th {
660 border-bottom-color: #aaa;
661}
662
663
664.warning {
665 background-color: #fea;
666}
667
668.caution {
669 background-color: #fea;
670}
671
672.tip {
673 background-color: #eff;
674}
675
676.note {
677 background-color: #dfc;
678}
679
680.glossary dl dt,
681.variablelist dl dt,
682.variablelist dl dt span.term {
683 color: #044;
684}
685
686div.figure,
687div.table,
688div.example,
689div.informalfigure,
690div.informaltable,
691div.informalexample {
692 border-color: #aaa;
693}
694
695pre.programlisting {
696 color: black;
697 background-color: #fff;
698 border-color: #aaa;
699 border-width: 2px;
700}
701
702.guimenu,
703.guilabel,
704.guimenuitem {
705 background-color: #eee;
706}
707
708
709b.keycap,
710.keycap {
711 background-color: #eee;
712 border-color: #999;
713}
714
715
716div.navheader {
717 border-color: black;
718}
719
720
721div.navfooter {
722 border-color: black;
723}
724
725
726 /*********** /
727 / graphics /
728/ ***********/
729
730/*
731body {
732 background-image: url("images/body_bg.jpg");
733 background-attachment: fixed;
734}
735
736.navheader,
737.note,
738.tip {
739 background-image: url("images/note_bg.jpg");
740 background-attachment: fixed;
741}
742
743.warning,
744.caution {
745 background-image: url("images/warning_bg.jpg");
746 background-attachment: fixed;
747}
748
749.figure,
750.informalfigure,
751.example,
752.informalexample,
753.table,
754.informaltable {
755 background-image: url("images/figure_bg.jpg");
756 background-attachment: fixed;
757}
758
759*/
760h1,
761h2,
762h3,
763h4,
764h5,
765h6,
766h7{
767}
768
769div.preface .titlepage .title,
770div.colophon .title,
771div.chapter .titlepage .title {
772 background-image: url("images/title-bg.png");
773 background-position: bottom;
774 background-repeat: repeat-x;
775}
776
777div.section div.section .titlepage .title,
778div.sect2 .titlepage .title {
779 background: none;
780}
781
782
783h1.title {
784 background-color: transparent;
785 background-image: url("poky-handbook.png");
786 background-repeat: no-repeat;
787 height: 256px;
788 text-indent: -9000px;
789 overflow:hidden;
790}
791
792h2.subtitle {
793 background-color: transparent;
794 text-indent: -9000px;
795 overflow:hidden;
796 width: 0px;
797 display: none;
798}
799
800 /*************************************** /
801 / pippin.gimp.org specific alterations /
802/ ***************************************/
803
804/*
805div.heading, div.navheader {
806 color: #777;
807 font-size: 80%;
808 padding: 0;
809 margin: 0;
810 text-align: left;
811 position: absolute;
812 top: 0px;
813 left: 0px;
814 width: 100%;
815 height: 50px;
816 background: url('/gfx/heading_bg.png') transparent;
817 background-repeat: repeat-x;
818 background-attachment: fixed;
819 border: none;
820}
821
822div.heading a {
823 color: #444;
824}
825
826div.footing, div.navfooter {
827 border: none;
828 color: #ddd;
829 font-size: 80%;
830 text-align:right;
831
832 width: 100%;
833 padding-top: 10px;
834 position: absolute;
835 bottom: 0px;
836 left: 0px;
837
838 background: url('/gfx/footing_bg.png') transparent;
839}
840*/
841
842
843
844 /****************** /
845 / nasty ie tweaks /
846/ ******************/
847
848/*
849div.heading, div.navheader {
850 width:expression(document.body.clientWidth + "px");
851}
852
853div.footing, div.navfooter {
854 width:expression(document.body.clientWidth + "px");
855 margin-left:expression("-5em");
856}
857body {
858 padding:expression("4em 5em 0em 5em");
859}
860*/
861
862 /**************************************** /
863 / mozilla vendor specific css extensions /
864/ ****************************************/
865/*
866div.navfooter, div.footing{
867 -moz-opacity: 0.8em;
868}
869
870div.figure,
871div.table,
872div.informalfigure,
873div.informaltable,
874div.informalexample,
875div.example,
876.tip,
877.warning,
878.caution,
879.note {
880 -moz-border-radius: 0.5em;
881}
882
883b.keycap,
884.keycap {
885 -moz-border-radius: 0.3em;
886}
887*/
888
889table tr td table tr td {
890 display: none;
891}
892
893
894hr {
895 display: none;
896}
897
898table {
899 border: 0em;
900}
901
902 .photo {
903 float: right;
904 margin-left: 1.5em;
905 margin-bottom: 1.5em;
906 margin-top: 0em;
907 max-width: 17em;
908 border: 1px solid gray;
909 padding: 3px;
910 background: white;
911}
912 .seperator {
913 padding-top: 2em;
914 clear: both;
915 }
916
917 #validators {
918 margin-top: 5em;
919 text-align: right;
920 color: #777;
921 }
922 @media print {
923 body {
924 font-size: 8pt;
925 }
926 .noprint {
927 display: none;
928 }
929 }
930
931
932.tip,
933.note {
934 background: #91ae35;
935 color: #fff;
936 padding: 20px;
937 margin: 20px;
938}
939
940.tip h3,
941.note h3 {
942 padding: 0em;
943 margin: 0em;
944 font-size: 2em;
945 font-weight: bold;
946 color: #fff;
947}
948
949.tip a,
950.note a {
951 color: #fff;
952 text-decoration: underline;
953}
diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml
new file mode 100644
index 0000000000..ad6bda2545
--- /dev/null
+++ b/documentation/poky-ref-manual/usingpoky.xml
@@ -0,0 +1,316 @@
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-layers'>'layer'</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 be 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 set up using the following command:
118 </para>
119 <para>
120 <literallayout class='monospaced'>
121$ source poky-init-build-env [build_dir]
122</literallayout>
123 </para>
124 <para>
125 The build_dir is the dir containing all the building object files. The default
126 build dir is poky-dir/build. Multiple build_dir can be used for different targets.
127 For example, ~/build/x86 for qemux86 target, and ~/build/arm for qemuarm target.
128 Please refer to <link linkend="structure-core-script">poky-init-build-env</link>
129 for detail info
130 </para>
131 <para>
132 Once the Poky build environment is set up, a target can now be built using:
133 </para>
134 <para>
135 <literallayout class='monospaced'>
136$ bitbake &lt;target&gt;
137$ bitbake qemu-native
138</literallayout>
139 </para>
140 <para>
141 The target is the name of the recipe you want to build. Common targets are the
142 images (in <filename class="directory">meta/packages/images/</filename>)
143 or the name of a recipe for a specific piece of software like
144 <application>busybox</application>. More details about the standard images
145 are available in the <link linkend='ref-images'>image reference section</link>.
146 The qemu-native target will build the poky customized qemu, and will be used
147 by runqemu script later.
148 </para>
149</section>
150
151<section id='usingpoky-install'>
152 <title>Installing and Using the Result</title>
153
154 <para>
155 Once an image has been built it often needs to be installed. The images/kernels built
156 by Poky are placed in the <filename class="directory">tmp/deploy/images</filename>
157 directory. Running qemux86 and qemuarm images is covered in the <link
158 linkend='intro-quickstart-qemu'>Running an Image</link> section. See your
159 board/machine documentation for information about how to install these images.
160 </para>
161
162</section>
163
164<section id='usingpoky-debugging'>
165 <title>Debugging Build Failures</title>
166
167 <para>
168 The exact method for debugging Poky depends on the nature of the
169 bug(s) and which part of the system they might be from. Standard
170 debugging practises such as comparing to the last
171 known working version and examining the changes, reapplying the
172 changes in steps to identify the one causing the problem etc. are
173 valid for Poky just like any other system. It's impossible to detail
174 every possible potential failure here but there are some general
175 tips to aid debugging:
176 </para>
177
178 <section id='usingpoky-debugging-taskfailures'>
179 <title>Task Failures</title>
180
181 <para>The log file for shell tasks is available in <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
182 For the compile task of busybox 1.01 on the ARM spitz machine, this
183 might be <filename>tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</filename>
184 for example. To see what bitbake ran to generate that log, look at the <filename>run.do_taskname.pid </filename>
185 file in the same directory.
186 </para>
187
188 <para>The output from python tasks is sent directly to the console at present.</para>
189 </section>
190
191 <section id='usingpoky-debugging-taskrunning'>
192 <title>Running specific tasks</title>
193
194 <para> Any given package consists of a set of tasks, in most
195 cases the series is fetch, unpack, patch, configure,
196 compile, install, package, package_write and build. The
197 default task is "build" and any tasks this depends on are
198 built first hence the standard bitbake behaviour. There are
199 some tasks such as devshell which are not part of the
200 default build chain. If you wish to run such a task you can
201 use the "-c" option to bitbake e.g. <command>bitbake
202 matchbox-desktop -c devshell</command>.
203 </para>
204
205 <para>
206 If you wish to rerun a task you can use the force option
207 "-f". A typical usage session might look like: </para>
208
209 <para>
210 <literallayout class='monospaced'>
211% bitbake matchbox-desktop
212[change some source in the WORKDIR for example]
213% bitbake matchbox-desktop -c compile -f
214% bitbake matchbox-desktop</literallayout>
215 </para>
216
217 <para>
218 which would build matchbox-desktop, then recompile it. The
219 final command reruns all tasks after the compile (basically
220 the packaging tasks) since bitbake will notice that the
221 compile has been rerun and hence the other tasks also need
222 to run again.
223 </para>
224
225 <para>
226 You can view a list of tasks in a given package by running
227 the listtasks task e.g. <command>bitbake matchbox-desktop -c
228 listtasks</command>, and the result is in file ${WORKDIR}/temp/log.do_listtasks.pid.
229 </para>
230 </section>
231
232 <section id='usingpoky-debugging-dependencies'>
233 <title>Dependency Graphs</title>
234
235 <para>
236 Sometimes it can be hard to see why bitbake wants to build
237 some other packages before a given package you've specified.
238 <command>bitbake -g targetname</command> will create
239 <filename>depends.dot</filename> and
240 <filename>task-depends.dot</filename> files in the current
241 directory. They show
242 which packages and tasks depend on which other packages and
243 tasks and are useful for debugging purposes.
244 <command>"bitbake -g -u depexp targetname"</command> will show result
245 in more human-readable GUI style.
246 </para>
247 </section>
248
249 <section id='usingpoky-debugging-bitbake'>
250 <title>General Bitbake Problems</title>
251
252 <para>
253 Debug output from bitbake can be seen with the "-D" option.
254 The debug output gives more information about what bitbake
255 is doing and/or why. Each -D option increases the logging
256 level, the most common usage being "-DDD".
257 </para>
258
259 <para>
260 The output from <command>bitbake -DDD -v targetname</command> can reveal why
261 a certain version of a package might be chosen, why bitbake
262 picked a certain provider or help in other situations where
263 bitbake does something you're not expecting.
264 </para>
265 </section>
266
267 <section id='usingpoky-debugging-buildfile'>
268 <title>Building with no dependencies</title>
269
270 <para>
271 If you really want to build a specific .bb file, you can use
272 the form <command>bitbake -b somepath/somefile.bb</command>. Note that this
273 will not check the dependencies so this option should only
274 be used when you know its dependencies already exist. You
275 can specify fragments of the filename and bitbake will see
276 if it can find a unique match.
277 </para>
278
279 </section>
280
281 <section id='usingpoky-debugging-variables'>
282 <title>Variables</title>
283
284 <para>
285 The "-e" option will dump the resulting environment for
286 either the configuration (no package specified) or for a
287 specific package when specified with the "-b" option.
288 </para>
289 </section>
290
291 <section id='usingpoky-debugging-others'>
292 <title>Other Tips</title>
293
294 <tip>
295 <para>When adding new packages it is worth keeping an eye open for bad
296 things creeping into compiler commandlines such as references to local
297 system files (<filename>/usr/lib/</filename> or <filename>/usr/include/</filename> etc.).
298 </para>
299 </tip>
300
301 <tip>
302 <para>
303 If you want to remove the psplash boot splashscreen, add "psplash=false"
304 to the kernel commandline and psplash won't load allowing you to see
305 the console. It's also possible to switch out of the splashscreen by
306 switching virtual console (Fn+Left or Fn+Right on a Zaurus).
307 </para>
308 </tip>
309
310 </section>
311</section>
312
313</chapter>
314<!--
315vim: expandtab tw=80 ts=4
316-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-16 14:01:48 +0000