summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-12-11 12:24:29 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-01-07 14:43:26 +0000
commit8753c6b2888cbe64760800cba1e55e4ce53309d2 (patch)
tree7b026a799e528737fb5bfed2cc73f61788a00feb /documentation
parentbb8e9d0599bdaef032741078820490385ea6b0c3 (diff)
downloadpoky-8753c6b2888cbe64760800cba1e55e4ce53309d2.tar.gz
Documentation: ref-manual - removing old poky-ref-manual files
Removed the old poky-ref-manuals from the new ref-manual structure. (From yocto-docs rev: b5db4ddea205875ed3acacb90f46efd557337e0d) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/poky-ref-manual/TODO11
-rw-r--r--documentation/poky-ref-manual/examples/hello-autotools/hello_2.3.bb8
-rw-r--r--documentation/poky-ref-manual/examples/hello-single/files/helloworld.c8
-rw-r--r--documentation/poky-ref-manual/examples/hello-single/hello.bb17
-rw-r--r--documentation/poky-ref-manual/examples/libxpm/libxpm_3.5.6.bb14
-rw-r--r--documentation/poky-ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb15
-rw-r--r--documentation/poky-ref-manual/faq.xml606
-rw-r--r--documentation/poky-ref-manual/figures/buildhistory-web.pngbin49966 -> 0 bytes
-rw-r--r--documentation/poky-ref-manual/figures/buildhistory.pngbin42062 -> 0 bytes
-rw-r--r--documentation/poky-ref-manual/figures/poky-title.pngbin11592 -> 0 bytes
-rw-r--r--documentation/poky-ref-manual/introduction.xml322
-rw-r--r--documentation/poky-ref-manual/migration.xml235
-rw-r--r--documentation/poky-ref-manual/poky-ref-manual-customization.xsl6
-rw-r--r--documentation/poky-ref-manual/poky-ref-manual.xml125
-rw-r--r--documentation/poky-ref-manual/ref-bitbake.xml419
-rw-r--r--documentation/poky-ref-manual/ref-classes.xml720
-rw-r--r--documentation/poky-ref-manual/ref-features.xml294
-rw-r--r--documentation/poky-ref-manual/ref-images.xml132
-rw-r--r--documentation/poky-ref-manual/ref-structure.xml709
-rw-r--r--documentation/poky-ref-manual/ref-style.css979
-rw-r--r--documentation/poky-ref-manual/ref-variables.xml3018
-rw-r--r--documentation/poky-ref-manual/ref-varlocality.xml193
-rw-r--r--documentation/poky-ref-manual/resources.xml114
-rw-r--r--documentation/poky-ref-manual/technical-details.xml1011
-rw-r--r--documentation/poky-ref-manual/usingpoky.xml651
25 files changed, 0 insertions, 9607 deletions
diff --git a/documentation/poky-ref-manual/TODO b/documentation/poky-ref-manual/TODO
deleted file mode 100644
index ee0db977cc..0000000000
--- a/documentation/poky-ref-manual/TODO
+++ /dev/null
@@ -1,11 +0,0 @@
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/examples/hello-autotools/hello_2.3.bb b/documentation/poky-ref-manual/examples/hello-autotools/hello_2.3.bb
deleted file mode 100644
index 5dfb0b30cf..0000000000
--- a/documentation/poky-ref-manual/examples/hello-autotools/hello_2.3.bb
+++ /dev/null
@@ -1,8 +0,0 @@
1DESCRIPTION = "GNU Helloworld application"
2SECTION = "examples"
3LICENSE = "GPLv3"
4LIC_FILES_CHKSUM = "file://COPYING;md5=adefda309052235aa5d1e99ce7557010"
5
6SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2"
7
8inherit 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
deleted file mode 100644
index fc7169b7b8..0000000000
--- a/documentation/poky-ref-manual/examples/hello-single/files/helloworld.c
+++ /dev/null
@@ -1,8 +0,0 @@
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
deleted file mode 100644
index 0812743e39..0000000000
--- a/documentation/poky-ref-manual/examples/hello-single/hello.bb
+++ /dev/null
@@ -1,17 +0,0 @@
1DESCRIPTION = "Simple helloworld application"
2SECTION = "examples"
3LICENSE = "MIT"
4LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
5
6SRC_URI = "file://helloworld.c"
7
8S = "${WORKDIR}"
9
10do_compile() {
11 ${CC} helloworld.c -o helloworld
12}
13
14do_install() {
15 install -d ${D}${bindir}
16 install -m 0755 helloworld ${D}${bindir}
17}
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
deleted file mode 100644
index b58d4d7bd1..0000000000
--- a/documentation/poky-ref-manual/examples/libxpm/libxpm_3.5.6.bb
+++ /dev/null
@@ -1,14 +0,0 @@
1require xorg-lib-common.inc
2
3DESCRIPTION = "X11 Pixmap library"
4LICENSE = "X-BSD"
5LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
6DEPENDS += "libxext"
7PR = "r2"
8PE = "1"
9
10XORG_PN = "libXpm"
11
12PACKAGES =+ "sxpm cxpm"
13FILES_cxpm = "${bindir}/cxpm"
14FILES_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
deleted file mode 100644
index 5d05a437a4..0000000000
--- a/documentation/poky-ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb
+++ /dev/null
@@ -1,15 +0,0 @@
1DESCRIPTION = "Tools for managing memory technology devices."
2SECTION = "base"
3DEPENDS = "zlib"
4HOMEPAGE = "http://www.linux-mtd.infradead.org/"
5LICENSE = "GPLv2"
6LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
7 file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
8
9SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz"
10
11CFLAGS_prepend = "-I ${S}/include "
12
13do_install() {
14 oe_runmake install DESTDIR=${D}
15}
diff --git a/documentation/poky-ref-manual/faq.xml b/documentation/poky-ref-manual/faq.xml
deleted file mode 100644
index 176573de28..0000000000
--- a/documentation/poky-ref-manual/faq.xml
+++ /dev/null
@@ -1,606 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='faq'>
6<title>FAQ</title>
7<qandaset>
8 <qandaentry>
9 <question>
10 <para>
11 How does Poky differ from <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>?
12 </para>
13 </question>
14 <answer>
15 <para>
16 The term "Poky" refers to the specific reference build system that
17 the Yocto Project provides.
18 Poky is based on <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink>
19 and BitBake.
20 Thus, the generic term used here for the build system is
21 the "OpenEmbedded build system."
22 Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
23 changes always being merged to OE-Core or BitBake first before being pulled back
24 into Poky.
25 This practice benefits both projects immediately.
26 For a fuller description of the term "Poky", see the
27 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>poky</ulink> term in the Yocto Project
28 Development Manual.
29 </para>
30 </answer>
31 </qandaentry>
32
33 <qandaentry>
34 <question>
35 <para>
36 I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7.
37 Can I still use the Yocto Project?
38 </para>
39 </question>
40 <answer>
41 <para>
42 You can use a stand-alone tarball to provide Python 2.6.
43 You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations:
44 <itemizedlist>
45 <listitem><para><ulink url='&YOCTO_PYTHON-i686_DL_URL;'>32-bit tarball</ulink></para></listitem>
46 <listitem><para><ulink url='&YOCTO_PYTHON-x86_64_DL_URL;'>64-bit tarball</ulink></para></listitem>
47 </itemizedlist>
48 </para>
49 <para>
50 These tarballs are self-contained with all required libraries and should work
51 on most Linux systems.
52 To use the tarballs extract them into the root
53 directory and run the appropriate command:
54 <literallayout class='monospaced'>
55 $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH
56 $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH
57 </literallayout>
58 </para>
59 <para>
60 Once you run the command, BitBake uses Python 2.6.
61 </para>
62 </answer>
63 </qandaentry>
64
65 <qandaentry>
66 <question>
67 <para>
68 How can you claim Poky / OpenEmbedded-Core is stable?
69 </para>
70 </question>
71 <answer>
72 <para>
73 There are three areas that help with stability;
74 <itemizedlist>
75 <listitem><para>The Yocto Project team keeps
76 <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink> small
77 and focused, containing around 830 recipes as opposed to the thousands
78 available in other OpenEmbedded community layers.
79 Keeping it small makes it easy to test and maintain.</para></listitem>
80 <listitem><para>The Yocto Project team runs manual and automated tests
81 using a small, fixed set of reference hardware as well as emulated
82 targets.</para></listitem>
83 <listitem><para>The Yocto Project uses an an autobuilder,
84 which provides continuous build and integration tests.</para></listitem>
85 </itemizedlist>
86 </para>
87 </answer>
88 </qandaentry>
89
90 <qandaentry>
91 <question>
92 <para>
93 How do I get support for my board added to the Yocto Project?
94 </para>
95 </question>
96 <answer>
97 <para>
98 Support for an additional board is added by creating a BSP layer for it.
99 For more information on how to create a BSP layer, see the
100 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
101 </para>
102 <para>
103 Usually, if the board is not completely exotic, adding support in
104 the Yocto Project is fairly straightforward.
105 </para>
106 </answer>
107 </qandaentry>
108
109 <qandaentry>
110 <question>
111 <para>
112 Are there any products built using the OpenEmbedded build system?
113 </para>
114 </question>
115 <answer>
116 <para>
117 The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink>
118 is built using the OpenEmbedded build system.
119 See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink>
120 website for more information.
121 There are a number of pre-production devices using the OpenEmbedded build system
122 and the Yocto Project team
123 announces them as soon as they are released.
124 </para>
125 </answer>
126 </qandaentry>
127
128 <qandaentry>
129 <question>
130 <para>
131 What does the OpenEmbedded build system produce as output?
132 </para>
133 </question>
134 <answer>
135 <para>
136 Because the same set of recipes can be used to create output of various formats, the
137 output of an OpenEmbedded build depends on how it was started.
138 Usually, the output is a flashable image ready for the target device.
139 </para>
140 </answer>
141 </qandaentry>
142
143 <qandaentry>
144 <question>
145 <para>
146 How do I add my package to the Yocto Project?
147 </para>
148 </question>
149 <answer>
150 <para>
151 To add a package, you need to create a BitBake recipe.
152 For information on how to add a package, see the section
153 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg'>Adding a Package</ulink>"
154 in the Yocto Project Development Manual.
155 </para>
156 </answer>
157 </qandaentry>
158
159 <qandaentry>
160 <question>
161 <para>
162 Do I have to reflash my entire board with a new Yocto Project image when recompiling
163 a package?
164 </para>
165 </question>
166 <answer>
167 <para>
168 The OpenEmbedded build system can build packages in various formats such as
169 <filename>ipk</filename> for <filename>opkg</filename>,
170 Debian package (<filename>.deb</filename>), or RPM.
171 The packages can then be upgraded using the package tools on the device, much like
172 on a desktop distribution such as Ubuntu or Fedora.
173 </para>
174 </answer>
175 </qandaentry>
176
177 <qandaentry>
178 <question>
179 <para>
180 What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
181 </para>
182 </question>
183 <answer>
184 <para>
185 GNOME Mobile is a subset of the <ulink url='http://www.gnome.org'>GNOME</ulink>
186 platform targeted at mobile and embedded devices.
187 The the main difference between GNOME Mobile and standard GNOME is that
188 desktop-orientated libraries have been removed, along with deprecated libraries,
189 creating a much smaller footprint.
190 </para>
191 </answer>
192 </qandaentry>
193
194 <qandaentry>
195 <question>
196 <para>
197 I see the error '<filename>chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</filename>'.
198 What is wrong?
199 </para>
200 </question>
201 <answer>
202 <para>
203 You are probably running the build on an NTFS filesystem.
204 Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead.
205 </para>
206 </answer>
207 </qandaentry>
208
209 <qandaentry>
210 <question>
211 <para>
212 How do I make the Yocto Project work in RHEL/CentOS?
213 </para>
214 </question>
215 <answer>
216 <para>
217 To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
218 install some required packages.
219 The standard CentOS packages needed are:
220 <itemizedlist>
221 <listitem><para>"Development tools" (selected during installation)</para></listitem>
222 <listitem><para><filename>texi2html</filename></para></listitem>
223 <listitem><para><filename>compat-gcc-34</filename></para></listitem>
224 </itemizedlist>
225 On top of these, you need the following external packages:
226 <itemizedlist>
227 <listitem><para><filename>python-sqlite2</filename> from
228 <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink>
229 </para></listitem>
230 <listitem><para><filename>help2man</filename> from
231 <ulink url='http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html'>Karan repository</ulink></para></listitem>
232 </itemizedlist>
233 </para>
234
235 <para>
236 Once these packages are installed, the OpenEmbedded build system will be able
237 to build standard images.
238 However, there might be a problem with the QEMU emulator segfaulting.
239 You can either disable the generation of binary locales by setting
240 <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
241 </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename>
242 from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
243 </para>
244 </answer>
245 </qandaentry>
246
247 <qandaentry>
248 <question>
249 <para>
250 I see lots of 404 responses for files on
251 <filename>http://www.yoctoproject.org/sources/*</filename>. Is something wrong?
252 </para>
253 </question>
254 <answer>
255 <para>
256 Nothing is wrong.
257 The OpenEmbedded build system checks any configured source mirrors before downloading
258 from the upstream sources.
259 The build system does this searching for both source archives and
260 pre-checked out versions of SCM managed software.
261 These checks help in large installations because it can reduce load on the SCM servers
262 themselves.
263 The address above is one of the default mirrors configured into the
264 build system.
265 Consequently, if an upstream source disappears, the team
266 can place sources there so builds continue to work.
267 </para>
268 </answer>
269 </qandaentry>
270
271 <qandaentry>
272 <question>
273 <para>
274 I have machine-specific data in a package for one machine only but the package is
275 being marked as machine-specific in all cases, how do I prevent this?
276 </para>
277 </question>
278 <answer>
279 <para>
280 Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
281 </filename> = "0" in the <filename>.bb</filename> file but make sure the package is
282 manually marked as
283 machine-specific in the case that needs it.
284 The code that handles <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in <filename>base.bbclass</filename>.
285 </para>
286 </answer>
287 </qandaentry>
288
289 <qandaentry>
290 <question>
291 <para>
292 I'm behind a firewall and need to use a proxy server. How do I do that?
293 </para>
294 </question>
295 <answer>
296 <para>
297 Most source fetching by the OpenEmbedded build system is done by <filename>wget</filename>
298 and you therefore need to specify the proxy settings in a
299 <filename>.wgetrc</filename> file in your home directory.
300 Example settings in that file would be
301 <literallayout class='monospaced'>
302 http_proxy = http://proxy.yoyodyne.com:18023/
303 ftp_proxy = http://proxy.yoyodyne.com:18023/
304 </literallayout>
305 The Yocto Project also includes a <filename>site.conf.sample</filename>
306 file that shows how to configure CVS and Git proxy servers
307 if needed.
308 </para>
309 </answer>
310 </qandaentry>
311
312 <qandaentry>
313 <question>
314 <para>
315 What’s the difference between <filename>foo</filename> and <filename>foo-native</filename>?
316 </para>
317 </question>
318 <answer>
319 <para>
320 The <filename>*-native</filename> targets are designed to run on the system
321 being used for the build.
322 These are usually tools that are needed to assist the build in some way such as
323 <filename>quilt-native</filename>, which is used to apply patches.
324 The non-native version is the one that runs on the target device.
325 </para>
326 </answer>
327 </qandaentry>
328
329 <qandaentry>
330 <question>
331 <para>
332 I'm seeing random build failures. Help?!
333 </para>
334 </question>
335 <answer>
336 <para>
337 If the same build is failing in totally different and random ways,
338 the most likely explanation is that either the hardware you're running the
339 build on has some problem, or, if you are running the build under virtualisation,
340 the virtualisation probably has bugs.
341 The OpenEmbedded build system processes a massive amount of data causing lots of network, disk and
342 CPU activity and is sensitive to even single bit failures in any of these areas.
343 True random failures have always been traced back to hardware or virtualisation issues.
344 </para>
345 </answer>
346 </qandaentry>
347
348 <qandaentry>
349 <question>
350 <para>
351 What do we need to ship for license compliance?
352 </para>
353 </question>
354 <answer>
355 <para>
356 This is a difficult question and you need to consult your lawyer for the answer
357 for your specific case.
358 It is worth bearing in mind that for GPL compliance there needs to be enough
359 information shipped to allow someone else to rebuild the same end result
360 you are shipping.
361 This means sharing the source code, any patches applied to it, and also any
362 configuration information about how that package was configured and built.
363 </para>
364 </answer>
365 </qandaentry>
366
367 <qandaentry>
368 <question>
369 <para>
370 How do I disable the cursor on my touchscreen device?
371 </para>
372 </question>
373 <answer>
374 <para>
375 You need to create a form factor file as described in the
376 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous Recipe Files</ulink>"
377 section and set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to one as follows:
378 <literallayout class='monospaced'>
379 HAVE_TOUCHSCREEN=1
380 </literallayout>
381 </para>
382 </answer>
383 </qandaentry>
384
385 <qandaentry>
386 <question>
387 <para>
388 How do I make sure connected network interfaces are brought up by default?
389 </para>
390 </question>
391 <answer>
392 <para>
393 The default interfaces file provided by the netbase recipe does not
394 automatically bring up network interfaces.
395 Therefore, you will need to add a BSP-specific netbase that includes an interfaces
396 file.
397 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous Recipe Files</ulink>"
398 section for information on creating these types of miscellaneous recipe files.
399 </para>
400 <para>
401 For example, add the following files to your layer:
402 <literallayout class='monospaced'>
403 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
404 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
405 </literallayout>
406 </para>
407 </answer>
408 </qandaentry>
409
410 <qandaentry>
411 <question>
412 <para>
413 How do I create images with more free space?
414 </para>
415 </question>
416 <answer>
417 <para>
418 Images are created to be 1.2 times the size of the populated root filesystem.
419 To modify this ratio so that there is more free space available, you need to
420 set the configuration value <filename>IMAGE_OVERHEAD_FACTOR</filename>.
421 For example, setting <filename>IMAGE_OVERHEAD_FACTOR</filename> to 1.5 sets
422 the image size ratio to one and a half times the size of the populated
423 root filesystem.
424 <literallayout class='monospaced'>
425 IMAGE_OVERHEAD_FACTOR = "1.5"
426 </literallayout>
427 </para>
428 </answer>
429 </qandaentry>
430
431 <qandaentry>
432 <question>
433 <para>
434 Why don't you support directories with spaces in the pathnames?
435 </para>
436 </question>
437 <answer>
438 <para>
439 The Yocto Project team has tried to do this before but too many of the tools
440 the OpenEmbedded build system depends on such as <filename>autoconf</filename>
441 break when they find spaces in pathnames.
442 Until that situation changes, the team will not support spaces in pathnames.
443 </para>
444 </answer>
445 </qandaentry>
446
447 <qandaentry>
448 <question>
449 <para>
450 How do I use an external toolchain?
451 </para>
452 </question>
453 <answer>
454 <para>
455 The toolchain configuration is very flexible and customizable.
456 It is primarily controlled with the
457 <filename><link linkend='var-TCMODE'>TCMODE</link></filename> variable.
458 This variable controls which <filename>tcmode-*.inc</filename> file to include
459 from the <filename>meta/conf/distro/include</filename> directory within the
460 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>.
461 </para>
462
463 <para>
464 The default value of <filename>TCMODE</filename> is "default"
465 (i.e. <filename>tcmode-default.inc</filename>).
466 However, other patterns are accepted.
467 In particular, "external-*" refers to external toolchains of which there are some
468 basic examples included in the OpenEmbedded Core (<filename>meta</filename>).
469 You can use your own custom toolchain definition in your own layer
470 (or as defined in the <filename>local.conf</filename> file) at the location
471 <filename>conf/distro/include/tcmode-*.inc</filename>.
472 </para>
473
474 <para>
475 In addition to the toolchain configuration, you also need a corresponding toolchain recipe file.
476 This recipe file needs to package up any pre-built objects in the toolchain such as
477 <filename>libgcc</filename>, <filename>libstdcc++</filename>,
478 any locales, and <filename>libc</filename>.
479 An example is the <filename>external-sourcery-toolchain.bb</filename>, which is located
480 in <filename>meta/recipes-core/meta/</filename> within the source directory.
481 </para>
482 </answer>
483 </qandaentry>
484
485 <qandaentry>
486 <question>
487 <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>
488 How does the OpenEmbedded build system obtain source code and will it work behind my
489 firewall or proxy server?
490 </para>
491 </question>
492 <answer>
493 <para>
494 The way the build system obtains source code is highly configurable.
495 You can setup the build system to get source code in most environments if
496 HTTP transport is available.
497 </para>
498 <para>
499 When the build system searches for source code, it first tries the local download directory.
500 If that location fails, Poky tries PREMIRRORS, the upstream source,
501 and then MIRRORS in that order.
502 </para>
503 <para>
504 By default, the OpenEmbedded build system uses the Yocto Project source PREMIRRORS
505 for SCM-based sources,
506 upstreams for normal tarballs, and then falls back to a number of other mirrors
507 including the Yocto Project source mirror if those fail.
508 </para>
509 <para>
510 As an example, you could add a specific server for Poky to attempt before any
511 others by adding something like the following to the <filename>local.conf</filename>
512 configuration file:
513 <literallayout class='monospaced'>
514 PREMIRRORS_prepend = "\
515 git://.*/.* http://www.yoctoproject.org/sources/ \n \
516 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
517 http://.*/.* http://www.yoctoproject.org/sources/ \n \
518 https://.*/.* http://www.yoctoproject.org/sources/ \n"
519 </literallayout>
520 </para>
521 <para>
522 These changes cause Poky to intercept Git, FTP, HTTP, and HTTPS
523 requests and direct them to the <filename>http://</filename> sources mirror.
524 You can use <filename>file://</filename> URLs to point to local directories
525 or network shares as well.
526 </para>
527 <para>
528 Aside from the previous technique, these options also exist:
529 <literallayout class='monospaced'>
530 BB_NO_NETWORK = "1"
531 </literallayout>
532 This statement tells BitBake to throw an error instead of trying to access the
533 Internet.
534 This technique is useful if you want to ensure code builds only from local sources.
535 </para>
536 <para>
537 Here is another technique:
538 <literallayout class='monospaced'>
539 BB_FETCH_PREMIRRORONLY = "1"
540 </literallayout>
541 This statement limits Poky to pulling source from the PREMIRRORS only.
542 Again, this technique is useful for reproducing builds.
543 </para>
544 <para>
545 Here is another technique:
546 <literallayout class='monospaced'>
547 BB_GENERATE_MIRROR_TARBALLS = "1"
548 </literallayout>
549 This statement tells Poky to generate mirror tarballs.
550 This technique is useful if you want to create a mirror server.
551 If not, however, the technique can simply waste time during the build.
552 </para>
553 <para>
554 Finally, consider an example where you are behind an HTTP-only firewall.
555 You could make the following changes to the <filename>local.conf</filename>
556 configuration file as long as the PREMIRROR server is up to date:
557 <literallayout class='monospaced'>
558 PREMIRRORS_prepend = "\
559 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
560 http://.*/.* http://www.yoctoproject.org/sources/ \n \
561 https://.*/.* http://www.yoctoproject.org/sources/ \n"
562 BB_FETCH_PREMIRRORONLY = "1"
563 </literallayout>
564 These changes would cause Poky to successfully fetch source over HTTP and
565 any network accesses to anything other than the PREMIRROR would fail.
566 </para>
567 <para>
568 The build system also honors the standard shell environment variables
569 <filename>http_proxy</filename>, <filename>ftp_proxy</filename>,
570 <filename>https_proxy</filename>, and <filename>all_proxy</filename>
571 to redirect requests through proxy servers.
572 </para>
573 </answer>
574 </qandaentry>
575
576 <qandaentry>
577 <question>
578 <para>
579 Can I get rid of build output so I can start over?
580 </para>
581 </question>
582 <answer>
583 <para>
584 Yes - you can easily do this.
585 When you use BitBake to build an image, all the build output goes into the
586 directory created when you source the <filename>oe-init-build-env</filename>
587 setup file.
588 By default, this <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>
589 is named <filename>build</filename> but can be named
590 anything you want.
591 </para>
592
593 <para>
594 Within the build directory is the <filename>tmp</filename> directory.
595 To remove all the build output yet preserve any source code or downloaded files
596 from previous builds, simply remove the <filename>tmp</filename> directory.
597 </para>
598 </answer>
599 </qandaentry>
600
601
602</qandaset>
603</chapter>
604<!--
605vim: expandtab tw=80 ts=4
606-->
diff --git a/documentation/poky-ref-manual/figures/buildhistory-web.png b/documentation/poky-ref-manual/figures/buildhistory-web.png
deleted file mode 100644
index f6db86c977..0000000000
--- a/documentation/poky-ref-manual/figures/buildhistory-web.png
+++ /dev/null
Binary files differ
diff --git a/documentation/poky-ref-manual/figures/buildhistory.png b/documentation/poky-ref-manual/figures/buildhistory.png
deleted file mode 100644
index 614b8ee2e4..0000000000
--- a/documentation/poky-ref-manual/figures/buildhistory.png
+++ /dev/null
Binary files differ
diff --git a/documentation/poky-ref-manual/figures/poky-title.png b/documentation/poky-ref-manual/figures/poky-title.png
deleted file mode 100644
index 2893d84620..0000000000
--- a/documentation/poky-ref-manual/figures/poky-title.png
+++ /dev/null
Binary files differ
diff --git a/documentation/poky-ref-manual/introduction.xml b/documentation/poky-ref-manual/introduction.xml
deleted file mode 100644
index 38c58da262..0000000000
--- a/documentation/poky-ref-manual/introduction.xml
+++ /dev/null
@@ -1,322 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='intro'>
6<title>Introduction</title>
7
8<section id='intro-welcome'>
9 <title>Introduction</title>
10
11 <para>
12 This manual provides reference information for the current release of the Yocto Project.
13 The Yocto Project is an open-source collaboration project focused on embedded Linux
14 developers.
15 Amongst other things, the Yocto Project uses the OpenEmbedded build system, which
16 is based on the Poky project, to construct complete Linux images.
17 You can find complete introductory and getting started information on the Yocto Project
18 by reading the
19 <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
20 For task-based information using the Yocto Project, see the
21 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>.
22 You can also find lots of information on the Yocto Project on the
23 <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.
24 </para>
25</section>
26
27<section id='intro-manualoverview'>
28 <title>Documentation Overview</title>
29 <para>
30 This reference manual consists of the following:
31 <itemizedlist>
32 <listitem><para><emphasis>
33 <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis> This chapter
34 provides an overview of the components that make up the Yocto Project
35 followed by information about debugging images created in the Yocto Project.
36 </para></listitem>
37 <listitem><para><emphasis>
38 <link linkend='technical-details'>Technical Details</link>:</emphasis>
39 This chapter describes fundamental Yocto Project components as well as an explanation
40 behind how the Yocto Project uses shared state (sstate) cache to speed build time.
41 </para></listitem>
42 <listitem><para><emphasis>
43 <link linkend='ref-structure'>Directory Structure</link>:</emphasis>
44 This chapter describes the
45 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink> created
46 either by unpacking a released Yocto Project tarball on your host development system,
47 or by cloning the upstream
48 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
49 </para></listitem>
50 <listitem><para><emphasis>
51 <link linkend='ref-bitbake'>BitBake</link>:</emphasis>
52 This chapter provides an overview of the BitBake tool and its role within
53 the Yocto Project.</para></listitem>
54 <listitem><para><emphasis>
55 <link linkend='ref-classes'>Classes</link>:</emphasis>
56 This chapter describes the classes used in the Yocto Project.</para></listitem>
57 <listitem><para><emphasis>
58 <link linkend='ref-images'>Images</link>:</emphasis>
59 This chapter describes the standard images that the Yocto Project supports.
60 </para></listitem>
61 <listitem><para><emphasis>
62 <link linkend='ref-features'>Features</link>:</emphasis>
63 This chapter describes mechanisms for creating distribution, machine, and image
64 features during the build process using the OpenEmbedded build system.</para></listitem>
65 <listitem><para><emphasis>
66 <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis>
67 This chapter presents most variables used by the OpenEmbedded build system, which
68 using BitBake.
69 Entries describe the function of the variable and how to apply them.
70 </para></listitem>
71 <listitem><para><emphasis>
72 <link linkend='ref-varlocality'>Variable Context</link>:</emphasis>
73 This chapter provides variable locality or context.</para></listitem>
74 <listitem><para><emphasis>
75 <link linkend='faq'>FAQ</link>:</emphasis>
76 This chapter provides answers for commonly asked questions in the Yocto Project
77 development environment.</para></listitem>
78 <listitem><para><emphasis>
79 <link linkend='resources'>Contributing to the Yocto Project</link>:</emphasis>
80 This chapter provides guidance on how you can contribute back to the Yocto
81 Project.</para></listitem>
82 </itemizedlist>
83 </para>
84</section>
85
86
87<section id='intro-requirements'>
88<title>System Requirements</title>
89 <para>
90 For general Yocto Project system requirements, see the
91 "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" section
92 in the Yocto Project Quick Start.
93 The remainder of this section provides details on system requirements
94 not covered in the Yocto Project Quick Start.
95 </para>
96
97 <section id='detailed-supported-distros'>
98 <title>Supported Linux Distributions</title>
99
100 <para>
101 Currently, the Yocto Project is supported on the following distributions:
102 <itemizedlist>
103 <listitem><para>Ubuntu 10.04.4 LTS</para></listitem>
104 <listitem><para>Ubuntu 11.10</para></listitem>
105 <listitem><para>Ubuntu 12.04.1 LTS</para></listitem>
106 <listitem><para>Ubuntu 12.04.1 LTS</para></listitem>
107 <listitem><para>Ubuntu 12.10</para></listitem>
108 <listitem><para>Fedora release 16 (Verne)</para></listitem>
109 <listitem><para>Fedora release 17 (Beefy Miracle)</para></listitem>
110 <listitem><para>Fedora release 18 (Spherical Cow)</para></listitem>
111 <listitem><para>CentOS release 5.6 (Final)</para></listitem>
112 <listitem><para>CentOS release 5.7 (Final)</para></listitem>
113 <listitem><para>CentOS release 5.8 (Final)</para></listitem>
114 <listitem><para>CentOS release 6.3 (Final)</para></listitem>
115 <listitem><para>Debian GNU/Linux 6.0.6 (squeeze)</para></listitem>
116 <listitem><para>openSUSE 11.4</para></listitem>
117 <listitem><para>openSUSE 12.1</para></listitem>
118 <listitem><para>openSUSE 12.2</para></listitem>
119 </itemizedlist>
120 </para>
121
122 <note>
123 For additional information on distributions that support the
124 Yocto Project, see the
125 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink> wiki page.
126 </note>
127 </section>
128
129 <section id='required-packages-for-the-host-development-system'>
130 <title>Required Packages for the Host Development System</title>
131
132 <para>
133 The list of packages you need on the host development system can
134 be large when covering all build scenarios using the Yocto Project.
135 This section provides required packages by Linux distribution and
136 further categorized by function.
137 </para>
138
139 <section id='ubuntu-packages'>
140 <title>Ubuntu</title>
141
142 <para>
143 The following list shows the required packages by function
144 given a supported Ubuntu Linux distribution:
145 <itemizedlist>
146 <listitem><para><emphasis>Essentials:</emphasis>
147 Packages needed to build an image on a headless
148 system:
149 <literallayout class='monospaced'>
150 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
151 </literallayout></para></listitem>
152 <listitem><para><emphasis>Graphical Extras:</emphasis>
153 Packages recommended if the host system has graphics support:
154 <literallayout class='monospaced'>
155 $ sudo apt-get install libsdl1.2-dev xterm
156 </literallayout></para></listitem>
157 <listitem><para><emphasis>Documentation:</emphasis>
158 Packages needed if you are going to build out the
159 Yocto Project documentation manuals:
160 <literallayout class='monospaced'>
161 $ sudo apt-get install make xsltproc docbook-utils fop
162 </literallayout></para></listitem>
163 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
164 Packages needed if you are going to be using the
165 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
166 <literallayout class='monospaced'>
167 $ sudo apt-get install autoconf automake libtool libglib2.0-dev
168 </literallayout></para></listitem>
169 </itemizedlist>
170 </para>
171 </section>
172
173 <section id='fedora-packages'>
174 <title>Fedora Packages</title>
175
176 <para>
177 The following list shows the required packages by function
178 given a supported Fedora Linux distribution:
179 <itemizedlist>
180 <listitem><para><emphasis>Essentials:</emphasis>
181 Packages needed to build an image for a headless
182 system:
183 <literallayout class='monospaced'>
184 $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL;
185 </literallayout></para></listitem>
186 <listitem><para><emphasis>Graphical Extras:</emphasis>
187 Packages recommended if the host system has graphics support:
188 <literallayout class='monospaced'>
189 $ sudo yum install SDL-devel xterm
190 </literallayout></para></listitem>
191 <listitem><para><emphasis>Documentation:</emphasis>
192 Packages needed if you are going to build out the
193 Yocto Project documentation manuals:
194 <literallayout class='monospaced'>
195 $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
196 docbook-dtds docbook-utils fop libxslt
197 </literallayout></para></listitem>
198 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
199 Packages needed if you are going to be using the
200 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
201 <literallayout class='monospaced'>
202 $ sudo yum install autoconf automake libtool glib2-devel
203 </literallayout></para></listitem>
204 </itemizedlist>
205 </para>
206 </section>
207
208 <section id='opensuse-packages'>
209 <title>OpenSUSE Packages</title>
210
211 <para>
212 The following list shows the required packages by function
213 given a supported OpenSUSE Linux distribution:
214 <itemizedlist>
215 <listitem><para><emphasis>Essentials:</emphasis>
216 Packages needed to build an image for a headless
217 system:
218 <literallayout class='monospaced'>
219 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
220 </literallayout></para></listitem>
221 <listitem><para><emphasis>Graphical Extras:</emphasis>
222 Packages recommended if the host system has graphics support:
223 <literallayout class='monospaced'>
224 $ sudo zypper install libSDL-devel xterm
225 </literallayout></para></listitem>
226 <listitem><para><emphasis>Documentation:</emphasis>
227 Packages needed if you are going to build out the
228 Yocto Project documentation manuals:
229 <literallayout class='monospaced'>
230 $ sudo zypper install make fop xsltproc
231 </literallayout></para></listitem>
232 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
233 Packages needed if you are going to be using the
234 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
235 <literallayout class='monospaced'>
236 $ sudo zypper install autoconf automake libtool glib2-devel
237 </literallayout></para></listitem>
238 </itemizedlist>
239 </para>
240 </section>
241
242 <section id='centos-packages'>
243 <title>CentOS Packages</title>
244
245 <para>
246 The following list shows the required packages by function
247 given a supported CentOS Linux distribution:
248 <itemizedlist>
249 <listitem><para><emphasis>Essentials:</emphasis>
250 Packages needed to build an image for a headless
251 system:
252 <literallayout class='monospaced'>
253 $ sudo yum -y install &CENTOS_HOST_PACKAGES_ESSENTIAL;
254 </literallayout></para></listitem>
255 <listitem><para><emphasis>Graphical Extras:</emphasis>
256 Packages recommended if the host system has graphics support:
257 <literallayout class='monospaced'>
258 $ sudo yum -y install SDL-devel xterm
259 </literallayout></para></listitem>
260 <listitem><para><emphasis>Documentation:</emphasis>
261 Packages needed if you are going to build out the
262 Yocto Project documentation manuals:
263 <literallayout class='monospaced'>
264 $ sudo yum -y install make docbook-style-dsssl docbook-style-xsl \
265 docbook-dtds docbook-utils fop libxslt
266 </literallayout></para></listitem>
267 <listitem><para><emphasis>ADT Installer Extras:</emphasis>
268 Packages needed if you are going to be using the
269 <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
270 <literallayout class='monospaced'>
271 $ sudo yum -y install autoconf automake libtool glib2-devel
272 </literallayout></para></listitem>
273 </itemizedlist>
274 <note>Depending on the CentOS version you are using, other requirements
275 and dependencies might exist.
276 For details, you should look at the CentOS sections on the
277 <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink>
278 wiki page.</note>
279 </para>
280 </section>
281 </section>
282</section>
283
284<section id='intro-getit'>
285 <title>Obtaining the Yocto Project</title>
286 <para>
287 The Yocto Project development team makes the Yocto Project available through a number
288 of methods:
289 <itemizedlist>
290 <listitem><para><emphasis>Releases:</emphasis> Stable, tested releases are available through
291 <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem>
292 <listitem><para><emphasis>Nightly Builds:</emphasis> These releases are available at
293 <ulink url='http://autobuilder.yoctoproject.org/nightly'/>.
294 These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and
295 experimental builds.</para></listitem>
296 <listitem><para><emphasis>Yocto Project Website:</emphasis> You can find releases
297 of the Yocto Project and supported BSPs at the
298 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
299 Along with these downloads, you can find lots of other information at this site.
300 </para></listitem>
301 </itemizedlist>
302 </para>
303</section>
304
305<section id='intro-getit-dev'>
306 <title>Development Checkouts</title>
307 <para>
308 Development using the Yocto Project requires a local
309 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
310 You can set up the source directory by downloading a Yocto Project release tarball and unpacking it,
311 or by cloning a copy of the upstream
312 <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
313 For information on both these methods, see the
314 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Setup</ulink>"
315 section in the Yocto Project Development Manual.
316 </para>
317</section>
318
319</chapter>
320<!--
321vim: expandtab tw=80 ts=4
322-->
diff --git a/documentation/poky-ref-manual/migration.xml b/documentation/poky-ref-manual/migration.xml
deleted file mode 100644
index 40c570f8ca..0000000000
--- a/documentation/poky-ref-manual/migration.xml
+++ /dev/null
@@ -1,235 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='migration'>
6<title>Migrating to a Newer Yocto Project Release</title>
7
8 <para>
9 This chapter provides information you can use to migrate work to a
10 newer Yocto Project release. You can find the same information in the
11 release notes for a given release.
12 </para>
13
14<section id='moving-to-the-yocto-project-1.3-release'>
15 <title>Moving to the Yocto Project 1.3 Release</title>
16
17 <para>
18 This section provides migration information for moving to the
19 Yocto Project 1.3 Release.
20 </para>
21
22 <section id='1.3-local-configuration'>
23 <title>Local Configuration</title>
24
25 <para>
26 Differences include changes for
27 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
28 and <filename>bblayers.conf</filename>.
29 </para>
30
31 <section id='migration-1.3-sstate-mirrors'>
32 <title>SSTATE_MIRRORS</title>
33
34 <para>
35 The shared state cache (sstate-cache) as pointed to by
36 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> by default
37 now has two-character subdirectories to prevent there being an issue with too
38 many files in the same directory.
39 Also, native sstate-cache packages will go into a subdirectory named using
40 the distro ID string.
41 If you copy the newly structured sstate-cache to a mirror location
42 (either local or remote) and then point to it in
43 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>,
44 you need to append "PATH" to the end of the mirror URL so that
45 the path used by BitBake before the mirror substitution is
46 appended to the path used to access the mirror.
47 Here is an example:
48 <literallayout class='monospaced'>
49 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
50 </literallayout>
51 </para>
52 </section>
53
54 <section id='migration-1.3-bblayers-conf'>
55 <title>bblayers.conf</title>
56
57 <para>
58 The <filename>meta-yocto</filename> layer has been split into
59 two parts: <filename>meta-yocto</filename> and
60 <filename>meta-yocto-bsp</filename>, corresponding to the
61 Poky reference distro configuration and the reference
62 hardware Board Support Packages (BSPs), respectively.
63 When running BitBake or Hob for the first time after upgrading,
64 your <filename>conf/bblayers.conf</filename> file will be
65 updated to handle this change and you will be asked to
66 re-run/restart for the changes to take effect.
67 </para>
68 </section>
69 </section>
70
71 <section id='1.3-recipes'>
72 <title>Recipes</title>
73
74 <para>
75 Differences include changes for the following:
76 <itemizedlist>
77 <listitem><para>Python function whitespace</para></listitem>
78 <listitem><para><filename>proto=</filename> in <filename>SRC_URI</filename></para></listitem>
79 <listitem><para><filename>nativesdk</filename></para></listitem>
80 <listitem><para>Task recipes</para></listitem>
81 <listitem><para><filename>IMAGE_FEATURES</filename></para></listitem>
82 <listitem><para>Removed recipes</para></listitem>
83 </itemizedlist>
84 </para>
85
86 <section id='migration-1.3-python-function-whitespace'>
87 <title>Python Function Whitespace</title>
88
89 <para>
90 All Python functions must now use four spaces for indentation.
91 Previously, an inconsistent mix of spaces and tabs existed,
92 which made extending these functions using
93 <filename>_append</filename> or <filename>_prepend</filename>
94 complicated given that Python treats whitespace as
95 syntactically significant.
96 If you are defining or extending any Python functions (e.g.
97 <filename>populate_packages</filename>, <filename>do_unpack</filename>,
98 <filename>do_patch</filename> and so forth) in custom recipes
99 or classes, you need to ensure you are using consistent
100 four-space indentation.
101 </para>
102 </section>
103
104 <section id='migration-1.3-proto=-in-src-uri'>
105 <title>proto= in SRC_URI</title>
106
107 <para>
108 Any use of <filename>proto=</filename> in
109 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
110 needs to be changed to <filename>protocol=</filename>.
111 In particular, this applies to the following URIs:
112 <itemizedlist>
113 <listitem><para><filename>svn://</filename></para></listitem>
114 <listitem><para><filename>bzr://</filename></para></listitem>
115 <listitem><para><filename>hg://</filename></para></listitem>
116 <listitem><para><filename>osc://</filename></para></listitem>
117 </itemizedlist>
118 Other URIs were already using <filename>protocol=</filename>.
119 This change improves consistency.
120 </para>
121 </section>
122
123 <section id='migration-1.3-nativesdk'>
124 <title>nativesdk</title>
125
126 <para>
127 The suffix <filename>nativesdk</filename> is now implemented
128 as a prefix, which simplifies a lot of the packaging code for
129 <filename>nativesdk</filename> recipes.
130 All custom <filename>nativesdk</filename> recipes and any
131 references need to be updated to use
132 <filename>nativesdk-*</filename> instead of
133 <filename>*-nativesdk</filename>.
134 </para>
135 </section>
136
137 <section id='migration-1.3-task-recipes'>
138 <title>Task Recipes</title>
139
140 <para>
141 "Task" recipes are now known as "Package groups" and have
142 been renamed from <filename>task-*.bb</filename> to
143 <filename>packagegroup-*.bb</filename>.
144 Existing references to the previous <filename>task-*</filename>
145 names should work in most cases as there is an automatic
146 upgrade path for most packages.
147 However, you should update references in your own recipes and
148 configurations as they could be removed in future releases.
149 You should also rename any custom <filename>task-*</filename>
150 recipes to <filename>packagegroup-*</filename>, and change
151 them to inherit <filename>packagegroup</filename> instead of
152 <filename>task</filename>, as well as taking the opportunity
153 to remove anything now handled by
154 <filename>packagegroup.bbclass</filename>, such as providing
155 <filename>-dev</filename> and <filename>-dbg</filename>
156 packages, setting
157 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>,
158 and so forth.
159 See the
160 "<link linkend='ref-classes-packagegroup'>Package Groups - packagegroup.bbclass</link>"
161 section for further details.
162 </para>
163 </section>
164
165 <section id='migration-1.3-image-features'>
166 <title>IMAGE_FEATURES</title>
167
168 <para>
169 Image recipes that previously included "apps-console-core"
170 in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
171 should now include "splash" instead to enable the boot-up
172 splash screen.
173 Retaining "apps-console-core" will still include the splash
174 screen generates a warning.
175 The "apps-x11-core" and "apps-x11-games"
176 <filename>IMAGE_FEATURES</filename> features have been removed.
177 </para>
178 </section>
179
180 <section id='migration-1.3-removed-recipes'>
181 <title>Removed Recipes</title>
182
183 <para>
184 The following recipes have been removed.
185 For most of them, it is unlikely that you would have any
186 references to them in your own metadata.
187 However, you should check your metadata against this list to be sure:
188 <itemizedlist>
189 <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>:
190 Replaced by <filename>libx11</filename>, which has a negligible
191 size difference with modern Xorg.</para></listitem>
192 <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>:
193 Use <filename>xserver-xorg</filename>, which has a negligible
194 size difference when DRI and GLX modules are not installed.</para></listitem>
195 <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>:
196 Effectively unmaintained for many years.</para></listitem>
197 <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>:
198 No longer serves any purpose.</para></listitem>
199 <listitem><para><emphasis><filename>galago</filename></emphasis>:
200 Replaced by telepathy.</para></listitem>
201 <listitem><para><emphasis><filename>gail</filename></emphasis>:
202 Functionality was integrated into GTK+ 2.13.</para></listitem>
203 <listitem><para><emphasis><filename>eggdbus</filename></emphasis>:
204 No longer needed.</para></listitem>
205 <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>:
206 The build has been restructured to avoid the need for
207 this step.</para></listitem>
208 <listitem><para><emphasis><filename>libgsmd</filename></emphasis>:
209 Unmaintained for many years.
210 Functionality now provided by
211 <filename>ofono</filename> instead.</para></listitem>
212 <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>:
213 Largely unmaintained PIM application suite.
214 It has been moved to <filename>meta-gnome</filename>
215 in <filename>meta-openembedded</filename>.</para></listitem>
216 </itemizedlist>
217 In addition to the previously listed changes, the
218 <filename>meta-demoapps</filename> directory has also been removed
219 because the recipes in it were not being maintained and many
220 had become obsolete or broken.
221 Additionally, these recipes were not parsed in the default configuration.
222 Many of these recipes are already provided in an updated and
223 maintained form within OpenEmbedded community layers such as
224 <filename>meta-oe</filename> and <filename>meta-gnome</filename>.
225 For the remainder, you can now find them in the
226 <filename>meta-extras</filename> repository, which is in the
227 Yocto Project source repositories.
228 </para>
229 </section>
230 </section>
231</section>
232</chapter>
233<!--
234vim: expandtab tw=80 ts=4
235-->
diff --git a/documentation/poky-ref-manual/poky-ref-manual-customization.xsl b/documentation/poky-ref-manual/poky-ref-manual-customization.xsl
deleted file mode 100644
index 362ebed131..0000000000
--- a/documentation/poky-ref-manual/poky-ref-manual-customization.xsl
+++ /dev/null
@@ -1,6 +0,0 @@
1<?xml version='1.0'?>
2<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
3
4 <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
5
6</xsl:stylesheet>
diff --git a/documentation/poky-ref-manual/poky-ref-manual.xml b/documentation/poky-ref-manual/poky-ref-manual.xml
deleted file mode 100644
index 2fcc68d88c..0000000000
--- a/documentation/poky-ref-manual/poky-ref-manual.xml
+++ /dev/null
@@ -1,125 +0,0 @@
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<book id='poky-ref-manual' lang='en'
6 xmlns:xi="http://www.w3.org/2003/XInclude"
7 xmlns="http://docbook.org/ns/docbook"
8 >
9 <bookinfo>
10
11 <mediaobject>
12 <imageobject>
13 <imagedata fileref='figures/poky-title.png'
14 format='SVG'
15 align='left' scalefit='1' width='100%'/>
16 </imageobject>
17 </mediaobject>
18
19 <title></title>
20
21 <authorgroup>
22 <author>
23 <firstname>Richard</firstname> <surname>Purdie</surname>
24 <affiliation>
25 <orgname>Linux Foundation</orgname>
26 </affiliation>
27 <email>richard.purdie@linuxfoundation.org</email>
28 </author>
29
30 </authorgroup>
31
32 <revhistory>
33 <revision>
34 <revnumber>4.0+git</revnumber>
35 <date>24 November 2010</date>
36 <revremark>Released with the Yocto Project 0.9 Release</revremark>
37 </revision>
38 <revision>
39 <revnumber>1.0</revnumber>
40 <date>6 April 2011</date>
41 <revremark>Released with the Yocto Project 1.0 Release.</revremark>
42 </revision>
43 <revision>
44 <revnumber>1.0.1</revnumber>
45 <date>23 May 2011</date>
46 <revremark>Released with the Yocto Project 1.0.1 Release.</revremark>
47 </revision>
48 <revision>
49 <revnumber>1.1</revnumber>
50 <date>6 October 2011</date>
51 <revremark>Released with the Yocto Project 1.1 Release.</revremark>
52 </revision>
53 <revision>
54 <revnumber>1.2</revnumber>
55 <date>April 2012</date>
56 <revremark>Released with the Yocto Project 1.2 Release.</revremark>
57 </revision>
58 <revision>
59 <revnumber>1.3</revnumber>
60 <date>October 2012</date>
61 <revremark>Released with the Yocto Project 1.3 Release.</revremark>
62 </revision>
63 <revision>
64 <revnumber>1.4</revnumber>
65 <date>Sometime in 2013</date>
66 <revremark>Released with the Yocto Project 1.4 Release.</revremark>
67 </revision>
68 </revhistory>
69
70 <copyright>
71 <year>&COPYRIGHT_YEAR;</year>
72 <holder>Linux Foundation</holder>
73 </copyright>
74
75 <legalnotice>
76 <para>
77 Permission is granted to copy, distribute and/or modify this document under
78 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
79 </para>
80 <note>
81 Due to production processes, there could be differences between the Yocto Project
82 documentation bundled in the release tarball and the
83 <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink> on
84 the <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
85 For the latest version of this manual, see the manual on the website.
86 </note>
87 </legalnotice>
88
89 </bookinfo>
90
91 <xi:include href="introduction.xml"/>
92
93 <xi:include href="usingpoky.xml"/>
94
95 <xi:include href="technical-details.xml"/>
96
97 <xi:include href="migration.xml"/>
98
99 <xi:include href="ref-structure.xml"/>
100
101 <xi:include href="ref-bitbake.xml"/>
102
103 <xi:include href="ref-classes.xml"/>
104
105 <xi:include href="ref-images.xml"/>
106
107 <xi:include href="ref-features.xml"/>
108
109 <xi:include href="ref-variables.xml"/>
110
111 <xi:include href="ref-varlocality.xml"/>
112
113 <xi:include href="faq.xml"/>
114
115 <xi:include href="resources.xml"/>
116
117<!-- <index id='index'>
118 <title>Index</title>
119 </index>
120-->
121
122</book>
123<!--
124vim: expandtab tw=80 ts=4
125-->
diff --git a/documentation/poky-ref-manual/ref-bitbake.xml b/documentation/poky-ref-manual/ref-bitbake.xml
deleted file mode 100644
index 4d4b9d6188..0000000000
--- a/documentation/poky-ref-manual/ref-bitbake.xml
+++ /dev/null
@@ -1,419 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-bitbake'>
6
7 <title>BitBake</title>
8
9 <para>
10 BitBake is a program written in Python that interprets the metadata used by the OpenEmbedded
11 build system.
12 At some point, developers wonder what actually happens when you enter:
13 <literallayout class='monospaced'>
14 $ bitbake core-image-sato
15 </literallayout>
16 </para>
17
18 <para>
19 This chapter provides an overview of what happens behind the scenes from BitBake's perspective.
20 </para>
21
22 <note>
23 BitBake strives to be a generic "task" executor that is capable of handling complex dependency relationships.
24 As such, it has no real knowledge of what the tasks being executed actually do.
25 BitBake just considers a list of tasks with dependencies and handles metadata
26 that consists of variables in a certain format that get passed to the tasks.
27 </note>
28
29 <section id='ref-bitbake-parsing'>
30 <title>Parsing</title>
31
32 <para>
33 BitBake parses configuration files, classes, and <filename>.bb</filename> files.
34 </para>
35
36 <para>
37 The first thing BitBake does is look for the <filename>bitbake.conf</filename> file.
38 This file resides in the
39 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
40 within the <filename>meta/conf/</filename> directory.
41 BitBake finds it by examining its
42 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> environment
43 variable and looking for the <filename>meta/conf/</filename>
44 directory.
45 </para>
46
47 <para>
48 The <filename>bitbake.conf</filename> file lists other configuration
49 files to include from a <filename>conf/</filename>
50 directory below the directories listed in <filename>BBPATH</filename>.
51 In general, the most important configuration file from a user's perspective
52 is <filename>local.conf</filename>, which contains a user's customized
53 settings for the OpenEmbedded build environment.
54 Other notable configuration files are the distribution
55 configuration file (set by the
56 <filename><link linkend='var-DISTRO'>DISTRO</link></filename> variable)
57 and the machine configuration file
58 (set by the
59 <filename><link linkend='var-MACHINE'>MACHINE</link></filename> variable).
60 The <filename>DISTRO</filename> and <filename>MACHINE</filename> BitBake environment
61 variables are both usually set in
62 the <filename>local.conf</filename> file.
63 Valid distribution
64 configuration files are available in the <filename>meta/conf/distro/</filename> directory
65 and valid machine configuration
66 files in the <filename>meta/conf/machine/</filename> directory.
67 Within the <filename>meta/conf/machine/include/</filename>
68 directory are various <filename>tune-*.inc</filename> configuration files that provide common
69 "tuning" settings specific to and shared between particular architectures and machines.
70 </para>
71
72 <para>
73 After the parsing of the configuration files, some standard classes are included.
74 The <filename>base.bbclass</filename> file is always included.
75 Other classes that are specified in the configuration using the
76 <filename><link linkend='var-INHERIT'>INHERIT</link></filename>
77 variable are also included.
78 Class files are searched for in a <filename>classes</filename> subdirectory
79 under the paths in <filename>BBPATH</filename> in the same way as
80 configuration files.
81 </para>
82
83 <para>
84 After classes are included, the variable
85 <filename><link linkend='var-BBFILES'>BBFILES</link></filename>
86 is set, usually in
87 <filename>local.conf</filename>, and defines the list of places to search for
88 <filename>.bb</filename> files.
89 By default, the <filename>BBFILES</filename> variable specifies the
90 <filename>meta/recipes-*/</filename> directory within Poky.
91 Adding extra content to <filename>BBFILES</filename> is best achieved through the use of
92 BitBake layers as described in the
93 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and
94 Creating Layers</ulink>" section of the Yocto Project Development Manual.
95 </para>
96
97 <para>
98 BitBake parses each <filename>.bb</filename> file in <filename>BBFILES</filename> and
99 stores the values of various variables.
100 In summary, for each <filename>.bb</filename>
101 file the configuration plus the base class of variables are set, followed
102 by the data in the <filename>.bb</filename> file
103 itself, followed by any inherit commands that
104 <filename>.bb</filename> file might contain.
105 </para>
106
107 <para>
108 Because parsing <filename>.bb</filename> files is a time
109 consuming process, a cache is kept to speed up subsequent parsing.
110 This cache is invalid if the timestamp of the <filename>.bb</filename>
111 file itself changes, or if the timestamps of any of the include,
112 configuration or class files the <filename>.bb</filename>
113 file depends on changes.
114 </para>
115 </section>
116
117 <section id='ref-bitbake-providers'>
118 <title>Preferences and Providers</title>
119
120 <para>
121 Once all the <filename>.bb</filename> files have been
122 parsed, BitBake starts to build the target (<filename>core-image-sato</filename>
123 in the previous section's example) and looks for providers of that target.
124 Once a provider is selected, BitBake resolves all the dependencies for
125 the target.
126 In the case of <filename>core-image-sato</filename>, it would lead to
127 <filename>packagegroup-core-x11-sato</filename>,
128 which in turn leads to recipes like <filename>matchbox-terminal</filename>,
129 <filename>pcmanfm</filename> and <filename>gthumb</filename>.
130 These recipes in turn depend on <filename>eglibc</filename> and the toolchain.
131 </para>
132
133 <para>
134 Sometimes a target might have multiple providers.
135 A common example is "virtual/kernel", which is provided by each kernel package.
136 Each machine often selects the best kernel provider by using a line similar to the
137 following in the machine configuration file:
138 </para>
139
140 <literallayout class='monospaced'>
141 PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
142 </literallayout>
143
144 <para>
145 The default <filename><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></filename>
146 is the provider with the same name as the target.
147 </para>
148
149 <para>
150 Understanding how providers are chosen is made complicated by the fact
151 that multiple versions might exist.
152 BitBake defaults to the highest version of a provider.
153 Version comparisons are made using the same method as Debian.
154 You can use the
155 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
156 variable to specify a particular version (usually in the distro configuration).
157 You can influence the order by using the
158 <filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></filename>
159 variable.
160 By default, files have a preference of "0".
161 Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the
162 package unlikely to be used unless it is explicitly referenced.
163 Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the package is used.
164 <filename>PREFERRED_VERSION</filename> overrides any <filename>DEFAULT_PREFERENCE</filename> setting.
165 <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental package
166 versions until they have undergone sufficient testing to be considered stable.
167 </para>
168
169 <para>
170 In summary, BitBake has created a list of providers, which is prioritized, for each target.
171 </para>
172 </section>
173
174 <section id='ref-bitbake-dependencies'>
175 <title>Dependencies</title>
176
177 <para>
178 Each target BitBake builds consists of multiple tasks such as
179 <filename>fetch</filename>, <filename>unpack</filename>,
180 <filename>patch</filename>, <filename>configure</filename>,
181 and <filename>compile</filename>.
182 For best performance on multi-core systems, BitBake considers each task as an independent
183 entity with its own set of dependencies.
184 </para>
185
186 <para>
187 Dependencies are defined through several variables.
188 You can find information about variables BitBake uses in the BitBake documentation,
189 which is found in the <filename>bitbake/doc/manual</filename> directory within the
190 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
191 At a basic level, it is sufficient to know that BitBake uses the
192 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename> and
193 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variables when
194 calculating dependencies.
195 </para>
196 </section>
197
198 <section id='ref-bitbake-tasklist'>
199 <title>The Task List</title>
200
201 <para>
202 Based on the generated list of providers and the dependency information,
203 BitBake can now calculate exactly what tasks it needs to run and in what
204 order it needs to run them.
205 The build now starts with BitBake forking off threads up to the limit set in the
206 <filename><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></filename> variable.
207 BitBake continues to fork threads as long as there are tasks ready to run,
208 those tasks have all their dependencies met, and the thread threshold has not been
209 exceeded.
210 </para>
211
212 <para>
213 It is worth noting that you can greatly speed up the build time by properly setting
214 the <filename>BB_NUMBER_THREADS</filename> variable.
215 See the
216 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
217 section in the Yocto Project Quick Start for more information.
218 </para>
219
220 <para>
221 As each task completes, a timestamp is written to the directory specified by the
222 <filename><link linkend='var-STAMP'>STAMP</link></filename> variable.
223 On subsequent runs, BitBake looks within the <filename>/build/tmp/stamps</filename>
224 directory and does not rerun
225 tasks that are already completed unless a timestamp is found to be invalid.
226 Currently, invalid timestamps are only considered on a per
227 <filename>.bb</filename> file basis.
228 So, for example, if the configure stamp has a timestamp greater than the
229 compile timestamp for a given target, then the compile task would rerun.
230 Running the compile task again, however, has no effect on other providers
231 that depend on that target.
232 This behavior could change or become configurable in future versions of BitBake.
233 </para>
234
235 <note>
236 Some tasks are marked as "nostamp" tasks.
237 No timestamp file is created when these tasks are run.
238 Consequently, "nostamp" tasks are always rerun.
239 </note>
240 </section>
241
242 <section id='ref-bitbake-runtask'>
243 <title>Running a Task</title>
244
245 <para>
246 Tasks can either be a shell task or a Python task.
247 For shell tasks, BitBake writes a shell script to
248 <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> and then executes the script.
249 The generated shell script contains all the exported variables, and the shell functions
250 with all variables expanded.
251 Output from the shell script goes to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
252 Looking at the expanded shell functions in the run file and the output in the log files
253 is a useful debugging technique.
254 </para>
255
256 <para>
257 For Python tasks, BitBake executes the task internally and logs information to the
258 controlling terminal.
259 Future versions of BitBake will write the functions to files similar to the way
260 shell tasks are handled.
261 Logging will be handled in way similar to shell tasks as well.
262 </para>
263
264 <para>
265 Once all the tasks have been completed BitBake exits.
266 </para>
267
268 <para>
269 When running a task, BitBake tightly controls the execution environment
270 of the build tasks to make sure unwanted contamination from the build machine
271 cannot influence the build.
272 Consequently, if you do want something to get passed into the build
273 task's environment, you must take a few steps:
274 <orderedlist>
275 <listitem><para>Tell BitBake to load what you want from the environment
276 into the data store.
277 You can do so through the <filename>BB_ENV_EXTRAWHITE</filename>
278 variable.
279 For example, assume you want to prevent the build system from
280 accessing your <filename>$HOME/.ccache</filename> directory.
281 The following command tells BitBake to load
282 <filename>CCACHE_DIR</filename> from the environment into the data
283 store:
284 <literallayout class='monospaced'>
285 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
286 </literallayout></para></listitem>
287 <listitem><para>Tell BitBake to export what you have loaded into the
288 environment store to the task environment of every running task.
289 Loading something from the environment into the data store
290 (previous step) only makes it available in the datastore.
291 To export it to the task environment of every running task,
292 use a command similar to the following in your
293 <filename>local.conf</filename> or distro configuration file:
294 <literallayout class='monospaced'>
295 export CCACHE_DIR
296 </literallayout></para></listitem>
297 </orderedlist>
298 </para>
299
300 <note>
301 A side effect of the previous steps is that BitBake records the variable
302 as a dependency of the build process in things like the shared state
303 checksums.
304 If doing so results in unnecessary rebuilds of tasks, you can whitelist the
305 variable so that the shared state code ignores the dependency when it creates
306 checksums.
307 For information on this process, see the <filename>BB_HASHBASE_WHITELIST</filename>
308 example in the "<link linkend='checksums'>Checksums (Signatures)</link>" section.
309 </note>
310 </section>
311
312 <section id='ref-bitbake-commandline'>
313 <title>BitBake Command Line</title>
314
315 <para>
316 Following is the BitBake help output:
317 </para>
318
319 <screen>
320$ bitbake --help
321Usage: bitbake [options] [package ...]
322
323Executes the specified task (default is 'build') for a given set of BitBake files.
324It expects that BBFILES is defined, which is a space separated list of files to
325be executed. BBFILES does support wildcards.
326Default BBFILES are the .bb files in the current directory.
327
328Options:
329 --version show program's version number and exit
330 -h, --help show this help message and exit
331 -b BUILDFILE, --buildfile=BUILDFILE
332 execute the task against this .bb file, rather than a
333 package from BBFILES. Does not handle any
334 dependencies.
335 -k, --continue continue as much as possible after an error. While the
336 target that failed, and those that depend on it,
337 cannot be remade, the other dependencies of these
338 targets can be processed all the same.
339 -a, --tryaltconfigs continue with builds by trying to use alternative
340 providers where possible.
341 -f, --force force run of specified cmd, regardless of stamp status
342 -c CMD, --cmd=CMD Specify task to execute. Note that this only executes
343 the specified task for the providee and the packages
344 it depends on, i.e. 'compile' does not implicitly call
345 stage for the dependencies (IOW: use only if you know
346 what you are doing). Depending on the base.bbclass a
347 listtasks tasks is defined and will show available
348 tasks
349 -r PREFILE, --read=PREFILE
350 read the specified file before bitbake.conf
351 -R POSTFILE, --postread=POSTFILE
352 read the specified file after bitbake.conf
353 -v, --verbose output more chit-chat to the terminal
354 -D, --debug Increase the debug level. You can specify this more
355 than once.
356 -n, --dry-run don't execute, just go through the motions
357 -S, --dump-signatures
358 don't execute, just dump out the signature
359 construction information
360 -p, --parse-only quit after parsing the BB files (developers only)
361 -s, --show-versions show current and preferred versions of all packages
362 -e, --environment show the global or per-package environment (this is
363 what used to be bbread)
364 -g, --graphviz emit the dependency trees of the specified packages in
365 the dot syntax
366 -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
367 Assume these dependencies don't exist and are already
368 provided (equivalent to ASSUME_PROVIDED). Useful to
369 make dependency graphs more appealing
370 -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
371 Show debug logging for the specified logging domains
372 -P, --profile profile the command and print a report
373 -u UI, --ui=UI userinterface to use
374 -t SERVERTYPE, --servertype=SERVERTYPE
375 Choose which server to use, none, process or xmlrpc
376 --revisions-changed Set the exit code depending on whether upstream
377 floating revisions have changed or not
378 </screen>
379 </section>
380
381 <section id='ref-bitbake-fetchers'>
382 <title>Fetchers</title>
383
384 <para>
385 BitBake also contains a set of "fetcher" modules that allow
386 retrieval of source code from various types of sources.
387 For example, BitBake can get source code from a disk with the metadata, from websites,
388 from remote shell accounts or from Source Code Management (SCM) systems
389 like <filename>cvs/subversion/git</filename>.
390 </para>
391
392 <para>
393 Fetchers are usually triggered by entries in
394 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>.
395 You can find information about the options and formats of entries for specific
396 fetchers in the BitBake manual located in the
397 <filename>bitbake/doc/manual</filename> directory of the
398 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
399 </para>
400
401 <para>
402 One useful feature for certain Source Code Manager (SCM) fetchers is the ability to
403 "auto-update" when the upstream SCM changes version.
404 Since this ability requires certain functionality from the SCM, not all
405 systems support it.
406 Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update".
407 This feature works using the <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
408 variable.
409 See the
410 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-srcrev'>Using an External SCM</ulink>" section
411 in the Yocto Project Development Manual for more information.
412 </para>
413
414 </section>
415
416</chapter>
417<!--
418vim: expandtab tw=80 ts=4 spell spelllang=en_gb
419-->
diff --git a/documentation/poky-ref-manual/ref-classes.xml b/documentation/poky-ref-manual/ref-classes.xml
deleted file mode 100644
index 2caea272a4..0000000000
--- a/documentation/poky-ref-manual/ref-classes.xml
+++ /dev/null
@@ -1,720 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-classes'>
6<title>Classes</title>
7
8<para>
9 Class files are used to abstract common functionality and share it amongst multiple
10 <filename>.bb</filename> files.
11 Any metadata usually found in a <filename>.bb</filename> file can also be placed in a class
12 file.
13 Class files are identified by the extension <filename>.bbclass</filename> and are usually placed
14 in a <filename>classes/</filename> directory beneath the
15 <filename>meta*/</filename> directory found in the
16 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
17 Class files can also be pointed to by BUILDDIR (e.g. <filename>build/</filename>)in the same way as
18 <filename>.conf</filename> files in the <filename>conf</filename> directory.
19 Class files are searched for in <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
20 using the same method by which <filename>.conf</filename> files are searched.
21</para>
22
23<para>
24 In most cases inheriting the class is enough to enable its features, although
25 for some classes you might need to set variables or override some of the
26 default behaviour.
27</para>
28
29<section id='ref-classes-base'>
30 <title>The base class - <filename>base.bbclass</filename></title>
31
32 <para>
33 The base class is special in that every <filename>.bb</filename>
34 file inherits it automatically.
35 This class contains definitions for standard basic
36 tasks such as fetching, unpacking, configuring (empty by default), compiling
37 (runs any <filename>Makefile</filename> present), installing (empty by default) and packaging
38 (empty by default).
39 These classes are often overridden or extended by other classes
40 such as <filename>autotools.bbclass</filename> or <filename>package.bbclass</filename>.
41 The class also contains some commonly used functions such as <filename>oe_runmake</filename>.
42 </para>
43</section>
44
45<section id='ref-classes-autotools'>
46 <title>Autotooled Packages - <filename>autotools.bbclass</filename></title>
47
48 <para>
49 Autotools (<filename>autoconf</filename>, <filename>automake</filename>,
50 and <filename>libtool</filename>) bring standardization.
51 This class defines a set of tasks (configure, compile etc.) that
52 work for all Autotooled packages.
53 It should usually be enough to define a few standard variables
54 and then simply <filename>inherit autotools</filename>.
55 This class can also work with software that emulates Autotools.
56 For more information, see the
57 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg-autotools'>Autotooled Package</ulink>"
58 section in the Yocto Project Development Manual.
59 </para>
60
61 <para>
62 It's useful to have some idea of how the tasks defined by this class work
63 and what they do behind the scenes.
64 <itemizedlist>
65 <listitem><para><filename>do_configure</filename> &dash; regenerates the
66 configure script (using <filename>autoreconf</filename>) and then launches it
67 with a standard set of arguments used during cross-compilation.
68 You can pass additional parameters to <filename>configure</filename> through the
69 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
70 </para></listitem>
71 <listitem><para><filename>do_compile</filename> &dash; runs <filename>make</filename> with
72 arguments that specify the compiler and linker.
73 You can pass additional arguments through
74 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
75 </para></listitem>
76 <listitem><para><filename>do_install</filename> &dash; runs <filename>make install</filename>
77 and passes a DESTDIR option, which takes its value from the standard
78 <filename><link linkend='var-DESTDIR'>DESTDIR</link></filename> variable.
79 </para></listitem>
80 </itemizedlist>
81 </para>
82</section>
83
84<section id='ref-classes-update-alternatives'>
85 <title>Alternatives - <filename>update-alternatives.bbclass</filename></title>
86
87 <para>
88 Several programs can fulfill the same or similar function and be installed with the same name.
89 For example, the <filename>ar</filename> command is available from the
90 <filename>busybox</filename>, <filename>binutils</filename> and
91 <filename>elfutils</filename> packages.
92 The <filename>update-alternatives.bbclass</filename> class handles renaming the
93 binaries so that multiple packages can be installed without conflicts.
94 The <filename>ar</filename> command still works regardless of which packages are installed
95 or subsequently removed.
96 The class renames the conflicting binary in each package and symlinks the highest
97 priority binary during installation or removal of packages.
98 </para>
99 <para>
100 Four variables control this class:
101 <itemizedlist>
102 <listitem><para><filename>ALTERNATIVE_NAME</filename> &dash; The name of the
103 binary that is replaced (<filename>ar</filename> in this example).</para></listitem>
104 <listitem><para><filename>ALTERNATIVE_LINK</filename> &dash; The path to
105 the resulting binary (<filename>/bin/ar</filename> in this example).</para></listitem>
106 <listitem><para><filename>ALTERNATIVE_PATH</filename> &dash; The path to the
107 real binary (<filename>/usr/bin/ar.binutils</filename> in this example).</para></listitem>
108 <listitem><para><filename>ALTERNATIVE_PRIORITY</filename> &dash; The priority of
109 the binary.
110 The version with the most features should have the highest priority.</para></listitem>
111 </itemizedlist>
112 </para>
113
114 <para>
115 Currently, the OpenEmbedded build system supports only one binary per package.
116 </para>
117</section>
118
119<section id='ref-classes-update-rc.d'>
120 <title>Initscripts - <filename>update-rc.d.bbclass</filename></title>
121
122 <para>
123 This class uses <filename>update-rc.d</filename> to safely install an
124 initialization script on behalf of the package.
125 The OpenEmbedded build system takes care of details such as making sure the script is stopped before
126 a package is removed and started when the package is installed.
127 Three variables control this class:
128 <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>,
129 <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and
130 <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>.
131 See the variable links for details.
132 </para>
133</section>
134
135<section id='ref-classes-binconfig'>
136 <title>Binary config scripts - <filename>binconfig.bbclass</filename></title>
137
138 <para>
139 Before <filename>pkg-config</filename> had become widespread, libraries shipped shell
140 scripts to give information about the libraries and include paths needed
141 to build software (usually named <filename>LIBNAME-config</filename>).
142 This class assists any recipe using such scripts.
143 </para>
144
145 <para>
146 During staging, BitBake installs such scripts into the
147 <filename>sysroots/</filename> directory.
148 BitBake also changes all paths to point into the <filename>sysroots/</filename>
149 directory so all builds that use the script will use the correct
150 directories for the cross compiling layout.
151 </para>
152</section>
153
154<section id='ref-classes-debian'>
155 <title>Debian renaming - <filename>debian.bbclass</filename></title>
156
157 <para>
158 This class renames packages so that they follow the Debian naming
159 policy (i.e. <filename>eglibc</filename> becomes <filename>libc6</filename>
160 and <filename>eglibc-devel</filename> becomes <filename>libc6-dev</filename>.
161 </para>
162</section>
163
164<section id='ref-classes-pkgconfig'>
165 <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title>
166
167 <para>
168 <filename>pkg-config</filename> brought standardization and this class aims to make its
169 integration smooth for all libraries that make use of it.
170 </para>
171
172 <para>
173 During staging, BitBake installs <filename>pkg-config</filename> data into the
174 <filename>sysroots/</filename> directory.
175 By making use of sysroot functionality within <filename>pkg-config</filename>,
176 this class no longer has to manipulate the files.
177 </para>
178</section>
179
180<section id='ref-classes-src-distribute'>
181 <title>Distribution of sources - <filename>src_distribute_local.bbclass</filename></title>
182
183 <para>
184 Many software licenses require that source files be provided along with the binaries.
185 To simplify this process, two classes were created:
186 <filename>src_distribute.bbclass</filename> and
187 <filename>src_distribute_local.bbclass</filename>.
188 </para>
189
190 <para>
191 The results of these classes are <filename>tmp/deploy/source/</filename>
192 subdirs with sources sorted by
193 <filename><link linkend='var-LICENSE'>LICENSE</link></filename> field.
194 If recipes list few licenses (or have entries like "Bitstream Vera"),
195 the source archive is placed in each license directory.
196 </para>
197
198 <para>
199 This class operates using three modes:
200 <itemizedlist>
201 <listitem><para><emphasis>copy:</emphasis> Copies the files to the
202 distribute directory.</para></listitem>
203 <listitem><para><emphasis>symlink:</emphasis> Symlinks the files to the
204 distribute directory.</para></listitem>
205 <listitem><para><emphasis>move+symlink:</emphasis> Moves the files into
206 the distribute directory and then symlinks them back.</para></listitem>
207 </itemizedlist>
208 </para>
209</section>
210
211<section id='ref-classes-perl'>
212 <title>Perl modules - <filename>cpan.bbclass</filename></title>
213
214 <para>
215 Recipes for Perl modules are simple.
216 These recipes usually only need to point to the source's archive and then inherit the
217 proper <filename>.bbclass</filename> file.
218 Building is split into two methods depending on which method the module authors used.
219 </para>
220
221 <para>
222 Modules that use old <filename>Makefile.PL</filename>-based build system require
223 <filename>cpan.bbclass</filename> in their recipes.
224 </para>
225
226 <para>
227 Modules that use <filename>Build.PL</filename>-based build system require
228 using <filename>cpan_build.bbclass</filename> in their recipes.
229 </para>
230</section>
231
232<section id='ref-classes-distutils'>
233 <title>Python extensions - <filename>distutils.bbclass</filename></title>
234
235 <para>
236 Recipes for Python extensions are simple.
237 These recipes usually only need to point to the source's archive and then inherit
238 the proper <filename>.bbclass</filename> file.
239 Building is split into two methods dependling on which method the module authors used.
240 </para>
241
242 <para>
243 Extensions that use an Autotools-based build system require Autotools and
244 <filename>distutils</filename>-based <filename>.bbclasse</filename> files in their recipes.
245 </para>
246
247 <para>
248 Extensions that use <filename>distutils</filename>-based build systems require
249 <filename>distutils.bbclass</filename> in their recipes.
250 </para>
251</section>
252
253<section id='ref-classes-devshell'>
254 <title>Developer Shell - <filename>devshell.bbclass</filename></title>
255
256 <para>
257 This class adds the <filename>devshell</filename> task.
258 Distribution policy dictates whether to include this class.
259 See the
260 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
261 in the Yocto Project Development Manual for more information about using <filename>devshell</filename>.
262 </para>
263</section>
264
265<section id='ref-classes-packagegroup'>
266 <title>Package Groups - <filename>packagegroup.bbclass</filename></title>
267
268 <para>
269 This class sets default values appropriate for package group recipes (such as
270 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>,
271 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>,
272 <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>,
273 and so forth.
274 It is highly recommended that all package group recipes inherit this class.
275 </para>
276 <para>
277 For information on how to use this class, see the
278 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Tasks</ulink>"
279 section in the Yocto Project Development Manual.
280 </para>
281 <para>
282 Previously, this class was named <filename>task.bbclass</filename>.
283 </para>
284</section>
285
286
287<section id='ref-classes-package'>
288 <title>Packaging - <filename>package*.bbclass</filename></title>
289
290 <para>
291 The packaging classes add support for generating packages from a build's
292 output.
293 The core generic functionality is in <filename>package.bbclass</filename>.
294 The code specific to particular package types is contained in various sub-classes such as
295 <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename>,
296 and <filename>package_rpm.bbclass</filename>.
297 Most users will want one or more of these classes.
298 </para>
299
300 <para>
301 You can control the list of resulting package formats by using the
302 <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename>
303 variable defined in the <filename>local.conf</filename> configuration file,
304 which is located in the <filename>conf</filename> folder of the
305 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
306 When defining the variable, you can specify one or more package types.
307 Since images are generated from packages, a packaging class is
308 needed to enable image generation.
309 The first class listed in this variable is used for image generation.
310 </para>
311
312 <para>
313 The package class you choose can affect build-time performance and has space
314 ramifications.
315 In general, building a package with RPM takes about thirty percent more time as
316 compared to using IPK to build the same or similar package.
317 This comparison takes into account a complete build of the package with all
318 dependencies previously built.
319 The reason for this discrepancy is because the RPM package manager creates and
320 processes more metadata than the IPK package manager.
321 Consequently, you might consider setting <filename>PACKAGE_CLASSES</filename>
322 to "package_ipk" if you are building smaller systems.
323 </para>
324
325 <para>
326 Keep in mind, however, that RPM starts to provide more abilities than IPK due to
327 the fact that it processes more metadata.
328 For example, this information includes individual file types, file checksum generation
329 and evaluation on install, sparse file support, conflict detection and resolution
330 for multilib systems, ACID style upgrade, and repackaging abilities for rollbacks.
331 </para>
332
333 <para>
334 Another consideration for packages built using the RPM package manager is space.
335 For smaller systems, the extra space used for the Berkley Database and the amount
336 of metadata can affect your ability to do on-device upgrades.
337 </para>
338
339 <para>
340 You can find additional information on the effects of the package class at these
341 two Yocto Project mailing list links:
342 <itemizedlist>
343 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'>
344 https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem>
345 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html'>
346 https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem>
347 </itemizedlist>
348 </para>
349</section>
350
351<section id='ref-classes-kernel'>
352 <title>Building kernels - <filename>kernel.bbclass</filename></title>
353
354 <para>
355 This class handles building Linux kernels.
356 The class contains code to build all kernel trees.
357 All needed headers are staged into the
358 <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename>
359 directory to allow out-of-tree module builds using <filename>module.bbclass</filename>.
360 </para>
361
362 <para>
363 This means that each built kernel module is packaged separately and inter-module
364 dependencies are created by parsing the <filename>modinfo</filename> output.
365 If all modules are required, then installing the <filename>kernel-modules</filename>
366 package installs all packages with modules and various other kernel packages
367 such as <filename>kernel-vmlinux</filename>.
368 </para>
369
370 <para>
371 Various other classes are used by the kernel and module classes internally including
372 <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>,
373 <filename>module-base.bbclass</filename>, and <filename>linux-kernel-base.bbclass</filename>.
374 </para>
375</section>
376
377<section id='ref-classes-image'>
378 <title>Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title>
379
380 <para>
381 These classes add support for creating images in several formats.
382 First, the root filesystem is created from packages using
383 one of the <filename>rootfs_*.bbclass</filename>
384 files (depending on the package format used) and then the image is created.
385 </para>
386
387 <para>
388 The <filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename>
389 variable controls the types of images to generate.
390 </para>
391
392 <para>
393 The <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
394 variable controls the list of packages to install into the image.
395 </para>
396</section>
397
398<section id='ref-classes-sanity'>
399 <title>Host System sanity checks - <filename>sanity.bbclass</filename></title>
400
401 <para>
402 This class checks to see if prerequisite software is present so that
403 users can be notified of potential problems that might affect their build.
404 The class also performs basic user configuration checks from
405 the <filename>local.conf</filename> configuration file to
406 prevent common mistakes that cause build failures.
407 Distribution policy usually determines whether to include this class.
408 </para>
409</section>
410
411<section id='ref-classes-insane'>
412 <title>Generated output quality assurance checks - <filename>insane.bbclass</filename></title>
413
414 <para>
415 This class adds a step to the package generation process that sanity checks the
416 packages generated by the OpenEmbedded build system.
417 A range of checks are performed that check the build's output
418 for common problems that show up during runtime.
419 Distribution policy usually dictates whether to include this class.
420 </para>
421
422 <para>
423 You can configure the sanity checks so that specific test failures either raise a warning or
424 an error message.
425 Typically, failures for new tests generate a warning.
426 Subsequent failures for the same test would then generate an error message
427 once the metadata is in a known and good condition.
428 You use the <filename>WARN_QA</filename> variable to specify tests for which you
429 want to generate a warning message on failure.
430 You use the <filename>ERROR_QA</filename> variable to specify tests for which you
431 want to generate an error message on failure.
432 </para>
433
434 <para>
435 The following list shows the tests you can list with the <filename>WARN_QA</filename>
436 and <filename>ERROR_QA</filename> variables:
437 <itemizedlist>
438 <listitem><para><emphasis><filename>ldflags:</filename></emphasis>
439 Ensures that the binaries were linked with the
440 <filename>LDFLAGS</filename> options provided by the build system.
441 If this test fails, check that the <filename>LDFLAGS</filename> variable
442 is being passed to the linker command.</para></listitem>
443 <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
444 Checks for dynamic library load paths (rpaths) in the binaries that
445 by default on a standard system are searched by the linker (e.g.
446 <filename>/lib</filename> and <filename>/usr/lib</filename>).
447 While these paths will not cause any breakage, they do waste space and
448 are unnecessary.</para></listitem>
449 <listitem><para><emphasis><filename>rpaths:</filename></emphasis>
450 Checks for rpaths in the binaries that contain build system paths such
451 as <filename>TMPDIR</filename>.
452 If this test fails, bad <filename>-rpath</filename> options are being
453 passed to the linker commands and your binaries have potential security
454 issues.</para></listitem>
455 <listitem><para><emphasis><filename>dev-so:</filename></emphasis>
456 Checks that the <filename>.so</filename> symbolic links are in the
457 <filename>-dev</filename> package and not in any of the other packages.
458 In general, these symlinks are only useful for development purposes.
459 Thus, the <filename>-dev</filename> package is the correct location for
460 them.
461 Some very rare cases do exist for dynamically loaded modules where
462 these symlinks are needed instead in the main package.
463 </para></listitem>
464 <listitem><para><emphasis><filename>debug-files:</filename></emphasis>
465 Checks for <filename>.debug</filename> directories in anything but the
466 <filename>-dbg</filename> package.
467 The debug files should all be in the <filename>-dbg</filename> package.
468 Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
469 <listitem><para><emphasis><filename>arch:</filename></emphasis>
470 Checks the Executable and Linkable Format (ELF) type, bit size and endianness
471 of any binaries to ensure it matches the target architecture.
472 This test fails if any binaries don't match the type since there would be an
473 incompatibility.
474 Sometimes software, like bootloaders, might need to bypass this check.
475 </para></listitem>
476 <listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
477 Checks that <filename>-dbg</filename> packages only depend on other
478 <filename>-dbg</filename> packages and not on any other types of packages,
479 which would cause a packaging bug.</para></listitem>
480 <listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
481 Checks that <filename>-dev</filename> packages only depend on other
482 <filename>-dev</filename> packages and not on any other types of packages,
483 which would be a packaging bug.</para></listitem>
484 <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
485 Checks <filename>.pc</filename> files for any
486 <filename>TMPDIR/WORKDIR</filename> paths.
487 Any <filename>.pc</filename> file containing these paths is incorrect
488 since <filename>pkg-config</filename> itself adds the correct sysroot prefix
489 when the files are accessed.</para></listitem>
490 <listitem><para><emphasis><filename>la:</filename></emphasis>
491 Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
492 paths.
493 Any <filename>.la</filename> file continaing these paths is incorrect since
494 <filename>libtool</filename> adds the correct sysroot prefix when using the
495 files automatically itself.</para></listitem>
496 <listitem><para><emphasis><filename>desktop:</filename></emphasis>
497 Runs the <filename>desktop-file-validate</filename> program against any
498 <filename>.desktop</filename> files to validate their contents against
499 the specification for <filename>.desktop</filename> files.</para></listitem>
500 </itemizedlist>
501 </para>
502</section>
503
504<section id='ref-classes-siteinfo'>
505 <title>Autotools configuration data cache - <filename>siteinfo.bbclass</filename></title>
506
507 <para>
508 Autotools can require tests that must execute on the target hardware.
509 Since this is not possible in general when cross compiling, site information is
510 used to provide cached test results so these tests can be skipped over but
511 still make the correct values available.
512 The <filename><link linkend='structure-meta-site'>meta/site directory</link></filename>
513 contains test results sorted into different categories such as architecture, endianness, and
514 the <filename>libc</filename> used.
515 Site information provides a list of files containing data relevant to
516 the current build in the
517 <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable
518 that Autotools automatically picks up.
519 </para>
520
521 <para>
522 The class also provides variables like
523 <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename>
524 and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename>
525 that can be used elsewhere in the metadata.
526 </para>
527
528 <para>
529 Because this class is included from <filename>base.bbclass</filename>, it is always active.
530 </para>
531</section>
532
533<section id='ref-classes-useradd'>
534 <title>Adding Users - <filename>useradd.bbclass</filename></title>
535
536 <para>
537 If you have packages that install files that are owned by custom users or groups,
538 you can use this class to specify those packages and associate the users and groups
539 with those packages.
540 The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
541 recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
542 provides a simple exmample that shows how to add three
543 users and groups to two packages.
544 See the <filename>useradd-example.bb</filename> for more information on how to
545 use this class.
546 </para>
547</section>
548
549<section id='ref-classes-externalsrc'>
550 <title>Using External Source - <filename>externalsrc.bbclass</filename></title>
551
552 <para>
553 You can use this class to build software from source code that is external to the
554 OpenEmbedded build system.
555 In other words, your source code resides in an external tree outside of the Yocto Project.
556 Building software from an external source tree means that the normal fetch, unpack, and
557 patch process is not used.
558 </para>
559
560 <para>
561 To use the class, you need to define the
562 <link linkend='var-S'><filename>S</filename></link> variable to point to the directory that contains the source files.
563 You also need to have your recipe inherit the <filename>externalsrc.bbclass</filename> class.
564 </para>
565
566 <para>
567 This class expects the source code to support recipe builds that use the
568 <link linkend='var-B'><filename>B</filename></link> variable to point to the directory in
569 which the OpenEmbedded build system places the generated objects built from the recipes.
570 By default, the <filename>B</filename> directory is set to the following, which is separate from the
571 Source Directory (<filename>S</filename>):
572 <literallayout class='monospaced'>
573 ${WORKDIR}/${BPN}/{PV}/
574 </literallayout>
575 See the glossary entries for the
576 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
577 <link linkend='var-BPN'><filename>BPN</filename></link>,
578 <link linkend='var-PV'><filename>PV</filename></link>,
579 <link linkend='var-S'><filename>S</filename></link>, and
580 <link linkend='var-B'><filename>B</filename></link> for more information.
581 </para>
582
583 <para>
584 You can build object files in the external tree by setting the
585 <filename>B</filename> variable equal to <filename>"${S}"</filename>.
586 However, this practice does not work well if you use the source for more than one variant
587 (i.e., "natives" such as <filename>quilt-native</filename>,
588 or "crosses" such as <filename>gcc-cross</filename>).
589 So, be sure there are no "native", "cross", or "multilib" variants of the recipe.
590 </para>
591
592 <para>
593 If you do want to build different variants of a recipe, you can use the
594 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> variable.
595 When you do, the <link linkend='var-B'><filename>B</filename></link> variable must support the
596 recipe's ability to build variants in different working directories.
597 Most autotools-based recipes support separating these directories.
598 The OpenEmbedded build system defaults to using separate directories for <filename>gcc</filename>
599 and some kernel recipes.
600 Alternatively, you can make sure that separate recipes exist that each
601 use the <filename>BBCLASSEXTEND</filename> variable to build each variant.
602 The separate recipes can inherit a single target recipe.
603 </para>
604
605 <para>
606 For information on how to use this class, see the
607 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building
608 Software from an External Source</ulink>" section in the Yocto Project Development Manual.
609 </para>
610</section>
611
612<section id='ref-classes-others'>
613 <title>Other Classes</title>
614
615 <para>
616 Thus far, this chapter has discussed only the most useful and important
617 classes.
618 However, other classes exist within the <filename>meta/classes</filename> directory
619 in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
620 You can examine the <filename>.bbclass</filename> files directly for more
621 information.
622 </para>
623</section>
624
625<!-- Undocumented classes are:
626 allarch.bbclass
627 archive*.bbclass
628 binconfig.bbclass
629 blacklist.bbclass
630 bootimg.bbclass
631 boot-directdisk.bbclass
632 bugzilla.bbclass
633 buildhistory.bbclass
634 buildstats.bbclass
635 ccache.bbclass
636 chrpath.bbclass
637 cmake.bbclass
638 cml1.bbclass
639 copyleft_compliance.bbclass
640 core-image.bbclass
641 cross.bbclass
642 cross-canadian.bbclass
643 crosssdk.bbclass
644 deploy.bbclass
645 distrodata.bbclass
646 dummy.bbclass
647 gconf.bbclass
648 gettext.bbclass
649 gnomebase.bbclass
650 gnome.bbclass
651 gtk-doc.bbclass
652 gtk-icon-cache.bbclass
653 gzipnative.bbclass
654 icecc.bbclass
655 image-empty.bbclass
656 image-live.bbclass
657 image-vmdk.bbclass
658 image-mklibs.bbclass
659 image-prelink.bbclass
660 image-swab.bbclass
661 imagetest-dummy.bbclass
662 imagetest-qemu.bbclass
663 image_types.bbclass
664 image_types_uboot.bbclass
665 insserv.bbclass
666 kernel-arch.bbclass
667 kernel-yocto.bbclass
668 lib_package.bbclass
669 linux-kernel-base.bbclass
670 license.bbclass
671 logging.bbclass
672 meta.bbclass
673 metadata_scm.bbclass
674 mime.bbclass
675 mirrors.bbclass
676 multilib*.bbclass
677 native.bbclass
678 nativesdk.bbclass
679 oelint.bbclass
680 own-mirrors.bbclass
681 packagedata.bbclass
682 packageinfo.bbclass
683 patch.bbclass
684 perlnative.bbclass
685 pkg_distribute.bbclass
686 pkg_metainfo.bbclass
687 populate_sdk*.bbclass
688 prexport.bbclass
689 primport.bbclass
690 prserv.bbclass
691 python-dir.bbclass
692 pythonnative.bbclass
693 qemu.bbclass
694 qmake*.bbclass
695 qt4*.bbclass
696 recipe_sanity.bbclass
697 relocatable.bbclass
698 rm_work.bbclass
699 scons.bbclass
700 sdl.bbclass
701 setuptools.bbclass
702 sip.bbclass
703 siteconfig.bbclass
704 sourcepkg.bbclass
705 sstate.bbclass
706 staging.bbclass
707 syslinux.bbclass
708 terminal.bbclass
709 tinderclient.bbclass
710 toolchain-scripts.bbclass
711 typecheck.bbclass
712 utility-tasks.bbclass
713 utils.bbclass
714-->
715
716
717</chapter>
718<!--
719vim: expandtab tw=80 ts=4
720-->
diff --git a/documentation/poky-ref-manual/ref-features.xml b/documentation/poky-ref-manual/ref-features.xml
deleted file mode 100644
index 77c31275ae..0000000000
--- a/documentation/poky-ref-manual/ref-features.xml
+++ /dev/null
@@ -1,294 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-features'>
6 <title>Reference: Features</title>
7
8 <para>
9 Features provide a mechanism for working out which packages
10 should be included in the generated images.
11 Distributions can select which features they want to support through the
12 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
13 variable, which is set in the <filename>poky.conf</filename> distribution configuration file.
14 Machine features are set in the
15 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
16 variable, which is set in the machine configuration file and
17 specifies the hardware features for a given machine.
18 </para>
19
20 <para>
21 These two variables combine to work out which kernel modules,
22 utilities, and other packages to include.
23 A given distribution can support a selected subset of features so some machine features might not
24 be included if the distribution itself does not support them.
25 </para>
26
27 <para>
28 One method you can use to determine which recipes are checking to see if a
29 particular feature is contained or not is to <filename>grep</filename> through
30 the metadata for the feature.
31 Here is an example that discovers the recipes whose build is potentially
32 changed based on a given feature:
33 <literallayout class='monospaced'>
34 $ cd $HOME/poky
35 $ git grep 'contains.*MACHINE_FEATURES.*&lt;feature&gt;'
36 </literallayout>
37 </para>
38
39 <para>
40 This chapter provides a reference of shipped machine and distro features
41 you can include as part of the image, a reference on image types you can
42 build, and a reference on feature backfilling.
43 </para>
44
45
46 <section id='ref-features-distro'>
47 <title>Distro</title>
48
49 <para>
50 The items below are features you can use with
51 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
52 Features do not have a one-to-one correspondence to packages, and they can
53 go beyond simply controlling the installation of a package or packages.
54 Sometimes a feature can influence how certain recipes are built.
55 For example, a feature might determine whether a particular configure option
56 is specified within <filename>do_configure</filename> for a particular
57 recipe.
58 </para>
59
60 <para>
61 This list only represents features as shipped with the Yocto Project metadata:
62 <itemizedlist>
63 <listitem><para><emphasis>alsa:</emphasis> ALSA support will be included (OSS compatibility
64 kernel modules will be installed if available).</para></listitem>
65 <listitem><para><emphasis>bluetooth:</emphasis> Include bluetooth support (integrated BT only)
66 </para></listitem>
67 <listitem><para><emphasis>ext2:</emphasis> Include tools for supporting for devices with internal
68 HDD/Microdrive for storing files (instead of Flash only devices)
69 </para></listitem>
70 <listitem><para><emphasis>irda:</emphasis> Include Irda support
71 </para></listitem>
72 <listitem><para><emphasis>keyboard:</emphasis> Include keyboard support (e.g. keymaps will be
73 loaded during boot).
74 </para></listitem>
75 <listitem><para><emphasis>pci:</emphasis> Include PCI bus support
76 </para></listitem>
77 <listitem><para><emphasis>pcmcia:</emphasis> Include PCMCIA/CompactFlash support
78 </para></listitem>
79 <listitem><para><emphasis>usbgadget:</emphasis> USB Gadget Device support (for USB
80 networking/serial/storage)
81 </para></listitem>
82 <listitem><para><emphasis>usbhost:</emphasis> USB Host support (allows to connect external
83 keyboard, mouse, storage, network etc)
84 </para></listitem>
85 <listitem><para><emphasis>wifi:</emphasis> WiFi support (integrated only)
86 </para></listitem>
87 <listitem><para><emphasis>cramfs:</emphasis> CramFS support
88 </para></listitem>
89 <listitem><para><emphasis>ipsec:</emphasis> IPSec support
90 </para></listitem>
91 <listitem><para><emphasis>ipv6:</emphasis> IPv6 support
92 </para></listitem>
93 <listitem><para><emphasis>nfs:</emphasis> NFS client support (for mounting NFS exports on
94 device)</para></listitem>
95 <listitem><para><emphasis>ppp:</emphasis> PPP dialup support</para></listitem>
96 <listitem><para><emphasis>smbfs:</emphasis> SMB networks client support (for mounting
97 Samba/Microsoft Windows shares on device)</para></listitem>
98 </itemizedlist>
99 </para>
100 </section>
101
102 <section id='ref-features-machine'>
103 <title>Machine</title>
104
105 <para>
106 The items below are features you can use with
107 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>.
108 Features do not have a one-to-one correspondence to packages, and they can
109 go beyond simply controlling the installation of a package or packages.
110 Sometimes a feature can influence how certain recipes are built.
111 For example, a feature might determine whether a particular configure option
112 is specified within <filename>do_configure</filename> for a particular
113 recipe.
114 </para>
115
116 <para>
117 This feature list only represents features as shipped with the Yocto Project metadata:
118 <itemizedlist>
119 <listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only)
120 </para></listitem>
121 <listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers
122 </para></listitem>
123 <listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation)
124 </para></listitem>
125 <listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT
126 </para></listitem>
127 <listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive
128 </para></listitem>
129 <listitem><para><emphasis>irda:</emphasis> Hardware has Irda support
130 </para></listitem>
131 <listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard
132 </para></listitem>
133 <listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus
134 </para></listitem>
135 <listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets
136 </para></listitem>
137 <listitem><para><emphasis>screen:</emphasis> Hardware has a screen
138 </para></listitem>
139 <listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232)
140 </para></listitem>
141 <listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen
142 </para></listitem>
143 <listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable
144 </para></listitem>
145 <listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable
146 </para></listitem>
147 <listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi
148 </para></listitem>
149 </itemizedlist>
150 </para>
151 </section>
152
153 <section id='ref-features-image'>
154 <title>Images</title>
155
156 <para>
157 The contents of images generated by the OpenEmbedded build system can be controlled by the
158 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
159 and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename>
160 variables that you typically configure in your image recipes.
161 Through these variables you can add several different
162 predefined packages such as development utilities or packages with debug
163 information needed to investigate application problems or profile applications.
164 </para>
165
166 <para>
167 Current list of
168 <filename>IMAGE_FEATURES</filename> contains the following:
169 <itemizedlist>
170 <listitem><para><emphasis>splash:</emphasis> Enables showing a splash screen during boot.
171 By default, this screen is provided by <filename>psplash</filename>, which does
172 allow customization.
173 If you prefer to use an alternative splash screen package, you can do so by
174 setting the <filename>SPLASH</filename> variable
175 to a different package name (or names) within the image recipe or at the distro
176 configuration level.</para></listitem>
177 <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal
178 SSH server.
179 </para></listitem>
180 <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server,
181 which is more full-featured than Dropbear.
182 Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server
183 are present in <filename>IMAGE_FEATURES</filename>, then OpenSSH will take
184 precedence and Dropbear will not be installed.</para></listitem>
185 <listitem><para><emphasis>x11:</emphasis> Installs the X server</para></listitem>
186 <listitem><para><emphasis>x11-base:</emphasis> Installs the X server with a
187 minimal environment.</para></listitem>
188 <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment.
189 </para></listitem>
190 <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device.
191 </para></listitem>
192 <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as
193 <filename>strace</filename> and <filename>gdb</filename>.
194 </para></listitem>
195 <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as
196 <filename>oprofile</filename>, <filename>exmap</filename>, and
197 <filename>LTTng</filename>.</para></listitem>
198 <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g.
199 touchscreen debugging).</para></listitem>
200 <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</para></listitem>
201 <listitem><para><emphasis>dev-pkgs:</emphasis> Installs development packages (headers and
202 extra library links) for all packages installed in a given image.</para></listitem>
203 <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development
204 packages (i.e. static libraries containing <filename>*.a</filename> files) for all
205 packages installed in a given image.</para></listitem>
206 <listitem><para><emphasis>dbg-pkgs:</emphasis> Installs debug symbol packages for all packages
207 installed in a given image.</para></listitem>
208 <listitem><para><emphasis>doc-pkgs:</emphasis> Installs documentation packages for all packages
209 installed in a given image.</para></listitem>
210 </itemizedlist>
211 </para>
212 </section>
213
214 <section id='ref-features-backfill'>
215 <title>Feature Backfilling</title>
216
217 <para>
218 Sometimes it is necessary in the OpenEmbedded build system to extend
219 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
220 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
221 to control functionality that was previously enabled and not able
222 to be disabled.
223 For these cases, we need to add an
224 additional feature item to appear in one of these variables,
225 but we do not want to force developers who have existing values
226 of the variables in their configuration to add the new feature
227 in order to retain the same overall level of functionality.
228 Thus, the OpenEmbedded build system has a mechanism to
229 automatically "backfill" these added features into existing
230 distro or machine configurations.
231 You can see the list of features for which this is done by
232 finding the
233 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
234 and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
235 variables in the <filename>meta/conf/bitbake.conf</filename> file.
236 </para>
237
238 <para>
239 Because such features are backfilled by default into all
240 configurations as described in the previous paragraph, developers
241 who wish to disable the new features need to be able to selectively
242 prevent the backfilling from occurring.
243 They can do this by adding the undesired feature or features to the
244 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
245 or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
246 variables for distro features and machine features respectively.
247 </para>
248
249 <para>
250 Here are two examples to help illustrate feature backfilling:
251 <itemizedlist>
252 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
253 Previously, PulseAudio support was enabled within the Qt and
254 GStreamer frameworks.
255 Because of this, the feature is backfilled and thus
256 enabled for all distros through the
257 <filename>DISTRO_FEATURES_BACKFILL</filename>
258 variable in the <filename>meta/conf/bitbake.conf</filename> file.
259 However, your distro needs to disable the feature.
260 You can disable the feature without affecting
261 other existing distro configurations that need PulseAudio support
262 by adding "pulseaudio" to
263 <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
264 in your distro's <filename>.conf</filename> file.
265 Adding the feature to this variable when it also
266 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
267 variable prevents the build system from adding the feature to
268 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
269 the feature for that particular distro.</para></listitem>
270 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
271 Previously, real time clock (RTC) support was enabled for all
272 target devices.
273 Because of this, the feature is backfilled and thus enabled
274 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
275 variable in the <filename>meta/conf/bitbake.conf</filename> file.
276 However, your target device does not have this capability.
277 You can disable RTC support for your device without
278 affecting other machines that need RTC support
279 by adding the feature to your machine's
280 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
281 list in the machine's <filename>.conf</filename> file.
282 Adding the feature to this variable when it also
283 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
284 variable prevents the build system from adding the feature to
285 your configuration's <filename>MACHINE_FEATURES</filename>, effectively
286 disabling RTC support for that particular machine.</para></listitem>
287 </itemizedlist>
288 </para>
289 </section>
290</chapter>
291
292<!--
293vim: expandtab tw=80 ts=4 spell spelllang=en_gb
294-->
diff --git a/documentation/poky-ref-manual/ref-images.xml b/documentation/poky-ref-manual/ref-images.xml
deleted file mode 100644
index 0a827ca235..0000000000
--- a/documentation/poky-ref-manual/ref-images.xml
+++ /dev/null
@@ -1,132 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-images'>
6 <title>Images</title>
7
8 <para>
9 The OpenEmbedded build process supports several types of images to satisfy different needs.
10 When you issue the <filename>bitbake</filename> command you provide a “top-level” recipe
11 that essentially begins the build for the type of image you want.
12 </para>
13
14 <note>
15 Building an image without GNU General Public License Version 3 (GPLv3) components
16 is only supported for minimal and base images.
17 Furthermore, if you are going to build an image using non-GPLv3 components,
18 you must make the following changes in the <filename>local.conf</filename> file
19 before using the BitBake command to build the minimal or base image:
20 <literallayout class='monospaced'>
21 1. Comment out the EXTRA_IMAGE_FEATURES line
22 2. Set INCOMPATIBLE_LICENSE = "GPLv3"
23 </literallayout>
24 </note>
25
26 <para>
27 From within the <filename>poky</filename> Git repository, use the following command to list
28 the supported images:
29 <literallayout class='monospaced'>
30 $ ls meta*/recipes*/images/*.bb
31 </literallayout>
32 These recipes reside in the <filename>meta/recipes-core/images</filename>,
33 <filename>meta/recipes-extended/images</filename>,
34 <filename>meta/recipes-graphics/images</filename>, and
35 <filename>meta/recipes-sato/images</filename> directories
36 within the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>.
37 Although the recipe names are somewhat explanatory, here is a list that describes them:
38 </para>
39
40 <itemizedlist>
41 <listitem><para><emphasis><filename>core-image-base</filename>:</emphasis>
42 A console-only image that fully supports the target device hardware.</para></listitem>
43 <listitem><para><emphasis><filename>core-image-minimal</filename>:</emphasis>
44 A small image just capable of allowing a device to boot.</para></listitem>
45 <listitem><para><emphasis><filename>core-image-minimal-dev</filename>:</emphasis>
46 A <filename>core-image-minimal</filename> image suitable for development work
47 using the host.
48 The image includes headers and libraries you can use in a host development
49 environment.
50 </para></listitem>
51 <listitem><para><emphasis><filename>core-image-minimal-initramfs</filename>:</emphasis>
52 A <filename>core-image-minimal</filename> image that has the Minimal RAM-based
53 Initial Root Filesystem (<filename>initramfs</filename>) as part of the kernel,
54 which allows the system to find the first “init” program more efficiently.
55 </para></listitem>
56 <listitem><para><emphasis><filename>core-image-minimal-mtdutils</filename>:</emphasis>
57 A <filename>core-image-minimal</filename> image that has support
58 for the Minimal MTD Utilities, which let the user interact with the
59 MTD subsystem in the kernel to perform operations on flash devices.
60 </para></listitem>
61 <listitem><para><emphasis><filename>core-image-x11</filename>:</emphasis>
62 A very basic X11 image with a terminal.
63 </para></listitem>
64 <listitem><para><emphasis><filename>core-image-basic</filename>:</emphasis>
65 A console-only image with more full-featured Linux system
66 functionality installed.</para></listitem>
67 <listitem><para><emphasis><filename>core-image-lsb</filename>:</emphasis>
68 An image that conforms to the Linux Standard Base (LSB) specification.</para></listitem>
69 <listitem><para><emphasis><filename>core-image-lsb-dev</filename>:</emphasis>
70 A <filename>core-image-lsb</filename> image that is suitable for development work
71 using the host.
72 The image includes headers and libraries you can use in a host development
73 environment.
74 </para></listitem>
75 <listitem><para><emphasis><filename>core-image-lsb-sdk</filename>:</emphasis>
76 A <filename>core-image-lsb</filename> that includes everything in meta-toolchain
77 but also includes development headers and libraries to form a complete standalone SDK.
78 This image is suitable for development using the target.</para></listitem>
79 <listitem><para><emphasis><filename>core-image-clutter</filename>:</emphasis>
80 An image with support for the Open GL-based toolkit Clutter, which enables development of
81 rich and animated graphical user interfaces.</para></listitem>
82 <listitem><para><emphasis><filename>core-image-sato</filename>:</emphasis>
83 An image with Sato support, a mobile environment and visual style that works well
84 with mobile devices.
85 The image supports X11 with a Sato theme and applications such as
86 a terminal, editor, file manager, media player, and so forth.</para></listitem>
87 <listitem><para><emphasis><filename>core-image-sato-dev</filename>:</emphasis>
88 A <filename>core-image-sato</filename> image suitable for development
89 using the host.
90 The image includes libraries needed to build applications on the device itself,
91 testing and profiling tools, and debug symbols.
92 This image was formerly <filename>core-image-sdk</filename>.</para></listitem>
93 <listitem><para><emphasis><filename>core-image-sato-sdk</filename>:</emphasis>
94 A <filename>core-image-sato</filename> image that includes everything in meta-toolchain.
95 The image also includes development headers and libraries to form a complete standalone SDK
96 and is suitable for development using the target.</para></listitem>
97 <listitem><para><emphasis><filename>core-image-rt</filename>:</emphasis>
98 A <filename>core-image-minimal</filename> image plus a real-time test suite and
99 tools appropriate for real-time use.</para></listitem>
100 <listitem><para><emphasis><filename>core-image-rt-sdk</filename>:</emphasis>
101 A <filename>core-image-rt</filename> image that includes everything in
102 <filename>meta-toolchain</filename>.
103 The image also includes development headers and libraries to form a complete
104 stand-alone SDK and is suitable for development using the target.</para></listitem>
105 <listitem><para><emphasis><filename>core-image-gtk-directfb</filename>:</emphasis>
106 An image that uses <filename>gtk+</filename> over <filename>directfb</filename>
107 instead of X11.
108 In order to build, this image requires specific distro configuration that enables
109 <filename>gtk</filename> over <filename>directfb</filename>.</para></listitem>
110 <listitem><para><emphasis><filename>build-appliance-image</filename>:</emphasis>
111 An image you can boot and run using either the
112 <ulink url='http://www.vmware.com/products/player/overview.html'>VMware Player</ulink>
113 or <ulink url='http://www.vmware.com/products/workstation/overview.html'>VMware Workstation</ulink>.
114 For more information on this image, see the
115 <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink> page on
116 the Yocto Project website.</para></listitem>
117 </itemizedlist>
118
119 <tip>
120 From the Yocto Project release 1.1 onwards, <filename>-live</filename> and
121 <filename>-directdisk</filename> images have been replaced by a "live"
122 option in <filename>IMAGE_FSTYPES</filename> that will work with any image to produce an
123 image file that can be
124 copied directly to a CD or USB device and run as is.
125 To build a live image, simply add
126 "live" to <filename>IMAGE_FSTYPES</filename> within the <filename>local.conf</filename>
127 file or wherever appropriate and then build the desired image as normal.
128 </tip>
129</chapter>
130<!--
131vim: expandtab tw=80 ts=4
132-->
diff --git a/documentation/poky-ref-manual/ref-structure.xml b/documentation/poky-ref-manual/ref-structure.xml
deleted file mode 100644
index ea48299600..0000000000
--- a/documentation/poky-ref-manual/ref-structure.xml
+++ /dev/null
@@ -1,709 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-structure'>
6
7<title>Source Directory Structure</title>
8
9<para>
10 The <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> consists of several components.
11 Understanding them and knowing where they are located is key to using the Yocto Project well.
12 This chapter describes the Source Directory and gives information about the various
13 files and directories.
14</para>
15
16<para>
17 For information on how to establish a local Source Directory on your development system, see the
18 "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"
19 section in the Yocto Project Development Manual.
20</para>
21
22<note>
23 The OpenEmbedded build system does not support file or directory names that
24 contain spaces.
25 Be sure that the Source Directory you use does not contain these types
26 of names.
27</note>
28
29<section id='structure-core'>
30 <title>Top level core components</title>
31
32 <section id='structure-core-bitbake'>
33 <title><filename>bitbake/</filename></title>
34
35 <para>
36 The <ulink url='source-directory'>Source Directory</ulink>
37 includes a copy of BitBake for ease of use.
38 The copy usually matches the current stable BitBake release from the BitBake project.
39 BitBake, a metadata interpreter, reads the Yocto Project metadata and runs the tasks
40 defined by that data.
41 Failures are usually from the metadata and not from BitBake itself.
42 Consequently, most users do not need to worry about BitBake.
43 </para>
44
45 <para>
46 When you run the <filename>bitbake</filename> command, the wrapper script in
47 <filename>scripts/</filename> is executed to run the main BitBake executable,
48 which resides in the <filename>bitbake/bin/</filename> directory.
49 Sourcing the <link linkend="structure-core-script">&OE_INIT_FILE;</link>
50 script places the <filename>scripts</filename> and <filename>bitbake/bin</filename>
51 directories (in that order) into the shell's <filename>PATH</filename> environment
52 variable.
53 </para>
54
55 <para>
56 For more information on BitBake, see the BitBake documentation
57 inculded in the <filename>bitbake/doc/manual</filename> directory of the
58 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
59 </para>
60 </section>
61
62 <section id='structure-core-build'>
63 <title><filename>build/</filename></title>
64
65 <para>
66 This directory contains user configuration files and the output
67 generated by the OpenEmbedded build system in its standard configuration where
68 the source tree is combined with the output.
69 The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
70 is created initially when you <filename>source</filename>
71 the OpenEmbedded build environment setup script <filename>&OE_INIT_FILE;</filename>.
72 </para>
73
74 <para>
75 It is also possible to place output and configuration
76 files in a directory separate from the
77 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
78 by providing a directory name when you <filename>source</filename>
79 the setup script.
80 For information on separating output from your local Source Directory files, see <link
81 linkend='structure-core-script'>&OE_INIT_FILE;</link>.
82 </para>
83 </section>
84
85 <section id='handbook'>
86 <title><filename>documentation</filename></title>
87
88 <para>
89 This directory holds the source for the Yocto Project documentation
90 as well as templates and tools that allow you to generate PDF and HTML
91 versions of the manuals.
92 Each manual is contained in a sub-folder.
93 For example, the files for this manual reside in
94 <filename>poky-ref-manual</filename>.
95 </para>
96 </section>
97
98 <section id='structure-core-meta'>
99 <title><filename>meta/</filename></title>
100
101 <para>
102 This directory contains the OpenEmbedded Core metadata.
103 The directory holds recipes, common classes, and machine
104 configuration for emulated targets (qemux86, qemuarm,
105 and so on.)
106 </para>
107 </section>
108
109 <section id='structure-core-meta-yocto'>
110 <title><filename>meta-yocto/</filename></title>
111
112 <para>
113 This directory contains the configuration for the Poky
114 reference distribution.
115 </para>
116 </section>
117
118 <section id='structure-core-meta-yocto-bsp'>
119 <title><filename>meta-yocto-bsp/</filename></title>
120
121 <para>
122 This directory contains the Yocto Project reference
123 hardware BSPs.
124 </para>
125 </section>
126
127 <section id='structure-meta-hob'>
128 <title><filename>meta-hob/</filename></title>
129
130 <para>
131 This directory contains template recipes used by the
132 <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink>
133 build UI.
134 </para>
135 </section>
136
137 <section id='structure-meta-skeleton'>
138 <title><filename>meta-skeleton/</filename></title>
139
140 <para>
141 This directory contains template recipes for BSP and kernel development.
142 </para>
143 </section>
144
145 <section id='structure-core-scripts'>
146 <title><filename>scripts/</filename></title>
147
148 <para>
149 This directory contains various integration scripts that implement
150 extra functionality in the Yocto Project environment (e.g. QEMU scripts).
151 The <link linkend="structure-core-script">&OE_INIT_FILE;</link> script appends this
152 directory to the shell's <filename>PATH</filename> environment variable.
153 </para>
154
155 <para>
156 The <filename>scripts</filename> directory has useful scripts that assist contributing
157 back to the Yocto Project, such as <filename>create_pull_request</filename> and
158 <filename>send_pull_request</filename>.
159 </para>
160 </section>
161
162 <section id='structure-core-script'>
163 <title><filename>&OE_INIT_FILE;</filename></title>
164
165 <para>
166 This script sets up the OpenEmbedded build environment.
167 Running this script with the <filename>source</filename> command in
168 a shell makes changes to <filename>PATH</filename> and sets other core BitBake variables based on the
169 current working directory.
170 You need to run this script before running BitBake commands.
171 The script uses other scripts within the <filename>scripts</filename> directory to do
172 the bulk of the work.
173 </para>
174
175 <para>
176 By default, running this script without a Build Directory argument creates the
177 <filename>build</filename> directory.
178 If you provide a Build Directory argument when you <filename>source</filename>
179 the script, you direct OpenEmbedded build system to create a
180 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> of your choice.
181 For example, the following command creates a Build Directory named
182 <filename>mybuilds</filename> that is outside of the
183 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
184 <literallayout class='monospaced'>
185 $ source &OE_INIT_FILE; ~/mybuilds
186 </literallayout>
187 <note>
188 The OpenEmbedded build system does not support file or directory names that
189 contain spaces.
190 If you attempt to run the <filename>&OE_INIT_FILE;</filename> script
191 from a Source Directory that contains spaces in either the filenames
192 or directory names, the script returns an error indicating no such
193 file or directory.
194 Be sure to use a Source Directory free of names containing spaces.
195 </note>
196 </para>
197 </section>
198
199 <section id='structure-basic-top-level'>
200 <title><filename>LICENSE, README, and README.hardware</filename></title>
201
202 <para>
203 These files are standard top-level files.
204 </para>
205 </section>
206</section>
207
208<section id='structure-build'>
209 <title>The Build Directory - <filename>build/</filename></title>
210
211 <section id='structure-build-pseudodone'>
212 <title><filename>build/pseudodone</filename></title>
213
214 <para>
215 This tag file indicates that the initial pseudo binary was created.
216 The file is built the first time BitBake is invoked.
217 </para>
218 </section>
219
220 <section id='structure-build-conf-local.conf'>
221 <title><filename>build/conf/local.conf</filename></title>
222
223 <para>
224 This file contains all the local user configuration for your build environment.
225 If there is no <filename>local.conf</filename> present, it is created from
226 <filename>local.conf.sample</filename>.
227 The <filename>local.conf</filename> file contains documentation on the various configuration options.
228 Any variable set here overrides any variable set elsewhere within the environment unless
229 that variable is hard-coded within a file (e.g. by using '=' instead of '?=').
230 Some variables are hard-coded for various reasons but these variables are
231 relatively rare.
232 </para>
233
234 <para>
235 Edit this file to set the <filename><link linkend='var-MACHINE'>MACHINE</link></filename>
236 for which you want to build, which package types you wish to use
237 (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
238 where you want to downloaded files
239 (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>),
240 and how you want your host machine to use resources
241 (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> and
242 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>).
243 </para>
244 </section>
245
246 <section id='structure-build-conf-bblayers.conf'>
247 <title><filename>build/conf/bblayers.conf</filename></title>
248
249 <para>
250 This file defines layers, which are directory trees, traversed (or walked) by BitBake.
251 If <filename>bblayers.conf</filename>
252 is not present, it is created from <filename>bblayers.conf.sample</filename> when
253 you <filename>source</filename> the environment setup script.
254 </para>
255
256 <para>
257 The <filename>bblayers.conf</filename> file uses the
258 <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link> variable to
259 list the layers BitBake tries to find.
260 The file uses the
261 <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link>
262 variable to list layers that must not be removed.
263 </para>
264 </section>
265
266 <section id='structure-build-conf-sanity_info'>
267 <title><filename>build/conf/sanity_info</filename></title>
268
269 <para>
270 This file is created during the build to indicate the state of the sanity checks.
271 </para>
272 </section>
273
274 <section id='structure-build-downloads'>
275 <title><filename>build/downloads/</filename></title>
276
277 <para>
278 This directory is used for the upstream source tarballs.
279 The directory can be reused by multiple builds or moved to another location.
280 You can control the location of this directory through the
281 <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable.
282 </para>
283 </section>
284
285 <section id='structure-build-sstate-cache'>
286 <title><filename>build/sstate-cache/</filename></title>
287
288 <para>
289 This directory is used for the shared state cache.
290 The directory can be reused by multiple builds or moved to another location.
291 You can control the location of this directory through the
292 <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable.
293 </para>
294 </section>
295
296 <section id='structure-build-tmp'>
297 <title><filename>build/tmp/</filename></title>
298
299 <para>
300 This directory receives all the OpenEmbedded build system's output.
301 BitBake creates this directory if it does not exist.
302 As a last resort, to clean up a build and start it from scratch (other than the downloads),
303 you can remove everything in the <filename>tmp</filename> directory or get rid of the
304 directory completely.
305 If you do, you should also completely remove the <filename>build/sstate-cache</filename>
306 directory as well.
307 </para>
308 </section>
309
310 <section id='structure-build-tmp-buildstats'>
311 <title><filename>build/tmp/buildstats/</filename></title>
312
313 <para>
314 This directory stores the build statistics.
315 </para>
316 </section>
317
318 <section id='structure-build-tmp-cache'>
319 <title><filename>build/tmp/cache/</filename></title>
320
321 <para>
322 When BitBake parses the metadata, it creates a cache file of the result that can
323 be used when subsequently running commands.
324 These results are stored here on a per-machine basis.
325 </para>
326 </section>
327
328 <section id='structure-build-tmp-deploy'>
329 <title><filename>build/tmp/deploy/</filename></title>
330
331 <para>
332 This directory contains any 'end result' output from the OpenEmbedded build process.
333 </para>
334 </section>
335
336 <section id='structure-build-tmp-deploy-deb'>
337 <title><filename>build/tmp/deploy/deb/</filename></title>
338
339 <para>
340 This directory receives any <filename>.deb</filename> packages produced by
341 the build process.
342 The packages are sorted into feeds for different architecture types.
343 </para>
344 </section>
345
346 <section id='structure-build-tmp-deploy-rpm'>
347 <title><filename>build/tmp/deploy/rpm/</filename></title>
348
349 <para>
350 This directory receives any <filename>.rpm</filename> packages produced by
351 the build process.
352 The packages are sorted into feeds for different architecture types.
353 </para>
354 </section>
355
356 <section id='structure-build-tmp-deploy-licenses'>
357 <title><filename>build/tmp/deploy/licenses/</filename></title>
358
359 <para>
360 This directory receives package licensing information.
361 For example, the directory contains sub-directories for <filename>bash</filename>,
362 <filename>busybox</filename>, and <filename>eglibc</filename> (among others) that in turn
363 contain appropriate <filename>COPYING</filename> license files with other licensing information.
364 </para>
365 </section>
366
367 <section id='structure-build-tmp-deploy-images'>
368 <title><filename>build/tmp/deploy/images/</filename></title>
369
370 <para>
371 This directory receives complete filesystem images.
372 If you want to flash the resulting image from a build onto a device, look here for the image.
373 </para>
374
375 <para>
376 Be careful when deleting files in this directory.
377 You can safely delete old images from this directory (e.g.
378 <filename>core-image-*</filename>, <filename>hob-image-*</filename>,
379 etc.).
380 However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, etc.),
381 bootloader and other supplementary files might be deployed here prior to building an
382 image.
383 Because these files, however, are not directly produced from the image, if you
384 delete them they will not be automatically re-created when you build the image again.
385 </para>
386
387 <para>
388 If you do accidentally delete files here, you will need to force them to be
389 re-created.
390 In order to do that, you will need to know the target that produced them.
391 For example, these commands rebuild and re-create the kernel files:
392 <literallayout class='monospaced'>
393 $ bitbake -c clean virtual/kernel
394 $ bitbake virtual/kernel
395 </literallayout>
396 </para>
397 </section>
398
399 <section id='structure-build-tmp-deploy-ipk'>
400 <title><filename>build/tmp/deploy/ipk/</filename></title>
401
402 <para>
403 This directory receives <filename>.ipk</filename> packages produced by
404 the build process.</para>
405 </section>
406
407 <section id='structure-build-tmp-sysroots'>
408 <title><filename>build/tmp/sysroots/</filename></title>
409
410 <para>
411 This directory contains shared header files and libraries as well as other shared
412 data.
413 Packages that need to share output with other packages do so within this directory.
414 The directory is subdivided by architecture so multiple builds can run within
415 the one Build Directory.
416 </para>
417 </section>
418
419 <section id='structure-build-tmp-stamps'>
420 <title><filename>build/tmp/stamps/</filename></title>
421
422 <para>
423 This directory holds information that BitBake uses for accounting purposes
424 to track what tasks have run and when they have run.
425 The directory is sub-divided by architecture, package name, and
426 version.
427 Following is an example:
428 <literallayout class='monospaced'>
429 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
430 </literallayout>
431 Although the files in the directory are empty of data,
432 BitBake uses the filenames and timestamps for tracking purposes.
433 </para>
434 </section>
435
436 <section id='structure-build-tmp-log'>
437 <title><filename>build/tmp/log/</filename></title>
438
439 <para>
440 This directory contains general logs that are not otherwise placed using the
441 package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
442 Examples of logs are the output from the <filename>check_pkg</filename> or
443 <filename>distro_check</filename> tasks.
444 Running a build does not necessarily mean this directory is created.
445 </para>
446 </section>
447
448 <section id='structure-build-tmp-pkgdata'>
449 <title><filename>build/tmp/pkgdata/</filename></title>
450
451 <para>
452 This directory contains intermediate packaging data that is used later in the packaging process.
453 For more information, see the "<link linkend='ref-classes-package'>Packaging - package*.bbclass</link>" section.
454 </para>
455 </section>
456
457 <section id='structure-build-tmp-work'>
458 <title><filename>build/tmp/work/</filename></title>
459
460 <para>
461 This directory contains architecture-specific work sub-directories
462 for packages built by BitBake.
463 All tasks execute from the appropriate work directory.
464 For example, the source for a particular package is unpacked,
465 patched, configured and compiled all within its own work directory.
466 Within the work directory, organization is based on the package group
467 and version for which the source is being compiled
468 as defined by the
469 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
470 </para>
471
472 <para>
473 It is worth considering the structure of a typical work directory.
474 As an example, consider the <filename>linux-yocto-kernel-3.0</filename>
475 on the machine <filename>qemux86</filename>
476 built within the Yocto Project.
477 For this package, a work directory of
478 <filename>tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+&lt;.....&gt;</filename>,
479 referred to as the
480 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, is created.
481 Within this directory, the source is unpacked to
482 <filename>linux-qemux86-standard-build</filename> and then patched by Quilt
483 (see the
484 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Modifying Package
485 Source Code with Quilt</ulink>" section in the Yocto Project Development Manual.
486 Within the <filename>linux-qemux86-standard-build</filename> directory,
487 standard Quilt directories <filename>linux-3.0/patches</filename>
488 and <filename>linux-3.0/.pc</filename> are created,
489 and standard Quilt commands can be used.
490 </para>
491
492 <para>
493 There are other directories generated within <filename>WORKDIR</filename>.
494 The most important directory is <filename>WORKDIR/temp/</filename>,
495 which has log files for each task (<filename>log.do_*.pid</filename>)
496 and contains the scripts BitBake runs for each task
497 (<filename>run.do_*.pid</filename>).
498 The <filename>WORKDIR/image/</filename> directory is where "make
499 install" places its output that is then split into sub-packages
500 within <filename>WORKDIR/packages-split/</filename>.
501 </para>
502 </section>
503</section>
504
505<section id='structure-meta'>
506 <title>The Metadata - <filename>meta/</filename></title>
507
508 <para>
509 As mentioned previously, metadata is the core of the Yocto Project.
510 Metadata has several important subdivisions:
511 </para>
512
513 <section id='structure-meta-classes'>
514 <title><filename>meta/classes/</filename></title>
515
516 <para>
517 This directory contains the <filename>*.bbclass</filename> files.
518 Class files are used to abstract common code so it can be reused by multiple
519 packages.
520 Every package inherits the <filename>base.bbclass</filename> file.
521 Examples of other important classes are <filename>autotools.bbclass</filename>, which
522 in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort.
523 Another example is <filename>kernel.bbclass</filename> that contains common code and functions
524 for working with the Linux kernel.
525 Functions like image generation or packaging also have their specific class files
526 such as <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and
527 <filename>package*.bbclass</filename>.
528 </para>
529 </section>
530
531 <section id='structure-meta-conf'>
532 <title><filename>meta/conf/</filename></title>
533
534 <para>
535 This directory contains the core set of configuration files that start from
536 <filename>bitbake.conf</filename> and from which all other configuration
537 files are included.
538 See the include statements at the end of the file and you will note that even
539 <filename>local.conf</filename> is loaded from there.
540 While <filename>bitbake.conf</filename> sets up the defaults, you can often override
541 these by using the (<filename>local.conf</filename>) file, machine file or
542 the distribution configuration file.
543 </para>
544 </section>
545
546 <section id='structure-meta-conf-machine'>
547 <title><filename>meta/conf/machine/</filename></title>
548
549 <para>
550 This directory contains all the machine configuration files.
551 If you set <filename>MACHINE="qemux86"</filename>,
552 the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this
553 directory.
554 The <filename>include</filename> directory contains various data common to multiple machines.
555 If you want to add support for a new machine to the Yocto Project, look in this directory.
556 </para>
557 </section>
558
559 <section id='structure-meta-conf-distro'>
560 <title><filename>meta/conf/distro/</filename></title>
561
562 <para>
563 Any distribution-specific configuration is controlled from this directory.
564 For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here.
565 This directory includes the versions and the
566 <filename>SRCDATE</filename> definitions for applications that are configured here.
567 An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>.
568 Although this file mainly inherits its configuration from Poky.
569 </para>
570 </section>
571
572 <section id='structure-meta-recipes-bsp'>
573 <title><filename>meta/recipes-bsp/</filename></title>
574
575 <para>
576 This directory contains anything linking to specific hardware or hardware
577 configuration information such as "u-boot" and "grub".
578 </para>
579 </section>
580
581 <section id='structure-meta-recipes-connectivity'>
582 <title><filename>meta/recipes-connectivity/</filename></title>
583
584 <para>
585 This directory contains libraries and applications related to communication with other devices.
586 </para>
587 </section>
588
589 <section id='structure-meta-recipes-core'>
590 <title><filename>meta/recipes-core/</filename></title>
591
592 <para>
593 This directory contains what is needed to build a basic working Linux image
594 including commonly used dependencies.
595 </para>
596 </section>
597
598 <section id='structure-meta-recipes-devtools'>
599 <title><filename>meta/recipes-devtools/</filename></title>
600
601 <para>
602 This directory contains tools that are primarily used by the build system.
603 The tools, however, can also be used on targets.
604 </para>
605 </section>
606
607 <section id='structure-meta-recipes-extended'>
608 <title><filename>meta/recipes-extended/</filename></title>
609
610 <para>
611 This directory contains non-essential applications that add features compared to the
612 alternatives in core.
613 You might need this directory for full tool functionality or for Linux Standard Base (LSB)
614 compliance.
615 </para>
616 </section>
617
618 <section id='structure-meta-recipes-gnome'>
619 <title><filename>meta/recipes-gnome/</filename></title>
620
621 <para>
622 This directory contains all things related to the GTK+ application framework.
623 </para>
624 </section>
625
626 <section id='structure-meta-recipes-graphics'>
627 <title><filename>meta/recipes-graphics/</filename></title>
628
629 <para>
630 This directory contains X and other graphically related system libraries
631 </para>
632 </section>
633
634 <section id='structure-meta-recipes-kernel'>
635 <title><filename>meta/recipes-kernel/</filename></title>
636
637 <para>
638 This directory contains the kernel and generic applications and libraries that
639 have strong kernel dependencies.
640 </para>
641 </section>
642
643 <section id='structure-meta-recipes-multimedia'>
644 <title><filename>meta/recipes-multimedia/</filename></title>
645
646 <para>
647 This directory contains codecs and support utilities for audio, images and video.
648 </para>
649 </section>
650
651 <section id='structure-meta-recipes-qt'>
652 <title><filename>meta/recipes-qt/</filename></title>
653
654 <para>
655 This directory contains all things related to the Qt application framework.
656 </para>
657 </section>
658
659 <section id='structure-meta-recipes-rt'>
660 <title><filename>meta/recipes-rt/</filename></title>
661
662 <para>
663 This directory contains package and image recipes for using and testing
664 the <filename>PREEMPT_RT</filename> kernel.
665 </para>
666 </section>
667
668 <section id='structure-meta-recipes-sato'>
669 <title><filename>meta/recipes-sato/</filename></title>
670
671 <para>
672 This directory contains the Sato demo/reference UI/UX and its associated applications
673 and configuration data.
674 </para>
675 </section>
676
677 <section id='structure-meta-recipes-support'>
678 <title><filename>meta/recipes-support/</filename></title>
679
680 <para>
681 This directory contains recipes that used by other recipes, but that are not directly
682 included in images (i.e. dependencies of other recipes).
683 </para>
684 </section>
685
686 <section id='structure-meta-site'>
687 <title><filename>meta/site/</filename></title>
688
689 <para>
690 This directory contains a list of cached results for various architectures.
691 Because certain "autoconf" test results cannot be determined when cross-compiling due to
692 the tests not able to run on a live system, the information in this directory is
693 passed to "autoconf" for the various architectures.
694 </para>
695 </section>
696
697 <section id='structure-meta-recipes-txt'>
698 <title><filename>meta/recipes.txt</filename></title>
699
700 <para>
701 This file is a description of the contents of <filename>recipes-*</filename>.
702 </para>
703 </section>
704</section>
705
706</chapter>
707<!--
708vim: expandtab tw=80 ts=4
709-->
diff --git a/documentation/poky-ref-manual/ref-style.css b/documentation/poky-ref-manual/ref-style.css
deleted file mode 100644
index e896a39d33..0000000000
--- a/documentation/poky-ref-manual/ref-style.css
+++ /dev/null
@@ -1,979 +0,0 @@
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: #00557D;
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: bold;
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: bold;
94}
95
96h4 {
97 margin: 1em 0em 0.5em 0em;
98 padding: 1em 0em 0em 0em;
99 font-size: 120%;
100 font-weight: bold;
101}
102
103h5 {
104 margin: 1em 0em 0.5em 0em;
105 padding: 1em 0em 0em 0em;
106 font-size: 110%;
107 font-weight: bold;
108}
109
110h6 {
111 margin: 1em 0em 0em 0em;
112 padding: 1em 0em 0em 0em;
113 font-size: 110%;
114 font-weight: bold;
115}
116
117.authorgroup {
118 background-color: transparent;
119 background-repeat: no-repeat;
120 padding-top: 256px;
121 background-image: url("figures/poky-title.png");
122 background-position: left top;
123 margin-top: -256px;
124 padding-right: 50px;
125 margin-left: 0px;
126 text-align: right;
127 width: 740px;
128}
129
130h3.author {
131 margin: 0em 0me 0em 0em;
132 padding: 0em 0em 0em 0em;
133 font-weight: normal;
134 font-size: 100%;
135 color: #333;
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 color: #00557D;
159}
160
161.toc p,
162.list-of-tables p,
163.list-of-figures p,
164.list-of-examples p {
165 padding: 0em 0em 0em 0em;
166 padding: 0em 0em 0.3em;
167 margin: 1.5em 0em 0em 0em;
168}
169
170.toc p b,
171.list-of-tables p b,
172.list-of-figures p b,
173.list-of-examples p b{
174 font-size: 100.0%;
175 font-weight: bold;
176}
177
178.toc dl,
179.list-of-tables dl,
180.list-of-figures dl,
181.list-of-examples dl {
182 margin: 0em 0em 0.5em 0em;
183 padding: 0em 0em 0em 0em;
184}
185
186.toc dt {
187 margin: 0em 0em 0em 0em;
188 padding: 0em 0em 0em 0em;
189}
190
191.toc dd {
192 margin: 0em 0em 0em 2.6em;
193 padding: 0em 0em 0em 0em;
194}
195
196div.glossary dl,
197div.variablelist dl {
198}
199
200.glossary dl dt,
201.variablelist dl dt,
202.variablelist dl dt span.term {
203 font-weight: normal;
204 width: 20em;
205 text-align: right;
206}
207
208.variablelist dl dt {
209 margin-top: 0.5em;
210}
211
212.glossary dl dd,
213.variablelist dl dd {
214 margin-top: -1em;
215 margin-left: 25.5em;
216}
217
218.glossary dd p,
219.variablelist dd p {
220 margin-top: 0em;
221 margin-bottom: 1em;
222}
223
224
225div.calloutlist table td {
226 padding: 0em 0em 0em 0em;
227 margin: 0em 0em 0em 0em;
228}
229
230div.calloutlist table td p {
231 margin-top: 0em;
232 margin-bottom: 1em;
233}
234
235div p.copyright {
236 text-align: left;
237}
238
239div.legalnotice p.legalnotice-title {
240 margin-bottom: 0em;
241}
242
243p {
244 line-height: 1.5em;
245 margin-top: 0em;
246
247}
248
249dl {
250 padding-top: 0em;
251}
252
253hr {
254 border: solid 1px;
255}
256
257
258.mediaobject,
259.mediaobjectco {
260 text-align: center;
261}
262
263img {
264 border: none;
265}
266
267ul {
268 padding: 0em 0em 0em 1.5em;
269}
270
271ul li {
272 padding: 0em 0em 0em 0em;
273}
274
275ul li p {
276 text-align: left;
277}
278
279table {
280 width :100%;
281}
282
283th {
284 padding: 0.25em;
285 text-align: left;
286 font-weight: normal;
287 vertical-align: top;
288}
289
290td {
291 padding: 0.25em;
292 vertical-align: top;
293}
294
295p a[id] {
296 margin: 0px;
297 padding: 0px;
298 display: inline;
299 background-image: none;
300}
301
302a {
303 text-decoration: underline;
304 color: #444;
305}
306
307pre {
308 overflow: auto;
309}
310
311a:hover {
312 text-decoration: underline;
313 /*font-weight: bold;*/
314}
315
316
317div.informalfigure,
318div.informalexample,
319div.informaltable,
320div.figure,
321div.table,
322div.example {
323 margin: 1em 0em;
324 padding: 1em;
325 page-break-inside: avoid;
326}
327
328
329div.informalfigure p.title b,
330div.informalexample p.title b,
331div.informaltable p.title b,
332div.figure p.title b,
333div.example p.title b,
334div.table p.title b{
335 padding-top: 0em;
336 margin-top: 0em;
337 font-size: 100%;
338 font-weight: normal;
339}
340
341.mediaobject .caption,
342.mediaobject .caption p {
343 text-align: center;
344 font-size: 80%;
345 padding-top: 0.5em;
346 padding-bottom: 0.5em;
347}
348
349.epigraph {
350 padding-left: 55%;
351 margin-bottom: 1em;
352}
353
354.epigraph p {
355 text-align: left;
356}
357
358.epigraph .quote {
359 font-style: italic;
360}
361.epigraph .attribution {
362 font-style: normal;
363 text-align: right;
364}
365
366span.application {
367 font-style: italic;
368}
369
370.programlisting {
371 font-family: monospace;
372 font-size: 80%;
373 white-space: pre;
374 margin: 1.33em 0em;
375 padding: 1.33em;
376}
377
378.tip,
379.warning,
380.caution,
381.note {
382 margin-top: 1em;
383 margin-bottom: 1em;
384
385}
386
387/* force full width of table within div */
388.tip table,
389.warning table,
390.caution table,
391.note table {
392 border: none;
393 width: 100%;
394}
395
396
397.tip table th,
398.warning table th,
399.caution table th,
400.note table th {
401 padding: 0.8em 0.0em 0.0em 0.0em;
402 margin : 0em 0em 0em 0em;
403}
404
405.tip p,
406.warning p,
407.caution p,
408.note p {
409 margin-top: 0.5em;
410 margin-bottom: 0.5em;
411 padding-right: 1em;
412 text-align: left;
413}
414
415.acronym {
416 text-transform: uppercase;
417}
418
419b.keycap,
420.keycap {
421 padding: 0.09em 0.3em;
422 margin: 0em;
423}
424
425.itemizedlist li {
426 clear: none;
427}
428
429.filename {
430 font-size: medium;
431 font-family: Courier, monospace;
432}
433
434
435div.navheader, div.heading{
436 position: absolute;
437 left: 0em;
438 top: 0em;
439 width: 100%;
440 background-color: #cdf;
441 width: 100%;
442}
443
444div.navfooter, div.footing{
445 position: fixed;
446 left: 0em;
447 bottom: 0em;
448 background-color: #eee;
449 width: 100%;
450}
451
452
453div.navheader td,
454div.navfooter td {
455 font-size: 66%;
456}
457
458div.navheader table th {
459 /*font-family: Georgia, Times, serif;*/
460 /*font-size: x-large;*/
461 font-size: 80%;
462}
463
464div.navheader table {
465 border-left: 0em;
466 border-right: 0em;
467 border-top: 0em;
468 width: 100%;
469}
470
471div.navfooter table {
472 border-left: 0em;
473 border-right: 0em;
474 border-bottom: 0em;
475 width: 100%;
476}
477
478div.navheader table td a,
479div.navfooter table td a {
480 color: #777;
481 text-decoration: none;
482}
483
484/* normal text in the footer */
485div.navfooter table td {
486 color: black;
487}
488
489div.navheader table td a:visited,
490div.navfooter table td a:visited {
491 color: #444;
492}
493
494
495/* links in header and footer */
496div.navheader table td a:hover,
497div.navfooter table td a:hover {
498 text-decoration: underline;
499 background-color: transparent;
500 color: #33a;
501}
502
503div.navheader hr,
504div.navfooter hr {
505 display: none;
506}
507
508
509.qandaset tr.question td p {
510 margin: 0em 0em 1em 0em;
511 padding: 0em 0em 0em 0em;
512}
513
514.qandaset tr.answer td p {
515 margin: 0em 0em 1em 0em;
516 padding: 0em 0em 0em 0em;
517}
518.answer td {
519 padding-bottom: 1.5em;
520}
521
522.emphasis {
523 font-weight: bold;
524}
525
526
527 /************* /
528 / decorations /
529/ *************/
530
531.titlepage {
532}
533
534.part .title {
535}
536
537.subtitle {
538 border: none;
539}
540
541/*
542h1 {
543 border: none;
544}
545
546h2 {
547 border-top: solid 0.2em;
548 border-bottom: solid 0.06em;
549}
550
551h3 {
552 border-top: 0em;
553 border-bottom: solid 0.06em;
554}
555
556h4 {
557 border: 0em;
558 border-bottom: solid 0.06em;
559}
560
561h5 {
562 border: 0em;
563}
564*/
565
566.programlisting {
567 border: solid 1px;
568}
569
570div.figure,
571div.table,
572div.informalfigure,
573div.informaltable,
574div.informalexample,
575div.example {
576 border: 1px solid;
577}
578
579
580
581.tip,
582.warning,
583.caution,
584.note {
585 border: 1px solid;
586}
587
588.tip table th,
589.warning table th,
590.caution table th,
591.note table th {
592 border-bottom: 1px solid;
593}
594
595.question td {
596 border-top: 1px solid black;
597}
598
599.answer {
600}
601
602
603b.keycap,
604.keycap {
605 border: 1px solid;
606}
607
608
609div.navheader, div.heading{
610 border-bottom: 1px solid;
611}
612
613
614div.navfooter, div.footing{
615 border-top: 1px solid;
616}
617
618 /********* /
619 / colors /
620/ *********/
621
622body {
623 color: #333;
624 background: white;
625}
626
627a {
628 background: transparent;
629}
630
631a:hover {
632 background-color: #dedede;
633}
634
635
636h1,
637h2,
638h3,
639h4,
640h5,
641h6,
642h7,
643h8 {
644 background-color: transparent;
645}
646
647hr {
648 border-color: #aaa;
649}
650
651
652.tip, .warning, .caution, .note {
653 border-color: #fff;
654}
655
656
657.tip table th,
658.warning table th,
659.caution table th,
660.note table th {
661 border-bottom-color: #fff;
662}
663
664
665.warning {
666 background-color: #f0f0f2;
667}
668
669.caution {
670 background-color: #f0f0f2;
671}
672
673.tip {
674 background-color: #f0f0f2;
675}
676
677.note {
678 background-color: #f0f0f2;
679}
680
681.glossary dl dt,
682.variablelist dl dt,
683.variablelist dl dt span.term {
684 color: #044;
685}
686
687div.figure,
688div.table,
689div.example,
690div.informalfigure,
691div.informaltable,
692div.informalexample {
693 border-color: #aaa;
694}
695
696pre.programlisting {
697 color: black;
698 background-color: #fff;
699 border-color: #aaa;
700 border-width: 2px;
701}
702
703.guimenu,
704.guilabel,
705.guimenuitem {
706 background-color: #eee;
707}
708
709
710b.keycap,
711.keycap {
712 background-color: #eee;
713 border-color: #999;
714}
715
716
717div.navheader {
718 border-color: black;
719}
720
721
722div.navfooter {
723 border-color: black;
724}
725
726
727 /*********** /
728 / graphics /
729/ ***********/
730
731/*
732body {
733 background-image: url("images/body_bg.jpg");
734 background-attachment: fixed;
735}
736
737.navheader,
738.note,
739.tip {
740 background-image: url("images/note_bg.jpg");
741 background-attachment: fixed;
742}
743
744.warning,
745.caution {
746 background-image: url("images/warning_bg.jpg");
747 background-attachment: fixed;
748}
749
750.figure,
751.informalfigure,
752.example,
753.informalexample,
754.table,
755.informaltable {
756 background-image: url("images/figure_bg.jpg");
757 background-attachment: fixed;
758}
759
760*/
761h1,
762h2,
763h3,
764h4,
765h5,
766h6,
767h7{
768}
769
770/*
771Example of how to stick an image as part of the title.
772
773div.article .titlepage .title
774{
775 background-image: url("figures/white-on-black.png");
776 background-position: center;
777 background-repeat: repeat-x;
778}
779*/
780
781div.preface .titlepage .title,
782div.colophon .title,
783div.chapter .titlepage .title,
784div.article .titlepage .title
785{
786}
787
788div.section div.section .titlepage .title,
789div.sect2 .titlepage .title {
790 background: none;
791}
792
793
794h1.title {
795 background-color: transparent;
796 background-image: url("figures/poky-title.png");
797 background-repeat: no-repeat;
798 height: 256px;
799 text-indent: -9000px;
800 overflow:hidden;
801}
802
803h2.subtitle {
804 background-color: transparent;
805 text-indent: -9000px;
806 overflow:hidden;
807 width: 0px;
808 display: none;
809}
810
811 /*************************************** /
812 / pippin.gimp.org specific alterations /
813/ ***************************************/
814
815/*
816div.heading, div.navheader {
817 color: #777;
818 font-size: 80%;
819 padding: 0;
820 margin: 0;
821 text-align: left;
822 position: absolute;
823 top: 0px;
824 left: 0px;
825 width: 100%;
826 height: 50px;
827 background: url('/gfx/heading_bg.png') transparent;
828 background-repeat: repeat-x;
829 background-attachment: fixed;
830 border: none;
831}
832
833div.heading a {
834 color: #444;
835}
836
837div.footing, div.navfooter {
838 border: none;
839 color: #ddd;
840 font-size: 80%;
841 text-align:right;
842
843 width: 100%;
844 padding-top: 10px;
845 position: absolute;
846 bottom: 0px;
847 left: 0px;
848
849 background: url('/gfx/footing_bg.png') transparent;
850}
851*/
852
853
854
855 /****************** /
856 / nasty ie tweaks /
857/ ******************/
858
859/*
860div.heading, div.navheader {
861 width:expression(document.body.clientWidth + "px");
862}
863
864div.footing, div.navfooter {
865 width:expression(document.body.clientWidth + "px");
866 margin-left:expression("-5em");
867}
868body {
869 padding:expression("4em 5em 0em 5em");
870}
871*/
872
873 /**************************************** /
874 / mozilla vendor specific css extensions /
875/ ****************************************/
876/*
877div.navfooter, div.footing{
878 -moz-opacity: 0.8em;
879}
880
881div.figure,
882div.table,
883div.informalfigure,
884div.informaltable,
885div.informalexample,
886div.example,
887.tip,
888.warning,
889.caution,
890.note {
891 -moz-border-radius: 0.5em;
892}
893
894b.keycap,
895.keycap {
896 -moz-border-radius: 0.3em;
897}
898*/
899
900table tr td table tr td {
901 display: none;
902}
903
904
905hr {
906 display: none;
907}
908
909table {
910 border: 0em;
911}
912
913 .photo {
914 float: right;
915 margin-left: 1.5em;
916 margin-bottom: 1.5em;
917 margin-top: 0em;
918 max-width: 17em;
919 border: 1px solid gray;
920 padding: 3px;
921 background: white;
922}
923 .seperator {
924 padding-top: 2em;
925 clear: both;
926 }
927
928 #validators {
929 margin-top: 5em;
930 text-align: right;
931 color: #777;
932 }
933 @media print {
934 body {
935 font-size: 8pt;
936 }
937 .noprint {
938 display: none;
939 }
940 }
941
942
943.tip,
944.note {
945 background: #f0f0f2;
946 color: #333;
947 padding: 20px;
948 margin: 20px;
949}
950
951.tip h3,
952.note h3 {
953 padding: 0em;
954 margin: 0em;
955 font-size: 2em;
956 font-weight: bold;
957 color: #333;
958}
959
960.tip a,
961.note a {
962 color: #333;
963 text-decoration: underline;
964}
965
966.footnote {
967 font-size: small;
968 color: #333;
969}
970
971/* Changes the announcement text */
972.tip h3,
973.warning h3,
974.caution h3,
975.note h3 {
976 font-size:large;
977 color: #00557D;
978}
979
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
deleted file mode 100644
index c490fc360d..0000000000
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ /dev/null
@@ -1,3018 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<!-- Dummy chapter -->
6<chapter id='ref-variables-glos'>
7
8<title>Variables Glossary</title>
9
10<para>
11 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
12 of their function and contents.
13</para>
14
15<glossary id='ref-variables-glossary'>
16
17
18 <para>
19 <link linkend='var-ALLOW_EMPTY'>A</link>
20 <link linkend='var-B'>B</link>
21 <link linkend='var-CFLAGS'>C</link>
22 <link linkend='var-D'>D</link>
23 <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link>
24 <link linkend='var-FILES'>F</link>
25<!-- <link linkend='var-glossary-g'>G</link> -->
26 <link linkend='var-HOMEPAGE'>H</link>
27 <link linkend='var-IMAGE_FEATURES'>I</link>
28<!-- <link linkend='var-glossary-j'>J</link> -->
29 <link linkend='var-KBRANCH'>K</link>
30 <link linkend='var-LAYERDIR'>L</link>
31 <link linkend='var-MACHINE'>M</link>
32<!-- <link linkend='var-glossary-n'>N</link> -->
33 <link linkend='var-OE_TERMINAL'>O</link>
34 <link linkend='var-P'>P</link>
35<!-- <link linkend='var-glossary-q'>Q</link> -->
36 <link linkend='var-RCONFLICTS'>R</link>
37 <link linkend='var-S'>S</link>
38 <link linkend='var-T'>T</link>
39<!-- <link linkend='var-glossary-u'>U</link> -->
40<!-- <link linkend='var-glossary-v'>V</link> -->
41 <link linkend='var-WORKDIR'>W</link>
42<!-- <link linkend='var-glossary-x'>X</link> -->
43<!-- <link linkend='var-glossary-y'>Y</link> -->
44<!-- <link linkend='var-glossary-z'>Z</link>-->
45 </para>
46
47 <glossdiv id='var-glossary-a'><title>A</title>
48
49 <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
50 <glossdef>
51 <para>
52 Specifies if an output package should still be produced if it is empty.
53 By default, BitBake does not produce empty packages.
54 This default behavior can cause issues when there is an
55 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
56 some other runtime hard-requirement on the existence of the package.
57 </para>
58
59 <para>
60 Like all package-controlling variables, you must always use them in
61 conjunction with a package name override.
62 Here is an example:
63 <literallayout class='monospaced'>
64 ALLOW_EMPTY_${PN} = "1"
65 </literallayout>
66 </para>
67 </glossdef>
68 </glossentry>
69
70 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
71 <glossdef>
72 <para>The email address used to contact the original author or authors in
73 order to send patches, forward bugs, etc.</para>
74 </glossdef>
75 </glossentry>
76
77 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
78 <glossdef>
79 <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
80 is set to the value of this variable, it specifies that the latest
81 source revision in the repository should be used. Here is an example:
82 <literallayout class='monospaced'>
83 SRCREV = "${AUTOREV}"
84 </literallayout>
85 </para>
86 </glossdef>
87 </glossentry>
88
89 </glossdiv>
90
91 <glossdiv id='var-glossary-b'><title>B</title>
92
93 <glossentry id='var-B'><glossterm>B</glossterm>
94 <glossdef>
95 <para>
96 The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
97 The OpenEmbedded build system places generated objects into the Build Directory
98 during a recipe's build process.
99 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
100 directory:
101 <literallayout class='monospaced'>
102 B = ${WORKDIR}/${BPN}/{PV}/
103 </literallayout>
104 You can separate the (<filename>S</filename>) directory and the directory pointed to
105 by the <filename>B</filename> variable.
106 Most autotools-based recipes support separating these directories.
107 The build system defaults to using separate directories for <filename>gcc</filename>
108 and some kernel recipes.
109 </para>
110 </glossdef>
111 </glossentry>
112
113 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
114 <glossdef>
115 <para>
116 A list of packages not to install despite being recommended by a recipe.
117 Support for this variable exists only when using the
118 <filename>ipk</filename> packaging backend.
119 </para>
120 </glossdef>
121 </glossentry>
122
123 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
124 <glossdef>
125 <para>
126 Monitors disk space and available inodes during the build
127 and allows you to control the build based on these
128 parameters.
129 </para>
130
131 <para>
132 Disk space monitoring is disabled by default.
133 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
134 variable to your <filename>conf/local.conf</filename> file found in the
135 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
136 Use the following form:
137 <literallayout class='monospaced'>
138 BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
139
140 where:
141
142 &lt;action&gt; is:
143 ABORT: Immediately abort the build when
144 a threshold is broken.
145 STOPTASKS: Stop the build after the currently
146 executing tasks have finished when
147 a threshold is broken.
148 WARN: Issue a warning but continue the
149 build when a threshold is broken.
150 Subsequent warnings are issued as
151 defined by the
152 <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
153 which must be defined in the
154 conf/local.conf file.
155
156 &lt;dir&gt; is:
157 Any directory you choose. You can specify one or
158 more directories to monitor by separating the
159 groupings with a space. If two directories are
160 on the same device, only the first directory
161 is monitored.
162
163 &lt;threshold&gt; is:
164 Either the minimum available disk space,
165 the minimum number of free inodes, or
166 both. You must specify at least one. To
167 omit one or the other, simply omit the value.
168 Specify the threshold using G, M, K for Gbytes,
169 Mbytes, and Kbytes, respectively. If you do
170 not specify G, M, or K, Kbytes is assumed by
171 default. Do not use GB, MB, or KB.
172 </literallayout>
173 </para>
174
175 <para>
176 Here are some examples:
177 <literallayout class='monospaced'>
178 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
179 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
180 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
181 </literallayout>
182 The first example works only if you also provide
183 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
184 in the <filename>conf/local.conf</filename>.
185 This example causes the build system to immediately
186 abort when either the disk space in <filename>${TMPDIR}</filename> drops
187 below 1 Gbyte or the available free inodes drops below
188 100 Kbytes.
189 Because two directories are provided with the variable, the
190 build system also issue a
191 warning when the disk space in the
192 <filename>${SSTATE_DIR}</filename> directory drops
193 below 1 Gbyte or the number of free inodes drops
194 below 100 Kbytes.
195 Subsequent warnings are issued during intervals as
196 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
197 variable.
198 </para>
199
200 <para>
201 The second example stops the build after all currently
202 executing tasks complete when the minimum disk space
203 in the <filename>${TMPDIR}</filename> directory drops
204 below 1 Gbyte.
205 No disk monitoring occurs for the free inodes in this case.
206 </para>
207
208 <para>
209 The final example immediately aborts the build when the
210 number of free inodes in the <filename>${TMPDIR}</filename> directory
211 drops below 100 Kbytes.
212 No disk space monitoring for the directory itself occurs
213 in this case.
214 </para>
215 </glossdef>
216 </glossentry>
217
218 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
219 <glossdef>
220 <para>
221 Defines the disk space and free inode warning intervals.
222 To set these intervals, define the variable in your
223 <filename>conf/local.conf</filename> file in the
224 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
225 </para>
226
227 <para>
228 If you are going to use the
229 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
230 also use the
231 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
232 and define its action as "WARN".
233 During the build, subsequent warnings are issued each time
234 disk space or number of free inodes further reduces by
235 the respective interval.
236 </para>
237
238 <para>
239 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
240 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
241 the "WARN" action, the disk monitoring interval defaults to
242 the following:
243 <literallayout class='monospaced'>
244 BB_DISKMON_WARNINTERVAL = "50M,5K"
245 </literallayout>
246 </para>
247
248 <para>
249 When specifying the variable in your configuration file,
250 use the following form:
251 <literallayout class='monospaced'>
252 BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
253
254 where:
255
256 &lt;disk_space_interval&gt; is:
257 An interval of memory expressed in either
258 G, M, or K for Gbytes, Mbytes, or Kbytes,
259 respectively. You cannot use GB, MB, or KB.
260
261 &lt;disk_inode_interval&gt; is:
262 An interval of free inodes expressed in either
263 G, M, or K for Gbytes, Mbytes, or Kbytes,
264 respectively. You cannot use GB, MB, or KB.
265 </literallayout>
266 </para>
267
268 <para>
269 Here is an example:
270 <literallayout class='monospaced'>
271 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
272 BB_DISKMON_WARNINTERVAL = "50M,5K"
273 </literallayout>
274 These variables cause the OpenEmbedded build system to
275 issue subsequent warnings each time the available
276 disk space further reduces by 50 Mbytes or the number
277 of free inodes further reduces by 5 Kbytes in the
278 <filename>${SSTATE_DIR}</filename> directory.
279 Subsequent warnings based on the interval occur each time
280 a respective interval is reached beyond the intial warning
281 (i.e. 1 Gbytes and 100 Kbytes).
282 </para>
283 </glossdef>
284 </glossentry>
285
286 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
287 <glossdef>
288 <para>
289 Allows you to extend a recipe so that it builds variants of the software.
290 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
291 which is a copy of quilt built to run on the build system;
292 "crosses" such as <filename>gcc-cross</filename>,
293 which is a compiler built to run on the build machine but produces binaries
294 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
295 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
296 and "mulitlibs" in the form "<filename>multilib:&lt;multilib_name&gt;</filename>".
297 </para>
298
299 <para>
300 To build a different variant of the recipe with a minimal amount of code, it usually
301 is as simple as adding the following to your recipe:
302 <literallayout class='monospaced'>
303 BBCLASSEXTEND =+ "native nativesdk"
304 BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
305 </literallayout>
306 </para>
307 </glossdef>
308 </glossentry>
309
310 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
311 <glossdef>
312 <para>Prevents BitBake from processing recipes and recipe append files.
313 You can use the <filename>BBMASK</filename> variable to "hide"
314 these <filename>.bb</filename> and <filename>.bbappend</filename> files.
315 BitBake ignores any recipe or recipe append files that match the expression.
316 It is as if BitBake does not see them at all.
317 Consequently, matching files are not parsed or otherwise used by
318 BitBake.</para>
319 <para>The value you provide is passed to python's regular expression compiler.
320 For complete syntax information, see python's documentation at
321 <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
322 The expression is compared against the full paths to the files.
323 For example, the following uses a complete regular expression to tell
324 BitBake to ignore all recipe and recipe append files in the
325 <filename>.*/meta-ti/recipes-misc/</filename> directory:
326 <literallayout class='monospaced'>
327 BBMASK = ".*/meta-ti/recipes-misc/"
328 </literallayout></para>
329 <para>Use the <filename>BBMASK</filename> variable from within the
330 <filename>conf/local.conf</filename> file found
331 in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.</para>
332 </glossdef>
333 </glossentry>
334
335 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
336 <glossdef>
337 <para>The maximum number of tasks BitBake should run in parallel at any one time.
338 If your host development system supports multiple cores a good rule of thumb
339 is to set this variable to twice the number of cores.</para>
340 </glossdef>
341 </glossentry>
342
343 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
344 <glossdef>
345 <para>Lists the names of configured layers.
346 These names are used to find the other <filename>BBFILE_*</filename>
347 variables.
348 Typically, each layer will append its name to this variable in its
349 <filename>conf/layer.conf</filename> file.
350 </para>
351 </glossdef>
352 </glossentry>
353
354 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
355 <glossdef>
356 <para>Variable that expands to match files from <filename>BBFILES</filename> in a particular layer.
357 This variable is used in the <filename>conf/layer.conf</filename> file and must
358 be suffixed with the name of the specific layer (e.g.
359 <filename>BBFILE_PATTERN_emenlow</filename>).</para>
360 </glossdef>
361 </glossentry>
362
363 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
364 <glossdef>
365 <para>Assigns the priority for recipe files in each layer.</para>
366 <para>This variable is useful in situations where the same recipe appears in
367 more than one layer.
368 Setting this variable allows you to prioritize a
369 layer against other layers that contain the same recipe - effectively
370 letting you control the precedence for the multiple layers.
371 The precedence established through this variable stands regardless of a
372 recipe's version (<filename>PV</filename> variable).
373 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
374 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
375 lower precedence.</para>
376 <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
377 precedence.
378 For example, the value 6 has a higher precedence than the value 5.
379 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
380 dependencies (see the
381 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
382 more information.
383 The default priority, if unspecified
384 for a layer with no dependencies, is the lowest defined priority + 1
385 (or 1 if no priorities are defined).</para>
386 <tip>
387 You can use the command <filename>bitbake-layers show_layers</filename> to list
388 all configured layers along with their priorities.
389 </tip>
390 </glossdef>
391 </glossentry>
392
393 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
394 <glossdef>
395 <para>List of recipe files used by BitBake to build software</para>
396 </glossdef>
397 </glossentry>
398
399 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
400 <glossdef>
401 <para>Used by BitBake to locate <filename>.bbclass</filename> and configuration files.
402 This variable is analogous to the <filename>PATH</filename> variable.</para>
403 </glossdef>
404 </glossentry>
405
406 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
407 <glossdef>
408 <para>Variable that controls how BitBake displays logs on build failure.</para>
409 </glossdef>
410 </glossentry>
411
412 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
413 <glossdef>
414 <para>Lists the layers to enable during the build.
415 This variable is defined in the <filename>bblayers.conf</filename> configuration
416 file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
417 Here is an example:
418 <literallayout class='monospaced'>
419 BBLAYERS = " \
420 /home/scottrif/poky/meta \
421 /home/scottrif/poky/meta-yocto \
422 /home/scottrif/poky/meta-yocto-bsp \
423 /home/scottrif/poky/meta-mykernel \
424 "
425
426 BBLAYERS_NON_REMOVABLE ?= " \
427 /home/scottrif/poky/meta \
428 /home/scottrif/poky/meta-yocto \
429 "
430 </literallayout>
431 This example enables four layers, one of which is a custom, user-defined layer
432 named <filename>meta-mykernel</filename>.
433 </para>
434 </glossdef>
435 </glossentry>
436
437 <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm>
438 <glossdef>
439Core layer for images cannot be removed
440 <para>Lists core layers that cannot be removed from the
441 <filename>bblayers.conf</filename> file.
442 In order for BitBake to build your image, your
443 <filename>bblayers.conf</filename> file must include the
444 <filename>meta</filename> and <filename>meta-yocto</filename>
445 core layers.
446 Here is an example that shows these two layers listed in
447 the <filename>BBLAYERS_NON_REMOVABLE</filename> statement:
448 <literallayout class='monospaced'>
449 BBLAYERS = " \
450 /home/scottrif/poky/meta \
451 /home/scottrif/poky/meta-yocto \
452 /home/scottrif/poky/meta-yocto-bsp \
453 /home/scottrif/poky/meta-mykernel \
454 "
455
456 BBLAYERS_NON_REMOVABLE ?= " \
457 /home/scottrif/poky/meta \
458 /home/scottrif/poky/meta-yocto \
459 "
460 </literallayout>
461 </para>
462 </glossdef>
463 </glossentry>
464
465 <glossentry id='var-BP'><glossterm>BP</glossterm>
466 <glossdef>
467 <para>The base recipe name and version but without any special
468 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
469 and so forth).
470 <filename>BP</filename> is comprised of the following:
471 <literallayout class="monospaced">
472 ${BPN}-${PV}
473 </literallayout></para>
474 </glossdef>
475 </glossentry>
476
477 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
478 <glossdef>
479 <para>The bare name of the recipe.
480 This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable
481 but removes common suffixes such as "-native" and "-cross" as well
482 as removes common prefixes such as multilib's "lib64-" and "lib32-".
483 The exact list of suffixes removed is specified by the
484 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable.
485 The exact list of prefixes removed is specified by the
486 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable.
487 Prefixes are removed for multilib and nativesdk cases.</para>
488 </glossdef>
489 </glossentry>
490
491 </glossdiv>
492
493 <glossdiv id='var-glossary-c'><title>C</title>
494
495 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
496 <glossdef>
497 <para>
498 Flags passed to C compiler for the target system.
499 This variable evaluates to the same as
500 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>.
501 </para>
502 </glossdef>
503 </glossentry>
504
505 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
506 <glossdef>
507 <para>A set of features common between
508 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
509 and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
510 See the glossary descriptions for these variables for more information.</para>
511 </glossdef>
512 </glossentry>
513
514 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
515 <glossdef>
516 <para>A regular expression which evaluates to match the machines the recipe
517 works with.
518 It stops recipes being run on machines for which they are not compatible.
519 This is particularly useful with kernels.
520 It also helps to increase parsing speed as further parsing of the recipe is skipped
521 if it is found the current machine is not compatible.</para>
522 </glossdef>
523 </glossentry>
524
525 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
526 <glossdef>
527 <para>
528 Identifies editable or configurable files that are part of a package.
529 If the Package Management System (PMS) is being used to update
530 packages on the target system, it is possible that
531 configuration files you have changed after the original installation
532 and that you now want to remain unchanged are overwritten.
533 In other words, editable files might exist in the package that you do not
534 want reset as part of the package update process.
535 You can use the <filename>CONFFILES</filename> variable to list the files in the
536 package that you wish to prevent the PMS from overwriting during this update process.
537 </para>
538
539 <para>
540 To use the <filename>CONFFILES</filename> variable, provide a package name
541 override that identifies the resulting package.
542 Then, provide a space-separated list of files.
543 Here is an example:
544 <literallayout class='monospaced'>
545 CONFFILES_${PN} += "${sysconfdir}/file1 \
546 ${sysconfdir}/file2 ${sysconfdir}/file3"
547 </literallayout>
548 </para>
549
550 <para>
551 A relationship exists between the <filename>CONFFILES</filename> and
552 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
553 The files listed within <filename>CONFFILES</filename> must be a subset of
554 the files listed within <filename>FILES</filename>.
555 Because the configuration files you provide with <filename>CONFFILES</filename>
556 are simply being identified so that the PMS will not overwrite them,
557 it makes sense that
558 the files must already be included as part of the package through the
559 <filename>FILES</filename> variable.
560 </para>
561
562 <note>
563 When specifying paths as part of the <filename>CONFFILES</filename> variable,
564 it is good practice to use appropriate path variables.
565 For example, <filename>${sysconfdir}</filename> rather than
566 <filename>/etc</filename> or <filename>${bindir}</filename> rather
567 than <filename>/usr/bin</filename>.
568 You can find a list of these variables at the top of the
569 <filename>/meta/conf/bitbake.conf</filename> file in the
570 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
571 </note>
572 </glossdef>
573 </glossentry>
574
575 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
576 <glossdef>
577 <para>
578 A list of files that contains <filename>autoconf</filename> test results relevant
579 to the current build.
580 This variable is used by the Autotools utilities when running
581 <filename>configure</filename>.
582 </para>
583 </glossdef>
584 </glossentry>
585
586 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
587 <glossdef>
588 <para>
589 Specifies the list of packages to be added to the image.
590 This variable should only be set in the <filename>local.conf</filename>
591 configuration file found in the
592 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
593 </para>
594
595 <para>
596 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
597 </para>
598 </glossdef>
599 </glossentry>
600
601 </glossdiv>
602
603 <glossdiv id='var-glossary-d'><title>D</title>
604
605 <glossentry id='var-D'><glossterm>D</glossterm>
606 <glossdef>
607 <para>The destination directory.</para>
608 </glossdef>
609 </glossentry>
610
611 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
612 <glossdef>
613 <para>
614 Specifies to build packages with debugging information.
615 This influences the value of the
616 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
617 variable.
618 </para>
619 </glossdef>
620 </glossentry>
621
622 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
623 <glossdef>
624 <para>
625 The options to pass in
626 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
627 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
628 a system for debugging.
629 This variable defaults to "-O -fno-omit-frame-pointer -g".
630 </para>
631 </glossdef>
632 </glossentry>
633
634 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
635 <glossdef>
636 <para>Specifies the priority of recipes.</para>
637 </glossdef>
638 </glossentry>
639
640 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
641 <glossdef>
642 <para>
643 Lists a recipe's build-time dependencies
644 (i.e. other recipe files).
645 The system ensures that all the dependencies listed
646 have been built and have their contents in the appropriate
647 sysroots before the recipe's configure task is executed.
648 </para>
649 </glossdef>
650 </glossentry>
651
652 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
653 <glossdef>
654 <para>The package description used by package managers.
655 If not set, <filename>DESCRIPTION</filename> takes
656 the value of the
657 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
658 variable.
659 </para>
660 </glossdef>
661 </glossentry>
662
663 <glossentry id='var-DESTDIR'><glossterm>DESTDIR</glossterm>
664 <glossdef>
665 <para>the destination directory.</para>
666 </glossdef>
667 </glossentry>
668
669 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
670 <glossdef>
671 <para>
672 The short name of the distribution.
673 This variable corresponds to a file with the
674 extension <filename>.conf</filename>
675 located in a <filename>conf/distro</filename> directory
676 within the metadata that contains the distribution configuration.
677 The
678 value must not contain spaces, and is typically all lower-case.
679 </para>
680 <para>
681 If the variable is blank, a set of default configuration
682 will be used, which is specified
683 within <filename>meta/conf/distro/defaultsetup.conf</filename>.
684 </para>
685 </glossdef>
686 </glossentry>
687
688 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
689 <glossdef>
690 <para>
691 Specifies a list of distro-specific packages to add to all images.
692 This variable takes affect through
693 <filename>packagegroup-base</filename> so the
694 variable only really applies to the more full-featured
695 images that include <filename>packagegroup-base</filename>.
696 You can use this variable to keep distro policy out of
697 generic images.
698 As with all other distro variables, you set this variable
699 in the distro <filename>.conf</filename> file.
700 </para>
701 </glossdef>
702 </glossentry>
703
704 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
705 <glossdef>
706 <para>
707 Specifies a list of distro-specific packages to add to all images
708 if the packages exist.
709 The packages might not exist or be empty (e.g. kernel modules).
710 The list of packages are automatically installed but can be
711 removed by the user.
712 </para>
713 </glossdef>
714 </glossentry>
715
716 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
717 <glossdef>
718 <para>The features enabled for the distribution.
719 For a list of features supported by the Yocto Project as shipped,
720 see the "<link linkend='ref-features-distro'>Distro</link>"
721 section.
722 </para>
723 </glossdef>
724 </glossentry>
725
726 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
727 <glossdef>
728 <para>Features to be added to
729 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
730 if not also present in
731 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
732 </para>
733
734 <para>
735 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
736 It is not intended to be user-configurable.
737 It is best to just reference the variable to see which distro features are
738 being backfilled for all distro configurations.
739 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
740 more information.
741 </para>
742 </glossdef>
743 </glossentry>
744
745 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
746 <glossdef>
747 <para>Features from
748 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
749 that should not backfilled (i.e. added to
750 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
751 during the build.
752 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
753 more information.
754 </para>
755 </glossdef>
756 </glossentry>
757
758 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
759 <glossdef>
760 <para>The long name of the distribution.</para>
761 </glossdef>
762 </glossentry>
763
764 <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
765 <glossdef>
766 <para>Alias names used for the recipe in various Linux distributions.</para>
767 <para>See the
768 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling
769 a Package Name Alias</ulink>" section in the Yocto Project Development
770 Manual for more information.</para>
771 </glossdef>
772 </glossentry>
773
774 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
775 <glossdef>
776 <para>the version of the distribution.</para>
777 </glossdef>
778 </glossentry>
779
780 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
781 <glossdef>
782 <para>
783 The central download directory used by the build process to store downloads.
784 You can set this directory by defining the <filename>DL_DIR</filename>
785 variable in the <filename>/conf/local.conf</filename> file.
786 This directory is self-maintaining and you should not have
787 to touch it.
788 By default, the directory is <filename>downloads</filename> in the
789 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
790 <literallayout class='monospaced'>
791 #DL_DIR ?= "${TOPDIR}/downloads"
792 </literallayout>
793 To specify a different download directory, simply uncomment the line
794 and provide your directory.
795 </para>
796
797 <para>
798 During a first build, the system downloads many different source code
799 tarballs from various upstream projects.
800 Downloading can take a while, particularly if your network
801 connection is slow.
802 Tarballs are all stored in the directory defined by
803 <filename>DL_DIR</filename> and the build system looks there first
804 to find source tarballs.
805 <note>
806 When wiping and rebuilding, you can preserve this directory to speed
807 up this part of subsequent builds.
808 </note>
809 </para>
810
811 <para>
812 You can safely share this directory between multiple builds on the
813 same development machine.
814 For additional information on how the build process gets source files
815 when working behind a firewall or proxy server, see the
816 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
817 chapter.
818 </para>
819 </glossdef>
820
821 </glossentry>
822 </glossdiv>
823
824 <glossdiv id='var-glossary-e'><title>E</title>
825
826 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
827 <glossdef>
828 <para></para>
829 <para>Variable that controls which locales for <filename>eglibc</filename> are
830 to be generated during the build (useful if the target device has 64Mbytes
831 of RAM or less).</para>
832 </glossdef>
833 </glossentry>
834
835 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
836 <glossdef>
837 <para>
838 Used with file and pathnames to create a prefix for a recipe's
839 version based on the recipe's
840 <link linkend='var-PE'><filename>PE</filename></link> value.
841 If <filename>PE</filename> is set and greater than zero for a recipe,
842 <filename>EXTENDPE</filename> becomes that value (e.g if
843 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
844 becomes "1_").
845 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
846 zero, <filename>EXTENDPE</filename> becomes "".</para>
847 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
848 variable for an example.
849 </para>
850 </glossdef>
851 </glossentry>
852
853 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
854 <glossdef>
855 <para>Allows extra packages to be added to the generated images.
856 You set this variable in the <filename>local.conf</filename>
857 configuration file.
858 Note that some image features are also added using the
859 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
860 variable generally configured in image recipes.
861 You can use this variable to add more features in addition to those.
862 Here are some examples of features you can add:</para>
863 <literallayout class='monospaced'>
864"dbg-pkgs" - Adds -dbg packages for all installed packages
865 including symbol information for debugging and
866 profiling.
867
868"dev-pkgs" - Adds -dev packages for all installed packages.
869 This is useful if you want to develop against
870 the libraries in the image.
871
872"tools-sdk" - Adds development tools such as gcc, make,
873 pkgconfig and so forth.
874
875"tools-debug" - Adds debugging tools such as gdb and
876 strace.
877
878"tools-profile" - Adds profiling tools such as oprofile,
879 exmap, lttng and valgrind (x86 only).
880
881"tools-testapps" - Adds useful testing tools such as
882 ts_print, aplay, arecord and so
883 forth.
884
885"debug-tweaks" - Makes an image suitable for development.
886 For example, ssh root access has a blank
887 password. You should remove this feature
888 before you produce a production image.
889 </literallayout>
890
891 <para>There are other valid features too, see the
892 <link linkend='ref-features-image'>Images</link>
893 section for more details.</para>
894 </glossdef>
895 </glossentry>
896
897 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
898 <glossdef>
899 <para>A list of recipes to be built that do not provide packages to be installed in
900 the root filesystem.
901 </para>
902 <para>Sometimes a recipe is required to build the final image but is not
903 needed in the root filesystem.
904 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
905 list these recipes and thus, specify the dependencies.
906 A typical example is a required bootloader in a machine configuration.
907 </para>
908 <note>
909 To add packages to the root filesystem, see the various
910 <filename>*DEPENDS</filename> and <filename>*RECOMMENDS</filename>
911 variables.
912 </note>
913 </glossdef>
914 </glossentry>
915
916 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
917 <glossdef>
918 <para>Additional <filename>cmake</filename> options.</para>
919 </glossdef>
920 </glossentry>
921
922 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
923 <glossdef>
924 <para>Additional <filename>configure</filename> script options.</para>
925 </glossdef>
926 </glossentry>
927
928 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
929 <glossdef>
930 <para>Additional GNU <filename>make</filename> options.</para>
931 </glossdef>
932 </glossentry>
933
934 </glossdiv>
935
936 <glossdiv id='var-glossary-f'><title>F</title>
937
938 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
939 <glossdef>
940 <para>
941 The list of directories or files that are placed in packages.
942 </para>
943
944 <para>
945 To use the <filename>FILES</filename> variable, provide a package name
946 override that identifies the resulting package.
947 Then, provide a space-separated list of files or paths that identifies the
948 files you want included as part of the resulting package.
949 Here is an example:
950 <literallayout class='monospaced'>
951 FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
952 </literallayout>
953 </para>
954
955 <note>
956 When specifying paths as part of the <filename>FILES</filename> variable,
957 it is good practice to use appropriate path variables.
958 For example, <filename>${sysconfdir}</filename> rather than
959 <filename>/etc</filename> or <filename>${bindir}</filename> rather
960 than <filename>/usr/bin</filename>.
961 You can find a list of these variables at the top of the
962 <filename>/meta/conf/bitbake.conf</filename> file in the
963 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
964 </note>
965
966 <para>
967 If some of the files you provide with the <filename>FILES</filename> variable
968 are editable and you know they should not be
969 overwritten during the package update process by the Package Management
970 System (PMS), you can identify these files so that the PMS will not
971 overwrite them.
972 See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename>
973 variable for information on how to identify these files to the PMS.
974 </para>
975
976 </glossdef>
977 </glossentry>
978
979 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
980 <glossdef>
981 <para>
982 Extends the search path the OpenEmbedded build system uses when
983 looking for files and patches as it processes recipes.
984 The directories BitBake uses when it processes recipes is defined by the
985 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> variable.
986 You can add directories to the search path by defining the
987 <filename>FILESEXTRAPATHS</filename> variable.
988 </para>
989
990 <para>
991 To add paths to the search order, provide a list of directories and separate
992 each path using a colon character as follows:
993 <literallayout class='monospaced'>
994 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
995 </literallayout>
996 Typically, you want your directories searched first.
997 To make sure that happens, use <filename>_prepend</filename> and
998 the immediate expansion (<filename>:=</filename>) operator as shown in the
999 previous example.
1000 Finally, to maintain the integrity of the <filename>FILESPATH</filename> variable,
1001 you must include the appropriate beginning or ending (as needed) colon character.
1002 </para>
1003
1004 <para>
1005 The <filename>FILESEXTRAPATHS</filename> variable is intended for use in
1006 <filename>.bbappend</filename> files to include any additional files provided in that layer.
1007 You typically accomplish this with the following:
1008 <literallayout class='monospaced'>
1009 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1010 </literallayout>
1011 </para>
1012 </glossdef>
1013 </glossentry>
1014
1015 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
1016 <glossdef>
1017 <para>
1018 The default set of directories the OpenEmbedded build system uses
1019 when searching for patches and files.
1020 During the build process, BitBake searches each directory in
1021 <filename>FILESPATH</filename> in the specified order when looking for
1022 files and patches specified by each <filename>file://</filename> URI in a recipe.
1023 </para>
1024
1025 <para>
1026 The default value for the <filename>FILESPATH</filename> variable is defined
1027 in the <filename>base.bbclass</filename> class found in
1028 <filename>meta/classes</filename> in the
1029 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
1030 <literallayout class='monospaced'>
1031FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \
1032 "${FILE_DIRNAME}/${P}", "${FILE_DIRNAME}/${PN}", \
1033 "${FILE_DIRNAME}/${BP}", "${FILE_DIRNAME}/${BPN}", \
1034 "${FILE_DIRNAME}/files", "${FILE_DIRNAME}" ], d)}"
1035 </literallayout>
1036 Do not hand-edit the <filename>FILESPATH</filename> variable.
1037 If you want to extend the set of pathnames that BitBake uses when searching for
1038 files and patches, use the
1039 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link> variable.
1040 </para>
1041 </glossdef>
1042 </glossentry>
1043
1044 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
1045 <glossdef>
1046 <para>Allows you to define your own file permissions settings table as part of
1047 your configuration for the packaging process.
1048 For example, suppose you need a consistent set of custom permissions for
1049 a set of groups and users across an entire work project.
1050 It is best to do this in the packages themselves but this is not always
1051 possible.
1052 </para>
1053 <para>
1054 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
1055 is located in the <filename>meta/files</filename> folder in the
1056 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1057 If you create your own file permissions setting table, you should place it in your
1058 layer or the distros layer.
1059 </para>
1060 <para>
1061 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
1062 <filename>conf/local.conf</filename> file, which is found in the
1063 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to
1064 point to your custom <filename>fs-perms.txt</filename>.
1065 You can specify more than a single file permissions setting table.
1066 The paths you specify to these files must be defined within the
1067 <filename>BBPATH</filename> variable.
1068 </para>
1069 <para>
1070 For guidance on how to create your own file permissions settings table file,
1071 examine the existing <filename>fs-perms.txt</filename>.
1072 </para>
1073 </glossdef>
1074 </glossentry>
1075
1076 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
1077 <glossdef>
1078 <para>
1079 The options to pass in
1080 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
1081 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
1082 when compiling an optimized system.
1083 This variable defaults to
1084 "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
1085 </para>
1086 </glossdef>
1087 </glossentry>
1088
1089 </glossdiv>
1090
1091<!-- <glossdiv id='var-glossary-g'><title>G</title>-->
1092<!-- </glossdiv>-->
1093
1094 <glossdiv id='var-glossary-h'><title>H</title>
1095
1096 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
1097 <glossdef>
1098 <para>Website where more information about the software the recipe is building
1099 can be found.</para>
1100 </glossdef>
1101 </glossentry>
1102
1103 </glossdiv>
1104
1105 <glossdiv id='var-glossary-i'><title>I</title>
1106
1107 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
1108 <glossdef>
1109 <para>The list of features to include in an image.
1110 Typically, you configure this variable in an image recipe.
1111 Note that you can also add extra features to the image by using the
1112 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
1113 See the "<link linkend="ref-features-image">Images</link>" section for the
1114 full list of features that can be included in images built by the
1115 OpenEmbedded build system.</para>
1116 </glossdef>
1117 </glossentry>
1118
1119 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
1120 <glossdef>
1121 <para>Formats of root filesystem images that you want to have created.</para>
1122 </glossdef>
1123 </glossentry>
1124
1125 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
1126 <glossdef>
1127 <para>
1128 Specifies the packages to install into an image.
1129 The <filename>IMAGE_INSTALL</filename> variable is a mechanism for an image
1130 recipe and you should use it with care to avoid ordering issues.
1131 </para>
1132
1133 <para>
1134 Image recipes set <filename>IMAGE_INSTALL</filename> to specify the
1135 packages to install into an image through <filename>image.bbclass</filename>.
1136 Additionally, "helper" classes exist, such as <filename>core-image.bbclass</filename>,
1137 that can take
1138 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> lists
1139 and turn these into auto-generated entries in
1140 <filename>IMAGE_INSTALL</filename> in addition to its default contents.
1141 </para>
1142
1143 <para>
1144 Using <filename>IMAGE_INSTALL</filename> with the <filename>+=</filename>
1145 operator from the <filename>/conf/local.conf</filename> file or from within
1146 an image recipe is not recommended as it can cause ordering issues.
1147 Since <filename>core-image.bbclass</filename> sets <filename>IMAGE_INSTALL</filename>
1148 to a default value using the <filename>?=</filename> operator, using a
1149 <filename>+=</filename> operation against <filename>IMAGE_INSTALL</filename>
1150 will result in unexpected behavior when used in
1151 <filename>/conf/local.conf</filename>.
1152 Furthermore, the same operation from with an image recipe may or may not
1153 succeed depending on the specific situation.
1154 In both these cases, the behavior is contrary to how most users expect
1155 the <filename>+=</filename> operator to work.
1156 </para>
1157
1158 <para>
1159 When you use this variable, it is best to use it as follows:
1160 <literallayout class='monospaced'>
1161 IMAGE_INSTALL_append = " package-name"
1162 </literallayout>
1163 Be sure to include the space between the quotation character and the start of the
1164 package name.
1165 </para>
1166 </glossdef>
1167 </glossentry>
1168
1169 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
1170 <glossdef>
1171 <para>
1172 Defines a multiplier that the build system applies to the initial image
1173 size for cases when the multiplier times the returned disk usage value
1174 for the image is greater than the sum of
1175 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
1176 and
1177 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
1178 The result of the multiplier applied to the initial image size creates
1179 free disk space in the image as overhead.
1180 By default, the build process uses a multiplier of 1.3 for this variable.
1181 This default value results in 30% free disk space added to the image when this
1182 method is used to determine the final generated image size.
1183 You should be aware that post install scripts and the package management
1184 system uses disk space inside this overhead area.
1185 Consequently, the multiplier does not produce an image with
1186 all the theoretical free disk space.
1187 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
1188 for information on how the build system determines the overall image size.
1189 </para>
1190
1191 <para>
1192 The default 30% free disk space typically gives the image enough room to boot
1193 and allows for basic post installs while still leaving a small amount of
1194 free disk space.
1195 If 30% free space is inadequate, you can increase the default value.
1196 For example, the following setting gives you 50% free space added to the image:
1197 <literallayout class='monospaced'>
1198 IMAGE_OVERHEAD_FACTOR = "1.5"
1199 </literallayout>
1200 </para>
1201
1202 <para>
1203 Alternatively, you can ensure a specific amount of free disk space is added
1204 to the image by using
1205 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
1206 the variable.
1207 </para>
1208 </glossdef>
1209 </glossentry>
1210
1211 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
1212 <glossdef>
1213 <para>
1214 Defines additional free disk space created in the image in Kbytes.
1215 By default, this variable is set to "0".
1216 This free disk space is added to the image after the build system determines
1217 the image size as described in
1218 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
1219 </para>
1220
1221 <para>
1222 This variable is particularly useful when you want to ensure that a
1223 specific amount of free disk space is available on a device after an image
1224 is installed and running.
1225 For example, to be sure 5 Gbytes of free disk space is available, set the
1226 variable as follows:
1227 <literallayout class='monospaced'>
1228 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
1229 </literallayout>
1230 </para>
1231 </glossdef>
1232 </glossentry>
1233
1234 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
1235 <glossdef>
1236 <para>
1237 Defines the size in Kbytes for the generated image.
1238 The OpenEmbedded build system determines the final size for the generated
1239 image using an algorithm that takes into account the initial disk space used
1240 for the generated image, a requested size for the image, and requested
1241 additional free disk space to be added to the image.
1242 Programatically, the build system determines the final size of the
1243 generated image as follows:
1244 <literallayout class='monospaced'>
1245 if (image-du * overhead) &lt; rootfs-size:
1246 internal-rootfs-size = rootfs-size + xspace
1247 else:
1248 internal-rootfs-size = (image-du * overhead) + xspace
1249
1250 where:
1251
1252 image-du = Returned value of the du command on
1253 the image.
1254
1255 overhead = IMAGE_OVERHEAD_FACTOR
1256
1257 rootfs-size = IMAGE_ROOTFS_SIZE
1258
1259 internal-rootfs-size = Initial root filesystem
1260 size before any modifications.
1261
1262 xspace = IMAGE_ROOTFS_EXTRA_SPACE
1263 </literallayout>
1264<!-- In the above example, <filename>overhead</filename> is defined by the
1265 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
1266 variable, <filename>xspace</filename> is defined by the
1267 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
1268 variable, and <filename>du</filename> is the results of the disk usage command
1269 on the initially generated image. -->
1270 </para>
1271 </glossdef>
1272 </glossentry>
1273
1274 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
1275 <glossdef>
1276 <para>Helps define the recipe revision for recipes that share
1277 a common <filename>include</filename> file.
1278 You can think of this variable as part of the recipe revision
1279 as set from within an include file.</para>
1280 <para>Suppose, for example, you have a set of recipes that
1281 are used across several projects.
1282 And, within each of those recipes the revision
1283 (its <filename>PR</filename> value) is set accordingly.
1284 In this case, when the revision of those recipes changes
1285 the burden is on you to find all those recipes and
1286 be sure that they get changed to reflect the updated
1287 version of the recipe.
1288 In this scenario, it can get complicated when recipes
1289 used in many places and that provide common functionality
1290 are upgraded to a new revision.</para>
1291 <para>A more efficient way of dealing with this situation is
1292 to set the <filename>INC_PR</filename> variable inside
1293 the <filename>include</filename> files that the recipes
1294 share and then expand the <filename>INC_PR</filename>
1295 variable within the recipes to help
1296 define the recipe revision.
1297 </para>
1298 <para>
1299 The following provides an example that shows how to use
1300 the <filename>INC_PR</filename> variable
1301 given a common <filename>include</filename> file that
1302 defines the variable.
1303 Once the variable is defined in the
1304 <filename>include</filename> file, you can use the
1305 variable to set the <filename>PR</filename> values in
1306 each recipe.
1307 You will notice that when you set a recipe's
1308 <filename>PR</filename> you can provide more granular
1309 revisioning by appending values to the
1310 <filename>INC_PR</filename> variable:
1311 <literallayout class='monospaced'>
1312recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
1313recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
1314recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
1315recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
1316 </literallayout>
1317 The first line of the example establishes the baseline
1318 revision to be used for all recipes that use the
1319 <filename>include</filename> file.
1320 The remaining lines in the example are from individual
1321 recipes and show how the <filename>PR</filename> value
1322 is set.</para>
1323 </glossdef>
1324 </glossentry>
1325
1326 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
1327 <glossdef>
1328 <para>
1329 Causes the build to not strip binaries in resulting packages.
1330 </para>
1331 </glossdef>
1332 </glossentry>
1333
1334
1335 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
1336 <glossdef>
1337 <para>
1338 Causes the named class to be inherited at
1339 this point during parsing.
1340 The variable is only valid in configuration files.
1341 </para>
1342 </glossdef>
1343 </glossentry>
1344
1345
1346 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
1347 <glossdef>
1348 <para>
1349 A list of the packages that contain initscripts.
1350 If multiple packages are specified, you need to append the package name
1351 to the other <filename>INITSCRIPT_*</filename> as an override.</para>
1352 <para>
1353 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
1354 The variable is optional and defaults to the <filename>PN</filename> variable.
1355 </para>
1356 </glossdef>
1357 </glossentry>
1358
1359 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
1360 <glossdef>
1361 <para>
1362 The filename of the initscript (as installed to <filename>${etcdir}/init.d)</filename>.
1363 </para>
1364 <para>
1365 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
1366 The variable is Mandatory.
1367 </para>
1368 </glossdef>
1369 </glossentry>
1370
1371 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
1372 <glossdef>
1373 <para>
1374 Specifies the options to pass to <filename>update-rc.d</filename>.
1375 An example is <filename>start 99 5 2 . stop 20 0 1 6 .</filename>, which gives the script a
1376 runlevel of 99, starts the script in initlevels 2 and 5, and
1377 stops the script in levels 0, 1 and 6.
1378 </para>
1379 <para>
1380 The variable is mandatory and is used in recipes when using
1381 <filename>update-rc.d.bbclass</filename>.
1382 </para>
1383 </glossdef>
1384 </glossentry>
1385
1386
1387 </glossdiv>
1388
1389<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
1390<!-- </glossdiv>-->
1391
1392 <glossdiv id='var-glossary-k'><title>K</title>
1393
1394 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
1395 <glossdef>
1396 <para>
1397 A regular expression used by the build process to explicitly identify the kernel
1398 branch that is validated, patched and configured during a build.
1399 The <filename>KBRANCH</filename> variable is optional.
1400 You can use it to trigger checks to ensure the exact kernel branch you want is
1401 being used by the build process.
1402 </para>
1403
1404 <para>
1405 Values for this variable are set in the kernel's recipe file and the kernel's
1406 append file.
1407 For example, if you are using the Yocto Project kernel that is based on the
1408 Linux 3.4 kernel, the kernel recipe file is the
1409 <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename> file.
1410 Following is the default value for <filename>KBRANCH</filename> and the default
1411 override for the architectures the Yocto Project supports:
1412 <literallayout class='monospaced'>
1413 KBRANCH_DEFAULT = "standard/base"
1414 KBRANCH = "${KBRANCH_DEFAULT}"
1415 </literallayout>
1416 This branch exists in the <filename>linux-yocto-3.4</filename> kernel Git
1417 repository <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>.
1418 </para>
1419
1420 <para>
1421 This variable is also used from the kernel's append file to identify the kernel
1422 branch specific to a particular machine or target hardware.
1423 The kernel's append file is located in the BSP layer for a given machine.
1424 For example, the kernel append file for the Crown Bay BSP is in the
1425 <filename>meta-intel</filename> Git repository and is named
1426 <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>.
1427 Here are the related statements from the append file:
1428 <literallayout class='monospaced'>
1429 COMPATIBLE_MACHINE_crownbay = "crownbay"
1430 KMACHINE_crownbay = "crownbay"
1431 KBRANCH_crownbay = "standard/crownbay"
1432
1433 COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
1434 KMACHINE_crownbay-noemgd = "crownbay"
1435 KBRANCH_crownbay-noemgd = "standard/crownbay"
1436 </literallayout>
1437 The <filename>KBRANCH_*</filename> statements identify the kernel branch to
1438 use when building for the Crown Bay BSP.
1439 In this case there are two identical statements: one for each type of
1440 Crown Bay machine.
1441 </para>
1442 </glossdef>
1443 </glossentry>
1444
1445 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
1446 <glossdef>
1447 <para>Includes additional metadata from the Yocto Project kernel Git repository.
1448 In the OpenEmbedded build system, the default Board Support Packages (BSPs)
1449 metadata is provided through
1450 the <filename>KMACHINE</filename> and <filename>KBRANCH</filename> variables.
1451 You can use the <filename>KERNEL_FEATURES</filename> variable to further
1452 add metadata for all BSPs.</para>
1453 <para>The metadata you add through this variable includes config fragments and
1454 features descriptions,
1455 which usually includes patches as well as config fragments.
1456 You typically override the <filename>KERNEL_FEATURES</filename> variable
1457 for a specific machine.
1458 In this way, you can provide validated, but optional, sets of kernel
1459 configurations and features.</para>
1460 <para>For example, the following adds <filename>netfilter</filename> to all
1461 the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>
1462 machine:
1463 <literallayout class='monospaced'>
1464 # Add netfilter to all linux-yocto kernels
1465 KERNEL_FEATURES="features/netfilter"
1466
1467 # Add sound support to the qemux86 machine
1468 KERNEL_FEATURES_append_qemux86=" cfg/sound"
1469 </literallayout></para>
1470 </glossdef>
1471 </glossentry>
1472
1473 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
1474 <glossdef>
1475 <para>The type of kernel to build for a device, usually set by the
1476 machine configuration files and defaults to "zImage".
1477 This variable is used
1478 when building the kernel and is passed to <filename>make</filename> as the target to
1479 build.</para>
1480 </glossdef>
1481 </glossentry>
1482
1483 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
1484 <glossdef>
1485 <para>
1486 The machine as known by the kernel.
1487 Sometimes the machine name used by the kernel does not match the machine name
1488 used by the OpenEmbedded build system.
1489 For example, the machine name that the OpenEmbedded build system understands as
1490 <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel.
1491 The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
1492 For cases like these, the <filename>KMACHINE</filename> variable maps the
1493 kernel machine name to the OpenEmbedded build system machine name.
1494 </para>
1495
1496 <para>
1497 Kernel machine names are initially defined in the
1498 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Yocto Linux Kernel</ulink> in
1499 the <filename>meta</filename> branch.
1500 From the <filename>meta</filename> branch, look in
1501 the <filename>meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</filename> file.
1502 For example, from the <filename>meta</filename> branch in the
1503 <filename>linux-yocto-3.0</filename> kernel, the
1504 <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file
1505 has the following:
1506 <literallayout class='monospaced'>
1507 define KMACHINE cedartrail
1508 define KTYPE standard
1509 define KARCH i386
1510
1511 include ktypes/standard
1512 branch cedartrail
1513
1514 include cedartrail.scc
1515 </literallayout>
1516 You can see that the kernel understands the machine name for the Cedar Trail BSP as
1517 <filename>cedartrail</filename>.
1518 </para>
1519
1520 <para>
1521 If you look in the Cedar Trail BSP layer in the <filename>meta-intel</filename> source
1522 repository at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>,
1523 you will find the following statements among others:
1524 <literallayout class='monospaced'>
1525 COMPATIBLE_MACHINE_cedartrail = "cedartrail"
1526 KMACHINE_cedartrail = "cedartrail"
1527 KBRANCH_cedartrail = "yocto/standard/cedartrail"
1528 KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
1529 KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
1530
1531 COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
1532 KMACHINE_cedartrail-nopvr = "cedartrail"
1533 KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail"
1534 KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
1535 </literallayout>
1536 The <filename>KMACHINE</filename> statements in the kernel's append file make sure that
1537 the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
1538 names.
1539 </para>
1540
1541 <para>
1542 This append file uses two <filename>KMACHINE</filename> statements.
1543 The first is not really necessary but does ensure that the machine known to the
1544 OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
1545 in the kernel also known as <filename>cedartrail</filename>:
1546 <literallayout class='monospaced'>
1547 KMACHINE_cedartrail = "cedartrail"
1548 </literallayout>
1549 </para>
1550
1551 <para>
1552 The second statement is a good example of why the <filename>KMACHINE</filename> variable
1553 is needed.
1554 In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename>
1555 machine name to refer to the Cedar Trail BSP that does not support the propriatory
1556 PowerVR driver.
1557 The kernel, however, uses the machine name <filename>cedartrail</filename>.
1558 Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to
1559 the kernel's <filename>cedartrail</filename> name:
1560 <literallayout class='monospaced'>
1561 KMACHINE_cedartrail-nopvr = "cedartrail"
1562 </literallayout>
1563 </para>
1564
1565 <para>
1566 BSPs that ship with the Yocto Project release provide all mappings between the Yocto
1567 Project kernel machine names and the OpenEmbedded machine names.
1568 Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine
1569 name you use is different than that used in the kernel.
1570 </para>
1571 </glossdef>
1572 </glossentry>
1573
1574 </glossdiv>
1575
1576 <glossdiv id='var-glossary-l'><title>L</title>
1577
1578 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
1579 <glossdef>
1580 <para>Lists the layers that this recipe depends upon, separated by spaces.
1581 Optionally, you can specify a specific layer version for a dependency
1582 by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
1583 to be compared against <filename>LAYERVERSION_anotherlayer</filename> in this case).
1584 An error will be produced if any dependency is missing or
1585 the version numbers do not match exactly (if specified).
1586 This variable is used in the <filename>conf/layer.conf</filename> file
1587 and must be suffixed with the name of the specific layer (e.g.
1588 <filename>LAYERDEPENDS_mylayer</filename>).</para>
1589 </glossdef>
1590 </glossentry>
1591
1592 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
1593 <glossdef>
1594 <para>When used inside the <filename>layer.conf</filename> configuration
1595 file, this variable provides the path of the current layer.
1596 This variable requires immediate expansion
1597 (see the BitBake manual) as lazy expansion can result in
1598 the expansion happening in the wrong directory and therefore
1599 giving the wrong value.</para>
1600 </glossdef>
1601 </glossentry>
1602
1603 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
1604 <glossdef>
1605 <para>Optionally specifies the version of a layer as a single number.
1606 You can use this within <filename>LAYERDEPENDS</filename> for another layer in order to
1607 depend on a specific version of the layer.
1608 This variable is used in the <filename>conf/layer.conf</filename> file
1609 and must be suffixed with the name of the specific layer (e.g.
1610 <filename>LAYERVERSION_mylayer</filename>).</para>
1611 </glossdef>
1612 </glossentry>
1613
1614 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
1615 <glossdef>
1616 <para>Checksums of the license text in the recipe source code.</para>
1617 <para>This variable tracks changes in license text of the source
1618 code files.
1619 If the license text is changed, it will trigger a build
1620 failure, which gives the developer an opportunity to review any
1621 license change.</para>
1622 <para>
1623 This variable must be defined for all recipes (unless <filename>LICENSE</filename>
1624 is set to "CLOSED")</para>
1625 <para>For more information, see the
1626 <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
1627 Tracking License Changes</link> section</para>
1628 </glossdef>
1629 </glossentry>
1630
1631 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
1632 <glossdef>
1633 <para>
1634 The list of source licenses for the recipe.
1635 Follow these rules:
1636 <itemizedlist>
1637 <listitem><para>Do not use spaces within individual
1638 license names.</para></listitem>
1639 <listitem><para>Separate license names using
1640 | (pipe) when there is a choice between licenses.
1641 </para></listitem>
1642 <listitem><para>Separate license names using
1643 &amp; (ampersand) when multiple licenses exist
1644 that cover different parts of the source.
1645 </para></listitem>
1646 <listitem><para>You can use spaces between license
1647 names.</para></listitem>
1648 </itemizedlist>
1649 </para>
1650
1651 <para>
1652 Here are some examples:
1653 <literallayout class='monospaced'>
1654 LICENSE = "LGPLv2.1 | GPLv3"
1655 LICENSE = "MPL-1 &amp; LGPLv2.1"
1656 LICENSE = "GPLv2+"
1657 </literallayout>
1658 The first example is from the recipes for Qt, which the user
1659 may choose to distribute under either the LGPL version
1660 2.1 or GPL version 3.
1661 The second example is from Cairo where two licenses cover
1662 different parts of the source code.
1663 The final example is from <filename>sysstat</filename>,
1664 which presents a single license.
1665 </para>
1666 </glossdef>
1667 </glossentry>
1668
1669 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
1670 <glossdef>
1671 <para>Path to additional licenses used during the build.
1672 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
1673 to define the directory that holds common license text used during the build.
1674 The <filename>LICENSE_PATH</filename> variable allows you to extend that
1675 location to other areas that have additional licenses:
1676 <literallayout class='monospaced'>
1677 LICENSE_PATH += "/path/to/additional/common/licenses"
1678 </literallayout></para>
1679 </glossdef>
1680 </glossentry>
1681
1682 </glossdiv>
1683
1684 <glossdiv id='var-glossary-m'><title>M</title>
1685
1686 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
1687 <glossdef>
1688 <para>
1689 Specifies the target device for which the image is built.
1690 You define <filename>MACHINE</filename> in the
1691 <filename>local.conf</filename> file found in the
1692 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
1693 By default, <filename>MACHINE</filename> is set to
1694 "qemux86", which is an x86-based architecture machine to
1695 be emulated using QEMU:
1696 <literallayout class='monospaced'>
1697 MACHINE ?= "qemux86"
1698 </literallayout>
1699 The variable corresponds to a machine configuration file of the
1700 same name, through which machine-specific configurations are set.
1701 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
1702 exists the corresponding <filename>qemux86.conf</filename> machine
1703 configuration file, which can be found in the
1704 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
1705 in <filename>meta/conf/machine</filename>.
1706 </para>
1707
1708 <para>
1709 The list of machines supported by the Yocto Project as
1710 shipped include the following:
1711 <literallayout class='monospaced'>
1712 MACHINE ?= "qemuarm"
1713 MACHINE ?= "qemumips"
1714 MACHINE ?= "qemuppc"
1715 MACHINE ?= "qemux86"
1716 MACHINE ?= "qemux86-64"
1717 MACHINE ?= "atom-pc"
1718 MACHINE ?= "beagleboard"
1719 MACHINE ?= "mpc8315e-rdb"
1720 MACHINE ?= "routerstationpro"
1721 </literallayout>
1722 The last four are Yocto Project reference hardware boards, which
1723 are provided in the <filename>meta-yocto-bsp</filename> layer.
1724 <note>Adding additional Board Support Package (BSP) layers
1725 to your configuration adds new possible settings for
1726 <filename>MACHINE</filename>.
1727 </note>
1728 </para>
1729 </glossdef>
1730 </glossentry>
1731
1732 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
1733 <glossdef>
1734 <para></para>
1735 <para>
1736 A list of required machine-specific packages to install as part of
1737 the image being built.
1738 The build process depends on these packages being present.
1739 Furthermore, because this is a "machine essential" variable, the list of
1740 packages are essential for the machine to boot.
1741 The impact of this variable affects images based on
1742 <filename>packagegroup-core-boot</filename>,
1743 including the <filename>core-image-minimal</filename> image.
1744 </para>
1745 <para>
1746 This variable is similar to the
1747 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
1748 variable with the exception that the image being built has a build
1749 dependency on the variable's list of packages.
1750 In other words, the image will not build if a file in this list is not found.
1751 </para>
1752 <para>
1753 As an example, suppose the machine for which you are building requires
1754 <filename>example-init</filename> to be run during boot to initialize the hardware.
1755 In this case, you would use the following in the machine's
1756 <filename>.conf</filename> configuration file:
1757 <literallayout class='monospaced'>
1758 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
1759 </literallayout>
1760 </para>
1761 </glossdef>
1762 </glossentry>
1763
1764 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
1765 <glossdef>
1766 <para></para>
1767 <para>
1768 A list of recommended machine-specific packages to install as part of
1769 the image being built.
1770 The build process does not depend on these packages being present.
1771 However, because this is a "machine essential" variable, the list of
1772 packages are essential for the machine to boot.
1773 The impact of this variable affects images based on
1774 <filename>packagegroup-core-boot</filename>,
1775 including the <filename>core-image-minimal</filename> image.
1776 </para>
1777 <para>
1778 This variable is similar to the
1779 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
1780 variable with the exception that the image being built does not have a build
1781 dependency on the variable's list of packages.
1782 In other words, the image will still build if a package in this list is not found.
1783 Typically, this variable is used to handle essential kernel modules, whose
1784 functionality may be selected to be built into the kernel rather than as a module,
1785 in which case a package will not be produced.
1786 </para>
1787 <para>
1788 Consider an example where you have a custom kernel where a specific touchscreen
1789 driver is required for the machine to be usable.
1790 However, the driver can be built as a module or
1791 into the kernel depending on the kernel configuration.
1792 If the driver is built as a module, you want it to be installed.
1793 But, when the driver is built into the kernel, you still want the
1794 build to succeed.
1795 This variable sets up a "recommends" relationship so that in the latter case,
1796 the build will not fail due to the missing package.
1797 To accomplish this, assuming the package for the module was called
1798 <filename>kernel-module-ab123</filename>, you would use the
1799 following in the machine's <filename>.conf</filename> configuration
1800 file:
1801 <literallayout class='monospaced'>
1802 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
1803 </literallayout>
1804 </para>
1805 <para>
1806 Some examples of these machine essentials are flash, screen, keyboard, mouse,
1807 or touchscreen drivers (depending on the machine).
1808 </para>
1809 </glossdef>
1810 </glossentry>
1811
1812 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
1813 <glossdef>
1814 <para>
1815 A list of machine-specific packages to install as part of the
1816 image being built that are not essential for the machine to boot.
1817 However, the build process for more fully-featured images
1818 depends on the packages being present.
1819 </para>
1820 <para>
1821 This variable affects all images based on
1822 <filename>packagegroup-base</filename>, which does not include the
1823 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
1824 images.
1825 </para>
1826 <para>
1827 The variable is similar to the
1828 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
1829 variable with the exception that the image being built has a build
1830 dependency on the variable's list of packages.
1831 In other words, the image will not build if a file in this list is not found.
1832 </para>
1833 <para>
1834 An example is a machine that has WiFi capability but is not essential
1835 For the machine to boot the image.
1836 However, if you are building a more fully-featured image, you want to enable
1837 the WiFi.
1838 The package containing the firmware for the WiFi hardware is always
1839 expected to exist, so it is acceptable for the build process to depend upon
1840 finding the package.
1841 In this case, assuming the package for the firmware was called
1842 <filename>wifidriver-firmware</filename>, you would use the following in the
1843 <filename>.conf</filename> file for the machine:
1844 <literallayout class='monospaced'>
1845 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
1846 </literallayout>
1847 </para>
1848 </glossdef>
1849 </glossentry>
1850
1851 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
1852 <glossdef>
1853 <para></para>
1854 <para>
1855 A list of machine-specific packages to install as part of the
1856 image being built that are not essential for booting the machine.
1857 The image being built has no build dependency on this list of packages.
1858 </para>
1859 <para>
1860 This variable affects only images based on
1861 <filename>packagegroup-base</filename>, which does not include the
1862 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
1863 images.
1864 </para>
1865 <para>
1866 This variable is similar to the
1867 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
1868 variable with the exception that the image being built does not have a build
1869 dependency on the variable's list of packages.
1870 In other words, the image will build if a file in this list is not found.
1871 </para>
1872 <para>
1873 An example is a machine that has WiFi capability but is not essential
1874 For the machine to boot the image.
1875 However, if you are building a more fully-featured image, you want to enable
1876 WiFi.
1877 In this case, the package containing the WiFi kernel module will not be produced
1878 if the WiFi driver is built into the kernel, in which case you still want the
1879 build to succeed instead of failing as a result of the package not being found.
1880 To accomplish this, assuming the package for the module was called
1881 <filename>kernel-module-examplewifi</filename>, you would use the
1882 following in the <filename>.conf</filename> file for the machine:
1883 <literallayout class='monospaced'>
1884 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
1885 </literallayout>
1886 </para>
1887 </glossdef>
1888 </glossentry>
1889
1890 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
1891 <glossdef>
1892 <para>Specifies the list of hardware features the
1893 <link linkend='var-MACHINE'>MACHINE</link> supports.
1894 For example, including the "bluetooth" feature causes the
1895 <filename>bluez</filename> bluetooth daemon to be built and
1896 added to the image.
1897 It also causes the <filename>connman</filename> recipe
1898 to look at <filename>MACHINE_FEATURES</filename> and when it
1899 finds "bluetooth" there it enables the bluetooth
1900 support in ConnMan.
1901 </para>
1902
1903 <para>
1904 For a list of features supported by the Yocto Project as shipped,
1905 see the "<link linkend='ref-features-machine'>Machine</link>" section.
1906 </para>
1907 </glossdef>
1908 </glossentry>
1909
1910 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
1911 <glossdef>
1912 <para>Features to be added to
1913 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
1914 if not also present in
1915 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
1916 </para>
1917
1918 <para>
1919 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
1920 It is not intended to be user-configurable.
1921 It is best to just reference the variable to see which machine features are
1922 being backfilled for all machine configurations.
1923 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1924 more information.
1925 </para>
1926 </glossdef>
1927 </glossentry>
1928
1929 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
1930 <glossdef>
1931 <para>Features from
1932 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
1933 that should not be backfilled (i.e. added to
1934 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
1935 during the build.
1936 See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
1937 more information.
1938 </para>
1939 </glossdef>
1940 </glossentry>
1941
1942 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
1943 <glossdef>
1944 <para>The email address of the distribution maintainer.</para>
1945 </glossdef>
1946 </glossentry>
1947
1948 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
1949 <glossdef>
1950 <para>
1951 Specifies a prefix has been added to
1952 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
1953 of a recipe or package, such as a multilib version.
1954 The variable is used in places where the prefix needs to be
1955 added to or removed from a the name (e.g. the
1956 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
1957 <filename>MLPREFIX</filename> gets set when a prefix has been
1958 added to <filename>PN</filename>.
1959 </para>
1960 </glossdef>
1961 </glossentry>
1962
1963 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
1964 <glossdef>
1965 <para>
1966 Separates files for different machines such that you can build
1967 for multiple target machines using the same output directories.
1968 See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable
1969 for an example.
1970 </para>
1971 </glossdef>
1972 </glossentry>
1973
1974 </glossdiv>
1975
1976<!-- <glossdiv id='var-glossary-n'><title>N</title>-->
1977<!-- </glossdiv>-->
1978
1979 <glossdiv id='var-glossary-o'><title>O</title>
1980
1981 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
1982 <glossdef>
1983 <para>
1984 Controls how the OpenEmbedded build system spawns
1985 interactive terminals on the host development system
1986 (e.g. using the BitBake command with the
1987 <filename>-c devshell</filename> command-line option).
1988 For more information, see the
1989 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
1990 in the Yocto Project Development Manual.
1991 </para>
1992
1993 <para>
1994 You can use the following values for the
1995 <filename>OE_TERMINAL</filename> variable:
1996 <literallayout class='monospaced'>
1997 auto
1998 gnome
1999 xfce
2000 rxvt
2001 screen
2002 konsole
2003 none
2004 </literallayout>
2005 <note>Konsole support only works for KDE 3.x.
2006 Also, "auto" is the default behavior for
2007 <filename>OE_TERMINAL</filename></note>
2008 </para>
2009 </glossdef>
2010 </glossentry>
2011 </glossdiv>
2012
2013 <glossdiv id='var-glossary-p'><title>P</title>
2014
2015 <glossentry id='var-P'><glossterm>P</glossterm>
2016 <glossdef>
2017 <para>The recipe name and version.
2018 <filename>P</filename> is comprised of the following:
2019 <literallayout class='monospaced'>
2020 ${PN}-${PV}
2021 </literallayout></para>
2022 </glossdef>
2023 </glossentry>
2024
2025 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
2026 <glossdef>
2027 <para>The architecture of the resulting package or packages.</para>
2028 </glossdef>
2029 </glossentry>
2030
2031 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
2032 <glossdef>
2033 <para>Enables easily adding packages to
2034 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
2035 before <filename>${PN}</filename> so that the packages can pick
2036 up files that would normally be included in the default package.</para>
2037 </glossdef>
2038 </glossentry>
2039
2040 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
2041 <glossdef>
2042 <para>This variable, which is set in the <filename>local.conf</filename> configuration
2043 file found in the <filename>conf</filename> folder of the
2044 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
2045 specifies the package manager to use when packaging data.
2046 You can provide one or more arguments for the variable with the first
2047 argument being the package manager used to create images:
2048 <literallayout class='monospaced'>
2049 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
2050 </literallayout>
2051 For information on build performance effects as a result of the
2052 package manager use, see
2053 <link linkend='ref-classes-package'>Packaging - <filename>package*.bbclass</filename></link>
2054 in this manual.
2055 </para>
2056 </glossdef>
2057 </glossentry>
2058
2059 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
2060 <glossdef>
2061 <para>Specifies the list of architectures compatible with the device CPU.
2062 This variable is useful when you build for several different devices that use
2063 miscellaneous processors such as XScale and ARM926-EJS).</para>
2064 </glossdef>
2065 </glossentry>
2066
2067 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
2068 <glossdef>
2069 <para>
2070 This variable provides a means of enabling or disabling
2071 features of a recipe on a per-recipe basis.
2072 The <filename>PACKAGECONFIG</filename>
2073 variable itself specifies a space-separated list of the
2074 features to enable.
2075 The features themselves are specified as flags on the
2076 <filename>PACKAGECONFIG</filename> variable.
2077 You can provide up to four arguments, which are separated by
2078 commas, to determine the behavior of each feature
2079 when it is enabled or disabled.
2080 You can omit any argument you like but must retain the
2081 separating commas.
2082 The arguments specify the following:
2083 <orderedlist>
2084 <listitem><para>Extra arguments
2085 that should be added to the configure script argument list
2086 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>)
2087 if the feature is enabled.</para></listitem>
2088 <listitem><para>Extra arguments
2089 that should be added to <filename>EXTRA_OECONF</filename>
2090 if the feature is disabled.
2091 </para></listitem>
2092 <listitem><para>Additional build dependencies
2093 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
2094 that should be added if the feature is enabled.
2095 </para></listitem>
2096 <listitem><para>Additional runtime dependencies
2097 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
2098 that should be added if the feature is enabled.
2099 </para></listitem>
2100 </orderedlist>
2101 </para>
2102
2103 <para>
2104 Consider the following example taken from the
2105 <filename>librsvg</filename> recipe.
2106 In this example the feature is <filename>croco</filename>, which
2107 has three arguments that determine the feature's behavior.
2108 <literallayout class='monospaced'>
2109 PACKAGECONFIG ??= "croco"
2110 PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
2111 </literallayout>
2112 The <filename>--with-croco</filename> and
2113 <filename>libcroco</filename> arguments apply only if
2114 the feature is enabled.
2115 In this case, <filename>--with-croco</filename> is
2116 added to the configure script argument list and
2117 <filename>libcroco</filename> is added to
2118 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
2119 On the other hand, if the feature is disabled say through
2120 a <filename>.bbappend</filename> file in another layer, then
2121 the second argument <filename>--without-croco</filename> is
2122 added to the configure script rather than
2123 <filename>--with-croco</filename>.
2124 </para>
2125 </glossdef>
2126 </glossentry>
2127
2128 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
2129 <glossdef>
2130 <para>The list of packages to be created from the recipe.
2131 The default value is the following:
2132 <literallayout class='monospaced'>
2133 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
2134 </literallayout></para>
2135 </glossdef>
2136 </glossentry>
2137
2138 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
2139 <glossdef>
2140 <para>
2141 A promise that your recipe satisfies runtime dependencies
2142 for optional modules that are found in other recipes.
2143 <filename>PACKAGES_DYNAMIC</filename>
2144 does not actually satisfy the dependencies, it only states that
2145 they should be satisfied.
2146 For example, if a hard, runtime dependency
2147 (<filename>RDEPENDS</filename>) of another package is satisfied
2148 at build time through the <filename>PACKAGES_DYNAMIC</filename>
2149 variable, but a package with the module name is never actually
2150 produced, then the other package will be broken.
2151 Thus, if you attempt to include that package in an image,
2152 you will get a dependency failure from the packaging system
2153 during <filename>do_rootfs</filename>.
2154 Typically, if there is a chance that such a situation can
2155 occur and the package that is not created is valid
2156 without the dependency being satisfied, then you should use
2157 <filename>RRECOMMENDS</filename> (a soft runtime dependency)
2158 instead of <filename>RDEPENDS</filename>.
2159 </para>
2160
2161 <para>
2162 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
2163 variable when you are splitting packages, see the
2164 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
2165 in the Yocto Project Development Manual.
2166 </para>
2167 </glossdef>
2168 </glossentry>
2169
2170 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
2171 <glossdef>
2172 <para>Specifies extra options that are passed to the <filename>make</filename> command during the
2173 compile tasks.
2174 This variable is usually in the form <filename>-j 4</filename>, where the number
2175 represents the maximum number of parallel threads make can run.
2176 If you development host supports multiple cores a good rule of thumb is to set
2177 this variable to twice the number of cores on the host.</para>
2178 </glossdef>
2179 </glossentry>
2180
2181 <glossentry id='var-PF'><glossterm>PF</glossterm>
2182 <glossdef>
2183 <para>Specifies the recipe or package name and includes all version and revision
2184 numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
2185 <filename>bash-4.2-r1/</filename>).
2186 This variable is comprised of the following:
2187 <literallayout class='monospaced'>
2188 ${PN}-${EXTENDPE}${PV}-${PR}
2189 </literallayout></para>
2190 </glossdef>
2191 </glossentry>
2192
2193 <glossentry id='var-PN'><glossterm>PN</glossterm>
2194 <glossdef>
2195 <para>This variable can have two separate functions depending on the context: a recipe
2196 name or a resulting package name.</para>
2197 <para><filename>PN</filename> refers to a recipe name in the context of a file used
2198 by the OpenEmbedded build system as input to create a package.
2199 The name is normally extracted from the recipe file name.
2200 For example, if the recipe is named
2201 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
2202 will be "expat".</para>
2203 <para>
2204 The variable refers to a package name in the context of a file created or produced by the
2205 OpenEmbedded build system.</para>
2206 <para>If applicable, the <filename>PN</filename> variable also contains any special
2207 suffix or prefix.
2208 For example, using <filename>bash</filename> to build packages for the native
2209 machine, <filename>PN</filename> is <filename>bash-native</filename>.
2210 Using <filename>bash</filename> to build packages for the target and for Multilib,
2211 <filename>PN</filename> would be <filename>bash</filename> and
2212 <filename>lib64-bash</filename>, respectively.
2213 </para>
2214 </glossdef>
2215 </glossentry>
2216
2217 <glossentry id='var-PR'><glossterm>PR</glossterm>
2218 <glossdef>
2219 <para>The revision of the recipe.
2220 The default value for this variable is "r0".
2221 </para>
2222 </glossdef>
2223 </glossentry>
2224
2225 <glossentry id='var-PRINC'><glossterm>PRINC</glossterm>
2226 <glossdef>
2227 <para>Causes the <filename>PR</filename> variable of
2228 <filename>.bbappend</filename> files to dynamically increment.
2229 This increment minimizes the impact of layer ordering.</para>
2230 <para>In order to ensure multiple <filename>.bbappend</filename> files can co-exist,
2231 <filename>PRINC</filename> should be self referencing.
2232 This variable defaults to 0.</para>
2233 <para>Following is an example that increments <filename>PR</filename> by two:
2234 <literallayout class='monospaced'>
2235 PRINC := "${@int(PRINC) + 2}"
2236 </literallayout>
2237 It is adviseable not to use strings such as ".= '.1'" with the variable because
2238 this usage is very sensitive to layer ordering.
2239 Explicit assignments should be avoided as they cannot adequately represent multiple
2240 <filename>.bbappend</filename> files.</para>
2241 </glossdef>
2242 </glossentry>
2243
2244 <glossentry id='var-PV'><glossterm>PV</glossterm>
2245 <glossdef>
2246 <para>The version of the recipe.
2247 The version is normally extracted from the recipe filename.
2248 For example, if the recipe is named
2249 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename>
2250 will be "2.0.1".
2251 <filename>PV</filename> is generally not overridden within
2252 a recipe unless it is building an unstable (i.e. development) version from a source code repository
2253 (e.g. Git or Subversion).
2254 </para>
2255 </glossdef>
2256 </glossentry>
2257
2258 <glossentry id='var-PE'><glossterm>PE</glossterm>
2259 <glossdef>
2260 <para>
2261 the epoch of the recipe.
2262 The default value is "0".
2263 The field is used to make upgrades possible when the versioning scheme changes in
2264 some backwards incompatible way.
2265 </para>
2266 </glossdef>
2267 </glossentry>
2268
2269 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
2270 <glossdef>
2271 <para>
2272 If multiple recipes provide an item, this variable
2273 determines which recipe should be given preference.
2274 The variable must always be suffixed with the name of the
2275 provided item, and should be set to the
2276 <filename>PN</filename> of the recipe
2277 to which you want to give precedence.
2278 Here is an example:
2279 <literallayout class='monospaced'>
2280 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
2281 </literallayout>
2282 </para>
2283 </glossdef>
2284 </glossentry>
2285
2286 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
2287 <glossdef>
2288 <para>
2289 If there are multiple versions of recipes available, this
2290 variable determines which recipe should be given preference.
2291 The variable must always be suffixed with the <filename>PN</filename>
2292 for which to select, and should be set to the
2293 <filename>PV</filename> to which you want to give precedence.
2294 You can use the "<filename>%</filename>" character as a wildcard
2295 to match any number of characters, which can be useful when
2296 specifying versions that contain long revision number that could
2297 potentially change.
2298 Here are two examples:
2299 <literallayout class='monospaced'>
2300 PREFERRED_VERSION_python = "2.6.6"
2301 PREFERRED_VERSION_linux-yocto = "3.0+git%"
2302 </literallayout>
2303 </para>
2304 </glossdef>
2305 </glossentry>
2306
2307 </glossdiv>
2308
2309<!-- <glossdiv id='var-glossary-q'><title>Q</title>-->
2310<!-- </glossdiv>-->
2311
2312 <glossdiv id='var-glossary-r'><title>R</title>
2313
2314 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
2315 <glossdef>
2316 <para>The list of packages that conflict with a package.
2317 Note that the package will not be installed if the conflicting packages are not
2318 first removed.</para>
2319 <para>
2320 Like all package-controlling variables, you must always use them in
2321 conjunction with a package name override.
2322 Here is an example:
2323 <literallayout class='monospaced'>
2324 RCONFLICTS_${PN} = "another-conflicting-package-name"
2325 </literallayout>
2326 </para>
2327 </glossdef>
2328 </glossentry>
2329
2330 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
2331 <glossdef>
2332 <para>
2333 Lists a package's run-time dependencies (i.e. other packages)
2334 that must be installed for the package to be built.
2335 In other words, in order for the package to be built and
2336 run correctly, it depends on the listed packages.
2337 If a package in this list cannot be found, it is probable
2338 that a dependency error would occur before the build.
2339 </para>
2340
2341 <para>
2342 The names of the variables you list with
2343 <filename>RDEPENDS</filename> must be the names of other
2344 packages as listed in the
2345 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
2346 variable.
2347 You should not list recipe names (<filename>PN</filename>).
2348 </para>
2349
2350 <para>
2351 Because the <filename>RDEPENDS</filename> variable applies
2352 to packages being built, you should
2353 always attach a package name to the variable to specify the
2354 particular run-time package that has the dependency.
2355 For example, suppose you are building a development package
2356 that depends on the <filename>perl</filename> package.
2357 In this case, you would use the following
2358 <filename>RDEPENDS</filename> statement:
2359 <literallayout class='monospaced'>
2360 RDEPENDS_${PN}-dev += "perl"
2361 </literallayout>
2362 In the example, the package name
2363 (<filename>${PN}-dev</filename>) must appear as it would
2364 in the
2365 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
2366 namespace before any renaming of the output package by
2367 classes like <filename>debian.bbclass</filename>.
2368 </para>
2369
2370 <para>
2371 In many cases you do not need to explicitly add dependencies
2372 to <filename>RDEPENDS</filename> since some automatic
2373 handling occurs:
2374 <itemizedlist>
2375 <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If
2376 a run-time package contains a shared library
2377 (<filename>.so</filename>), the build
2378 processes the library in order to determine other
2379 libraries to which it is dynamically linked.
2380 The build process adds these libraries to
2381 <filename>RDEPENDS</filename> when creating the run-time
2382 package.</para></listitem>
2383 <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If
2384 the package ships a <filename>pkg-config</filename>
2385 information file, the build process uses this file
2386 to add items to the <filename>RDEPENDS</filename>
2387 variable to create the run-time packages.
2388 </para></listitem>
2389 </itemizedlist>
2390 </para>
2391 </glossdef>
2392 </glossentry>
2393
2394 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
2395 <glossdef>
2396 <para>
2397 A list of packages that extend the usability of a package being
2398 built.
2399 The package being built does not depend on this list of packages in
2400 order to successfully build, but needs them for the extended usability.
2401 To specify runtime dependencies for packages, see the
2402 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variable.
2403 </para>
2404 <para>
2405 The OpenEmbedded build process automatically installs the list of packages
2406 as part of the built package.
2407 However, you can remove them later if you want.
2408 If, during the build, a package from the list cannot be found, the build
2409 process continues without an error.
2410 </para>
2411 <para>
2412 Because the <filename>RRECOMMENDS</filename> variable applies to packages
2413 being built, you should
2414 always attach an override to the variable to specify the particular package
2415 whose usability is being extended.
2416 For example, suppose you are building a development package that is extended
2417 to support wireless functionality.
2418 In this case, you would use the following:
2419 <literallayout class='monospaced'>
2420 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
2421 </literallayout>
2422 In the example, the package name (<filename>${PN}-dev</filename>) must
2423 appear as it would in the
2424 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> namespace before any
2425 renaming of the output package by classes like <filename>debian.bbclass</filename>.
2426 </para>
2427 </glossdef>
2428 </glossentry>
2429
2430 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
2431 <glossdef>
2432 <para>The list of packages that are replaced with this package.</para>
2433 </glossdef>
2434 </glossentry>
2435
2436 </glossdiv>
2437
2438 <glossdiv id='var-glossary-s'><title>S</title>
2439
2440 <glossentry id='var-S'><glossterm>S</glossterm>
2441 <glossdef>
2442 <para>
2443 The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
2444 where unpacked package source code resides.
2445 This location is within the working directory
2446 (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>), which
2447 is not static.
2448 The unpacked source location depends on the package name
2449 (<filename><link linkend='var-PN'>PN</link></filename>) and
2450 package version (<filename><link linkend='var-PV'>PV</link></filename>) as
2451 follows:
2452 <literallayout class='monospaced'>
2453 ${WORKDIR}/${PN}/${PV}
2454 </literallayout>
2455 As an example, assume a
2456 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level
2457 folder named <filename>poky</filename>
2458 and a default <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
2459 at <filename>poky/build</filename>.
2460 In this case, the working directory the build system uses to build
2461 the <filename>db</filename> package is the following:
2462 <literallayout class='monospaced'>
2463 ~/poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
2464 </literallayout>
2465 </para>
2466 </glossdef>
2467 </glossentry>
2468
2469 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
2470 <glossdef>
2471 <para>Equivalent to
2472 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
2473 However, this variable applies to the SDK generated from an image using
2474 <filename>bitbake -c populate_sdk imagename</filename>).
2475 </para>
2476 </glossdef>
2477 </glossentry>
2478
2479 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
2480 <glossdef>
2481 <para>The section in which packages should be categorized.
2482 Package management utilities can make use of this variable.</para>
2483 </glossdef>
2484 </glossentry>
2485
2486 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
2487 <glossdef>
2488 <para>
2489 The variable takes the value of
2490 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
2491 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
2492 In this case the value of
2493 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
2494 </para>
2495 </glossdef>
2496 </glossentry>
2497
2498
2499 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
2500 <glossdef>
2501 <para>The speed and device for the serial port used to attach the serial console.
2502 This variable is given to the kernel as the "console"
2503 parameter and after booting occurs <filename>getty</filename> is started on that port
2504 so remote login is possible.</para>
2505 </glossdef>
2506 </glossentry>
2507
2508 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
2509 <glossdef>
2510 <para>
2511 Specifies the endian byte order of the target system.
2512 The value should be either "le" for little-endian or "be" for big-endian.
2513 </para>
2514 </glossdef>
2515 </glossentry>
2516
2517 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
2518 <glossdef>
2519 <para>
2520 Specifies the number of bits for the target system CPU.
2521 The value should be either "32" or "64".
2522 </para>
2523 </glossdef>
2524 </glossentry>
2525
2526 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
2527 <glossdef>
2528 <para>
2529 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
2530 OpenEmbedded build system to create variants of recipes or packages.
2531 The list specifies the prefixes to strip off during certain circumstances
2532 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
2533 </para>
2534 </glossdef>
2535 </glossentry>
2536
2537 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
2538 <glossdef>
2539 <para>The list of source files - local or remote.
2540 This variable tells the OpenEmbedded build system which bits to pull
2541 in for the build and how to pull them in.
2542 For example, if the recipe only needs to fetch a tarball from the
2543 internet, the recipe uses a single <filename>SRC_URI</filename> entry.
2544 On the other hand, if the recipe needs to fetch a tarball, apply
2545 two patches, and include a custom file, the recipe would include four
2546 instances of the variable.</para>
2547 <para>The following list explains the available URI protocols:
2548 <itemizedlist>
2549 <listitem><para><emphasis><filename>file://</filename> -</emphasis> Fetches files, which is usually
2550 a file shipped with the metadata, from the local machine.
2551 The path is relative to the
2552 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
2553 variable.
2554 Thus, the build system searches, in order, from the following directories,
2555 which are assumed to be a subdirectories of the directory in which the
2556 recipe file resides:
2557 <itemizedlist>
2558 <listitem><para><emphasis><filename>${PN}</filename> -</emphasis> The recipe name
2559 with any special suffix or prefix, if applicable.
2560 For example, using <filename>bash</filename> to build for the native
2561 machine, <filename>PN</filename> is <filename>bash-native</filename>.
2562 Using <filename>bash</filename> to build for the target and for Multilib,
2563 <filename>PN</filename> would be <filename>bash</filename> and
2564 <filename>lib64-bash</filename>, respectively.
2565 </para></listitem>
2566 <listitem><para><emphasis><filename>${PF}</filename> - </emphasis>
2567 <filename>${PN}-${EXTENDPE}${PV}-${PR}</filename>.
2568 The recipe name including all version and revision numbers
2569 (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
2570 <filename>bash-4.2-r1/</filename>).</para></listitem>
2571 <listitem><para><emphasis><filename>${P}</filename> -</emphasis>
2572 <filename>${PN}-${PV}</filename>.
2573 The recipe name and version (i.e. <filename>bash-4.2</filename>).
2574 </para></listitem>
2575 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis> The
2576 base recipe name without any special suffix or version numbers.
2577 </para></listitem>
2578 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
2579 <filename>${BPN}-${PV}</filename>.
2580 The base recipe name and version but without any special
2581 package name suffix.</para></listitem>
2582 <listitem><para><emphasis>Files -</emphasis> Files beneath the directory in which the recipe
2583 resides.</para></listitem>
2584 <listitem><para><emphasis>Directory -</emphasis> The directory itself in which the recipe
2585 resides.</para></listitem>
2586 </itemizedlist></para></listitem>
2587 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
2588 Bazaar revision control repository.</para></listitem>
2589 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
2590 Git revision control repository.</para></listitem>
2591 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
2592 an OSC (OpenSuse Build service) revision control repository.</para></listitem>
2593 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
2594 a repo (Git) repository.</para></listitem>
2595 <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from
2596 an SVK revision control repository.</para></listitem>
2597 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
2598 the Internet using <filename>http</filename>.</para></listitem>
2599 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
2600 from the Internet using <filename>https</filename>.</para></listitem>
2601 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
2602 from the Internet using <filename>ftp</filename>.</para></listitem>
2603 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
2604 a CVS revision control repository.</para></listitem>
2605 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
2606 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
2607 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
2608 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
2609 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
2610 a secure shell.</para></listitem>
2611 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
2612 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
2613 </itemizedlist>
2614 </para>
2615 <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
2616 Here are standard options:
2617 <itemizedlist>
2618 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
2619 the patch or not.
2620 The default action is to apply the patch.</para></listitem>
2621 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
2622 striplevel to use when applying the patch.
2623 The default level is 1.</para></listitem>
2624 </itemizedlist>
2625 </para>
2626 <para>Here are options specific to recipes building code from a revision control system:
2627 <itemizedlist>
2628 <listitem><para><emphasis><filename>mindate</filename> -</emphasis> Only applies
2629 the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
2630 is equal to or greater than <filename>mindate</filename>.</para></listitem>
2631 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis> Only applies
2632 the patch if <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
2633 is not later than <filename>mindate</filename>.</para></listitem>
2634 <listitem><para><emphasis><filename>minrev</filename> -</emphasis> Only applies
2635 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2636 is equal to or greater than <filename>minrev</filename>.</para></listitem>
2637 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis> Only applies
2638 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2639 is not later than <filename>maxrev</filename>.</para></listitem>
2640 <listitem><para><emphasis><filename>rev</filename> -</emphasis> Only applies the
2641 patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2642 is equal to <filename>rev</filename>.</para></listitem>
2643 <listitem><para><emphasis><filename>notrev</filename> -</emphasis> Only applies
2644 the patch if <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
2645 is not equal to <filename>rev</filename>.</para></listitem>
2646 </itemizedlist>
2647 </para>
2648 <para>Here are some additional options worth mentioning:
2649 <itemizedlist>
2650 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
2651 whether or not to unpack the file if it is an archive.
2652 The default action is to upack the file.</para></listitem>
2653 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
2654 (or extracts its contents) into the specified
2655 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
2656 This option is useful for unusual tarballs or other archives that
2657 don't have their files already in a subdirectory within the archive.
2658 </para></listitem>
2659 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
2660 name to be used for association with <filename>SRC_URI</filename> checksums
2661 when you have more than one file specified in <filename>SRC_URI</filename>.
2662 </para></listitem>
2663 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
2664 the filename used when storing the downloaded file.</para></listitem>
2665 </itemizedlist>
2666 </para>
2667 </glossdef>
2668 </glossentry>
2669
2670 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
2671 <glossdef>
2672 <para></para>
2673 <para>
2674 By default, the OpenEmbedded build system automatically detects whether
2675 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
2676 contains files that are machine-specific.
2677 If so, the build system automatically changes
2678 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
2679 Setting this variable to "0" disables this behavior.
2680 </para>
2681 </glossdef>
2682 </glossentry>
2683
2684 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
2685 <glossdef>
2686 <para>
2687 The date of the source code used to build the package.
2688 This variable applies only if the source was fetched from a Source Code Manager (SCM).
2689 </para>
2690 </glossdef>
2691 </glossentry>
2692
2693 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
2694 <glossdef>
2695 <para>
2696 The revision of the source code used to build the package.
2697 This variable applies to Subversion, Git, Mercurial and Bazaar
2698 only.
2699 Note that if you wish to build a fixed revision and you wish
2700 to avoid performing a query on the remote repository every time
2701 BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
2702 full revision identifier and not just a tag.
2703 </para>
2704 </glossdef>
2705 </glossentry>
2706
2707 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
2708 <glossdef>
2709 <para>The directory for the shared state.</para>
2710 </glossdef>
2711 </glossentry>
2712
2713 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
2714 <glossdef>
2715 <para>
2716 Configures the OpenEmbedded build system to search other
2717 mirror locations for prebuilt cache data objects before
2718 building out the data.
2719 This variable works like fetcher
2720 <filename>MIRRORS</filename>/<filename>PREMIRRORS</filename>
2721 and points to the cache locations to check for the shared
2722 objects.
2723 </para>
2724
2725 <para>
2726 You can specify a filesystem directory or a remote URL such
2727 as HTTP or FTP.
2728 The locations you specify need to contain the shared state
2729 cache (sstate-cache) results from previous builds.
2730 The sstate-cache you point to can also be from builds on
2731 other machines.
2732 </para>
2733
2734 <para>
2735 If a mirror uses the same structure as
2736 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
2737 you need to add
2738 "PATH" at the end as shown in the examples below.
2739 The build system substitues the correct path within the
2740 directory structure.
2741 <literallayout class='monospaced'>
2742 SSTATE_MIRRORS ?= "\
2743 file://.* http://someserver.tld/share/sstate/PATH \n \
2744 file://.* file:///some/local/dir/sstate/PATH"
2745 </literallayout>
2746 </para>
2747 </glossdef>
2748 </glossentry>
2749
2750 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
2751 <glossdef>
2752 <para>
2753 The directory with kernel headers that are required to build out-of-tree
2754 modules.
2755 </para>
2756 </glossdef>
2757 </glossentry>
2758
2759 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
2760 <glossdef>
2761 <para>
2762 Specifies the base path used to create recipe stamp files.
2763 The path to an actual stamp file is constructed by evaluating this
2764 string and then appending additional information.
2765 Currently, the default assignment for <filename>STAMP</filename>
2766 as set in the <filename>meta/conf/bitbake.conf</filename> file
2767 is:
2768 <literallayout class='monospaced'>
2769 STAMP = "${TMPDIR}/stamps/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
2770 </literallayout>
2771 See <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
2772 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
2773 <link linkend='var-PN'><filename>PN</filename></link>,
2774 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
2775 <link linkend='var-PV'><filename>PV</filename></link>, and
2776 <link linkend='var-PR'><filename>PR</filename></link> for related variable
2777 information.
2778 </para>
2779 </glossdef>
2780 </glossentry>
2781
2782 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
2783 <glossdef>
2784 <para>The short (72 characters or less) summary of the binary package for packaging
2785 systems such as <filename>opkg</filename>, <filename>rpm</filename> or
2786 <filename>dpkg</filename>.
2787 By default, <filename>SUMMARY</filename> is used to define
2788 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
2789 variable if <filename>DESCRIPTION</filename> is not set
2790 in the recipe.
2791 </para>
2792 </glossdef>
2793 </glossentry>
2794
2795 </glossdiv>
2796
2797 <glossdiv id='var-glossary-t'><title>T</title>
2798
2799 <glossentry id='var-T'><glossterm>T</glossterm>
2800 <glossdef>
2801 <para>This variable points to a directory were Bitbake places temporary
2802 files when building a particular package.
2803 It is typically set as follows:
2804 <literallayout class='monospaced'>
2805 T = ${WORKDIR}/temp
2806 </literallayout>
2807 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
2808 is the directory into which Bitbake unpacks and builds the package.
2809 The default <filename>bitbake.conf</filename> file sets this variable.</para>
2810 <para>The <filename>T</filename> variable is not to be confused with
2811 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
2812 which points to the root of the directory tree where Bitbake
2813 places the output of an entire build.
2814 </para>
2815 </glossdef>
2816 </glossentry>
2817
2818 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
2819 <glossdef>
2820 <para>The architecture of the device being built.
2821 While a number of values are possible, the OpenEmbedded build system primarily supports
2822 <filename>arm</filename> and <filename>i586</filename>.</para>
2823 </glossdef>
2824 </glossentry>
2825
2826 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
2827 <glossdef>
2828 <para>
2829 Flags passed to the C compiler for the target system.
2830 This variable evaluates to the same as
2831 <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>.
2832 </para>
2833 </glossdef>
2834 </glossentry>
2835
2836
2837 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
2838 <glossdef>
2839 <para>Specifies the method for handling FPU code.
2840 For FPU-less targets, which include most ARM CPUs, the variable must be
2841 set to "soft".
2842 If not, the kernel emulation gets used, which results in a performance penalty.</para>
2843 </glossdef>
2844 </glossentry>
2845
2846 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
2847 <glossdef>
2848 <para>Specifies the target's operating system.
2849 The variable can be set to "linux" for <filename>eglibc</filename>-based systems and
2850 to "linux-uclibc" for <filename>uclibc</filename>.
2851 For ARM/EABI targets, there are also "linux-gnueabi" and
2852 "linux-uclibc-gnueabi" values possible.</para>
2853 </glossdef>
2854 </glossentry>
2855
2856 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
2857 <glossdef>
2858 <para>
2859 Specifies which variant of the GNU standard C library (<filename>libc</filename>)
2860 to use during the build process.
2861 This variable replaces <filename>POKYLIBC</filename>, which is no longer
2862 supported.
2863 </para>
2864 <para>
2865 You can select <filename>eglibc</filename> or <filename>uclibc</filename>.
2866 <note>
2867 This release of the Yocto Project does not support the
2868 <filename>glibc</filename> implementation of <filename>libc</filename>.
2869 </note>
2870 </para>
2871 </glossdef>
2872 </glossentry>
2873
2874 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
2875 <glossdef>
2876 <para>
2877 The toolchain selector.
2878 This variable replaces <filename>POKYMODE</filename>, which is no longer
2879 supported.
2880 </para>
2881 <para>
2882 The <filename>TCMODE</filename> variable selects the external toolchain
2883 built using the OpenEmbedded build system or a few supported combinations of
2884 the upstream GCC or CodeSourcery Labs toolchain.
2885 The variable identifies the <filename>tcmode-*</filename> files used in
2886 the <filename>meta/conf/distro/include</filename> directory, which is found in the
2887 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
2888 </para>
2889 <para>
2890 By default, <filename>TCMODE</filename> is set to "default", which
2891 chooses the <filename>tcmode-default.inc</filename> file.
2892 The variable is similar to
2893 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, which controls
2894 the variant of the GNU standard C library (<filename>libc</filename>)
2895 used during the build process: <filename>eglibc</filename> or <filename>uclibc</filename>.
2896 </para>
2897 </glossdef>
2898 </glossentry>
2899
2900 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
2901 <glossdef>
2902 <para>
2903 This variable is the temporary directory the OpenEmbedded build system
2904 uses when it does its work building images.
2905 By default, the <filename>TMPDIR</filename> variable is named
2906 <filename>tmp</filename> within the
2907 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2908 </para>
2909
2910 <para>
2911 If you want to establish this directory in a location other than the
2912 default, you can uncomment the following statement in the
2913 <filename>conf/local.conf</filename> file in the
2914 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
2915 <literallayout class='monospaced'>
2916 #TMPDIR = "${TOPDIR}/tmp"
2917 </literallayout>
2918 </para>
2919 </glossdef>
2920 </glossentry>
2921
2922 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
2923 <glossdef>
2924 <para>
2925 This variable is the
2926 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2927 BitBake automatically sets this variable.
2928 The OpenEmbedded build system uses the Build Directory when building images.
2929 </para>
2930 </glossdef>
2931 </glossentry>
2932
2933 </glossdiv>
2934
2935<!-- <glossdiv id='var-glossary-u'><title>U</title>-->
2936<!-- </glossdiv>-->
2937
2938<!-- <glossdiv id='var-glossary-v'><title>V</title>-->
2939<!-- </glossdiv>-->
2940
2941 <glossdiv id='var-glossary-w'><title>W</title>
2942
2943 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
2944 <glossdef>
2945 <para>
2946 The pathname of the working directory in which the OpenEmbedded build system
2947 builds a recipe.
2948 This directory is located within the
2949 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes
2950 as different packages are built.
2951 </para>
2952
2953 <para>
2954 The actual <filename>WORKDIR</filename> directory depends on several things:
2955 <itemizedlist>
2956 <listitem>The temporary directory - <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link></listitem>
2957 <listitem>The package architecture - <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link></listitem>
2958 <listitem>The target machine - <link linkend='var-MACHINE'><filename>MACHINE</filename></link></listitem>
2959 <listitem>The target operating system - <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link></listitem>
2960 <listitem>The recipe name - <link linkend='var-PN'><filename>PN</filename></link></listitem>
2961 <listitem>The recipe version - <link linkend='var-PV'><filename>PV</filename></link></listitem>
2962 <listitem>The recipe revision - <link linkend='var-PR'><filename>PR</filename></link></listitem>
2963 </itemizedlist>
2964 </para>
2965
2966 <para>
2967 For packages that are not dependent on a particular machine,
2968 <filename>WORKDIR</filename> is defined as follows:
2969 <literallayout class='monospaced'>
2970 ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
2971 </literallayout>
2972 As an example, assume a
2973 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level
2974 folder name <filename>poky</filename> and a default
2975 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
2976 at <filename>poky/build</filename>.
2977 In this case, the working directory the build system uses to build
2978 the <filename>v86d</filename> package is the following:
2979 <literallayout class='monospaced'>
2980 ~/poky/build/tmp/work/qemux86-poky-linux/v86d/01.9-r0
2981 </literallayout>
2982 </para>
2983
2984 <para>
2985 For packages that are dependent on a particular machine, <filename>WORKDIR</filename>
2986 is defined slightly different:
2987 <literallayout class='monospaced'>
2988 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
2989 </literallayout>
2990 As an example, again assume a Source Directory top-level folder
2991 named <filename>poky</filename> and a default Build Directory
2992 at <filename>poky/build</filename>.
2993 In this case, the working directory the build system uses to build
2994 the <filename>acl</filename> recipe, which is being built for a
2995 MIPS-based device, is the following:
2996 <literallayout class='monospaced'>
2997 ~/poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2
2998 </literallayout>
2999 </para>
3000 </glossdef>
3001 </glossentry>
3002
3003 </glossdiv>
3004
3005<!-- <glossdiv id='var-glossary-x'><title>X</title>-->
3006<!-- </glossdiv>-->
3007
3008<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
3009<!-- </glossdiv>-->
3010
3011<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
3012<!-- </glossdiv>-->
3013
3014</glossary>
3015</chapter>
3016<!--
3017vim: expandtab tw=80 ts=4
3018-->
diff --git a/documentation/poky-ref-manual/ref-varlocality.xml b/documentation/poky-ref-manual/ref-varlocality.xml
deleted file mode 100644
index ae8f75c2f5..0000000000
--- a/documentation/poky-ref-manual/ref-varlocality.xml
+++ /dev/null
@@ -1,193 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-varlocality'>
6 <title>Variable Context</title>
7
8 <para>
9 While most variables can be used in almost any context such as
10 <filename>.conf</filename>, <filename>.bbclass</filename>,
11 <filename>.inc</filename>, and <filename>.bb</filename> files,
12 some variables are often associated with a particular locality or context.
13 This chapter describes some common associations.
14 </para>
15
16 <section id='ref-varlocality-configuration'>
17 <title>Configuration</title>
18
19 <para>
20 The following subsections provide lists of variables whose context is
21 configuration: distribution, machine, and local.
22 </para>
23
24 <section id='ref-varlocality-config-distro'>
25 <title>Distribution (Distro)</title>
26
27 <para>
28 This section lists variables whose context is the distribution, or distro.
29 <itemizedlist>
30 <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename></para></listitem>
31 <listitem><para><filename><link linkend='var-DISTRO_NAME'>DISTRO_NAME</link></filename>
32 </para></listitem>
33 <listitem><para><filename><link linkend='var-DISTRO_VERSION'>DISTRO_VERSION</link>
34 </filename></para></listitem>
35 <listitem><para><filename><link linkend='var-MAINTAINER'>MAINTAINER</link></filename>
36 </para></listitem>
37 <listitem><para><filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link>
38 </filename></para></listitem>
39 <listitem><para><filename><link linkend='var-TARGET_OS'>TARGET_OS</link></filename>
40 </para></listitem>
41 <listitem><para><filename><link linkend='var-TARGET_FPU'>TARGET_FPU</link></filename>
42 </para></listitem>
43 <listitem><para><filename><link linkend='var-TCMODE'>TCMODE</link></filename>
44 </para></listitem>
45 <listitem><para><filename><link linkend='var-TCLIBC'>TCLIBC</link></filename>
46 </para></listitem>
47 </itemizedlist>
48 </para>
49 </section>
50
51 <section id='ref-varlocality-config-machine'>
52 <title>Machine</title>
53
54 <para>
55 This section lists variables whose context is the machine.
56 <itemizedlist>
57 <listitem><para><filename><link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></filename>
58 </para></listitem>
59 <listitem><para><filename><link linkend='var-SERIAL_CONSOLE'>SERIAL_CONSOLE</link>
60 </filename></para></listitem>
61 <listitem><para><filename><link linkend='var-PACKAGE_EXTRA_ARCHS'>PACKAGE_EXTRA_ARCHS</link>
62 </filename></para></listitem>
63 <listitem><para><filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link>
64 </filename></para></listitem>
65 <listitem><para><filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link>
66 </filename></para></listitem>
67 <listitem><para><filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS
68 </link></filename></para></listitem>
69 <listitem><para><filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS
70 </link></filename></para></listitem>
71 <listitem><para><filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS
72 </link></filename></para></listitem>
73 <listitem><para><filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>
74 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename></para></listitem>
75 </itemizedlist>
76 </para>
77 </section>
78
79 <section id='ref-varlocality-config-local'>
80 <title>Local</title>
81
82 <para>
83 This section lists variables whose context is the local configuration through the
84 <filename>local.conf</filename> file.
85 <itemizedlist>
86 <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename>
87 </para></listitem>
88 <listitem><para><filename><link linkend='var-MACHINE'>MACHINE</link></filename>
89 </para></listitem>
90 <listitem><para><filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>
91 </para></listitem>
92 <listitem><para><filename><link linkend='var-BBFILES'>BBFILES</link></filename>
93 </para></listitem>
94 <listitem><para><filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES
95 </link></filename></para></listitem>
96 <listitem><para><filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link>
97 </filename></para></listitem>
98 <listitem><para><filename><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link>
99 </filename></para></listitem>
100 <listitem><para><filename><link linkend='var-BBINCLUDELOGS'>BBINCLUDELOGS</link>
101 </filename></para></listitem>
102 <listitem><para><filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>
103 ENABLE_BINARY_LOCALE_GENERATION</link></filename></para></listitem>
104 </itemizedlist>
105 </para>
106 </section>
107 </section>
108
109 <section id='ref-varlocality-recipes'>
110 <title>Recipes</title>
111
112 <para>
113 The following subsections provide lists of variables whose context is
114 recipes: required, dependencies, path, and extra build information.
115 </para>
116
117 <section id='ref-varlocality-recipe-required'>
118 <title>Required</title>
119
120 <para>
121 This section lists variables that are required for recipes.
122 <itemizedlist>
123 <listitem><para><filename><link linkend='var-LICENSE'>LICENSE</link>
124 </filename></para></listitem>
125 <listitem><para><filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link>
126 </filename></para></listitem>
127 <listitem><para><filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> - used
128 in recipes that fetch local or remote files.
129 </para></listitem>
130 </itemizedlist>
131 </para>
132 </section>
133
134 <section id='ref-varlocality-recipe-dependencies'>
135 <title>Dependencies</title>
136
137 <para>
138 This section lists variables that define recipe dependencies.
139 <itemizedlist>
140 <listitem><para><filename><link linkend='var-DEPENDS'>DEPENDS</link>
141 </filename></para></listitem>
142 <listitem><para><filename><link linkend='var-RDEPENDS'>RDEPENDS</link>
143 </filename></para></listitem>
144 <listitem><para><filename><link linkend='var-RRECOMMENDS'>RRECOMMENDS</link>
145 </filename></para></listitem>
146 <listitem><para><filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link>
147 </filename></para></listitem>
148 <listitem><para><filename><link linkend='var-RREPLACES'>RREPLACES</link>
149 </filename></para></listitem>
150 </itemizedlist>
151 </para>
152 </section>
153
154 <section id='ref-varlocality-recipe-paths'>
155 <title>Paths</title>
156
157 <para>
158 This section lists variables that define recipe paths.
159 <itemizedlist>
160 <listitem><para><filename><link linkend='var-WORKDIR'>WORKDIR</link>
161 </filename></para></listitem>
162 <listitem><para><filename><link linkend='var-S'>S</link>
163 </filename></para></listitem>
164 <listitem><para><filename><link linkend='var-FILES'>FILES</link>
165 </filename></para></listitem>
166 </itemizedlist>
167 </para>
168 </section>
169
170 <section id='ref-varlocality-recipe-build'>
171 <title>Extra Build Information</title>
172
173 <para>
174 This section lists variables that define extra build information for recipes.
175 <itemizedlist>
176 <listitem><para><filename><link linkend='var-EXTRA_OECMAKE'>EXTRA_OECMAKE</link>
177 </filename></para></listitem>
178 <listitem><para><filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link>
179 </filename></para></listitem>
180 <listitem><para><filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link>
181 </filename></para></listitem>
182 <listitem><para><filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
183 </para></listitem>
184 <listitem><para><filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE
185 </link></filename></para></listitem>
186 </itemizedlist>
187 </para>
188 </section>
189 </section>
190</chapter>
191<!--
192vim: expandtab tw=80 ts=4 spell spelllang=en_gb
193-->
diff --git a/documentation/poky-ref-manual/resources.xml b/documentation/poky-ref-manual/resources.xml
deleted file mode 100644
index a6916064f6..0000000000
--- a/documentation/poky-ref-manual/resources.xml
+++ /dev/null
@@ -1,114 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='resources'>
6<title>Contributing to the Yocto Project</title>
7
8<section id='resources-intro'>
9 <title>Introduction</title>
10 <para>
11 The Yocto Project team is happy for people to experiment with the Yocto Project.
12 A number of places exist to find help if you run into difficulties or find bugs.
13 To find out how to download source code,
14 see the "<ulink url='&YOCTO_DOCS_DEV_URL;#local-yp-release'>Yocto Project Release</ulink>"
15 list item in the Yocto Project Development Manual.
16 </para>
17</section>
18
19<section id='resources-bugtracker'>
20 <title>Tracking Bugs</title>
21
22 <para>
23 If you find problems with the Yocto Project, you should report them using the
24 Bugzilla application at <ulink url='&YOCTO_BUGZILLA_URL;'></ulink>.
25 </para>
26</section>
27
28<section id='resources-mailinglist'>
29 <title>Mailing lists</title>
30
31 <para>
32 There are a number of mailing lists maintained by the Yocto Project as well as
33 related OpenEmbedded mailing lists for discussion, patch submission and announcements.
34 To subscribe to one of the following mailing lists, click on the appropriate URL
35 in the following list and follow the instructions:
36 <itemizedlist>
37 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> -
38 General Yocto Project discussion mailing list. </para></listitem>
39 <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'></ulink> -
40 Discussion mailing list about OpenEmbedded-Core (the core metadata).</para></listitem>
41 <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'></ulink> -
42 Discussion mailing list about OpenEmbedded.</para></listitem>
43 <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'></ulink> -
44 Discussion mailing list about the BitBake build tool.</para></listitem>
45 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> -
46 Discussion mailing list about Poky.</para></listitem>
47 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink> -
48 Mailing list to receive official Yocto Project release and milestone
49 announcements.</para></listitem>
50 </itemizedlist>
51 </para>
52</section>
53
54<section id='resources-irc'>
55 <title>Internet Relay Chat (IRC)</title>
56
57 <para>
58 Two IRC channels on freenode are available for the Yocto Project and Poky discussions:
59 <itemizedlist>
60 <listitem><para><filename>#yocto</filename></para></listitem>
61 <listitem><para><filename>#poky</filename></para></listitem>
62 </itemizedlist>
63 </para>
64</section>
65
66<section id='resources-links'>
67 <title>Links</title>
68
69 <para>
70 Following is a list of resources you will find helpful:
71 <itemizedlist>
72 <listitem><para><emphasis><ulink url='&YOCTO_HOME_URL;'>The Yocto Project website</ulink>:
73 </emphasis> The home site for the Yocto Project.</para></listitem>
74<!-- <listitem><para><emphasis><ulink url='&OH_HOME_URL;'>OpenedHand</ulink>:</emphasis>
75 The company where the Yocto Project build system Poky was first developed.
76 OpenedHand has since been acquired by Intel Corporation.</para></listitem> -->
77 <listitem><para><emphasis><ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis>
78 The company who acquired OpenedHand in 2008 and began development on the
79 Yocto Project.</para></listitem>
80 <listitem><para><emphasis><ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis>
81 The upstream, generic, embedded distribution used as the basis for the build system in the
82 Yocto Project.
83 Poky derives from and contributes back to the OpenEmbedded project.</para></listitem>
84 <listitem><para><emphasis><ulink url='http://developer.berlios.de/projects/bitbake/'>
85 BitBake</ulink>:</emphasis> The tool used to process metadata.</para></listitem>
86 <listitem><para><emphasis>BitBake User Manual:</emphasis>
87 A comprehensive guide to the BitBake tool.
88 You can find the BitBake User Manual in the <filename>bitbake/doc/manual</filename>
89 directory, which is found in the
90 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
91 </para></listitem>
92 <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Index.html'>QEMU</ulink>:
93 </emphasis> An open source machine emulator and virtualizer.</para></listitem>
94 </itemizedlist>
95 </para>
96</section>
97
98<section id='resources-contributions'>
99 <title>Contributions</title>
100
101 <para>
102 The Yocto Project gladly accepts contributions.
103 You can submit changes to the project either by creating and sending pull requests,
104 or by submitting patches through email.
105 For information on how to do both, see the
106 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>"
107 section in the Yocto Project Development Manual.
108 </para>
109</section>
110
111</chapter>
112<!--
113vim: expandtab tw=80 ts=4
114-->
diff --git a/documentation/poky-ref-manual/technical-details.xml b/documentation/poky-ref-manual/technical-details.xml
deleted file mode 100644
index b1d7c40799..0000000000
--- a/documentation/poky-ref-manual/technical-details.xml
+++ /dev/null
@@ -1,1011 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='technical-details'>
6<title>Technical Details</title>
7
8 <para>
9 This chapter provides technical details for various parts of the Yocto Project.
10 Currently, topics include Yocto Project components and shared state (sstate) cache.
11 </para>
12
13<section id='usingpoky-components'>
14 <title>Yocto Project Components</title>
15
16 <para>
17 The BitBake task executor together with various types of configuration files form the
18 OpenEmbedded Core.
19 This section overviews the BitBake task executor and the
20 configuration files by describing what they are used for and how they interact.
21 </para>
22
23 <para>
24 BitBake handles the parsing and execution of the data files.
25 The data itself is of various types:
26 <itemizedlist>
27 <listitem><para><emphasis>Recipes:</emphasis> Provides details about particular
28 pieces of software</para></listitem>
29 <listitem><para><emphasis>Class Data:</emphasis> An abstraction of common build
30 information (e.g. how to build a Linux kernel).</para></listitem>
31 <listitem><para><emphasis>Configuration Data:</emphasis> Defines machine-specific settings,
32 policy decisions, etc.
33 Configuration data acts as the glue to bind everything together.</para></listitem>
34 </itemizedlist>
35 For more information on data, see the
36 "<ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-terms'>Yocto Project Terms</ulink>"
37 section in the Yocto Project Development Manual.
38 </para>
39
40 <para>
41 BitBake knows how to combine multiple data sources together and refers to each data source
42 as a layer.
43 For information on layers, see the
44 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and
45 Creating Layers</ulink>" section of the Yocto Project Development Manual.
46 </para>
47
48 <para>
49 Following are some brief details on these core components.
50 For more detailed information on these components see the
51 "<link linkend='ref-structure'>Directory Structure</link>" chapter.
52 </para>
53
54 <section id='usingpoky-components-bitbake'>
55 <title>BitBake</title>
56
57 <para>
58 BitBake is the tool at the heart of the OpenEmbedded build system and is responsible
59 for parsing the metadata, generating a list of tasks from it,
60 and then executing those tasks.
61 To see a list of the options BitBake supports, use the following help command:
62 <literallayout class='monospaced'>
63 $ bitbake --help
64 </literallayout>
65 </para>
66
67 <para>
68 The most common usage for BitBake is <filename>bitbake &lt;packagename&gt;</filename>, where
69 <filename>packagename</filename> is the name of the package you want to build
70 (referred to as the "target" in this manual).
71 The target often equates to the first part of a <filename>.bb</filename> filename.
72 So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you
73 might type the following:
74 <literallayout class='monospaced'>
75 $ bitbake matchbox-desktop
76 </literallayout>
77 Several different versions of <filename>matchbox-desktop</filename> might exist.
78 BitBake chooses the one selected by the distribution configuration.
79 You can get more details about how BitBake chooses between different
80 target versions and providers in the
81 "<link linkend='ref-bitbake-providers'>Preferences and Providers</link>" section.
82 </para>
83
84 <para>
85 BitBake also tries to execute any dependent tasks first.
86 So for example, before building <filename>matchbox-desktop</filename>, BitBake
87 would build a cross compiler and <filename>eglibc</filename> if they had not already
88 been built.
89 <note>This release of the Yocto Project does not support the <filename>glibc</filename>
90 GNU version of the Unix standard C library. By default, the OpenEmbedded build system
91 builds with <filename>eglibc</filename>.</note>
92 </para>
93
94 <para>
95 A useful BitBake option to consider is the <filename>-k</filename> or
96 <filename>--continue</filename> option.
97 This option instructs BitBake to try and continue processing the job as much
98 as possible even after encountering an error.
99 When an error occurs, the target that
100 failed and those that depend on it cannot be remade.
101 However, when you use this option other dependencies can still be processed.
102 </para>
103 </section>
104
105 <section id='usingpoky-components-metadata'>
106 <title>Metadata (Recipes)</title>
107
108 <para>
109 The <filename>.bb</filename> files are usually referred to as "recipes."
110 In general, a recipe contains information about a single piece of software.
111 The information includes the location from which to download the source patches
112 (if any are needed), which special configuration options to apply,
113 how to compile the source files, and how to package the compiled output.
114 </para>
115
116 <para>
117 The term "package" can also be used to describe recipes.
118 However, since the same word is used for the packaged output from the OpenEmbedded
119 build system (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files),
120 this document avoids using the term "package" when referring to recipes.
121 </para>
122 </section>
123
124 <section id='usingpoky-components-classes'>
125 <title>Classes</title>
126
127 <para>
128 Class files (<filename>.bbclass</filename>) contain information that is useful to share
129 between metadata files.
130 An example is the Autotools class, which contains
131 common settings for any application that Autotools uses.
132 The "<link linkend='ref-classes'>Classes</link>" chapter provides details
133 about common classes and how to use them.
134 </para>
135 </section>
136
137 <section id='usingpoky-components-configuration'>
138 <title>Configuration</title>
139
140 <para>
141 The configuration files (<filename>.conf</filename>) define various configuration variables
142 that govern the OpenEmbedded build process.
143 These files fall into several areas that define machine configuration options,
144 distribution configuration options, compiler tuning options, general common configuration
145 options and user configuration options (<filename>local.conf</filename>, which is found
146 in the <ulink url='build-directory'>Build Directory</ulink>).
147 </para>
148 </section>
149</section>
150
151<section id="shared-state-cache">
152 <title>Shared State Cache</title>
153
154 <para>
155 By design, the OpenEmbedded build system builds everything from scratch unless
156 BitBake can determine that parts don't need to be rebuilt.
157 Fundamentally, building from scratch is attractive as it means all parts are
158 built fresh and there is no possibility of stale data causing problems.
159 When developers hit problems, they typically default back to building from scratch
160 so they know the state of things from the start.
161 </para>
162
163 <para>
164 Building an image from scratch is both an advantage and a disadvantage to the process.
165 As mentioned in the previous paragraph, building from scratch ensures that
166 everything is current and starts from a known state.
167 However, building from scratch also takes much longer as it generally means
168 rebuilding things that don't necessarily need rebuilt.
169 </para>
170
171 <para>
172 The Yocto Project implements shared state code that supports incremental builds.
173 The implementation of the shared state code answers the following questions that
174 were fundamental roadblocks within the OpenEmbedded incremental build support system:
175 <itemizedlist>
176 <listitem>What pieces of the system have changed and what pieces have not changed?</listitem>
177 <listitem>How are changed pieces of software removed and replaced?</listitem>
178 <listitem>How are pre-built components that don't need to be rebuilt from scratch
179 used when they are available?</listitem>
180 </itemizedlist>
181 </para>
182
183 <para>
184 For the first question, the build system detects changes in the "inputs" to a given task by
185 creating a checksum (or signature) of the task's inputs.
186 If the checksum changes, the system assumes the inputs have changed and the task needs to be
187 rerun.
188 For the second question, the shared state (sstate) code tracks which tasks add which output
189 to the build process.
190 This means the output from a given task can be removed, upgraded or otherwise manipulated.
191 The third question is partly addressed by the solution for the second question
192 assuming the build system can fetch the sstate objects from remote locations and
193 install them if they are deemed to be valid.
194 </para>
195
196 <para>
197 The rest of this section goes into detail about the overall incremental build
198 architecture, the checksums (signatures), shared state, and some tips and tricks.
199 </para>
200
201 <section id='overall-architecture'>
202 <title>Overall Architecture</title>
203
204 <para>
205 When determining what parts of the system need to be built, BitBake
206 uses a per-task basis and does not use a per-recipe basis.
207 You might wonder why using a per-task basis is preferred over a per-recipe basis.
208 To help explain, consider having the IPK packaging backend enabled and then switching to DEB.
209 In this case, <filename>do_install</filename> and <filename>do_package</filename>
210 output are still valid.
211 However, with a per-recipe approach, the build would not include the
212 <filename>.deb</filename> files.
213 Consequently, you would have to invalidate the whole build and rerun it.
214 Rerunning everything is not the best situation.
215 Also in this case, the core must be "taught" much about specific tasks.
216 This methodology does not scale well and does not allow users to easily add new tasks
217 in layers or as external recipes without touching the packaged-staging core.
218 </para>
219 </section>
220
221 <section id='checksums'>
222 <title>Checksums (Signatures)</title>
223
224 <para>
225 The shared state code uses a checksum, which is a unique signature of a task's
226 inputs, to determine if a task needs to be run again.
227 Because it is a change in a task's inputs that triggers a rerun, the process
228 needs to detect all the inputs to a given task.
229 For shell tasks, this turns out to be fairly easy because
230 the build process generates a "run" shell script for each task and
231 it is possible to create a checksum that gives you a good idea of when
232 the task's data changes.
233 </para>
234
235 <para>
236 To complicate the problem, there are things that should not be included in
237 the checksum.
238 First, there is the actual specific build path of a given task -
239 the <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
240 It does not matter if the working directory changes because it should not
241 affect the output for target packages.
242 Also, the build process has the objective of making native/cross packages relocatable.
243 The checksum therefore needs to exclude <filename>WORKDIR</filename>.
244 The simplistic approach for excluding the working directory is to set
245 <filename>WORKDIR</filename> to some fixed value and create the checksum
246 for the "run" script.
247 </para>
248
249 <para>
250 Another problem results from the "run" scripts containing functions that
251 might or might not get called.
252 The incremental build solution contains code that figures out dependencies
253 between shell functions.
254 This code is used to prune the "run" scripts down to the minimum set,
255 thereby alleviating this problem and making the "run" scripts much more
256 readable as a bonus.
257 </para>
258
259 <para>
260 So far we have solutions for shell scripts.
261 What about python tasks?
262 The same approach applies even though these tasks are more difficult.
263 The process needs to figure out what variables a python function accesses
264 and what functions it calls.
265 Again, the incremental build solution contains code that first figures out
266 the variable and function dependencies, and then creates a checksum for the data
267 used as the input to the task.
268 </para>
269
270 <para>
271 Like the <filename>WORKDIR</filename> case, situations exist where dependencies
272 should be ignored.
273 For these cases, you can instruct the build process to ignore a dependency
274 by using a line like the following:
275 <literallayout class='monospaced'>
276 PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
277 </literallayout>
278 This example ensures that the <filename>PACKAGE_ARCHS</filename> variable does not
279 depend on the value of <filename>MACHINE</filename>, even if it does reference it.
280 </para>
281
282 <para>
283 Equally, there are cases where we need to add dependencies BitBake is not able to find.
284 You can accomplish this by using a line like the following:
285 <literallayout class='monospaced'>
286 PACKAGE_ARCHS[vardeps] = "MACHINE"
287 </literallayout>
288 This example explicitly adds the <filename>MACHINE</filename> variable as a
289 dependency for <filename>PACKAGE_ARCHS</filename>.
290 </para>
291
292 <para>
293 Consider a case with inline python, for example, where BitBake is not
294 able to figure out dependencies.
295 When running in debug mode (i.e. using <filename>-DDD</filename>), BitBake
296 produces output when it discovers something for which it cannot figure out
297 dependencies.
298 The Yocto Project team has currently not managed to cover those dependencies
299 in detail and is aware of the need to fix this situation.
300 </para>
301
302 <para>
303 Thus far, this section has limited discussion to the direct inputs into a task.
304 Information based on direct inputs is referred to as the "basehash" in the
305 code.
306 However, there is still the question of a task's indirect inputs - the
307 things that were already built and present in the Build Directory.
308 The checksum (or signature) for a particular task needs to add the hashes
309 of all the tasks on which the particular task depends.
310 Choosing which dependencies to add is a policy decision.
311 However, the effect is to generate a master checksum that combines the basehash
312 and the hashes of the task's dependencies.
313 </para>
314
315 <para>
316 At the code level, there are a variety of ways both the basehash and the
317 dependent task hashes can be influenced.
318 Within the BitBake configuration file, we can give BitBake some extra information
319 to help it construct the basehash.
320 The following statements effectively result in a list of global variable
321 dependency excludes - variables never included in any checksum:
322 <literallayout class='monospaced'>
323 BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH"
324 BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS"
325 BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER"
326 BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET"
327 </literallayout>
328 The previous example actually excludes
329 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
330 since it is actually constructed as a path within
331 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on
332 the whitelist.
333 </para>
334
335 <para>
336 The rules for deciding which hashes of dependent tasks to include through
337 dependency chains are more complex and are generally accomplished with a
338 python function.
339 The code in <filename>meta/lib/oe/sstatesig.py</filename> shows two examples
340 of this and also illustrates how you can insert your own policy into the system
341 if so desired.
342 This file defines the two basic signature generators <filename>OE-Core</filename>
343 uses: "OEBasic" and "OEBasicHash".
344 By default, there is a dummy "noop" signature handler enabled in BitBake.
345 This means that behavior is unchanged from previous versions.
346 <filename>OE-Core</filename> uses the "OEBasic" signature handler by default
347 through this setting in the <filename>bitbake.conf</filename> file:
348 <literallayout class='monospaced'>
349 BB_SIGNATURE_HANDLER ?= "OEBasic"
350 </literallayout>
351 The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the
352 "OEBasic" version but adds the task hash to the stamp files.
353 This results in any metadata change that changes the task hash, automatically
354 causing the task to be run again.
355 This removes the need to bump <link linkend='var-PR'><filename>PR</filename></link>
356 values and changes to metadata automatically ripple across the build.
357 Currently, this behavior is not the default behavior for <filename>OE-Core</filename>
358 but is the default in <filename>poky</filename>.
359 </para>
360
361 <para>
362 It is also worth noting that the end result of these signature generators is to
363 make some dependency and hash information available to the build.
364 This information includes:
365 <literallayout class='monospaced'>
366 BB_BASEHASH_task-&lt;taskname&gt; - the base hashes for each task in the recipe
367 BB_BASEHASH_&lt;filename:taskname&gt; - the base hashes for each dependent task
368 BBHASHDEPS_&lt;filename:taskname&gt; - The task dependencies for each task
369 BB_TASKHASH - the hash of the currently running task
370 </literallayout>
371 </para>
372 </section>
373
374 <section id='shared-state'>
375 <title>Shared State</title>
376
377 <para>
378 Checksums and dependencies, as discussed in the previous section, solve half the
379 problem.
380 The other part of the problem is being able to use checksum information during the build
381 and being able to reuse or rebuild specific components.
382 </para>
383
384 <para>
385 The shared state class (<filename>sstate.bbclass</filename>)
386 is a relatively generic implementation of how to "capture" a snapshot of a given task.
387 The idea is that the build process does not care about the source of a task's output.
388 Output could be freshly built or it could be downloaded and unpacked from
389 somewhere - the build process doesn't need to worry about its source.
390 </para>
391
392 <para>
393 There are two types of output, one is just about creating a directory
394 in <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
395 A good example is the output of either <filename>do_install</filename> or
396 <filename>do_package</filename>.
397 The other type of output occurs when a set of data is merged into a shared directory
398 tree such as the sysroot.
399 </para>
400
401 <para>
402 The Yocto Project team has tried to keep the details of the implementation hidden in
403 <filename>sstate.bbclass</filename>.
404 From a user's perspective, adding shared state wrapping to a task
405 is as simple as this <filename>do_deploy</filename> example taken from
406 <filename>do_deploy.bbclass</filename>:
407 <literallayout class='monospaced'>
408 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
409 SSTATETASKS += "do_deploy"
410 do_deploy[sstate-name] = "deploy"
411 do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
412 do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
413
414 python do_deploy_setscene () {
415 sstate_setscene(d)
416 }
417 addtask do_deploy_setscene
418 </literallayout>
419 In the example, we add some extra flags to the task, a name field ("deploy"), an
420 input directory where the task sends data, and the output
421 directory where the data from the task should eventually be copied.
422 We also add a <filename>_setscene</filename> variant of the task and add the task
423 name to the <filename>SSTATETASKS</filename> list.
424 </para>
425
426 <para>
427 If you have a directory whose contents you need to preserve, you can do this with
428 a line like the following:
429 <literallayout class='monospaced'>
430 do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
431 </literallayout>
432 This method, as well as the following example, also works for multiple directories.
433 <literallayout class='monospaced'>
434 do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
435 do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
436 do_package[sstate-lockfile] = "${PACKAGELOCK}"
437 </literallayout>
438 These methods also include the ability to take a lockfile when manipulating
439 shared state directory structures since some cases are sensitive to file
440 additions or removals.
441 </para>
442
443 <para>
444 Behind the scenes, the shared state code works by looking in
445 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> and
446 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
447 for shared state files.
448 Here is an example:
449 <literallayout class='monospaced'>
450 SSTATE_MIRRORS ?= "\
451 file://.* http://someserver.tld/share/sstate/PATH \n \
452 file://.* file:///some/local/dir/sstate/PATH"
453 </literallayout>
454 <note>
455 The shared state directory (<filename>SSTATE_DIR</filename>) is
456 organized into two-character subdirectories, where the subdirectory
457 names are based on the first two characters of the hash.
458 If the shared state directory structure for a mirror has the
459 same structure as <filename>SSTATE_DIR</filename>, you must
460 specify "PATH" as part of the URI to enable the build system
461 to map to the appropriate subdirectory.
462 </note>
463 </para>
464
465 <para>
466 The shared state package validity can be detected just by looking at the
467 filename since the filename contains the task checksum (or signature) as
468 described earlier in this section.
469 If a valid shared state package is found, the build process downloads it
470 and uses it to accelerate the task.
471 </para>
472
473 <para>
474 The build processes uses the <filename>*_setscene</filename> tasks
475 for the task acceleration phase.
476 BitBake goes through this phase before the main execution code and tries
477 to accelerate any tasks for which it can find shared state packages.
478 If a shared state package for a task is available, the shared state
479 package is used.
480 This means the task and any tasks on which it is dependent are not
481 executed.
482 </para>
483
484 <para>
485 As a real world example, the aim is when building an IPK-based image,
486 only the <filename>do_package_write_ipk</filename> tasks would have their
487 shared state packages fetched and extracted.
488 Since the sysroot is not used, it would never get extracted.
489 This is another reason why a task-based approach is preferred over a
490 recipe-based approach, which would have to install the output from every task.
491 </para>
492 </section>
493
494 <section id='tips-and-tricks'>
495 <title>Tips and Tricks</title>
496
497 <para>
498 The code in the build system that supports incremental builds is not
499 simple code.
500 This section presents some tips and tricks that help you work around
501 issues related to shared state code.
502 </para>
503
504 <section id='debugging'>
505 <title>Debugging</title>
506
507 <para>
508 When things go wrong, debugging needs to be straightforward.
509 Because of this, the Yocto Project team included strong debugging
510 tools:
511 <itemizedlist>
512 <listitem><para>Whenever a shared state package is written out, so is a
513 corresponding <filename>.siginfo</filename> file.
514 This practice results in a pickled python database of all
515 the metadata that went into creating the hash for a given shared state
516 package.</para></listitem>
517 <listitem><para>If BitBake is run with the <filename>--dump-signatures</filename>
518 (or <filename>-S</filename>) option, BitBake dumps out
519 <filename>.siginfo</filename> files in
520 the stamp directory for every task it would have executed instead of
521 building the specified target package.</para></listitem>
522 <listitem><para>There is a <filename>bitbake-diffsigs</filename> command that
523 can process these <filename>.siginfo</filename> files.
524 If one file is specified, it will dump out the dependency
525 information in the file.
526 If two files are specified, it will compare the two files and dump out
527 the differences between the two.
528 This allows the question of "What changed between X and Y?" to be
529 answered easily.</para></listitem>
530 </itemizedlist>
531 </para>
532 </section>
533
534 <section id='invalidating-shared-state'>
535 <title>Invalidating Shared State</title>
536
537 <para>
538 The shared state code uses checksums and shared state
539 cache to avoid unnecessarily rebuilding tasks.
540 As with all schemes, this one has some drawbacks.
541 It is possible that you could make implicit changes that are not factored
542 into the checksum calculation, but do affect a task's output.
543 A good example is perhaps when a tool changes its output.
544 Let's say that the output of <filename>rpmdeps</filename> needed to change.
545 The result of the change should be that all the "package", "package_write_rpm",
546 and "package_deploy-rpm" shared state cache items would become invalid.
547 But, because this is a change that is external to the code and therefore implicit,
548 the associated shared state cache items do not become invalidated.
549 In this case, the build process would use the cached items rather than running the
550 task again.
551 Obviously, these types of implicit changes can cause problems.
552 </para>
553
554 <para>
555 To avoid these problems during the build, you need to understand the effects of any
556 change you make.
557 Note that any changes you make directly to a function automatically are factored into
558 the checksum calculation and thus, will invalidate the associated area of sstate cache.
559 You need to be aware of any implicit changes that are not obvious changes to the
560 code and could affect the output of a given task.
561 Once you are aware of such a change, you can take steps to invalidate the cache
562 and force the task to run.
563 The step to take is as simple as changing a function's comments in the source code.
564 For example, to invalidate package shared state files, change the comment statements
565 of <filename>do_package</filename> or the comments of one of the functions it calls.
566 The change is purely cosmetic, but it causes the checksum to be recalculated and
567 forces the task to be run again.
568 </para>
569
570 <note>
571 For an example of a commit that makes a cosmetic change to invalidate
572 a shared state, see this
573 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
574 </note>
575 </section>
576 </section>
577</section>
578
579<section id='x32'>
580 <title>x32</title>
581
582 <para>
583 x32 is a new processor-specific Application Binary Interface (psABI) for x86_64.
584 An ABI defines the calling conventions between functions in a processing environment.
585 The interface determines what registers are used and what the sizes are for various C data types.
586 </para>
587
588 <para>
589 Some processing environments prefer using 32-bit applications even when running
590 on Intel 64-bit platforms.
591 Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms.
592 The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources,
593 leaving the system underutilized.
594 Now consider the x86_64 psABI.
595 This ABI is newer and uses 64-bits for data sizes and program pointers.
596 The extra bits increase the footprint size of the programs, libraries,
597 and also increases the memory and file system size requirements.
598 Executing under the x32 psABI enables user programs to utilize CPU and system resources
599 more efficiently while keeping the memory footprint of the applications low.
600 Extra bits are used for registers but not for addressing mechanisms.
601 </para>
602
603 <section id='support'>
604 <title>Support</title>
605
606 <para>
607 While the x32 psABI specifications are not fully finalized, this Yocto Project
608 release supports current development specifications of x32 psABI.
609 As of this release of the Yocto Project, x32 psABI support exists as follows:
610 <itemizedlist>
611 <listitem><para>You can create packages and images in x32 psABI format on x86_64 architecture targets.
612 </para></listitem>
613 <listitem><para>You can use the x32 psABI support through the <filename>meta-x32</filename>
614 layer on top of the OE-core/Yocto layer.</para></listitem>
615 <listitem><para>The toolchain from the <filename>experimental/meta-x32</filename> layer
616 is used for building x32 psABI program binaries.</para></listitem>
617 <listitem><para>You can successfully build many recipes with the x32 toolchain.</para></listitem>
618 <listitem><para>You can create and boot <filename>core-image-minimal</filename> and
619 <filename>core-image-sato</filename> images.</para></listitem>
620 </itemizedlist>
621 </para>
622 </section>
623
624 <section id='future-development-and-limitations'>
625 <title>Future Development and Limitations</title>
626
627 <para>
628 As of this Yocto Project release, the x32 psABI kernel and library interfaces
629 specifications are not finalized.
630 </para>
631
632 <para>
633 Future Plans for the x32 psABI in the Yocto Project include the following:
634 <itemizedlist>
635 <listitem><para>Enhance and fix the few remaining recipes so they
636 work with and support x32 toolchains.</para></listitem>
637 <listitem><para>Enhance RPM Package Manager (RPM) support for x32 binaries.</para></listitem>
638 <listitem><para>Support larger images.</para></listitem>
639 <listitem><para>Integrate x32 recipes, toolchain, and kernel changes from
640 <filename>experimental/meta-x32</filename> into OE-core.</para></listitem>
641 </itemizedlist>
642 </para>
643 </section>
644
645 <section id='using-x32-right-now'>
646 <title>Using x32 Right Now</title>
647
648 <para>
649 Despite the fact the x32 psABI support is in development state for this release of the
650 Yocto Project, you can follow these steps to use the x32 spABI:
651 <itemizedlist>
652 <listitem><para>Add the <filename>experimental/meta-x32</filename> layer to your local
653 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
654 You can find the <filename>experimental/meta-x32</filename> source repository at
655 <ulink url='&YOCTO_GIT_URL;'></ulink>.</para></listitem>
656 <listitem><para>Edit your <filename>conf/bblayers.conf</filename> file so that it includes
657 the <filename>meta-x32</filename>.
658 Here is an example:
659 <literallayout class='monospaced'>
660 BBLAYERS ?= " \
661 /home/nitin/prj/poky.git/meta \
662 /home/nitin/prj/poky.git/meta-yocto \
663 /home/nitin/prj/poky.git/meta-yocto-bsp \
664 /home/nitin/prj/meta-x32.git \
665 "
666 BBLAYERS_NON_REMOVABLE ?= " \
667 /home/nitin/prj/poky.git/meta \
668 /home/nitin/prj/poky.git/meta-yocto \
669 "
670 </literallayout></para></listitem>
671 <listitem><para>Enable the x32 psABI tuning file for <filename>x86_64</filename>
672 machines by editing the <filename>conf/local.conf</filename> like this:
673 <literallayout class='monospaced'>
674 MACHINE = "qemux86-64"
675 DEFAULTTUNE = "x86-64-x32"
676 baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
677 or 'INVALID'), True) or 'lib'}"
678 #MACHINE = "atom-pc"
679 #DEFAULTTUNE = "core2-64-x32"
680 </literallayout></para></listitem>
681 <listitem><para>As usual, use BitBake to build an image that supports the x32 psABI.
682 Here is an example:
683 <literallayout class='monospaced'>
684 $ bitake core-image-sato
685 </literallayout></para></listitem>
686 <listitem><para>As usual, run your image using QEMU:
687 <literallayout class='monospaced'>
688 $ runqemu qemux86-64 core-image-sato
689 </literallayout></para></listitem>
690 </itemizedlist>
691 </para>
692 </section>
693</section>
694
695<section id="licenses">
696 <title>Licenses</title>
697
698 <para>
699 This section describes the mechanism by which the OpenEmbedded build system
700 tracks changes to licensing text.
701 The section also describes how to enable commercially licensed recipes,
702 which by default are disabled.
703 </para>
704
705 <para>
706 For information that can help you maintain compliance with various open
707 source licensing during the lifecycle of the product, see the
708 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Project's Lifecycle</ulink>" section
709 in the Yocto Project Development Manual.
710 </para>
711
712 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
713 <title>Tracking License Changes</title>
714
715 <para>
716 The license of an upstream project might change in the future.
717 In order to prevent these changes going unnoticed, the
718 <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
719 variable tracks changes to the license text. The checksums are validated at the end of the
720 configure step, and if the checksums do not match, the build will fail.
721 </para>
722
723 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
724 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
725
726 <para>
727 The <filename>LIC_FILES_CHKSUM</filename>
728 variable contains checksums of the license text in the source code for the recipe.
729 Following is an example of how to specify <filename>LIC_FILES_CHKSUM</filename>:
730 <literallayout class='monospaced'>
731 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
732 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
733 file://licfile2.txt;endline=50;md5=zzzz \
734 ..."
735 </literallayout>
736 </para>
737
738 <para>
739 The build system uses the
740 <filename><link linkend='var-S'>S</link></filename> variable as the
741 default directory used when searching files listed in
742 <filename>LIC_FILES_CHKSUM</filename>.
743 The previous example employs the default directory.
744 </para>
745
746 <para>
747 You can also use relative paths as shown in the following example:
748 <literallayout class='monospaced'>
749 LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
750 md5=bb14ed3c4cda583abc85401304b5cd4e"
751 LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
752 </literallayout>
753 </para>
754
755 <para>
756 In this example, the first line locates a file in
757 <filename>${S}/src/ls.c</filename>.
758 The second line refers to a file in
759 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, which is the parent
760 of <filename><link linkend='var-S'>S</link></filename>.
761 </para>
762 <para>
763 Note that this variable is mandatory for all recipes, unless the
764 <filename>LICENSE</filename> variable is set to "CLOSED".
765 </para>
766 </section>
767
768 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
769 <title>Explanation of Syntax</title>
770 <para>
771 As mentioned in the previous section, the
772 <filename>LIC_FILES_CHKSUM</filename> variable lists all the
773 important files that contain the license text for the source code.
774 It is possible to specify a checksum for an entire file, or a specific section of a
775 file (specified by beginning and ending line numbers with the "beginline" and "endline"
776 parameters, respectively).
777 The latter is useful for source files with a license notice header,
778 README documents, and so forth.
779 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
780 first line of the file.
781 Similarly, if you do not use the "endline" parameter, it is assumed that the license text
782 ends with the last line of the file.
783 </para>
784
785 <para>
786 The "md5" parameter stores the md5 checksum of the license text.
787 If the license text changes in any way as compared to this parameter
788 then a mismatch occurs.
789 This mismatch triggers a build failure and notifies the developer.
790 Notification allows the developer to review and address the license text changes.
791 Also note that if a mismatch occurs during the build, the correct md5
792 checksum is placed in the build log and can be easily copied to the recipe.
793 </para>
794
795 <para>
796 There is no limit to how many files you can specify using the
797 <filename>LIC_FILES_CHKSUM</filename> variable.
798 Generally, however, every project requires a few specifications for license tracking.
799 Many projects have a "COPYING" file that stores the license information for all the source
800 code files.
801 This practice allows you to just track the "COPYING" file as long as it is kept up to date.
802 </para>
803
804 <tip>
805 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
806 error and displays the correct "md5" parameter value during the build.
807 The correct parameter is also captured in the build log.
808 </tip>
809
810 <tip>
811 If the whole file contains only license text, you do not need to use the "beginline" and
812 "endline" parameters.
813 </tip>
814 </section>
815 </section>
816
817 <section id="enabling-commercially-licensed-recipes">
818 <title>Enabling Commercially Licensed Recipes</title>
819
820 <para>
821 By default, the OpenEmbedded build system disables
822 components that have commercial or other special licensing
823 requirements.
824 Such requirements are defined on a
825 recipe-by-recipe basis through the <filename>LICENSE_FLAGS</filename> variable
826 definition in the affected recipe.
827 For instance, the
828 <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
829 recipe contains the following statement:
830 <literallayout class='monospaced'>
831 LICENSE_FLAGS = "commercial"
832 </literallayout>
833 Here is a slightly more complicated example that contains both an
834 explicit recipe name and version (after variable expansion):
835 <literallayout class='monospaced'>
836 LICENSE_FLAGS = "license_${PN}_${PV}"
837 </literallayout>
838 In order for a component restricted by a <filename>LICENSE_FLAGS</filename>
839 definition to be enabled and included in an image, it
840 needs to have a matching entry in the global
841 <filename>LICENSE_FLAGS_WHITELIST</filename> variable, which is a variable
842 typically defined in your <filename>local.conf</filename> file.
843 For example, to enable
844 the <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
845 package, you could add either the string
846 "commercial_gst-plugins-ugly" or the more general string
847 "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
848 See the
849 "<link linkend='license-flag-matching'>License Flag Matching</link>" section
850 for a full explanation of how <filename>LICENSE_FLAGS</filename> matching works.
851 Here is the example:
852 <literallayout class='monospaced'>
853 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
854 </literallayout>
855 Likewise, to additionally enable the package built from the recipe containing
856 <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, and assuming
857 that the actual recipe name was <filename>emgd_1.10.bb</filename>,
858 the following string would enable that package as well as
859 the original <filename>gst-plugins-ugly</filename> package:
860 <literallayout class='monospaced'>
861 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
862 </literallayout>
863 As a convenience, you do not need to specify the complete license string
864 in the whitelist for every package.
865 you can use an abbreviated form, which consists
866 of just the first portion or portions of the license string before
867 the initial underscore character or characters.
868 A partial string will match
869 any license that contains the given string as the first
870 portion of its license.
871 For example, the following
872 whitelist string will also match both of the packages
873 previously mentioned as well as any other packages that have
874 licenses starting with "commercial" or "license".
875 <literallayout class='monospaced'>
876 LICENSE_FLAGS_WHITELIST = "commercial license"
877 </literallayout>
878 </para>
879
880 <section id="license-flag-matching">
881 <title>License Flag Matching</title>
882
883 <para>
884 The definition of 'matching' in reference to a
885 recipe's <filename>LICENSE_FLAGS</filename> setting is simple.
886 However, some things exist that you should know about in order to
887 correctly and effectively use it.
888 </para>
889
890 <para>
891 Before a flag
892 defined by a particular recipe is tested against the
893 contents of the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, the
894 string <filename>_${PN}</filename> (with
895 <link linkend='var-PN'><filename>PN</filename></link> expanded of course) is
896 appended to the flag, thus automatically making each
897 <filename>LICENSE_FLAGS</filename> value recipe-specific.
898 That string is
899 then matched against the whitelist.
900 So if you specify <filename>LICENSE_FLAGS = "commercial"</filename> in recipe
901 "foo" for example, the string <filename>"commercial_foo"</filename>
902 would normally be what is specified in the whitelist in order for it to
903 match.
904 </para>
905
906 <para>
907 You can broaden the match by
908 putting any "_"-separated beginning subset of a
909 <filename>LICENSE_FLAGS</filename> flag in the whitelist, which will also
910 match.
911 For example, simply specifying "commercial" in
912 the whitelist would match any expanded <filename>LICENSE_FLAGS</filename>
913 definition starting with "commercial" such as
914 "commercial_foo" and "commercial_bar", which are the
915 strings that would be automatically generated for
916 hypothetical "foo" and "bar" recipes assuming those
917 recipes had simply specified the following:
918 <literallayout class='monospaced'>
919 LICENSE_FLAGS = "commercial"
920 </literallayout>
921 </para>
922
923 <para>
924 Broadening the match allows for a range of specificity for the items
925 in the whitelist, from more general to perfectly
926 specific.
927 So you have the choice of exhaustively
928 enumerating each license flag in the whitelist to
929 allow only those specific recipes into the image, or
930 of using a more general string to pick up anything
931 matching just the first component or components of the specified
932 string.
933 </para>
934
935 <para>
936 This scheme works even if the flag already
937 has <filename>_${PN}</filename> appended - the extra <filename>_${PN}</filename> is
938 redundant, but does not affect the outcome.
939 For example, a license flag of "commercial_1.2_foo" would
940 turn into "commercial_1.2_foo_foo" and would match
941 both the general "commercial" and the specific
942 "commercial_1.2_foo", as expected.
943 The flag would also match
944 "commercial_1.2_foo_foo" and "commercial_1.2", which
945 does not make much sense regarding use in the whitelist.
946 </para>
947
948 <para>
949 For a versioned string, you could instead specify
950 "commercial_foo_1.2", which would turn into
951 "commercial_foo_1.2_foo".
952 And, as expected, this flag allows
953 you to pick up this package along with
954 anything else "commercial" when you specify "commercial"
955 in the whitelist.
956 Or, the flag allows you to pick up this package along with anything "commercial_foo"
957 regardless of version when you use "commercial_foo" in the whitelist.
958 Finally, you can be completely specific about the package and version and specify
959 "commercial_foo_1.2" package and version.
960 </para>
961 </section>
962
963 <section id="other-variables-related-to-commercial-licenses">
964 <title>Other Variables Related to Commercial Licenses</title>
965
966 <para>
967 Other helpful variables related to commercial
968 license handling exist and are defined in the
969 <filename>$HOME/poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
970 <literallayout class='monospaced'>
971 COMMERCIAL_AUDIO_PLUGINS ?= ""
972 COMMERCIAL_VIDEO_PLUGINS ?= ""
973 COMMERCIAL_QT = ""
974 </literallayout>
975 If you want to enable these components, you can do so by making sure you have
976 the following statements in your <filename>local.conf</filename> configuration file:
977 <literallayout class='monospaced'>
978 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
979 gst-plugins-ugly-mpegaudioparse"
980 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
981 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
982 COMMERCIAL_QT ?= "qmmp"
983 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
984 </literallayout>
985 Of course, you could also create a matching whitelist
986 for those components using the more general "commercial"
987 in the whitelist, but that would also enable all the
988 other packages with <filename>LICENSE_FLAGS</filename> containing
989 "commercial", which you may or may not want:
990 <literallayout class='monospaced'>
991 LICENSE_FLAGS_WHITELIST = "commercial"
992 </literallayout>
993 </para>
994
995 <para>
996 Specifying audio and video plug-ins as part of the
997 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
998 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
999 or commercial qt components as part of
1000 the <filename>COMMERCIAL_QT</filename> statement (along
1001 with the enabling <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
1002 plug-ins or components into built images, thus adding
1003 support for media formats or components.
1004 </para>
1005 </section>
1006 </section>
1007</section>
1008</chapter>
1009<!--
1010vim: expandtab tw=80 ts=4
1011-->
diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml
deleted file mode 100644
index 149490969a..0000000000
--- a/documentation/poky-ref-manual/usingpoky.xml
+++ /dev/null
@@ -1,651 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='usingpoky'>
6<title>Using the Yocto Project</title>
7
8 <para>
9 This chapter describes common usage for the Yocto Project.
10 The information is introductory in nature as other manuals in the Yocto Project
11 documentation set provide more details on how to use the Yocto Project.
12 </para>
13
14<section id='usingpoky-build'>
15 <title>Running a Build</title>
16
17 <para>
18 This section provides a summary of the build process and provides information
19 for less obvious aspects of the build process.
20 For general information on how to build an image using the OpenEmbedded build
21 system, see the
22 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
23 section of the Yocto Project Quick Start.
24 </para>
25
26 <section id='build-overview'>
27 <title>Build Overview</title>
28
29 <para>
30 The first thing you need to do is set up the OpenEmbedded build environment by sourcing
31 the <link linkend='structure-core-script'>environment setup script</link> as follows:
32 <literallayout class='monospaced'>
33 $ source &OE_INIT_FILE; [build_dir]
34 </literallayout>
35 </para>
36
37 <para>
38 The <filename>build_dir</filename> is optional and specifies the directory the
39 OpenEmbedded build system uses for the build -
40 the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
41 If you do not specify a Build Directory it defaults to <filename>build</filename>
42 in your current working directory.
43 A common practice is to use a different Build Directory for different targets.
44 For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename>
45 target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target.
46 See <link linkend="structure-core-script">&OE_INIT_FILE;</link>
47 for more information on this script.
48 </para>
49
50 <para>
51 Once the build environment is set up, you can build a target using:
52 <literallayout class='monospaced'>
53 $ bitbake &lt;target&gt;
54 </literallayout>
55 </para>
56
57 <para>
58 The <filename>target</filename> is the name of the recipe you want to build.
59 Common targets are the images in <filename>meta/recipes-core/images</filename>,
60 <filename>/meta/recipes-sato/images</filename>, etc. all found in the
61 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
62 Or, the target can be the name of a recipe for a specific piece of software such as
63 <application>busybox</application>.
64 For more details about the images the OpenEmbedded build system supports, see the
65 "<link linkend="ref-images">Images</link>" chapter.
66 </para>
67
68 <note>
69 Building an image without GNU General Public License Version 3 (GPLv3) components
70 is only supported for minimal and base images.
71 See the "<link linkend='ref-images'>Images</link>" chapter for more information.
72 </note>
73 </section>
74
75 <section id='building-an-image-using-gpl-components'>
76 <title>Building an Image Using GPL Components</title>
77
78 <para>
79 When building an image using GPL components, you need to maintain your original
80 settings and not switch back and forth applying different versions of the GNU
81 General Public License.
82 If you rebuild using different versions of GPL, dependency errors might occur
83 due to some components not being rebuilt.
84 </para>
85 </section>
86</section>
87
88<section id='usingpoky-install'>
89 <title>Installing and Using the Result</title>
90
91 <para>
92 Once an image has been built, it often needs to be installed.
93 The images and kernels built by the OpenEmbedded build system are placed in the
94 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in
95 <filename class="directory">tmp/deploy/images</filename>.
96 For information on how to run pre-built images such as <filename>qemux86</filename>
97 and <filename>qemuarm</filename>, see the
98 "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
99 section in the Yocto Project Quick Start.
100 For information about how to install these images, see the documentation for your
101 particular board/machine.
102 </para>
103</section>
104
105<section id='usingpoky-debugging'>
106 <title>Debugging Build Failures</title>
107
108 <para>
109 The exact method for debugging build failures depends on the nature of the
110 problem and on the system's area from which the bug originates.
111 Standard debugging practices such as comparison against the last
112 known working version with examination of the changes and the re-application of steps
113 to identify the one causing the problem are
114 valid for the Yocto Project just as they are for any other system.
115 Even though it is impossible to detail every possible potential failure,
116 this section provides some general tips to aid in debugging.
117 </para>
118
119 <section id='usingpoky-debugging-taskfailures'>
120 <title>Task Failures</title>
121
122 <para>The log file for shell tasks is available in
123 <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
124 For example, the <filename>compile</filename> task for the QEMU minimal image for the x86
125 machine (<filename>qemux86</filename>) might be
126 <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</filename>.
127 To see what BitBake runs to generate that log, look at the corresponding
128 <filename>run.do_taskname.pid</filename> file located in the same directory.
129 </para>
130
131 <para>
132 Presently, the output from Python tasks is sent directly to the console.
133 </para>
134 </section>
135
136 <section id='usingpoky-debugging-taskrunning'>
137 <title>Running Specific Tasks</title>
138
139 <para>
140 Any given package consists of a set of tasks.
141 The standard BitBake behavior in most cases is: <filename>fetch</filename>,
142 <filename>unpack</filename>,
143 <filename>patch</filename>, <filename>configure</filename>,
144 <filename>compile</filename>, <filename>install</filename>, <filename>package</filename>,
145 <filename>package_write</filename>, and <filename>build</filename>.
146 The default task is <filename>build</filename> and any tasks on which it depends
147 build first.
148 Some tasks exist, such as <filename>devshell</filename>, that are not part of the
149 default build chain.
150 If you wish to run a task that is not part of the default build chain, you can use the
151 <filename>-c</filename> option in BitBake as follows:
152 <literallayout class='monospaced'>
153 $ bitbake matchbox-desktop -c devshell
154 </literallayout>
155 </para>
156
157 <para>
158 If you wish to rerun a task, use the <filename>-f</filename> force option.
159 For example, the following sequence forces recompilation after changing files in the
160 working directory.
161 <literallayout class='monospaced'>
162 $ bitbake matchbox-desktop
163 .
164 .
165 [make some changes to the source code in the working directory]
166 .
167 .
168 $ bitbake matchbox-desktop -c compile -f
169 $ bitbake matchbox-desktop
170 </literallayout>
171 </para>
172
173 <para>
174 This sequence first builds <filename>matchbox-desktop</filename> and then recompiles it.
175 The last command reruns all tasks (basically the packaging tasks) after the compile.
176 BitBake recognizes that the <filename>compile</filename> task was rerun and therefore
177 understands that the other tasks also need to be run again.
178 </para>
179
180 <para>
181 You can view a list of tasks in a given package by running the
182 <filename>listtasks</filename> task as follows:
183 <literallayout class='monospaced'>
184 $ bitbake matchbox-desktop -c listtasks
185 </literallayout>
186 The results are in the file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
187 </para>
188 </section>
189
190 <section id='usingpoky-debugging-dependencies'>
191 <title>Dependency Graphs</title>
192
193 <para>
194 Sometimes it can be hard to see why BitBake wants to build some other packages before a given
195 package you have specified.
196 The <filename>bitbake -g targetname</filename> command creates the
197 <filename>depends.dot</filename>, <filename>package-depends.dot</filename>,
198 and <filename>task-depends.dot</filename> files in the current directory.
199 These files show the package and task dependencies and are useful for debugging problems.
200 You can use the <filename>bitbake -g -u depexp targetname</filename> command to
201 display the results in a more human-readable form.
202 </para>
203 </section>
204
205 <section id='usingpoky-debugging-bitbake'>
206 <title>General BitBake Problems</title>
207
208 <para>
209 You can see debug output from BitBake by using the <filename>-D</filename> option.
210 The debug output gives more information about what BitBake
211 is doing and the reason behind it.
212 Each <filename>-D</filename> option you use increases the logging level.
213 The most common usage is <filename>-DDD</filename>.
214 </para>
215
216 <para>
217 The output from <filename>bitbake -DDD -v targetname</filename> can reveal why
218 BitBake chose a certain version of a package or why BitBake
219 picked a certain provider.
220 This command could also help you in a situation where you think BitBake did something
221 unexpected.
222 </para>
223 </section>
224
225 <section id='usingpoky-debugging-buildfile'>
226 <title>Building with No Dependencies</title>
227 <para>
228 If you really want to build a specific <filename>.bb</filename> file, you can use
229 the command form <filename>bitbake -b &lt;somepath/somefile.bb&gt;</filename>.
230 This command form does not check for dependencies so you should use it
231 only when you know its dependencies already exist.
232 You can also specify fragments of the filename.
233 In this case, BitBake checks for a unique match.
234 </para>
235 </section>
236
237 <section id='usingpoky-debugging-variables'>
238 <title>Variables</title>
239 <para>
240 The <filename>-e</filename> option dumps the resulting environment for
241 either the configuration (no package specified) or for a
242 specific package when specified; or <filename>-b recipename</filename>
243 to show the environment from parsing a single recipe file only.
244 </para>
245 </section>
246
247 <section id='recipe-logging-mechanisms'>
248 <title>Recipe Logging Mechanisms</title>
249 <para>
250 Best practices exist while writing recipes that both log build progress and
251 act on build conditions such as warnings and errors.
252 Both Python and Bash language bindings exist for the logging mechanism:
253 <itemizedlist>
254 <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake
255 supports several loglevels: <filename>bb.fatal</filename>,
256 <filename>bb.error</filename>, <filename>bb.warn</filename>,
257 <filename>bb.note</filename>, <filename>bb.plain</filename>,
258 and <filename>bb.debug</filename>.</para></listitem>
259 <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set
260 of loglevels exist and are accessed with a similar syntax:
261 <filename>bbfatal</filename>, <filename>bberror</filename>,
262 <filename>bbwarn</filename>, <filename>bbnote</filename>,
263 <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem>
264 </itemizedlist>
265 </para>
266
267 <para>
268 For guidance on how logging is handled in both Python and Bash recipes, see the
269 <filename>logging.bbclass</filename> file in the
270 <filename>meta/classes</filename> folder of the
271 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
272 </para>
273
274 <section id='logging-with-python'>
275 <title>Logging With Python</title>
276 <para>
277 When creating recipes using Python and inserting code that handles build logs
278 keep in mind the goal is to have informative logs while keeping the console as
279 "silent" as possible.
280 Also, if you want status messages in the log use the "debug" loglevel.
281 </para>
282
283 <para>
284 Following is an example written in Python.
285 The code handles logging for a function that determines the number of tasks
286 needed to be run:
287 <literallayout class='monospaced'>
288 python do_listtasks() {
289 bb.debug(2, "Starting to figure out the task list")
290 if noteworthy_condition:
291 bb.note("There are 47 tasks to run")
292 bb.debug(2, "Got to point xyz")
293 if warning_trigger:
294 bb.warn("Detected warning_trigger, this might be a problem later.")
295 if recoverable_error:
296 bb.error("Hit recoverable_error, you really need to fix this!")
297 if fatal_error:
298 bb.fatal("fatal_error detected, unable to print the task list")
299 bb.plain("The tasks present are abc")
300 bb.debug(2, "Finished figuring out the tasklist")
301 }
302 </literallayout>
303 </para>
304 </section>
305
306 <section id='logging-with-bash'>
307 <title>Logging With Bash</title>
308 <para>
309 When creating recipes using Bash and inserting code that handles build
310 logs you have the same goals - informative with minimal console output.
311 The syntax you use for recipes written in Bash is similar to that of
312 recipes written in Python described in the previous section.
313 </para>
314
315 <para>
316 Following is an example written in Bash.
317 The code logs the progress of the <filename>do_my_function</filename> function.
318 <literallayout class='monospaced'>
319 do_my_function() {
320 bbdebug 2 "Running do_my_function"
321 if [ exceptional_condition ]; then
322 bbnote "Hit exceptional_condition"
323 fi
324 bbdebug 2 "Got to point xyz"
325 if [ warning_trigger ]; then
326 bbwarn "Detected warning_trigger, this might cause a problem later."
327 fi
328 if [ recoverable_error ]; then
329 bberror "Hit recoverable_error, correcting"
330 fi
331 if [ fatal_error ]; then
332 bbfatal "fatal_error detected"
333 fi
334 bbdebug 2 "Completed do_my_function"
335 }
336 </literallayout>
337 </para>
338 </section>
339 </section>
340
341 <section id='usingpoky-debugging-others'>
342 <title>Other Tips</title>
343
344 <para>
345 Here are some other tips that you might find useful:
346 <itemizedlist>
347 <listitem><para>When adding new packages, it is worth watching for
348 undesirable items making their way into compiler command lines.
349 For example, you do not want references to local system files like
350 <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>.
351 </para></listitem>
352 <listitem><para>If you want to remove the psplash boot splashscreen,
353 add <filename>psplash=false</filename> to the kernel command line.
354 Doing so prevents psplash from loading and thus allows you to see the console.
355 It is also possible to switch out of the splashscreen by
356 switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
357 </para></listitem>
358 </itemizedlist>
359 </para>
360 </section>
361</section>
362
363<section id='maintaining-build-output-quality'>
364 <title>Maintaining Build Output Quality</title>
365
366 <para>
367 A build's quality can be influenced by many things.
368 For example, if you upgrade a recipe to use a new version of an upstream software
369 package or you experiment with some new configuration options, subtle changes
370 can occur that you might not detect until later.
371 Consider the case where your recipe is using a newer version of an upstream package.
372 In this case, a new version of a piece of software might introduce an optional
373 dependency on another library, which is auto-detected.
374 If that library has already been built when the software is building,
375 then the software will link to the built library and that library will be pulled
376 into your image along with the new software even if you did not want the
377 library.
378 </para>
379
380 <para>
381 The <filename>buildhistory</filename> class exists to help you maintain
382 the quality of your build output.
383 You can use the class to highlight unexpected and possibly unwanted
384 changes in the build output.
385 When you enable build history it records information about the contents of
386 each package and image and then commits that information to a local Git
387 repository where you can examine the information.
388 </para>
389
390 <para>
391 The remainder of this section describes the following:
392 <itemizedlist>
393 <listitem><para>How you can enable and disable
394 build history</para></listitem>
395 <listitem><para>How to understand what the build history contains
396 </para></listitem>
397 <listitem><para>How to limit the information used for build history
398 </para></listitem>
399 <listitem><para>How to examine the build history from both a
400 command-line and web interface</para></listitem>
401 </itemizedlist>
402 </para>
403
404 <section id='enabling-and-disabling-build-history'>
405 <title>Enabling and Disabling Build History</title>
406
407 <para>
408 Build history is disabled by default.
409 To enable it, add the following statements to the end of your
410 <filename>conf/local.conf</filename> file found in the
411 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
412 <literallayout class='monospaced'>
413 INHERIT += "buildhistory"
414 BUILDHISTORY_COMMIT = "1"
415 </literallayout>
416 Enabling build history as previously described
417 causes the build process to collect build
418 output information and commit it to a local
419 <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository.
420 <note>
421 Enabling build history increases your build times slightly,
422 particularly for images, and increases the amount of disk
423 space used during the build.
424 </note>
425 </para>
426
427 <para>
428 You can disable build history by removing the previous statements
429 from your <filename>conf/local.conf</filename> file.
430 However, you should realize that enabling and disabling
431 build history in this manner can change the
432 <filename>do_package</filename> task checksums, which if you
433 are using the OEBasicHash signature generator (the default
434 for many current distro configurations including
435 <filename>DISTRO = "poky"</filename> and
436 <filename>DISTRO = ""</filename>) will result in the packaging
437 tasks being re-run during the subsequent build.
438 </para>
439
440 <para>
441 To disable the build history functionality without causing the
442 packaging tasks to be re-run, add just this statement to your
443 <filename>conf/local.conf</filename> file:
444 <literallayout class='monospaced'>
445 BUILDHISTORY_FEATURES = ""
446 </literallayout>
447 </para>
448 </section>
449
450 <section id='understanding-what-the-build-history-contains'>
451 <title>Understanding What the Build History Contains</title>
452
453 <para>
454 Build history information is kept in
455 <link linkend='var-TMPDIR'><filename>$TMPDIR</filename></link><filename>/buildhistory</filename>
456 in the Build Directory.
457 The following is an example abbreviated listing:
458 <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
459 </para>
460
461 <section id='build-history-package-information'>
462 <title>Build History Package Information</title>
463
464 <para>
465 The history for each package contains a text file that has
466 name-value pairs with information about the package.
467 For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename>
468 contains the following:
469 <literallayout class='monospaced'>
470 PV = 1.19.3
471 PR = r3
472 RDEPENDS = update-rc.d eglibc (>= 2.13)
473 RRECOMMENDS = busybox-syslog busybox-udhcpc
474 PKGSIZE = 564701
475 FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \
476 /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \
477 /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \
478 /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
479 FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh
480 </literallayout>
481 Most of these name-value pairs corresponds to variables used
482 to produce the package.
483 The exceptions are <filename>FILELIST</filename>, which is the
484 actual list of files in the package, and
485 <filename>PKGSIZE</filename>, which is the total size of files
486 in the package in bytes.
487 </para>
488
489 <para>
490 There is also a file corresponding to the recipe from which the
491 package came (e.g.
492 <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>):
493 <literallayout class='monospaced'>
494 PV = 1.19.3
495 PR = r3
496 DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \
497 virtual/libc update-rc.d-native
498 PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \
499 busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \
500 busybox-staticdev busybox-locale
501 </literallayout>
502 </para>
503 </section>
504
505 <section id='build-history-image-information'>
506 <title>Build History Image Information</title>
507
508 <para>
509 The files produced for each image are as follows:
510 <itemizedlist>
511 <listitem><para><emphasis>build-id:</emphasis>
512 Human-readable information about the build configuration
513 and metadata source revisions.</para></listitem>
514 <listitem><para><emphasis>*.dot:</emphasis>
515 Dependency graphs for the image that are
516 compatible with <filename>graphviz</filename>.
517 </para></listitem>
518 <listitem><para><emphasis>files-in-image.txt:</emphasis>
519 A list of files in the image with permissions,
520 owner, group, size, and symlink information.
521 </para></listitem>
522 <listitem><para><emphasis>image-info.txt:</emphasis>
523 A text file containing name-value pairs with information
524 about the image.
525 See the following listing example for more information.
526 </para></listitem>
527 <listitem><para><emphasis>installed-package-names.txt:</emphasis>
528 A list of installed packages by name only.</para></listitem>
529 <listitem><para><emphasis>installed-package-sizes.txt:</emphasis>
530 A list of installed packages ordered by size.
531 </para></listitem>
532 <listitem><para><emphasis>installed-packages.txt:</emphasis>
533 A list of installed packages with fuill package
534 filenames.</para></listitem>
535 </itemizedlist>
536 <note>
537 Installed package information is able to be gathered and
538 produced even if package management is disabled for the final
539 image.
540 </note>
541 </para>
542
543 <para>
544 Here is an example of <filename>image-info.txt</filename>:
545 <literallayout class='monospaced'>
546 DISTRO = poky
547 DISTRO_VERSION = 1.1+snapshot-20120207
548 USER_CLASSES = image-mklibs image-prelink
549 IMAGE_CLASSES = image_types
550 IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \
551 package-management ssh-server-dropbear package-management
552 IMAGE_LINGUAS = en-us en-gb
553 IMAGE_INSTALL = task-core-boot task-base-extended
554 BAD_RECOMMENDATIONS =
555 ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ;
556 IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
557 IMAGESIZE = 171816
558 </literallayout>
559 Other than <filename>IMAGESIZE</filename>, which is the
560 total size of the files in the image in Kbytes, the
561 name-value pairs are variables that may have influenced the
562 content of the image.
563 This information is often useful when you are trying to determine
564 why a change in the package or file listings has occurred.
565 </para>
566 </section>
567
568 <section id='using-build-history-to-gather-image-information-only'>
569 <title>Using Build History to Gather Image Information Only</title>
570
571 <para>
572 As you can see, build history produces image information,
573 including dependency graphs, so you can see why something
574 was pulled into the image.
575 If you are just interested in this information and not
576 interested in collecting history or any package information,
577 you can enable writing only image information without
578 any history by adding the following
579 to your <filename>conf/local.conf</filename> file found in the
580 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
581 <literallayout class='monospaced'>
582 INHERIT += "buildhistory"
583 BUILDHISTORY_COMMIT = "0"
584 BUILDHISTORY_FEATURES = "image"
585 </literallayout>
586 </para>
587 </section>
588
589 <section id='examining-build-history-information'>
590 <title>Examining Build History Information</title>
591
592 <para>
593 You can examine build history output from the command line or
594 from a web interface.
595 </para>
596
597 <para>
598 To see any changes that have occurred (assuming you have
599 <filename>BUILDHISTORY_COMMIT = "1"</filename>), you can simply
600 use any Git command that allows you to view the history of
601 a repository.
602 Here is one method:
603 <literallayout class='monospaced'>
604 $ git log -p
605 </literallayout>
606 You need to realize, however, that this method does show
607 changes that are not significant (e.g. a package's size
608 changing by a few bytes).
609 </para>
610
611 <para>
612 A command-line tool called <filename>buildhistory-diff</filename>
613 does exist though that queries the Git repository and prints just
614 the differences that might be significant in human-readable form.
615 Here is an example:
616 <literallayout class='monospaced'>
617 $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
618 Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt):
619 /etc/anotherpkg.conf was added
620 /sbin/anotherpkg was added
621 * (installed-package-names.txt):
622 * anotherpkg was added
623 Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt):
624 anotherpkg was added
625 packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
626 * PR changed from "r0" to "r1"
627 * PV changed from "0.1.10" to "0.1.12"
628 packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
629 * PR changed from "r0" to "r1"
630 * PV changed from "0.1.10" to "0.1.12"
631 </literallayout>
632 </para>
633
634 <para>
635 To see changes to the build history using a web interface, follow
636 the instruction in the <filename>README</filename> file here.
637 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
638 </para>
639
640 <para>
641 Here is a sample screenshot of the interface:
642 <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" />
643 </para>
644 </section>
645 </section>
646</section>
647
648</chapter>
649<!--
650vim: expandtab tw=80 ts=4
651-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-10 21:42:49 +0000